.
Eloquence JDLG contact contact

Documentation / Eloquence JDLG / Object and attribute reference

JDLG object and attribute reference

 
.
  Document revision: 2017-08-29
Refers to JDLG version: 1.7.6


Contents


Object position and size are specified in Dialog raster units or pixel units, depending on the posraster and sizeraster attribute values. The object position is relative to the parent container object.

By default, Dialog raster units are used (i.e., both posraster and sizeraster are nonzero).

Note: Using the posraster and sizeraster attributes to specify pixel units requires JDLG version 1.7.0 or newer.

The Dialog raster is defined by the Dialog font. If not specified, a 12-point DialogInput font is used, unless the eloquence.config.defaultfont.name and .size properties are configured otherwise. The resulting raster size is adjusted by the value of the Application.scalefactor attribute.

As a consequence, the object size is scaled according to the appearance of the Dialog font if it is specified in Dialog raster units. On the other hand, using pixel units allow for a more flexible Dialog layout but might cause an object size to no longer agree to its font size.

Horizontal and vertical layout modes may be specified using the xauto and yauto attributes, allowing to define if the object origin is left/top or right/bottom and if the object size is dynamically adjusted based on the size of the parent container object. If the Dialog resizepolicy is set to "layout", object position and/or object size are dynamically adjusted whenever the Dialog is resized.

x : integer, get/set
Same as xleft (see below).
xleft : integer, get/set
Left object position.
Used with xauto=1 and xauto=0 layout modes (see below).
xright : integer, get/set
Right object position.
Used with xauto=0 and xauto=-1 layout modes (see below).
w : integer, get/set
Object width.
Used with xauto=1 and xauto=-1 layout modes (see below).
xauto : integer, get/set
Horizontal layout mode:
xauto = 1
(default)
  xleft defines left object position,
w defines object width.
xauto = 0  xleft defines left object position,
xright defines right object position
(object width is dynamically adjusted).
xauto = -1  xright defines right object position,
w defines object width
(left object position is dynamically adjusted).
y : integer, get/set
Same as ytop (see below).
ytop : integer, get/set
Top object position.
Used with yauto=1 and yauto=0 layout modes (see below).
ybottom : integer, get/set
Bottom object position.
Used with yauto=0 and yauto=-1 layout modes (see below).
h : integer, get/set
Object height.
Used with yauto=1 and yauto=-1 layout modes (see below).
yauto : integer, get/set
Vertical layout mode:
yauto = 1
(default)
  ytop defines top object position,
h defines object height.
yauto = 0  ytop defines top object position,
ybottom defines bottom object position
(object height is dynamically adjusted).
yauto = -1  ybottom defines bottom object position,
h defines object height
(top object position is dynamically adjusted).
posraster : integer, get/set
This specifies how JDLG interprets the position attributes x, xleft, xright, y, ytop, ybottom of this object.

Nonzero (default): Position attributes are specified in Dialog raster units.

Zero: Position attributes are specified in pixel units.

Note: Requires JDLG version 1.7.0 or newer.

sizeraster : integer, get/set
This specifies how JDLG interprets the size attributes w, h of this object.

Nonzero (default): Size attributes are specified in Dialog raster units.

Zero: Size attributes are specified in pixel units.

Note: Requires JDLG version 1.7.0 or newer.

raster : integer, get/set
Used to set both the posraster and sizeraster attributes to the same value.

On DLG GET, 1 is returned if both posraster and sizeraster are set to a nonzero value, else 0 is returned.

Note: Requires JDLG version 1.7.0 or newer.


The attributes listed below are common for all object classes.

bgc : integer, get/set (also: string, set)
No function (provided for ASCII DLG backward compatibility).
If used with string argument in DLG SET: Same as bgcolor (see below).
bgcolor : string, get/set
Background color in hexadecimal #RRGGBB notation.

For example:
"#000000" black
"#FFFFFF" white
"#8b0000" dark red
"#00ff00" green
"#0000CD" medium blue
"#b03060" maroon
"#A020F0" purple
"#FFFF00" yellow
"#ffd700" gold
"#00ffff" cyan

The default background color depends on the object class and may be subject to the look-and-feel definition.

See also fgcolor below.

class : string, get
Object type (class name).
clipboardcontextmenu : string, get/set
Allows to override the global or session-specific clipboard context menu configuration with an object-specific value.

The clipboardcontextmenu attribute affects EditText and ComboBox objects. If specified for a container object, all contained EditText and ComboBox objects are affected.

For details, please refer to the documentation of the eloquence.config.clipboardcontextmenu configuration property.

By default, this is the value of the Application.clipboardcontextmenu attribute or the System.clipboardcontextmenu attribute or the eloquence.config.clipboardcontextmenu configuration property.

Note: Requires JDLG version 1.5.7-110518-1310 or newer.

contextmenu : string, get/set
Specifies the path of a Menu object that is opened at the mouse position when the context menu mouse button is clicked.

If the Menu object path starts with a . dot character, it is considered relative to the current Dialog, i.e., the id of the current Dialog is prepended.

The rmbmask attribute defines the context menu mouse button. By default this is the right mouse button.

For details, please refer to the Context menus documentation below.

fgc : integer, get/set (also: string, set)
No function (provided for ASCII DLG backward compatibility).
If used with string argument in DLG SET: Same as fgcolor (see below).
fgcolor : string, get/set
Foreground color in hexadecimal #RRGGBB notation
(see bgcolor above for examples).

The default foreground color depends on the object class and may be subject to the look-and-feel definition.

first : string, get
Used on a container object: Returns the path of the first child object.

Used on top-level (DLG GET ".first"): Returns the id of the first Dialog.

Note: Object path or Dialog id is always returned in lower-case. An empty string is returned if no object or Dialog is found. See also next below.

focus : integer, get/set
A nonzero focus value specifies or indicates that this object will obtain the keyboard focus on the next DLG DO invocation.

By default, the first focusable object in a Dialog will obtain the keyboard focus if the Dialog is opened for the first time.

focuscolor : string, get/set
Alternative background color in hexadecimal #RRGGBB notation, used when the object has the keyboard focus (see bgcolor above for examples).

By default, focuscolor equals bgcolor.

Note: Only applies to focusable object classes, such as EditText, ComboBox, ListBox, PopText, PushButton.

focusobj : string, get
Path of the object that currently has the keyboard focus.
Note: Always returned in lower-case.
fontface : string, get/set
Font face or font family name. The resulting object font is composed using the fontface, fontsize and fontstyle attributes (see below).

Valid font face or font family names depend on the installed fonts, for example Times, Helvetica, Courier.

The family names for logical fonts are: Dialog, DialogInput, Monospaced, Serif, SansSerif. These are mapped to available font face or font family names installed on the system.

By default, the object font attributes (fontface, fontsize, fontstyle) are derived from the parent object, while the Dialog font attributes are derived from the default font, defined by the eloquence.config.defaultfont.name and .size configuration properties. The default Dialog font is a 12-point DialogInput font.

fontsize : integer, get/set
Font size in point units (see fontface above). By default, the fontsize attribute is derived from the parent object or the Dialog.
fontstyle : string, get/set
Font style: plain, italic or bold (see fontface above). By default, the fontstyle attribute is derived from the parent object or the Dialog.
help : string, get/set
A rule value of -1 triggers the help system (see rule below), which uses the help attribute values of an object and its parent objects to compose the URL of a context-sensitive help document.

The base of this URL is defined by the System.helpbaseurl attribute or the eloquence.config.helpbaseurl configuration property, followed by the value of the Application.helpbaseurl attribute.

For example:
 System.helpbaseurl = "http://intranet/jdlg/doc/"
 Application.helpbaseurl = "erp/"
 MenuDialog.help = "menu.html"
 MenuDialog.Accounting.help = "#accounting"

Resulting URL:
 http://intranet/jdlg/doc/erp/menu.html#accounting

The configured browser is then invoked with the resulting URL. Please refer to the documentation of the Application.browser attribute for details.

Note: The F1 function key (i.e., the Dialog.f1 attribute) by default has a -1 rule value assigned.

id : string, get/set
Object identifier (object name).
Note: Always returned in lower-case.
next : string, get
Used on an object: Returns the path of the next object in the same hierarchy level.

Used on top-level (DLG GET ".next"): Returns the id of the next Dialog, based on previous top-level DLG GET ".first" or ".next" invocation.

Note: Object path or Dialog id is always returned in lower-case. An empty string is returned if no object or Dialog is found. See also first above.

path : string, get
The path specifies the object location in the Dialog hierarchy.

Path components are separated with . dot characters. The first path component is always the id of the Dialog.

Note: Always returned in lower-case.

rmbmask : integer, get/set
Defines which mouse button is used to trigger a context menu (see contextmenu above) or the Dialog.rmbr rule.

Possible values are:
 1 - the left mouse button
 2 - the middle mouse button (e.g., the mouse-wheel button)
 4 - the right mouse button

and any combination of these, for example 6 (middle and right) or 7 (all buttons).

The default value is 4 (right mouse button).

For details, please refer to the Context menus documentation below.

rule : integer, get/set
The rule value is returned to the program when an object issues a notification event, for example when a PushButton is clicked or a configured Dialog timeout has elapsed.

The rule value is transferred to the program through the first return variable on DLG DO. If in addition a second return variable is provided, it is used to transfer the context of the issued event, which is an object path, identifying for example the particular PushButton that was clicked.

Details on the notification event types are documented for each object class.

The default rule value is zero. Usually, a nonzero rule value needs to be specified to enable event notification for an object.

Note: A rule value of -1 triggers the help system (see help above). The F1 function key (i.e., the Dialog.f1 attribute) by default has a -1 rule value assigned.

sensitive : integer, get/set
Nonzero (default): Object and child objects are potentially sensitive (react upon keyboard and mouse input), depending on parent object sensitivity.

Zero: Object and child objects are insensitive (do not react upon keyboard and mouse input).

Note: Insensitive objects are usually displayed using dim foreground and background colors, subject to the look-and-feel definition.

tabstop : string, get/set
Nonzero (default): The object is part of the Dialog tab order.

Zero: The object is not part of the Dialog tab order.

Note: Before JDLG version 1.6.5, if tabstop is set to zero the object was no longer focusable.

toolhelp : string, get/set
Informational text to be displayed when the user hovers the mouse cursor over the object for some time without clicking the mouse.
udata : integer or string, get/set
User-defined data stored in the object context.
DLG SET defines the data type (integer or string).
The default value is integer zero.
visible : integer, get/set
Nonzero (default): Object and child objects are potentially visible, depending on parent object visibility.

Zero: Object and child objects are invisible (hidden).


The common contextmenu attribute allows to specify the path of a Menu object that is opened at the mouse position when the context menu mouse button is clicked.

The Menu object may be located in the current or another Dialog, for example in a model. An invalid Menu object path has no effect.

The common rmbmask attribute allows to separately define the context menu mouse button for each object. By default this is the right mouse button, but rmbmask may for example be used to specify that a StaticText context menu is opened when any mouse button is clicked.

When pressing the context menu mouse button, the following behavior applies:

  • If the object under the mouse cursor specifies a contextmenu, the context menu is opened. When the context menu is completed, DLG DO may return, depending on the selected menu item. The returned path specifies the object under the mouse cursor when the context menu was opened.

  • If the object under the mouse cursor does not specify a contextmenu, the further behavior depends on the object type.

This applies to objects of all classes, including those that do not act upon a mouse click or never return a rule value, for example StaticText objects.

Note: Pressing the context menu mouse button does not change the focus object.

When selecting an entry in the context menu that specifies a nonzero rule value, DLG DO returns with this value and the path of the object under the mouse cursor when the context menu was opened.

If the selected menu item has a zero rule value, DLG DO will not return.

Any MenuItem status change (checked, radio item selected) is preserved, i.e., may be set before or queried after the context menu is displayed.


The typeahead function prevents characters from being lost if they are typed while the Dialog is not interactive, i.e., currently outside DLG DO.

The typeahead function includes the TAB and/or ENTER keys used for forward focus navigation and therefore buffers keyboard input across multiple objects.

The System.typeahead or eloquence.config.typeahead configuration allow to globally enable or disable the typeahead function (default: typeahead enabled).

How the buffered keyboard input is processed depends on the class of the currently focused object, i.e., the object class receiving the buffered input the next time DLG DO is executed.

ComboBox, EditText:

  • The buffered characters are inserted at the cursor position or replace the current selection.

  • The TAB key moves the focus to the next focusable object.

  • Single-line EditText or ComboBox: The ENTER key moves the focus to the next focusable object.

  • Multi-line EditText: The ENTER key inserts a newline character at the cursor position.

CheckBox, PushButton, RadioButton:

  • The SPACE character triggers a button click.

  • The TAB key moves the focus to the next focusable object.

  • The ENTER key function depends on the setting of the traversecr attribute. If traversecr is zero, ENTER triggers a button click. If it is nonzero, ENTER moves the focus to the next focusable object.

  • All other characters are considered invalid (see notes below).

PopText:

  • The buffered characters are used to select a PopText entry. If no entry is matched the input is considered invalid (see notes below).

  • The TAB key moves the focus to the next focusable object.

  • The ENTER key function depends on the setting of the traversecr attribute. If traversecr is zero, ENTER submits the PopText rule to the program. If it is nonzero, ENTER moves the focus to the next focusable object.

All other object classes:

  • The TAB key moves the focus to the next focusable object.

  • All other characters are considered invalid (see notes below).

Notes:

  • DLG SET focus clears the buffer (i.e., the typeahead function is stopped).

  • When an invalid typeahead character is encountered, the buffer is cleared (i.e., the typeahead function is stopped) and a user beep notification is issued (depending on the System.notifybusy or eloquence.config.notifybusy configuration).

  • An invalid typeahead character may either occur during keyboard input or when the focused control processes the buffered input. The typeahead buffer only accepts input characters and forward focus navigation keys. Cursor, function and accelerator keys as well as editor keys (e.g. BACKSPACE) are considered invalid.

  • If the Dialog.cr attribute is set to a nonzero value, a buffered ENTER key is not processed but considered invalid.

  • The typeahead buffer expires 10 seconds after the last character was buffered.

  • Requires JDLG version 1.5.7-110518-1310 or newer.

  • JDLG versions before 1.7.0 only buffer keyboard input if a ComboBox or EditText object has the focus. TAB/ENTER forward focus navigation across multiple objects is not buffered.


The JDLG drag & drop functionality allows to selectively define which objects may start a drag operation, and what happens when a drop occurs.

The following drag & drop modes are supported:

Dialog-local drag & drop
Submits a rule to the program when a drag & drop operation takes place within the same Dialog.

This enables the program to control the drag & drop action. The involved objects do not perform a default drag & drop action, e.g., an EditText object does not insert the dropped text.

Set the drag attribute to 1 for those objects which should allow to start a dialog-local drag operation (see below).

Set the droprule attribute to nonzero for those objects which should allow a dialog-local drop (see below). This rule value is submitted to the program when a drop on this object occurs.

Both may be set on the same object, e.g., to allow drag & drop within the same ListBox.

Global drag
If global drag is enabled, the object's default drag function may be used to drag content from an object to other programs, e.g., to use drag & drop to copy selected EditText content to an external text editor.

Set the drag attribute to 2 for those objects which should allow to start a global drag operation (see below).

Global drop
By default, editable EditText and ComboBox objects insert dropped text which is dragged from other programs, e.g., when drag & drop is used to copy selected text from an external text editor to an EditText object.

The globaldroprule attribute allows to override this default behavior. In addition, it allows to enable global drop on object classes other than EditText or ComboBox (see below).

If the globaldroprule attribute is set to nonzero, the default drop action does not take place. Instead, the specified rule value is submitted to the program, and the Dialog.dropcontent attribute may be used to obtain the dropped content.

Notes:


drag : integer, get/set
Enables either dialog-local or global drag:
0 (default) :  Drag is disabled.
1 :  Dialog-local drag is enabled.
2 :  Global drag is enabled.

The drag attribute is implemented for the following object classes:
EditText (see EditText drag & drop attributes below)
ComboBox (see ComboBox drag & drop attributes below)
HtmlView (see HtmlView drag & drop attributes below)
ListBox (see ListBox drop attributes below)
Tree (see Tree drop attributes below)

dragactions : integer, get/set
Specifies the drag actions allowed for dialog-local drag & drop operations.

The dragactions attribute may be set to the sum of the modes below:
1 (default) :  MOVE
2 :  COPY (indicated with a plus-symbol)
4 :  LINK (indicated with a link symbol)

The default drag action is MOVE. The COPY or LINK actions are chosen by holding modifier keys while dragging. Typically, the Ctrl key activates the COPY action, and Ctrl-Shift activates the LINK action.

By default, the MOVE action is allowed only. A program may set dragactions if it wants to react differently depending on the drag action.

Note: The drag attribute must be set to 1 on the same object, otherwise the dragactions attribute has no effect.

droprule : integer, get/set
If nonzero, dialog-local drop is enabled.

When a dialog-local drop occurs, the following happens:

The program may then identify the involved objects and the drop action:

  • The object where the drop occured is identified by the droprule and/or the path returned by DLG DO.

  • DLG GET Dialog.dragfrom returns the path of the object where the drag originated.

  • DLG GET Dialog.dropaction returns the drag & drop action:
    1 :  MOVE
    2 :  COPY
    4 :  LINK

By default, the droprule is zero (dialog-local drop disabled).

The droprule attribute is implemented for the following object classes:
EditText (see EditText drag & drop attributes below)
ComboBox (see ComboBox drag & drop attributes below)
HtmlView (see HtmlView drag & drop attributes below)
ListBox (see ListBox drop attributes below)
Tree (see Tree drop attributes below)

In addition, the droprule attribute may be set for the object container classes Dialog, GroupBox, StatusBar and ToolBar.

Notes:

  • If a droprule is set on a container object, a drop on a child object which does not itself have the droprule attribute set is propagated to the container object. As a consequence, child objects can no longer provide their default drop behavior.

  • The same object may have both the droprule and globaldroprule attributes set, this way accepting both dialog-local and global drop actions, which are then submitted to the program with different rule values.
globaldroprule : integer, get/set
If nonzero, global drop notification is enabled.

When a global drop occurs, the following happens:

The program may then identify the object where the drop occurred, and the content which was dropped as well as the drop action:

  • The object where the drop occured is identified by the globaldroprule and/or the path returned by DLG DO.

  • DLG GET Dialog.dropcontent returns the content which was dropped.

  • DLG GET Dialog.dropaction returns the drag & drop action:
    1 :  MOVE
    2 :  COPY
    4 :  LINK

By default, the globaldroprule is zero (global drop notification disabled).

The globaldroprule attribute is implemented for the following object classes:
EditText (see EditText drag & drop attributes below)
ComboBox (see ComboBox drag & drop attributes below)
HtmlView (see HtmlView drag & drop attributes below)
ListBox (see ListBox drop attributes below)
Tree (see Tree drop attributes below)

In addition, the globaldroprule attribute may be set for the object container classes Dialog, GroupBox, StatusBar and ToolBar.

Notes:

  • If a globaldroprule is set on a container object, a drop on a child object which does not itself have the globaldroprule attribute set is propagated to the container object. As a consequence, child objects can no longer provide their default drop behavior.

  • The same object may have both the droprule and globaldroprule attributes set, this way accepting both dialog-local and global drop actions, which are then submitted to the program with different rule values.


The Dialog drag & drop attributes below are set when a dialog-local drag & drop has happened, or when a global drop has occurred on an object which has the globaldroprule attribute set.

dragfrom : string, get
Path of the object where a dialog-local drag originated.

If a rule submission is not caused by a dialog-local drag & drop, dragfrom is empty.

dropcontent : string, get
Content which was dropped during a global drag & drop on an object which has the globaldroprule attribute set.

If a rule submission is not caused by a global drop, dropcontent is empty.

Notes:

  • The dropped data must be convertible to text, otherwise a global drop is not detected and the globaldroprule is not submitted.

  • Convertible data includes text in a variety of formats, as well as files, e.g., dragged from a file manager or from the Desktop.

  • When a file is dropped, dropcontent contains its absolute path. If multiple files are dropped, the file paths are separated by LF (ASCII 10).
dropaction : integer, get
The drag & drop action associated with a submitted droprule or globaldroprule.
1 :  MOVE
2 :  COPY
4 :  LINK

If a rule submission is not caused by a dialog-local drag & drop or a global drop, dropaction is 0.


The EditText drag & drop attributes below are set when an EditText is involved in a dialog-local drag & drop, or when a global drop has occurred on an EditText which has the globaldroprule attribute set.

dragcontent : string, get
Dragging from an EditText presumes that text is selected.

The dragcontent attribute allows to programmatically query the text selection which was dragged.

If a rule submission is not caused by a dialog-local drag & drop originating from this EditText, dragcontent is empty.

dropcx : integer, get
The column where the drop occurred (starting with 0).

If a rule submission is not caused by a dialog-local or global drop on this EditText, dropcx is -1.

dropcy : integer, get
The line where the drop occurred (starting with 0).

If a rule submission is not caused by a dialog-local or global drop on this EditText, dropcy is -1.


The ComboBox drag & drop attributes below are set when a ComboBox is involved in a dialog-local drag & drop, or when a global drop has occurred on an ComboBox which has the globaldroprule attribute set.

dragcontent : string, get
Dragging from an ComboBox presumes that text is selected.

The dragcontent attribute allows to programmatically query the text selection which was dragged.

If a rule submission is not caused by a dialog-local drag & drop originating from this ComboBox, dragcontent is empty.

dropcx : integer, get
The column where the drop occurred (starting with 0).

If a rule submission is not caused by a dialog-local or global drop on this ComboBox, dropcx is -1.


The HtmlView drag & drop attributes below are set when an HtmlView is involved in a dialog-local drag & drop, or when a global drop has occurred on an HtmlView which has the globaldroprule attribute set.

dragcontent : string, get
Dragging from an HtmlView presumes that text is selected.

The dragcontent attribute allows to programmatically query the text selection which was dragged.

If a rule submission is not caused by a dialog-local drag & drop originating from this HtmlView, dragcontent is empty.

dropcx : integer, get
The column where the drop occurred (starting with 0).

If a rule submission is not caused by a dialog-local or global drop on this HtmlView, dropcx is -1.

Note: The returned value specifies the drop position for plain text documents only, i.e., if mimetype is set to "text/plain".

dropcy : integer, get
The line where the drop occurred (starting with 0).

If a rule submission is not caused by a dialog-local or global drop on this HtmlView, dropcy is -1.

Note: The returned value specifies the drop position for plain text documents only, i.e., if mimetype is set to "text/plain".

dropelement : string, get
If a HTML document is displayed, i.e., if mimetype is set to "text/html", this is set to the id attribute value of the HTML element where the drop occurred.

For example, if a drop occurs on element <div id='July-2016'>, the dropemelent attribute is set to "July-2016".

If a rule submission is not caused by a dialog-local or global drop on this HtmlView, dropelement is empty.


The ListBox drop attributes below are set when a dialog-local drop occurs on a ListBox which has the droprule attribute set, or when a global drop occurs on a ListBox which has the globaldroprule attribute set.

The dropmode attribute below specifies where in a ListBox a drop is allowed to occur.

When a dialog-local drag & drop originates from a ListBox, the following attributes are set: activecolumn, activeitem, activeline and cy.

dropcolumn : integer, get
The column where the drop occurred (starting with 0).

If a rule submission is not caused by a dialog-local or global drop on this ListBox, dropcolumn is -1.

dropline : integer, get
The line where the drop occurred (starting with 1).

If a rule submission is not caused by a dialog-local or global drop on this ListBox, dropline is 0.

dropmode : integer, get/set
Specifies where a drop is allowed to occur.
zero (default) :  Drop is allowed anywhere on a ListBox.
nonzero :  Drop is allowed only on existing ListBox lines.


The Tree drop attributes below are set when a dialog-local drop occurs on a Tree which has the droprule attribute set, or when a global drop occurs on a Tree which has the globaldroprule attribute set.

The dropmode attribute below specifies where in a Tree a drop is allowed to occur.

When a dialog-local drag & drop originates from a Tree, the following attributes are set: activeline and cy.

dropline : integer, get
The node or leaf where the drop occurred (starting with 1).

If a rule submission is not caused by a dialog-local or global drop on this Tree, dropline is 0.

dropmode : integer, get/set
Specifies where a drop is allowed to occur.
zero (default) :  Drop is allowed anywhere on a Tree.
nonzero :  Drop is allowed only on existing Tree entries.


 
 
.
 
 
  Privacy | Webmaster | Terms of use | Impressum Revision:  2017-08-29  
  Copyright © 2002-2017 Marxmeier Software AG