.
Eloquence B.07.10 contact contact

Documentation / Eloquence WEBDLG / Object classes and attribute reference

Object classes and attribute reference

 
.
  This reference covers every object class and attribute implemented with WEBDLG.

Contents:


Attributes common to all object classes

Name Type Default GET SET Description
class STRING   X - Object's class name
id STRING empty X X Object's identifier (name), must be unique in the current object level
x INT 0 X X Horizontal object position
y INT 0 X X Vertical object position
w INT 0* X X Object width (default value is class-specific)
h INT 0* X X Object height (default value is class-specific)
visible INT 1 X X Whether the object is visible (objects in a container are affected by the container's visibility)
sensitive INT 1 X X Whether the object is sensitive for user-input (objects in a container are affected by the container's sensitivity)
rule INT 0 X X If nonzero: value returned to the program on action (kind of action is class-specific)
ruleonchange INT 1* X X If nonzero: rule is triggered only when edittext contents change (default value depends on the RuleOnChange configuration). If defined in a dialog or groupbox, this attribute affects all contained objects.
focus INT 0 X X Whether this object has or shall get the keyboard focus
help STRING empty X X Currently unused since the help system is not functional yet
udata ANY   X X General-purpose user data
fgcolor STRING empty X X Object's foreground (text) color in hexadecimal RGB format (#rrggbb), for example: #000000 equals black, #ffffff equals white
bgcolor STRING empty X X Object's background color in hexadecimal RGB format (#rrggbb), for example: #000000 equals black, #ffffff equals white
fgc STRING* empty * X Provided for backwards compatibility, fgc accepts the same string argument format as fgcolor. However, integer values are accepted as well but ignored.
Note: DLG GET always returns a 0 integer value.
bgc STRING* empty * X Provided for backwards compatibility, bgc accepts the same string argument format as bgcolor. However, integer values are accepted as well but ignored.
Note: DLG GET always returns a 0 integer value.
font INT 0 X X Ignored but implemented for compatibility reasons
fontface STRING empty X X Aka. font family. The following universal font families should be supported by any browser regardless of the operating system used: Serif, Sans-serif, Cursive, Fantasy, Monospace. Otherwise, any system-specific font families such as Courier can be used as well but may cause non-portable appearance.
fontsize STRING* empty X X Either a pre-defined constant (xx-small, x-small, smaller, small, medium, large, larger, x-large, xx-large) or an absolute size followed by an unit (12pt for 12 points, 20px for 20 pixels). If no unit is given or an INT is passed, points are assumed.
fontstyle STRING empty X X A pre-defined constant (plain, bold, italic)
first STRING   X - Path of first contained object
next STRING   X - Path of next object in same level
kbcode INT   - X Ignored but implemented for compatibility reasons
focusobj INT   X - Path of current focused object
kbind INT   X X Ignored but implemented for compatibility reasons


Dialog

The dialog class serves as the root-level object container.

Name Type Default GET SET Description
x INT 0 X X Ignored but implemented for compatibility reasons (please refer to the document How compatible is Eloquence WEBDLG? for details)
y INT 0 X X Ignored but implemented for compatibility reasons (please refer to the document How compatible is Eloquence WEBDLG? for details)
title STRING empty X X Dialog title (a special token is provided to embed the title into customized page header and/or page trailer template files)
border INT 3 X X If nonzero: border width in pixels (has no effect with Netscape 4.x browsers).
bgimage STRING empty X X Location of a background image file, typically on a web server. If a relative URL is given the .baseurl attribute of the application object is prepended. Please note that with Netscape this disables any background colors (even with Netscape 6.2).
cr INT 0 X X Ignored but implemented for compatibility reasons
f1...f10 INT 0 X X Ignored but implemented for compatibility reasons
alt INT 0 X X Ignored but implemented for compatibility reasons


Groupbox

The groupbox class serves as a general-purpose object container.

Name Type Default GET SET Description
title STRING empty X X Currently ignored but implemented
border INT 1 X X If nonzero: border width in pixels (has no effect with Netscape 4.x browsers).


StaticText

The statictext class is used to display object labels as well as text of any purpose.

Name Type Default GET SET Description
w INT * X X Object width (default value depends on text length)
h INT 1 X X Object height
text STRING empty X X The text to be displayed (HTML is supported)


PushButton

The pushbutton class is used to submit actions to the program according to the rule value.

Name Type Default GET SET Description
w INT * X X Object width (default value depends on length of button's text)
h INT 1 X X Object height
rule INT 0 X X If nonzero: rule value to be triggered when the button is clicked.
text STRING empty X X The button's text (HTML is supported)
border INT 1 X X Currently ignored but implemented (a pushbutton always has a border)
adjust INT 0 X X Ignored but implemented for compatibility reasons
ruleoverride INT 1 X X Whether the rule of an edittext which currently has the focus will be overridden.


CheckBox

The checkbox class is used to select an option. Additionally, a rule can be triggered if the state of the checkbox changes.

Name Type Default GET SET Description
w INT * X X Object width (default value depends on length of label text)
h INT 1 X X Object height
rule INT 0 X X If nonzero: rule value to be triggered when the state of the checkbox is changed.
text STRING empty X X The label text of the checkbox (HTML is supported)
active INT 0 X X Whether the checkbox is active or to be activated
ruleoverride INT 1 X X Whether the rule of an edittext which currently has the focus will be overridden.


RadioButton

The radiobutton class is used to choose one of a number of options. Additionally, a rule can be triggered if the state of the radiobutton changes.

Name Type Default GET SET Description
w INT * X X Object width (default value depends on length of label text)
h INT 1 X X Object height
rule INT 0 X X If nonzero: rule value to be triggered when the state of the radiobutton is changed.
text STRING empty X X The label text of the radiobutton (HTML is supported)
activebtn STRING empty X - Path of active radiobutton in this group
active INT 0 X X Whether the radiobutton is active or to be activated
ruleoverride INT 1 X X Whether the rule of an edittext which currently has the focus will be overridden.


EditText

The edittext class is used for single- and multiline editable data entry areas. A rule can be triggered whenever the contents have changed and the focus moves out of the edittext.

Please note that although a cursor position is maintained, this is only used internally (eg. to specify the position where new contents are to be inserted). The browser however does not mention this cursor position at all.

Name Type Default GET SET Description
rule INT 0 X X If nonzero: rule value to be triggered when the contents have changed and the focus moves out of the edittext.
length INT   X - Current length of content
content STRING empty X X Current content
editable INT 1 X X Whether edittext is editable or read-only
multiline INT 0 X X Whether edittext is single- or multi-line
border INT 1 X X Currently ignored but implemented (an edittext always has a border)
title STRING empty X X Ignored but implemented for compatibility reasons
hsb INT 1 X X Ignored but implemented for compatibility reasons (horizontal scroll bar is displayed automatically by the browser)
vsb INT 1 X X Ignored but implemented for compatibility reasons (horizontal scroll bar is displayed automatically by the browser)
maxchars INT 0 X X Maximum characters accepted for input (0=unlimited)
maxlines INT 0 X X Ignored but implemented for compatibility reasons
ispassword INT 0 X X Whether contents are visible or displayed as '*' asterisk characters
vheight INT   X - Current number of lines
vwidth INT   X - Current number of columns
cx INT 0 X X Cursor column (starting with 0)
cy INT 0 X X Cursor line (starting with 0)
topitem INT 0 X X Topmost line (starting with 0)
clear     - X Clears the entire edittext
add STRING   - X Adds new contents to the end
line STRING   X X A specific line's contents
home     - X Moves the internal position to the beginning
end     - X Moves the internal position to the end
bol     - X Moves the internal position to the beginning of the current line
eol     - X Moves the internal position to the end of the current line
up INT   - X Moves the internal position up for the specified number of lines
down INT   - X Moves the internal position down for the specified number of lines
left INT   - X Moves the internal position left for the specified number of columns
right INT   - X Moves the internal position right for the specified number of columns
npage INT   - X Moves the internal position down for the specified number of pages
ppage INT   - X Moves the internal position up for the specified number of pages
ins STRING   - X Inserts new contents at the current position
delch INT   - X Deletes the specified number of characters from the current position
delln INT   - X Deletes the specified number of lines from the current position
deleol     - X Deletes from the current position up to the end of the current line
deleot     - X Deletes from the current position up to the end
file STRING   - X Name of a file from which the contents shall be read (the encoding of external files can be configured with the ExtCharset directive)
insertfile STRING   - X Name of a file from which the contents shall be inserted at the current position
writefile STRING   - X Name of a file to which the contents shall be written


ListBox

The listbox class is used to choose from a number of lines. Additionally, a rule can be triggered if the selected line changes.

Please note that although a cursor position is maintained, this is only used internally (eg. to specify the position where new contents are to be inserted). The browser however does not mention this cursor position at all.

Name Type Default GET SET Description
rule INT 0 X X If nonzero: rule value to be triggered when the selected line changes.
length INT   X - Current length of content
content STRING empty X X Current content
multiline INT 0 X X Whether edittext is single- or multi-line
border INT 1 X X Currently ignored but implemented (a listbox always has a border)
title STRING empty X X Ignored but implemented for compatibility reasons
hsb INT 1 X X Ignored but implemented for compatibility reasons (horizontal scroll bar is displayed automatically by the browser)
vsb INT 1 X X Ignored but implemented for compatibility reasons (horizontal scroll bar is displayed automatically by the browser)
vheight INT   X - Current number of lines
vwidth INT   X - Current number of columns
cx INT 0 X X Cursor column (starting with 0)
cy INT 0 X X Cursor line (starting with 0)
topitem INT 0 X X Topmost line (starting with 0)
activeline INT 0 X X Current active line (starting with 1, 0 = no active line)
clear     - X Clears the entire edittext
add STRING   - X Adds new contents to the end
line STRING   X X A specific line's contents
home     - X Moves the internal position to the beginning
end     - X Moves the internal position to the end
bol     - X Moves the internal position to the beginning of the current line
eol     - X Moves the internal position to the end of the current line
up INT   - X Moves the internal position up for the specified number of lines
down INT   - X Moves the internal position down for the specified number of lines
left INT   - X Moves the internal position left for the specified number of columns
right INT   - X Moves the internal position right for the specified number of columns
npage INT   - X Moves the internal position down for the specified number of pages
ppage INT   - X Moves the internal position up for the specified number of pages
ins STRING   - X Inserts new contents at the current position
delch INT   - X Deletes the specified number of characters from the current position
delln INT   - X Deletes the specified number of lines from the current position
deleol     - X Deletes from the current position up to the end of the current line
deleot     - X Deletes from the current position up to the end
file STRING   - X Name of a file from which the contents shall be read (the encoding of external files can be configured with the ExtCharset directive)
writefile STRING   - X Name of a file to which the contents shall be written


HelpText

The helptext class is currently not functional. It is however implemented for compatibility reasons.


POPUP BOX

The POPUP BOX displays a simple confirmation dialog with a variable number of text lines and pushbuttons.

Syntax:

    POPUP BOX X,Y,"[Title][Line 1|Line 2|Line 3][Button 1|Button 2]",Rc

Please note:

  • With WEBDLG, the X/Y coordinates are ignored.

  • On entry, WEBDLG ignores the value of Rc. With ASCII DLG, it would define the default button which can be submitted with the ENTER key, but with WEBDLG this is currently not implemented.

  • On exit, the value of Rc reflects which button was submitted (starting with 1).

  • CSS style sheets can be used to customize the appearance. Please refer to the document How compatible is Eloquence WEBDLG? for details.

  • HTML can be used in text lines and buttons to further customize the POPUP BOX layout. Please note that in the title HTML is not supported.


System

The non-visible root-level system object is used to query properties of the current driver. A program can use this information to dynamically find out eg. whether it uses a WEBDLG or Java DLG driver and change its behavior appropriately.

Name Type Default GET SET Description
driver STRING * X - WEB for WEBDLG, JDLG for Java DLG (will be implemented for ASCII DLG as well)
version STRING * X - The driver's version code
baseurl STRING empty X - Any given relative URL (eg. referring to image files) is prepended with this value. An URL is considered relative if it does not start with http:// (globally-absolute) or / (server-absolute).
helpbaseurl STRING empty X - Currently unused since the help system is not functional yet
remoteaddr STRING * X - The IP address of the remote PC where the user's browser runs
remotename STRING * X - The host name of the remote PC where the user's browser runs (equivalent to 'remoteaddr' if the host name is unkown, e.g. if the Apache web server is not configured to do DNS lookups)
remoteport STRING * X - The port number the remote PC's browser uses for this request

Example:

  ! Query the System.driver
     DLG GET "System.driver",Driver$


Application

The non-visible root-level application object is used to define session-wide parameters. If required, they should be specified early in the program before any dialog is loaded to ensure that every dialog will be affected.

Name Type Default GET SET Description
baseurl STRING empty X X Any given relative URL (eg. referring to image files) is prepended with this value. An URL is considered relative if it does not start with http:// (globally-absolute) or / (server-absolute).
helpbaseurl STRING empty X X Currently unused since the help system is not functional yet

Example:

  ! Set the Application.baseURL
     DLG SET "Application.baseURL","http://www.your-host.com/your-app/"

  ! Now load the first dialog
     DLG LOAD "dialog.dlg,YOURVOL"


Image

With the image class, graphics can be embedded into dialogs. The particular image file is typically stored on the same web server where the WEBDLG application runs.

Name Type Default GET SET Description
w INT 0 X X Width in character cells of the rectangular area where the image is to be placed. If the image's width extends this width the area is enlarged accordingly by the browser.
h INT 0 X X Height in character cells of the rectangular area where the image is to be placed. If the image's height extends this height the area is enlarged accordingly by the browser.
url STRING empty X X Location of the image file, typically on a web server. If a relative URL is given the .baseurl attribute of the application object is prepended.
rule INT 0 X X If nonzero: rule value to be triggered when the image is clicked.
ruleoverride INT 1 X X Whether the rule of an edittext which currently has the focus will be overridden.
border INT 0 X X If nonzero: border width in pixels (has no effect with Netscape 4.x browsers).
sw INT 0 X X Horizontal alignment:
 0: The image is horizontally centered
 <0: The image is horizontally scaled to .w (in character cells)
 >0: The image is horizontally scaled to .sw (in pixels)
sh INT 0 X X Vertical alignment:
 0: The image is vertically centered
 <0: The image is vertically scaled to .h (in character cells)
 >0: The image is vertically scaled to .sh (in pixels)
area STRING empty X X Image area (see below).

Using image areas

Image areas can be used to define different clickable areas within an image. Each area can return a different rule value.

An image area is defined with the following syntax:

  RULE:SHAPE:COORDINATES[:DESCRIPTION]
RULE
An integer value specifying the rule to be returned when the area is clicked
SHAPE
Defines the shape of the clickable area:
  • RECT - a rectangular area
  • CIRCLE - a circular area
  • POLY - a polygonal area
COORDINATES
A comma-separated list of integer values defining the coordinates of the clickable area. All coordinates are in pixel units:
  • For a RECT area, exactly 4 coordinates must be specified:
    • x coordinate of upper left corner
    • y coordinate of upper left corner
    • x coordinate of lower right corner
    • y coordinate of lower right corner
  • For a CIRCLE area, exactly 3 coordinates must be specified:
    • x coordinate of center point
    • y coordinate of center point
    • radius
  • For a POLY area, an even number of coordinates must be specified, defining the polygon points (x,y). The last polygon point is automatically connected to the first. At least 3 polygon points (6 coordinates) must be specified.
DESCRIPTION
An optional text which causes some browsers to display a tooltip when the mouse cursor touches the clickable area

The following example first clears any existing area and then defines a rectangle, a circle and a polygon:

  ! Clear any existing area
     DLG SET "My_Dialog.My_image.area",""
  ! Define a rectangular area with rule value 101
     DLG SET "My_Dialog.My_image.area[1]","101:rect:25,25,75,75:A Rectangle"
  ! Define a circular area with rule value 102
     DLG SET "My_Dialog.My_image.area[2]","102:circle:125,50,25:A Circle"
  ! Define a triangular area using a polygon with rule value 103
     DLG SET "My_Dialog.My_image.area[3]","103:poly:200,25,175,75,225,75:A Triangle"

Please note:

  • To define an area, an index must be specified, starting with 1:
    "My_Dialog.My_image.area[1]"

    The index must be specified in increments of 1 (1, 2, 3, ...), otherwise a DLG error 660 will be returned.

    If the index is omitted, the next index (highest index plus 1) is used, for example:
    DLG SET "My_Dialog.My_image.area","101:rect:25,25,75,75:A Rectangle"
    DLG SET "My_Dialog.My_image.area","102:circle:125,50,25:A Circle"
    DLG SET "My_Dialog.My_image.area","103:poly:200,25,175,75,225,75:A Triangle"

  • If the image itself has a rule, it is considered the "default rule" which is returned when you click the image but not into one of the areas.

  • The descriptions ('A Rectangle', 'A Circle', 'A Triangle' in the example) are optional and can be omitted, such as:
    DLG SET "My_Dialog.My_image.area[1]","101:rect:25,25,75,75"

    Please note that not all browsers use them to display a tooltip so they may be nonfunctional with some browsers.

  • To clear (undefine) an existing area, set it to an empty string, such as:
    DLG SET "My_Dialog.My_image.area[1]",""

  • To clear (undefine) all existing areas, omit the index, such as:
    DLG SET "My_Dialog.My_image.area",""

Image areas can be defined in the DLG file as well. Of course, in this case it does not make sense to previously clear the existing areas. Example:

  Image img
  {
    # Default rule
    .rule = 100
    # rectangular area with rule value 101
    .area[1] = "101:rect:25,25,75,75:A Rectangle"
    # circular area with rule value 102
    .area[2] = "102:circle:125,50,25:A Circle"
    # triangular area using a polygon with rule value 103
    .area[3] = "103:poly:200,25,175,75,225,75:A Triangle"
  }

Furthermore, the image areas can be read from a file. Please note that the file must be accessible by WEBDLG (i.e., you cannot specify an URL of a remote file).

The file should contain the area definitions in the same format as described above. Example:

  # rectangular area with rule value 101
  101:rect:25,25,75,75:A Rectangle
  # circular area with rule value 102
  102:circle:125,50,25:A Circle
  # triangular area using a polygon with rule value 103
  103:poly:200,25,175,75,225,75:A Triangle

The file can then be referenced with the .area attribute as follows:

  Image img
  {
    # Default rule
    .rule = 100
    # read area definitions from external file
    .area = "file:/path/to/area.file"
  }

Please note: The file must be specified using the absolute path and must be prefixed with "file:".


Using HTML in StaticText and Button objects

If the text in a StaticText, PushButton, CheckBox or RadioButton begins with <html> and ends with </html>, the remaining text is considered HTML code and inserted into the dialog as-is.

Example:

  ! Highlight the current item in a statictext with red color
  !
     Text$="<html>The current item is: <font color='red'>"&Item$&"</font></html>"
     DLG SET "My_Dialog.My_statictext.text",Text$

Because a POPUP BOX internally uses StaticText and PushButton objects, HTML is especially useful to further customize a POPUP BOX layout:

  ! <em>...</em> is used to show text in italic (emphasized)
  ! YES button is green, NO button is red
  !
     Buf$="[Confirmation]"
     Buf$=Buf$&"[<html>Do you <em>really</em> want to quit?</html>"
     Buf$=Buf$&"|<html>Any <em>unsaved</em> changes will be lost!</html>]"
     Buf$=Buf$&"[<html><font color='green'>Yes</font></html>"
     Buf$=Buf$&"|<html><font color='red'>No</font></html>]"
     POPUP BOX Buf$,Rc

Please note:

  • While using HTML offers a lot of flexibility, wrong HTML code can easily destroy a dialog's functionality.

  • The following characters have a special meaning in HTML and must be replaced with their so called "character entity references":
    • & - replace with &amp;
    • " - replace with &quot;
    • < - replace with &lt;
    • > - replace with &gt;

  • Take care of correctly balancing your HTML tags. For example, the following is correct HTML:
    <font color='green'><strong>some text</strong></font>
    Example of wrong HTML code (tags not correctly balanced):
    <font color='green'><strong>some text</font></strong>
    Another example of wrong HTML code (missing closing font tag):
    <font color='green'><strong>some text</strong>

  • Take care of correctly quoting any tag attribute. If you forget a closing quote, the dialog will probably not function correctly on some browsers. In particular, the Internet Explorer seems to tolerate most quoting errors, so if you forget a closing quote and then test your dialogs with the Internet Explorer, they may seem to be correct but won't work in other browsers such as Mozilla Firefox.
    This is an example of wrong HTML quoting (missing closing quote):
    <font color='green>

  • You can use single or double quotes. If you specify HTML text in a DLG file you must use single quotes because a double quote inside a string is not correctly recognized by the Eloquence DLG file parser (i.e., the string will be undesirably terminated).
    If you, however, specify HTML text with DLG SET you are free to use double quotes (CHR$(34)).

With HTML in a StaticText object, you can embed external hyperlinks into your dialogs. Example:

  ! Embed a hyperlink to our home page
  !
     Text$="<html><a href='http://www.our.homepage...' target='_blank'>Home</a></html>"
     DLG SET "My_Dialog.My_statictext.text",Text$

Please note the target='_blank' attribute which specifies that a new browser window should be opened to display the hyperlink target. This is important because if you don't specify to open a new browser window, the hyperlink target will be displayed in the current browser window where your WEBDLG program is running, kind of "interrupting" your program: There is no obvious way to return to your program so the less experienced user will probably end up with an idle WEBDLG session which will eventually expire silently.

A more sophisticated way to display external hyperlinks is to use JavaScript to open new browser windows with specific properties.

For example, put the following JavaScript code section into your page header:

  <script language="JavaScript">
  <!--
   function openWin(width, height, url)
   {
    window.open(url, 'win_' + width + '_' + height,
     'width=' + width + ',height=' + height
     + ',resizable=yes,scrollbars=yes');
   }
  //-->
  </script>

Having this function defined, you can conveniently display external links in new browser windows. The width and height parameters specify the size of the new window which will be resizable and show scrollbars when needed.

Example:

  ! Embed a hyperlink to our home page using javascript:openWin()
  ! <a href="javascript:openWin(500,350,'http://www.our.homepage...')">Home</a>
  !
     Text$="<html><a href="&CHR$(34)
     Text$=Text$&"javascript:openWin(500,350,'http://www.our.homepage...')"
     Text$=Text$&CHR$(34)&">Home</a></html>"
     DLG SET "My_Dialog.My_statictext.text",Text$

In the example above, the size of the window is 500x350 pixels. Note that our openWin() JavaScript function will compose the window's name from this size (2nd parameter of the window.open() function: 'win_' + width + '_' + height will result in "win_500_350") so that for each size there will be only one window present (i.e., windows of the same size will be reused).

Also note that when using JavaScript in hyperlinks, you have to use both double and single quotes, as shown in the example above. Therefore, you cannot define such hyperlinks in a DLG file: As explained above, double quotes inside a string do not work in DLG files.

To learn more about the JavaScript window.open() function please refer to the Mozilla Gecko DOM reference documentation. An informative introduction to hyperlinks can be found here.


 
 
.
 
 
  Privacy | Webmaster | Terms of use | Impressum Revision:  2005-05-29  
  Copyright © 1995-2005 Marxmeier Software AG