B.07.00 Release Notes

Status

This document describes the status of the Eloquence Java based dialog system. At this stage, the Eloquence Java based dialog system intends to be mostly compatible with the Eloquence text based dialogs and should be compatible with existing programs.


Recent changes:


Fixed problems:

The following problems have been identified in previous testing.


The Eloquence Java based dialog system currently implements most dialog controls and attributes as described in the manual. The section below describes differences in the implementation and behaviour for the dialog controls.

Base Attributes

The base attributes apply to all dialog objects.

Name Comment
class  
x Positions and size depends on a raster as set by the specified reference font in the configuration file.
xleft is a synonym for x.
xright is the right distance from the control to the side of the container which surrounds it.
xauto defines the horizontal layout behavior.
  • If xauto > 0 the position of the control is defined by the x coordinate.
    Its width is defined by w.
    This is the default and behaves like the ASCII-DLG server does.
  • If xauto = 0 the position of the control is defined by the x coordinate.
    xright shall be set and defines the distance of the right side of the control to its parent.
    Its width is calculated by w = parents.w - control.xright - control.x.
    As a result, scaling the dialog programmatically the width w of the control will be scaled too.
  • If xauto < 0 the position of the control is calculated by x = parents.w - control.xright - control.w.
    xright shall be defined and sets the controls distance between the right side to its parent right side.
    w shall be defined.
    As the result the control is attached to the right side of the parent with the distance of xright.
y see x
ytop is a synonym for y
ybottom defines the distance of the controls bottom side to the bottom of its parent
yauto defines the vertical layout behavior.
  • If yauto > 0 the position of the control is defined by y.
    The height can be set with h.
    This is the default and behaves like the ASCII-DLG server does.
  • If yauto = 0 the position of the control is defined by y.
    ybottom shall be set and defines the distance from the parents bottom to the controls bottom side.
    The height is calculated by h = parents.h - control.ybottom - control.y.
    As the result the height of the control will be scaled if the height of the parent is scaled.
  • If yauto < 0 the position is calculated by y = parents.h - control.ybottom - control.h.
    ybottom and h shall be set.
    The result is that the control is pined to the parents bottom side with the distance of ybottom.
w see x
h see x
fgcolor Sets the control's foreground color. Accepts a string argument in "#rrggbb" form, where rr, gg and bb are hexadecimal values for the red, green and blue color intensities.
Example: "#0000ff", "#0000c0" and "#000080" are various tones of blue.
bgcolor Sets the control's background color. See fgcolor for details.
fgc 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 Provided for backwards compatibility. See fgc for details.
visible  
sensitive  
rule  
focus  
focusobj  
kbind not yet supported
help  
udata Can contain string data or integer data. Initially the type is integer and returns 0. If a DLG SET call changes the type the DLG GET should have a variable which has the same type as the last set operation. Otherwise you will get an 659 error or an empty sting as the result of the call.
Keyboard Accelerators A Keyboard Accelerator can be used with a StaticText, PushButton, RadioButton and CheckBox control. The .alt attribute has no meaning and is ignored. A keyboard accelerator is triggered by pressing the ALT key and the underlined character at the same time. A keyboard accelerator is marked by a preceding & sign as described in the manual.
fontface The fontface attribute sets the font. Allowed string values are Serif, SansSerif, Monospaced, Dialog or DialogInput or a platform specific font name such as Courier (which may not be present on all systems).
It is recommended to use Monospaced or DialogInput as your fonts because they have a fixed width for each character otherwise the dialog layout may be different.
The default value is DialogInput.
fontsize The fontsize is the value for the fonts point size. Allowed values are every positive integer.
The default value is 12.
It is a positive integer value with the range bigger than zero. If it is less or equal than zero it will be set to the size of the default font.
fontstyle The fontstyle attribute says which style we want to apply to the characters.
Allowed string values are plain (example), italic (example) and bold (example).
The default value is plain.
toolhelp The toolhelp attribute is used to display a short context sensitive help text.
Is a string value. If set the text is displayed. Resetting it with an empty string turns it off again.


Dialog

A Dialog is the top-level Window which contains all other Controls. The size will be set programmatically. The user can not resize it.
Name Comment
x Sets the Dialog to the x Position which is calculated from the default fonts width multiplied with the value of the x Property. If x and y are set to -1 the dialog will be centered on the screen.
y see x
title  
border Value is ignored.
f1 - f12 The function keys are working as described in the ASCII Dialog manual. The F10 key has an exception. If a code>Menubar is defined, the F10 key will activate it and does not handle it's rule.
do Is an boolean value. If it is set to True the dialog falls in a special drawing mode. In that mode the dialog is active as it would be if a DLG DO command has been occured. But it does not run synchronized with the eloqcore process and it does not report a rule to the eloqcore process. The application developer needs to poll this attribute to find out that a rule was activated by the end user. If that had happened the attributes value had been set to False and the dialog became invisible implicit. The usage of this attribute is the implementation of a progress dialog where eloqcore processes a task and shall not block in a DLG DO command and the application developer want to give the end user the abillity to cancel the task.
cr Works as described in the dialog manual.
alt Keyboard accelerators are supported, but this attribute has no meaning. Accelerators are always use the ALT key.
bgimage The bgimage sets a background image for the Dialog. The value is an URL string which points to a GIF or JPEG image on a web server.
The default value is an empty string.
resizepolicy

The resizepolicy attribute defines the behavior of a Dialog when an end user resizes it.
There are three string values allowed:

The default value is none.

The resizepolicy effects also the size of a POPUP BOX which appears after a resized Dialog. If a Dialog has a policy of scale and was resized, than the fonts of the POPUP BOX are resized too (This does not work, if the controls contain HTML text!).

The Application.dialogscaling attribute may overlay this behavior.

maximized The maximized attribute means that the dialog will be displayed as big as possible on the screen.
It is an integer value. Set it to 1 before the DLG DRAW or DLG DO statement is executed.
logoicon The logoicon attribute sets a specific icon to the title of a Dialog. This could be managed system wide with the eloquence.config.logoicon property or session specific with the application.logoicon as well. The String must be an absolute URL to the location of the icon image file which might have the format of GIF, JPEG or PNG.


Groupbox

Name Comment
title The value will be used in the context of the TabBox control for the GroupBoxs tab folder. In other cases the title will not be shown.
border If .border is set to 0 no border is painted. If the value is 1 a thin border will be drawn. If it is >= 2 a thicker border will be drawn.
The border color is specified with the fgc attribute.
icon It's a string of an URL which points to GIF or JPEG image file on a web server. It will be used only in the context of the new TabBox control where the image is the icon for the GroupBoxs tab folder.
accelerator String value with the syntax: ( alt | ctrl )* [A-Z]. It will be used only in the context of the new TabBox control.


StaticText

Name Comment
text  
textpos This is a string value which specifies the text position in the statictext.
Allowed values are center, left, and right.
The default value is left.


PushButton

Name Comment
text  
border Value is ignored.
icon This is a string value specifying the URL of a GIF or JPEG image on a web server. When set an icon is displayed in the button. If the iconpressed attribute is also defined the image is exchanged when the button is pressed.
The default value is an empty string, so no icon is set to the button.
iconpressed This is a string value specifying the URL of a GIF or JPEG image on a web server. When defined this icon is displayed when the button is pressed.
The default value is an empty string.
textpos This is a string value which specifies the text position in the button.
Allowed values are center, top,left, bottom and right.
The default value is center if no icon is present, otherwise right.
ruleoverride This is a boolean attribute which signs how pending EditText rules are handled. The default value is 1 which means that the rule of the PushButton will be executed but the focus will be left onto the EditText field. If it is set to 0 than the rule value of the EditText will be sent and the focus will be moved to the PushButton. The second state is the ASCII DLG compatibility mode which must be set explicit in your dlg files!


CheckBox

Name Comment
text  
active  
ruleoverride This is a boolean which signs the system to execute the buttons rule instead a pending EditText rule. The default is false which means that the pending EditText rule will be executed. If it is true the rule of the button will be executed instead of the pending rule. The focus and the state will change, if the user has moved to the CheckBox by mouse.


RadioButton

Name Comment
text  
active  
activebtn Returns the active RadioButton of a container.
ruleoverride This is a boolean which signs the system to execute the buttons rule instead a pending EditText rule. The default is false which means that the pending EditText rule will be executed. If it is true the rule of the button will be executed instead of the pending rule. The focus and the state will change, if the user has moved to the RadioButton by mouse.


EditText

Name Comment
sensitive The sensitive attribute defines that the EditText control is focusable or not. If it is false the control is not in the focusable controls list otherwise it is.
As a sideffect the control becomes grayed out if it is not sensitive. If you want to have a normal lookout but the user shall not be able to put in text, set the attribute to true and the editable attribute to false.
length  
content  
editable The attribute defines if the user can write text to the control. If it is false the control does not recognize any key strokes. Otherwise the user can put in text.
multiline  
border Value is ignored.
title Value is ignored.
hsb Has no effect. In multiline mode scrollbars are visible if needed. A DLG GET operation returns always 0.
vsb see hsb
maxchars  
maxlines Is only implemented in multiline mode.
vheight  
vwidth  
cx  
cy  
line  
file Is not supported.
clear  
add  
topitem Is not supported.
writefile Is not supported.
ins  
delln  
ispassword This is a boolean value which allows the user to implement a password field. If it is 1 or true it shows asteriks instead of the typed characters. If it is 0 or false it works as a normal field.
Please note: This works only in single line mode.


ListBox

Name Comment
length  
content  
multiline Has no effect.
border Can be set and get. If this integer value is greater than 0 each text line is idented by a leading space.
title Value is ignored.
hsb Has no effect. The control gets a horizontal scrollbar if w is less than the number of characters in the longest line in the ListBox. A DLG GET operation returns always 0.
vsb Has no effect. A ListBox gets a vertical scrollbar if the number of lines in the ListBox exceeds h. A DLG GET operation returns always 0.
vheight  
vwidth  
cy  
line  
activeline  
file Is not yet supported.
clear  
add  
topitem Can be set and makes the line visible. If topitem + h is less than the number of visible lines in the ListBox, it becomes the first line. Otherwise we make it sure that the line is visible but it can not be set to the top of the ListBox.
ins  
delln  
singleclick It is an integer value. When it is set to 1 a single mouse click activates the rule. If it is set to 0 (which is the default) for activation a double mouse click is needed.
Please note: If the singleclick mode is active you can not click in the box and navigate through the entries with keys. If you'd stepped into the box using keys, key navigation is possible.
Setting the value to 2 the rule will be activated by using a double click and/or using the up or down key.
Setting the value to 3 the rule will be activated by a single click and/or using the up or down key.

Please note: In the current implementation empty lines will be deleted from the content. This might result in an other length of number of lines as you might expected. Example:

1000 DIM Lines$(10)[64]
1100 !
1200 Lines$(1)  = "Line 1"
1300 Lines$(2)  = "Line 2"
1400 Lines$(3)  = "Line 3"
1500 Lines$(4)  = "Line 4"
1600 Lines$(5)  = "Line 5"
1700 Lines$(6)  = "Line 6"
1800 Lines$(7)  = "Line 7"
1900 Lines$(8)  = "Line 8"
2000 Lines$(9)  = "Line 9"
2100 Lines$(10) = "Line 10"

has 10 lines but

1000 DIM Lines$(10)[64]
1100 !
1200 Lines$(1)  = "Line 1"
1300 Lines$(2)  = "Line 2"
1400 Lines$(3)  = "Line 3"
1500 Lines$(4)  = ""
1600 Lines$(5)  = "Line 5"
1700 Lines$(6)  = "Line 6"
1800 Lines$(7)  = ""
1900 Lines$(8)  = "Line 8"
2000 Lines$(9)  = "Line 9"
2100 Lines$(10) = "Line 10"

has 8 lines, because Lines$(4) and Lines$(7) will be deleted by the System.

To resolve that problem please use

1000 DIM Lines$(10)[64]
1100 !
1200 Lines$(1)  = "Line 1"
1300 Lines$(2)  = "Line 2"
1400 Lines$(3)  = "Line 3"
1500 Lines$(4)  = " "
1600 Lines$(5)  = "Line 5"
1700 Lines$(6)  = "Line 6"
1800 Lines$(7)  = " "
1900 Lines$(8)  = "Line 8"
2000 Lines$(9)  = "Line 9"
2100 Lines$(10) = "Line 10"


HelpText

Please refer to the description of the Help Sub System configuration.


PopText Control

The PopText control implements a selectable list which shows a single line.

Known Problems:
The Java Swing GUI Library has a few problems with the event handling model for this component. This causes keyboard navigation in a PopText control to execute a rule whenever the selection changes. If you select the control and press the up or down key it results in the rule execution everytime. We are looking for a solution of this problem.
An other bug is that the focusing does not work correctly for this control and effects the direct successor and predecessor. In the case that the rule is not zero it is possible that the focus will be set to the second successor and not to the first.
As a result it is a good idea not using this control with a rule != 0!

Attributes
Name Type Default value GET SET Description
activeline Integer 0 X X Sets the line which is visible.
In a get command it returns the line which is the active (and visible) line.
Is a 1 based value.
content String - X X Sets the content of the control. Each line is separated by a newline character.
The getter returns the lines separated by a new line.
length Integer - X - Gets the length of the content.
vheight Integer - X - Gets the number of lines.
vwidth Integer - X - Gets the width of the longest line in the PopText control.
topitem Integer 0 X X Sets the line which is visible (overlays activeline).
Gets the number of the visible line (in sync with cy).
Is a 0 based value.
cy Integer 0 X X Sets the line which is visible (syncs topitem and so overlays activeline).
Gets the number of the visible line.
Is a 0 based value.
line String - X X Sets the line with the given value. If the line exists the line will be replaced. If there is no given index the line will be inserted.
Gets the content of the line with the given index. If no index is given the actual line (the cy value) will be returned.
read String - - - Is not supported.
writefile String - - - Is not supported
clear - - - X Clears the content of the PopText.
add String - - X Adds the content to the end of the list. If the string contains more than one line, where each line is separated by a newline character, it appends all lines to the end of the list.
ins String - - X Inserts a line in front of the actual line which is signed by the cy attribute.
delln Integer - - X Deletes count number of lines beginning by the line where cy points to.


The POPUP BOX is a Message Box which shows a couple of lines and stops the execution thread of the program.

The syntax is as follows:

1000 ...
1100 Rc=2
1200 POPUP BOX X,Y,"[Title][Couple|Of|Lines][First|Second]",Rc
1300 DISP Rc
1400 ..

The statment shows a Message Box at the coordinates of X and Y. If the are both set to -1, the Box will be centered onto the screen or if a Dialog was active before, centered to this Dialog.
The String argument contains three parts, separated by squared brackets. The first contains the title of the POPUP BOX. The second part gives the control the lines of text which shall be displayed. They are separated with a |. The third part contains the texts for the buttons. The maximum of five buttons are allowed. The first character of a button is handled as an accelerator key.
The optional variable at the end of the statement has two functions. If it is not zero and less the maximum number of buttons, it defines which button has the focus when the POPUP BOX appears. After the activation of a button, it contains the number of which was used. The activation of a button could be done by clicking on it, walking through them with the TAB key and pressing ENTER or SPACE. At least you can press the accelerator key to activate it directly.


Following controls were added to the system.

Toolbar

A Dialog may have one ToolBar. A ToolBar makes it possible to show symbolic shortcuts for application functions. By default the ToolBar appears below the MenuBar (s.b.) but may also be located to the left, right or bottom side of the Dialog.

A ToolBar is a container (like a GroupBox) which can contain child controls of any type like PushButton, CheckBox or RadioButton other than GroupBox. The standard position attributes (x, y) of the ToolBar elements are ignored. The size attributes (w, h) are recognized.
The ToolBar container uses an automatic layout.

Attributes
Name Type Default value GET SET Description
position A string of: top|right|bottom|left. top X X Determines where the ToolBar appears in the Dialog.

Example

dialog main {

  Toolbar TheDialogShortCuts {
    .position = "bottom"

    Pushbutton save {
      ...
    }

    statictext hello {
      ...
    }

    edittext bingo {
      ...
    }
  }
}

Separator

The Separator control is a spaceholder and may be specially used to separate controls in the Toolbar
It has the attributes for background colors and the xleft, x, xright, ytop, y, ybottom, w, h, xauto, yauto attributes for positioning.

Menubar

A Dialog may have one MenuBar. A MenuBar appears at the top of a Dialog. It is a container which organizes the user Menus.

It has no attributes.

Example:

dialog main {

  menubar TheBar {

    menu program {
      .title = "&Program"

      menuitem open {
        .title = "Open &File"
        .accelerator = "ctrl F"
        .rule = 1000
        .icon = "http://anywhere.on-the.net/image.gif"
      }

      menuitem save {
        .title = "&Save File"
        .accelerator = "alt S"
        .rule = 1001
        .type = "checkbox"
      }
      
      menuitem exit {
        .title = "&Exit"
        .accelerator = "alt X"
        .rule = 1003
      }
    }

    menu edit {
      .title = "&Edit"
      
      menuitem copy {
        .title = "&Copy"
      }

      menuitem paste {
        .title = "&Paste"
      }

      menu insert {
        .title = "Insert"

        menuitem file {
          .title = "&File"
        }

        menuitem graphic {
          .title = "&graphic"
          .accelerator = "alt G"
          .rule = 2000
        }
      }
    }

    windowmenu wm {
      # the display of all active dialogs.
    }

    menu help {
      .title = "&Help"

      menuitem index {
        .title ="&Index"
      }
 
      menuitem sep1 {
        .type = "separator"
      }

      menuitem about {
        .title = "&About"
      }
    }
  }
}

Menu

A Menu is a child of the MenuBar. It provides functions to the user with MenuItems or in Sub-Menus. Its function is the grouping of these controls.
A Menu may have any pathname.

Attributes
Name Type Default value GET SET Description
title String Empty string X X This gives the Menu its title. An & signs the letter which will be used for the mnemonic keyboard shortcut. The ALT+<Mnemonic-Key> activates the Menu.

There is a special Menu available which has the control class WindowMenu and may have any name. It displays the active dialogs of all sessions in JDLG. You can place it anywhere in the MenuBar. If the user clicks on an entry in the Menu the selected Dialog comes to the front of all other windows.

Attributes
Name Type Default value GET SET Description
title String Window X X This gives the WindowMenu its title. The default is the title Window with the Alt+W accelerator key.

MenuItem

A MenuItem is a child of a Menu. It offers the user to activate a function via a mouse click or a keyboard combination. A MenuItem has a type which determines its appearance and behavior. The default item type offers a label. The checkbox type offers a checkbox with a label. The separator type show a separator line and the radiobutton type offers a radiobutton with a label. If there are more than one radiobutton in the Menu it acts as a controler for them like a Dialog or GroupBox do for normal RadioButton controls.

Attributes
Name Type Default value GET SET Description
title String Empty string X X Is the MenuItems description. An & signs the letter which will be used for the mnemonic keyboard shortcut. An item can be activated via a mnemonic key stroke if the Menu which contains the item is visible.
accelerator String value with the syntax: ( alt | ctrl )* [A-Z]. empty X X Defines the accelerator which activates the MenuItemwith a keyboard shortcut if its parent Menu is not visible. An accelerator can be defined only once in a Dialog!
rule Any positive integer 0 X X Is the rule value which will be sent back of a DLG DO command.
type Predefined string value: checkbox | item | radiobutton | separator. item X - Defines the type of an entry. It must be set in the dlg file and cannot be changed later.
active Boolean false X X In the case that the MenuItem is of the type radiobutton or checkbox it sets or gets the state of the control. If it is of type item a set does nothing and a get always returns False
activebtn String empty X - In the case that the MenuItem is of the type radiobutton it returns the path to the active radiobutton MenuItem. In the other cases it always returns an empty string for the path.
icon String of an URL which points to a GIF or JPEG image on a web server. empty X X This is an icon for an MenuItem entry. If it is set it will be displayed in front of the MenuItem label.
textpos Predefined string value: top | right | bottom | left | center. If no icon is available it is center otherwise right. X X Sets the position of the text.


Statusbar

A Dialog may have one StatusBar. It is a special container which appears at the bottom of a Dialog. The children of this container may have any type except Dialog, or any Menu-Controls type. The layout of the children inside the container works as in the GroupBox control by setting their x and y attributes.
Please note: This has been changed after Build 1.1.0.0.

Attributes
Name Type Default value GET SET Description
x Integer 0 X X This attribute has no meaning.
y Integer 0 X X see x.
w Integer width of the Dialog X - The StatusBar has the width of the Dialog.
h Integer 1 X X Defines the height of the StatusBar. The default is 1.

Example:

dialog main {
  .x = -1
  .y = -1
  .w = 50
  .h = 20

  statusbar TheStatusLine {
    .h = 1

    statictext text {
      .x = 0
      .y = 0

      .text = "Status:"
    }

    edittext output {
      .x = 8
      .y = 0

      .content = "Still calculating..."
      .editable = 0
    }

    edittext postoutput {
      .x = 30 
      .y = 0

      .content  = "An output String"
      .editable = 0
    }
  }

  statictext date {
    .x = 0
    .y = 0
    .h = 1
    .w = 10

    .text = "1999-12-31"
  }
}

ComboBox Control

The ComboBox control presents the user a single line text field which is connected to a popup list of choices. The user is allowed to select an entry of the choice list with the mouse or navigation keys. The selected entry will set to the text field as its content. If the user had used the mouse or finished the selection with the ESC key the focus will be set back to the text field which makes it possible to edit the text. If the selection was finished by pressing ENTER the focus will be set to the next control which activates the normal rule handling.

Please note, this type of control would normaly named PopText. For compatibility reasons we'd created a new control and left the original PopText untouched.
Attributes
Name Type Default value GET SET Description
content String - X X Is the text of the input line.
items Strings separated by CHR$(10). - X X Creates a choice list from the string. Each line is separated by a CHR$(10) character.
line[i] String - X X Sets or modifies a line. The index is 1-based. Index 0 on DLG GET returns the text of the input line, on DLG SET appends the line to the list.
add String - - X Adds the given single line string to the end of the choice list.
editable Integer 1 X X A nonzero integer value specifies that the input line is editable.
clear String - - X Clears the choice list.


HTML View Control

The intention of this control is the presentation of unstructured information in textual form to the user. The control can be used to read a HTML 3.2 page and display it to the user. It is not a complete web browser and can not execute any javascript, other scripting language code or shall be used to implement HTML Forms.

It can be used in two ways:

  1. Setting the page via a given URL, or
  2. Setting the page via it's content or add attributes.

In both cases it is assumed that the content contains any valid HTML 3.2 source code or plain text.

A HTML page may contain hyperlinks. A web browser can handle links with a lot of different schemas (protocols) like http, ftp, gopher or others. Our control is intented to be used with the http and/or eloq protocol. The http protocol works as expected: The activation of such type of link starts a download of the next HTML page to which it points to. The eloq protocol interacts with the JDLG server and activates a rule. If the dialog is in a DLG DO command it returns from its execution. The value of the returned rule is defined by the rule attribute of the control or the link. The eloq schema links have the following syntax:

eloqschema      :=   "eloq:" | "eloq:" optRule optLinkFragment
optRule         :=   <empty>
                   | <Integer Value>
optLinkFragment :=   <empty>
                   | '/' <AnyString>

Default Rule Activation

The activation of such link offers the programmer the opportunity to define fine granulated behaviour of his application. In the simplest form it activates the standard rule handling of the control. That means that if the controls rule value is not equal to zero it returns from the DLG DO with the expected behaviour. If it is set to -1 the help subsystem will be activated. An example of such a link is:

<a href="eloq:">Default rule handling</a> activation.

Specialized Rule Activation

The optRule part of the href attribute syntax defines an other type of rule activation. If the link contains an integer number, than the rule will be activated with that value. So the DO command returns with the path of the HTMLView control and the rule of the link.

Example:


<!-- In the HTML content -->

<a href="eloq:1234">A specialized</a> rule activation.


! In the Eloquence basic file

1000 DLG DO "htmlviewerdialog",Rule,Path$;Err_code
1100 PRINT "Rule="&VAL$(Rule)&" Path="&Path$"


The program prints out
Rule=1234 Path=htmlviewerdialog.hview
after the link activation if the dialog file contains the definitions
dialog htmlviewerdialog {
...

  htmlview hview {

    .rule = 2000
  }
...
}

the rule of the link overrides the rule of the control.

The Fragment of the Schema

The last part of our schema syntax is the optLinkFragment. It is a free string which you are allowed to use for everything you like.

For example: You have generated a list from a query result and presented it in a HTML table. Now you want to offer the user the ability to select a specific entry and show him a more detailed presentation of it. For this task you need the primary key of the entry but you do not want to remember it in your program. Instead you would preferre to save it in the presentation and resolve it from the system after, which entry had been activated.
For these situations we had implemented the link fragment.
The steps to realize it programmatically are:

  1. Generate the list with the key of the entry as a link fragment
  2. Ask JDLG after the DLG DO command returned which link had been activated.
Example:
      ! DO a DBFIND
      ! DO a DBGET
      !
10000 DLG SET "dlg.hview.add","<li><a href="eloq:/theKeyOfTheGetOp">"
                              &"The data presentation</a></li>" 
      !
20000 DLG DO "dlg",Rule
      !
21000 DLG GET "dlg.hview.lastlinkfragment",Llf$
      !
22000 PRINT Llf$
The program will print out
theKeyOfTheGetOp
which you can use to resolve the data again and create the detailed presentation.

The value of the link fragment depends on two parameters: The first is the value of HTML link definition. The second is the time when the dialog had been synchronized. If the dialog enters a DLG DO command the value of the lastlinkfragment will be reset to an empty string. After the command has been left, it might changed to another value if the user had been activated a link what you can find out with a specific rule.

The control has the default attributes as described in the Base Attributes section. The following table describes the specific attributes for the HTML View control.

Attributes
Name Type Default value GET SET Description
content String empty X X This attribute contains the content of the text which is presented by the control. If the getter is used, it returns the string presentation of the content. If it is set, the viewer presents a new page with the given content. It is assumed that the MIME type of the content is text/html.
mimetype String text/html X X This attribute says which mime type will be used if the content attribute is set. Allowed values are
  • text/plain
  • text/html
add String empty - X This attribute appends the given text to the content.
clear - empty - X Clears the content of the control.
url String empty X X This attribute is a string for an URL which points to a HTML document instance. If the getter is used, it returns the presentation of the URL. If it is set, a new page will be shown in the viewer with the content if the HTML file to which the URL points to. The web server should send text/html as the MIME type for the content of that file.
lastlinkfragment String empty X - This attribute returns the fragment of the last activated link which has the eloq schema in the URI description. It will be reset during the entrance of a DLG DO command and might be set through an activation of a link in the displayed HTML page.

Notes:

If you set a HTML page to the control which contains links to web servers which are not reachable JDLG hangs until it gets a time out. Because a user might think that JDLG had been crashed, it is not a good idea to give the user success setting links manually. It is safer to use verified links in your programs than allowing a manual user input.

An other problem is that the control might be go "out of order" if the HTML text is not conformant to the HTML 3.2 specification. To make it clear that you are using correct HTML code please use a tool like Tidy for varification or other public verification sites.


Tabbox

A TabBox is a container with one or more tab folder. A user can switch between tab panes by selecting the title of a tab folder.
The accepted type of TabBox children is GroupBox. The values of the GroupBoxs title and icon attributes will be set to the tab folders title and icon.

Attributes
Name Type Default value Getter Setter Description
rule Integer. -1 X X If it is set than a DLG DO command will return from its execution if the user selects an other folder then the one which is on top.
selectedtab String. 1 X X Setting this attribute brings the tab folder with the given path fragment to the front of the TabBox. Getting this value says which tab folder is on top of the other tab folders.
tabs Integer. 0 X - Getting this value says how many tab folders are available.
tabplacement Predefined string value: top | right | bottom | left. top X X This attributes defines the place where the titles of the tab folders are placed.
ruleoverride Integer. 0 X X When this attribute is set to 0 a pending EditText rule will be executed first and the pending rule of a tab folder change will be executed on the next DLG DO. If the focus is explicitly set before the second DLG DO command the pending rule will not be executed.
If the value is set to 1 the rule of the TabBox will be executed and a potential rule of an EditText field will be discarded.
scrollable Integer. 0 X X This attribute allows enabling the horizontal scrolling of the TabBox headers if it is set to 1. 0 disables scrolling and is the default value. Please note that this is just available if JDLG runs under a Java Virtual Machine with Version of 1.4 or above!

Rule handling

The rule handling in the TabBox makes it possible to find out how the end user interacted with your application. There are many situations possible where JDLG returns one or two rules of the TabBox, the inner GroupBoxes or an EditText field which is located in the TabBox. The following code snippets are contained in the TabBox directory of the example directory.

The simplest Form

In the simplest form your application dailog has a TabBox which has set a rule to it. The second condition is that the GroupBoxes do not have a rule set and at least all EditText fields do not have a rule either. A dialog looks like:
dialog simple {
  .x = -1
  .y = -1
  .w = 80
  .h = 24

  .title = "Simple"

  tabbox tb {
    .x = 1
    .y = 1
    .w = 78
    .h = 19

    .rule = 1000

    groupbox gr1 {
      .title = "First"
      
      edittext et1 {
        .x = 1
        .y = 1
        .w = 20
        .h = 1
      }
    }

    simple.tb.gr1 gr2 {
       .title = "Second"
    }
  }

  statictext info {
    .x = 5
    .y = 20
    .h = 1
  }

  pushbutton exit {
    .x    = 5
    .y    = 22
    .h    = 1
    .text = "E&xit"
    .rule = 5000
  }
}

In such a dialog you can obtain that the user has changed the tab order. If he or she clicks on the folder Second JDLG return the rule 1000. Now you know that a change appeared but you do not know which folder is on top. Finding out that you can use the operation

DLG GET "simple.tb.selectedtab",Path$
which returns the path fragment of the on top folder. With this information and your dialog structur in your mind. You can react on the state of the dialog as you need for your application.

Using GroupBox rules

Sometimes it is not usefull using the DLG GET "dialog.tb.selectedtab"operation to find out which folder is on top. Preventing this you can use the rule attribute of the GroupBoxes which are are the top level of each folder.
dialog groupboxusage {
  .x = -1
  .y = -1
  .w = 80
  .h = 24

  .title = "With GroupBoxes"

  tabbox tb {
    .x = 1
    .y = 1
    .w = 78
    .h = 19

    .rule = 1000

    groupbox gr1 {
      .title = "First"

      .rule = 10000
      
      edittext et1 {
        .x = 1
        .y = 1
        .w = 20
        .h = 1
      }
    }

    groupboxusage.tb.gr1 gr2 {
       .title = "Second"

       .rule = 0
    }

    groupboxusage.tb.gr1 gr3 {
       .title = "Third"

       .rule = 30000
    }
  }

  statictext info {
    .x = 5
    .y = 20
    .w = 40
    .h = 1
  }

  pushbutton exit {
    .x    = 5
    .y    = 22
    .h    = 1
    .text = "E&xit"
    .rule = 5000
  }
}

How does the dialog behave? If the First folder is on top and the user clicks on the Second folder JDLG returns the rule of the TabBox. JDLG behaves in that manner because the GroupBox does not have a rule set. Clicking on the other folders JDLG returns the rule values of that one which comes on to. In general words: If a GroupBox has a rule on it comes on top, JDLG returns that rule. If the rule of the GroupBox is zero the rule of the TabBox will be returned.

When an EditText has a rule

Both examples above do not have rules in the EditText fields set. Often you want that an EditText field has a rule e.g. for checking its value if the user left that field. A dialog looks like the following
dialog easyedit {
  .x = -1
  .y = -1
  .w = 80
  .h = 24

  .title = "EditText rules"

  tabbox tb {
    .x = 1
    .y = 1
    .w = 78
    .h = 19

    .rule = 1000

    groupbox gr1 {
      .title = "First"
      
      edittext et1 {
        .x = 1
        .y = 1
        .w = 20
        .h = 1
        .rule = 3000
      }
    }

    easyedit.tb.gr1 gr2 {
       .title = "Second"
    }
  }

  statictext info1 {
    .x = 5
    .y = 20
    .h = 1
  }

  statictext info2 {
    .x = 5
    .y = 21
    .h = 1
  }

  pushbutton exit {
    .x    = 5
    .y    = 22
    .h    = 1
    .text = "E&xit"
    .rule = 5000
  }
}

If you change form one folder to another when the focus set on a folder, the behavior is as shown in the Simple dialog example. If you set the focus into the EditText field and change the folder order now JDLG returns first the EditText rule. Now the application goes into a second DLG DO which returns immidiately with the rule of the TabBox. With this behavior you will get the ability to check the EditText and you know that the user changed the folder order. There is an exception of this order! When you are setting the focus between the first and the second DLG DO the pending TabBox rule will not be reported. In this situation the system expects that you are no longer interested in the order of the TabBox or you will set it implicitly with the focus which is possible and is described below.

GroupBox and EditText rules

If EditText fields have rules makes no difference finding out which folder is on top easily. In short words, it works as discribed in the GroupBox part above. If a GroupBox has a rule the pending control of the second DLG DO is no longer the TabBox. Instead the GroupBox takes the place and its rule will be returned. When you set the focus before the second DLG DO it will be thrown away as the system would do with a pending TabBox.

Ruleoverride

The last interesting thing in rules reporting in the TabBox context is when the ruleoverride is active. The usage of the feature is when you want to know that an EditText field has lost the focus to a control inside of the same folder and you do not need to know that the focus was lost to the TabBox.
dialog override {
  .x = -1
  .y = -1
  .w = 80
  .h = 24

  .title = "EditText TabBox ruleoverride"

  tabbox tb {
    .x = 1
    .y = 1
    .w = 78
    .h = 19

    .rule = 1000
    .ruleoverride = 1

    groupbox gr1 {
      .title = "First"
      
      edittext et1 {
        .x = 1
        .y = 1
        .w = 20
        .h = 1
        .rule = 3000
        .content = "has rule"
      }

      override.tb.gr1.et1 et2 {
        .y = 2
        .rule = 0
        .content = "has no rule"
      }
    }

    override.tb.gr1 gr2 {
       .title = "Second"
    }
  }

  statictext info1 {
    .x = 5
    .y = 20
    .h = 1
  }

  statictext info2 {
    .x = 5
    .y = 21
    .h = 1
  }

  pushbutton exit {
    .x    = 5
    .y    = 23
    .h    = 1
    .text = "E&xit"
    .rule = 5000
  }
}
The dialog behaves as follows: When the focus sits on the First folder and the user clicks on the Second folder the TabBox rule will be reported.

If the focus sits in the first EditText field of the first folder and the user presses the TAB key or clicks into the second EditText field, the rule of the EditText field will be reported in a DLG DO operation.

If the focus sit in th efirst EditText field of the first folder and the user clicks onto the second folder, JDLG report the rule of the TabBox and ignores the EditText rule because the ruleoverride attribute is set to 1
As GroupBoxes overlay the TabBox rules in other configurations they are overlay them here as well. So if the second folder would have a rule, the EditText has the focus and the user clicks on the second folder that folders rule would be reported by the system.

Focus influence to the tab folder order

A second thing to known when using TabBoxes is how a focus set operation on a control inside a TabBox works.
For example, if the First tab folder lays on top and the programmer sets the focus to the EditText control in the Second tab folder, the Second tab folder comes autmatically to the front. This behavior is recusivly defined which means that it works fine for nested TabBoxes too. This behavior makes sure for the end user where the focus of the system is located and where he or she can continue the work.

Image

The Image control gives an application the ability to display images in a dialog. The source of an image is a file loaded from a web server or the local system (client) as specified by the given URL. The image is displayed centered and clipped in the image control.

Name Comment
w If the image is bigger then the given value, it will be clipped at the right side.
h If the image is bigger then the given value, it will be clipped at the bottom.
url The URL of the image. GIF and JPEG format is supported. An image could be loaded from a web server (eg. http://www.yoursite.com/images/test.gif) or from the local file system (eg. file:/C:/images/test.gif).
sw Is an integer value with a default of 0. If the value is 0 the image will be centered or if it is too big for it it will be clipped. If it is -1 it will be set to the left and scaled to the right side. If you give it any other positiv value it will be set to the left and scaled to your given pixel size. Is the value -2 the image will be scaled in is aspect ratio and set to the center.
sh Is an integer value with a default of 0. If the value is 0 the image will be centered or if it is too big for it it will be clipped. If it is -1 it will be set to the top and scaled to the bottom side. If you give it any other positiv value it will be set to the top and scaled to your given pixel size. Is the value -2 the image will be scaled in is aspect ratio and set to the center.


Application object

The Application object is a non visible object named application. It describes and defines application specific properties in the Dialog Server for a session. Please set the properties after you have set the driver and before you load any DLG File. Otherwise the properties will not effect any control!

Attributes
Name Type Default value Getter Setter Description
ipaddress String - X - Returns the local ip address which is used in this session's DLG network connection.
dnsname String - X - Returns the local fully qualified host name which is used in this session's DLG network connection.
baseurl String empty string X X Sets the base which is used with a relative URL. This makes it possible to specify relative URLs for DLG files and images after setting baseURL initially in the application.
helpbaseurl String empty string X X Sets the base which is used with a relative URL. This makes it possible to specify relative URLs for the help function.
browser String empty string - X Sends a request to the Browser on the Machine where JDLG is running. It can be an absolute or relative URL.
activeontop Integer 1 X X If this attribute is true, the default, the activation of a Dialog which is not in the DLG DO command brings the Dialog to the front which is in the DO state. So the system ensures that the user can see the active Dialog of the session.
dialogscaling Integer 1 X X This attributes defines how a dialog behaves if it is becomes visible.

If the session has a scalable dialog running and the user resizes it the session calculates a rescaling factor. It is based on the size of the default font and the size of the font which the users dialog has.

Now a user finishes the actual dialog and the application shows another one with DLG DO or DLG DRAW. If the dialogscaling attribute is set to 1 the upcoming dialog will rescale itself using the factor which the session has.
If the dialogscaling is set to 0 the upcoming dialog would not be scaled.

Please note that this attribute do not affect if a dialog is scalable by the user or not. This is done with the Dialog.resizepolicy attribute itself.

History note: This behavior has been changed from 1.1.6.0 to 1.1.7.0!

referencepoint Integer 0 X X The referencpoint attribute activates or deactivates the new feature which reminds the relative position of dialogs on the screen.

Per default the value is set to 0 which means that JDLG does not affect the positioning of dialogs as it did before 1.1.7.0.

When it is set to 1 it manipulates the positioning of dialogs in the following manner: The first upcomming dialog after the activation sets a virtual reference point on the screen. This will be the base point for the later dialog positioning operations. When the user now moves an active dialog around on the screen, the reference point will be updated when the DLG DO command ends. The next upcomming dialog will be placed relativly to the new virtual base point now.

The advantage of the concept is, that active dialogs will appear near by each other. This makes it easier for an end user to determine which dialogs of a session belong together.

The rules of initialization: If a dialog has the centering coordinates for x, y of (-1, -1), the dialog will be centered on the screen and the Referencepoint is set to the upper left corner.
If a dialog has other coordinates, it is set to them on the screen relativly to the upper left corner. The Referencepoint is set to the upper left corner of the window.

Positioning rules: After the initialization all dialogs which becomes visible are positioned relatively to the Referencepoint with their coordinates.
Dialogs with the centering rule are set to the Referencepoint with their upper left corner.
Visible dialogs will be left untouched.
POPUP BOXes are handled in the same manner.

Please note: This feature is experimental and your feedback is welcome to find out if this is an appropriate implementation. It also may change in future releases!

logoicon String URL to the default system icon X X This property defines a session specific icon for the dialog title bar. When a dialog is instanciated it becomes this icon as the default icon. You can overlay this by setting the dialog.logoicon manually.

The following example defines the baseURL:

...
DLG SET ".driver", "yourhost"
...
DLG SET "Application.baseURL","http://www.hp-eloquence.com/lab"
...
DLG LOAD "YourFile.DLG"
...

System object

The System object is a non visible object named system. It describes what kind of Dialog Server you use and how its environment looks like. All values are specific to the driver. With Eloquence B.07.00 other drivers are expected to support the system object as well.

The following example lines return the driver type and version:

DLG GET "System.driver",D_type$
DLG GET "System.version",D_version$
PRINT "Driver type is "&D_type$&" version "&D_version$

System object - Attributes
Name Value Type Description Available in
driver String This attribute defines which dialog implementation is in use.
  • DLG is for the ASCII-Dialog implementation
  • IDM for the ISA Dialog Manager based dialog server
  • JDLG for the Java(TM) based dialog server
  • and WEB for the Web based dialog server implementation.
JDLG
version String This attribute returns the version number of the dialog server. (ex. B.07.00.p3) JDLG
jdlgversion String This attribute returns the version number of the Java(TM) dialog server. (ex. 1.1.7.0) JDLG
ipaddress String deprecated, use Application.ipaddress instead JDLG
dnsname String deprecated, use Application.dnsname instead JDLG
osname String This attribute returns which operating system the driver is running on. (ex. Windows) JDLG
osarch String This attribute returns the hardware architecture (ex. i386). JDLG
osversion String This attribute returns the version of the operating system (ex. 4.0). JDLG
username String This attribute returns who started the system (ex. Administrator). JDLG
userdir String This attribute returns the users home directory (ex. C:\Windows\Profiles\default). JDLG
workingdir String This attribute returns in which directory the system was started (ex. C:\Temp). JDLG
screenresolution Integer This attribute returns which screen resolution - in dots-per-inch - is in use (ex. 75). JDLG
screenwidth Integer This attribute returns how many pixel we have in X direction (1024). JDLG
screenheight Integer This attribute returns how many pixel we have in Y direction (ex. 768). JDLG
helpbaseurl String This attribute returns the configured URL for the Help Sub System. JDLG
baseurl String This attribute returns the configured URL for resolving relative paths of used resources in the dlg files. JDLG
javaversion String This attribute returns which version the Java Virtual Machine has. JDLG
javavendor String This attribute returns who is the Java Virtual Machines vendor. JDLG
javahome String This attribute returns where the Java Runtime System is installed. JDLG
alwaysontop Integer The attribue defines, that the last Dialog or POPUP BOX are on top, so that the user can not hide the window.
1 activates the function. 0 deactivates it.
If two or more sessions compete which Dialog is the on top one, the last DLG DO or POPUP BOX command wins.
JDLG


From the release 1.1.3.0 of JDLG on, there is a new capability to access a control by it's path. Normally the programmer needs to formulate the path to it and it's attribute absolutely like

1700 DLG SET "adialog.anedittext.content", "The content"

This has the disadvantage if you're changing the hierarchy of the Dialog, e.g. inserting a container to organize your layout, you need to change paths in your programs too.

To avoid the described problem, an asterisk * is allowed in the path know like

1700 DLG SET "adialog.*.anedittext.content","The content"
1800 ! Or
1900 DLG SET "adialog.acontainer.*.anedittext.content","The content"

If you use it in a set operation JDLG searches for all EditText Field descendends of the Dialog with the name of anedittext and sets their content attribute to the given value.
If you access a controls attribute in a get operation JDLG will return the value of the first recognized control with the given name.

So a path might have a structure like

path.to.a.container.*.accessed_control.attribute

Where the part before the asterisk points to a control which has a container type, the second last part of the path is a name of the control you want to access and the last part says which attribute shall be set.


© Copyright 2002-2005 Marxmeier Software AG. All rights reserved.
Revision: $Date: 2005/11/11 14:29:23 $