• Dialog class
• Dialog position and size attributes
• Dialog layout backward compatibility

alt : integer, get/set

No function (provided for ASCII DLG backward compatibility).

bgfill : string, get/set

Specifies the background image fill mode:

"none"		The background image is positioned in the topleft corner of the Dialog.
"center"		The background image is centered across the Dialog.
"tile"		The background image is tiled across the Dialog. This is the default.
"scale"		The background image is scaled to the Dialog size.

See also bgimage below.

bgimage : string, get/set

Specifies the URL referring to a Dialog background image in png, gif or jpg format. The image is tiled across the background if it is smaller than the Dialog.

If a relative URL is specified, the value of the Application.baseurl or System.baseurl attribute or eloquence.config.baseurl configuration property is prepended.

The default value is empty (no background image).
See also bgfill above.

border : integer, get/set

No function (provided for ASCII DLG backward compatibility).

class : string, get

Returns "Dialog".

cr : integer, get/set

If nonzero, the cr value is returned to the program when the RETURN (ENTER) key is pressed, along with the path of the object that currently has the keyboard focus.

The default cr value is zero (notification disabled).

Note: If a multiline EditText object has the keyboard focus, the cr attribute has no effect because RETURN (ENTER) is the multiline EditText newline key.

do : integer, get/set

Allows to implement a Cancel Dialog.

DLG SET "Dialog.do",1 enables the Dialog so that it may react upon keyboard and mouse input, then immediately returns to the program, while the Dialog remains enabled.

If the users triggers any rule on the Dialog (for example, the user clicks the Cancel PushButton), the program is not notified. Instead, visual feedback is given to the user, and an internal status is set which the program can query with DLG GET "Dialog.do":

• DLG GET "Dialog.do" returns nonzero if the Dialog is enabled and visible and the user so far did not trigger a rule on the Dialog.

• DLG GET "Dialog.do" returns zero if the Dialog is disabled and invisible, or if it is enabled and visible and the user triggered a rule on the Dialog.

The visual feedback may be configured with the dohide and (optionally) doshow attributes (see below).

If the dohide attribute is set, the object it refers to is made invisible. Optionally, the doshow attribute may be set to specify an object which should be made visible at the same time.

If the dohide attribute is not set, the Dialog is disabled and made invisible.

Notes:

• Using the dohide and doshow attributes requires JDLG version 1.6.6 or newer.

• JDLG versions before 1.6.6 behave as if the dohide attribute is not set.

DLG SET "Dialog.do",0 disables a previously enabled Dialog and makes it invisible.

Usually, a Cancel Dialog contains a Cancel PushButton. The idea is that before a program starts a lengthy task, it enables the Cancel Dialog using DLG SET "Dialog.do",1 and disables it again with DLG SET "Dialog.do",0 when the task is finished. During the task, it uses DLG GET "Dialog.do" in regular intervals to query whether the user has clicked the Cancel PushButton, in which case DLG GET "Dialog.do" would return zero.

Example:

• A Cancel Dialog contains two overlapping GroupBoxes named "hide" and "show".

• The "hide" GroupBox contains a status StaticText and the Cancel PushButton.

• The "show" GroupBox contains a StaticText informing the user that the Cancel request was recognized, such as "Canceling, please wait ...".

• The Dialog.dohide attribute is set to "hide", the doshow attribute is set to "show".

To start the Cancel Dialog, the status StaticText is set to inform the user about the lengthy task being run, such as "Archiving ...", then DLG SET "Dialog.do",1 is invoked.

DLG SET "Dialog.do",1 first initializes the visibility of the dohide and (optionally) doshow objects. In this example, the "hide" GroupBox is made visible and the "show" GroupBox is made invisible. After that, the Dialog is enabled and made visible.

The Cancel Dialog is now displaying the status StaticText ("Archiving ...") along with the Cancel PushButton.

If the user clicks the Cancel PushButton, the "hide" GroupBox is made invisible and the "show" GroupBox is made visible, so that the Cancel Dialog now displays the "Canceling, please wait ..." information.

Meanwhile, the program uses DLG GET "Dialog.do" on the Cancel Dialog to query the Cancel status in regular intervals. If the status is zero, the user has asked to cancel the task.

Because the user is given informational feedback, the overhead of querying the cancel status can be as low as possible because the program is not required to immediately respond to the user's cancel request.

dohide : string, get/set

Specifies the relative path to an object in the Dialog which should be made invisible when the Dialog is enabled with DLG SET "Dialog.do",1 and the user triggers a rule on the Dialog (for example, the user clicks the Cancel PushButton).

The default value is empty (not set).

Notes:

• When the Dialog is enabled with DLG SET "Dialog.do",1 the specified object is initially made visible.

• If the dohide attribute is not set, the Dialog is made invisible and disabled when the user triggers a rule on the Dialog.

• Requires JDLG version 1.6.6 or newer.

doshow : string, get/set

Specifies the relative path to an object in the Dialog which should be made visible when the Dialog is enabled with DLG SET "Dialog.do",1 and the user triggers a rule on the Dialog (for example, the user clicks the Cancel PushButton).

The default value is empty (not set).

Notes:

• When the Dialog is enabled with DLG SET "Dialog.do",1 the specified object is initially made invisible.

• The doshow attribute has no effect if the dohide attribute is not set.

• Requires JDLG version 1.6.6 or newer.

enablemaximize : integer, get/set

Nonzero (default): The auto-maximize function is enabled for this Dialog unless disabled by the Application.enablemaximize attribute.

Zero: The auto-maximize function is disabled for this Dialog.

Notes:

• See also setmaximize below.

• Requires JDLG version 1.7.2 or newer.

enablereference : integer, get/set

Nonzero (default): The reference point function is enabled for this Dialog unless disabled by the Application.enablereference attribute.

Zero: The reference point function is disabled for this Dialog.

Notes:

• See also setreference below.

• Requires JDLG version 1.7.2 or newer.

enablescalefactor : integer, get/set

Nonzero (default): The auto-scale function is enabled for this Dialog unless disabled by the Application.enablescalefactor attribute.

Zero: The auto-scale function is disabled for this Dialog.

Notes:

• See also setscalefactor below.

• Requires JDLG version 1.7.2 or newer.

enablesnap : integer, get/set

Nonzero (default): The auto-snap function is enabled for this Dialog unless disabled by the Application.enablesnap attribute.

Zero: The auto-snap function is disabled for this Dialog.

Notes:

• See also setsnap and snapadjustsize below.

• By default, the auto-snap function is disabled.

• Requires JDLG version 1.7.2 or newer.

f1 ... f12 : integer, get/set

The f1 ... f12 attributes define individual values for each of the function keys F1 ... F12, to be returned to the program when the respective function key is pressed, along with the path of the object that currently has the keyboard focus.

The default f1 value (for the F1 function key) is -1, which triggers the help system. For details, please refer to the common help attribute documentation.

The default f2 ... f12 values (for the F2 ... F12 function keys) are zero (notification disabled).

logoicon : string, get/set

Specifies the URL referring to an icon image in png, gif or jpg format, to be displayed in the Dialog caption bar. Usually, a 16x16 pixel image size works best.

If a relative URL is specified, the value of the Application.baseurl or System.baseurl attribute or eloquence.config.baseurl configuration property is prepended.

If not specified, the value of the Application.logoicon attribute or eloquence.config.logoicon configuration property is used.

By default, the Eloquence logo is displayed.

margin : integer, get/set

Used to set the left/right/top/bottom margin attributes to the same value (see below).

On DLG GET, 1 is returned if the left/right/top/bottom margin attributes are all set to a nonzero value, else 0 is returned.

Note: JDLG versions before 1.7.0 do not support individual left/right/top/bottom margins. If the margin attribute is set to a nonzero value, an inner margin is assumed which offsets the position of child objects in the Dialog. The horizontal margin size is half a raster width, the vertical margin size is half a raster height. The default value is zero (no margin).

marginbottom : integer, get/set

If nonzero, an inner bottom margin is assumed which offsets the position of child objects in the Dialog. This is used with the yauto vertical layout modes 0 and -1.

The bottom margin size is half a raster height.
The default value is zero (no bottom margin).

Note: Requires JDLG version 1.7.0 or newer.

marginleft : integer, get/set

If nonzero, an inner left margin is assumed which offsets the position of child objects in the Dialog. This is used with the xauto horizontal layout modes 0 and 1.

The left margin size is half a raster width.
The default value is zero (no left margin).

Note: Requires JDLG version 1.7.0 or newer.

marginright : integer, get/set

If nonzero, an inner right margin is assumed which offsets the position of child objects in the Dialog. This is used with the xauto horizontal layout modes 0 and -1.

The right margin size is half a raster width.
The default value is zero (no right margin).

Note: Requires JDLG version 1.7.0 or newer.

margintop : integer, get/set

If nonzero, an inner top margin is assumed which offsets the position of child objects in the Dialog. This is used with the yauto vertical layout modes 0 and 1.

The top margin size is half a raster height.
The default value is zero (no top margin).

Note: Requires JDLG version 1.7.0 or newer.

maximized : integer, get/set

A nonzero maximized value specifies or indicates that this Dialog takes or will take the whole space on the Desktop.

Note: Maximizing a Dialog is disabled if the Dialog is set to the default "none" resizepolicy.

minheight : integer, get/set

Minimal dialog height in raster units or pixel units, only effective if the Dialog is set to the "layout" resizepolicy.

Note: Using pixel units requires JDLG version 1.7.0 or newer.

minwidth : integer, get/set

Minimal dialog width in raster units or pixel units, only effective if the Dialog is set to the "layout" resizepolicy.

Note: Using pixel units requires JDLG version 1.7.0 or newer.

notify[] or notify: integer, get/set

Specifies a notification code and an associated rule value.

The notification code is specified in the index.

The System.notify[] attribute may be used to send notifications to other sessions. The specified code defines which Dialogs are notified.

For example, a Dialog configuration like ...

• Rule 1000 for notification code 174
• Rule 1088 for notification code 175

... could be defined like below:

Dialog customer_doc {

  .notify[174] = 1000
  .notify[175] = 1088

  ...
}

A program could then notify active Dialogs in other sessions which have notification code 175 configured:

DLG SET System.notify[175],Custno$

The notified Dialogs would then issue rule 1088 along with path set to the passed Custno$.

Please refer to the "Notifying other sessions" documentation for details.

If used without index and the value is zero, all notification codes are removed from the Dialog:

DLG SET Dialog.notify,0

resizepolicy : string, get/set

Specifies the action when the Dialog is resized:

"none"		The user cannot resize or maximize the dialog. This is the default.
"scale"		Resizing the Dialog affects its scale factor, which is used to adjust the Dialog raster size as well as the object and font sizes of all child objects. Unless the auto-scale function is disabled, resizing the Dialog also affects the current session's scale factor. When a new Dialog or POPUP BOX is opened or an existing Dialog is made visible, the session's scale factor is applied. This allows the user to control how the Dialogs of an application are scaled. The Application.scalefactor attribute may be used to programmatically save and restore the current session's scale factor.
"layout"		The Dialog layout is dynamically adjusted when the Dialog is resized. This affects all child objects which use the xauto/ yauto = 0 or -1 layout modes.

rmbr : integer, get/set

If nonzero, the rmbr value is returned to the program when the context menu mouse button is clicked, unless there is a contextmenu specified for the object under the mouse cursor when the mouse button was clicked, or for one of its parent objects.

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

The default rmbr value is zero (notification disabled).

For details, please refer to the Context menus documentation.

rule : integer, get/set

If a nonzero rule value is specified, the Dialog close box is enabled. The rule value is returned to the program when the dialog is closed, along with the id of the Dialog.

The default rule value is zero (Dialog close box disabled).

For details, please refer to the common rule attribute documentation.

setmaximize : integer, get/set

Nonzero (default): This Dialog modifies the session's auto-maximize status if the Dialog is maximized or normalized by the user, unless the auto-maximize function is disabled.

Zero: This Dialog does not modify the session's auto-maximize status.

Notes:

• See also enablemaximize above.

• Requires JDLG version 1.7.2 or newer.

setreference : integer, get/set

Nonzero (default): This Dialog modifies the session's reference point if the Dialog is moved by the user, unless the reference point function is disabled.

Zero: This Dialog does not modify the session's reference point.

Notes:

• See also enablereference above.

• Requires JDLG version 1.7.2 or newer.

setscalefactor : integer, get/set

Nonzero (default): This Dialog modifies the session's scale factor if the Dialog has the resizepolicy attribute set to "scale" and is resized by the user, unless the auto-scale function is disabled.

Zero: This Dialog does not modify the session's scale factor.

Notes:

• See also enablescalefactor above.

• Requires JDLG version 1.7.2 or newer.

setsnap : integer, get/set

Nonzero (default): This Dialog modifies the session's auto-snap status if the Dialog is snapped or unsnapped by the user, unless the auto-snap function is disabled.

Zero: This Dialog does not modify the session's auto-snap status.

Notes:

• See also enablesnap above and snapadjustsize below.

• By default, the auto-snap function is disabled.

• Requires JDLG version 1.7.2 or newer.

snapadjustsize : integer, get/set

Nonzero (default): The Dialog auto-snap adjust size function is enabled for this Dialog unless the auto-snap function is disabled.

Zero: The Dialog auto-snap adjust size function is disabled for this Dialog.

Notes:

• See also enablesnap and setsnap above.

• By default, the auto-snap function is disabled.

• Requires JDLG version 1.7.2 or newer.

timerfrequency : integer, get/set

Dialog timer interval in milliseconds.

If nonzero, the Dialog timer is enabled when DLG DO is invoked. If the timer interval elapses before any other event causes DLG DO to return, the timerrule value is returned to the program, along with the id of the Dialog.

The default value is zero (Dialog timer disabled).

timerrule : integer, get/set

A nonzero timerrule value enables the Dialog timer, along with the timerfrequency attribute (see above).

The default value is zero (Dialog timer disabled).

title : string, get/set

Dialog title (caption).

yield : integer, get/set

If zero, the Dialog puts itself into foreground when it becomes visible. This is the default behavior.

If nonzero, the Dialog opens behind the active Dialog of another session, i.e., it does not put itself into foreground. This may be useful for applications using multiple sessions, for example if a secondary session is used to display information related to the main session.

Please refer to the "Starting secondary sessions" documentation for details.

Note: Using 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.

Unless the reference point function is disabled, moving a Dialog also moves the current session's reference point. When a new Dialog or POPUP BOX is opened or an existing Dialog is made visible, the reference point is used to adjust the Dialog position. This allows the user to define where an application's Dialogs should appear on the Desktop. The Application.referencex and Application.referencey attributes may be used to programmatically save and restore the current sesssion's reference point.

x : integer, get/set

Same as xleft (see below).

xleft : integer, get/set

Left Dialog position.

If set to -1 the Dialog is horizontally centered:

• If the reference point function is enabled and this is not the first Dialog to be opened in the current session, the Dialog is horizontally centered to the position and size of the last active Dialog.
• Otherwise the Dialog is horizontally centered on the screen/desktop.

xright : integer, get/set

No function, xleft and w are used to define the horizontal Dialog position and size.

w : integer, get/set

Dialog width.

xauto : integer, get/set

No function, xleft and w are used to define the horizontal Dialog position and size.

y : integer, get/set

Same as ytop (see below).

ytop : integer, get/set

Top Dialog position.

If set to -1 the Dialog is vertically centered:

• If the reference point function is enabled and this is not the first Dialog to be opened in the current session, the Dialog is vertically centered to the position and size of the last active Dialog.
• Otherwise the Dialog is vertically centered on the screen/desktop.

ybottom : integer, get/set

No function, ytop and h are used to define the vertical Dialog position and size.

h : integer, get/set

Dialog height.

yauto : integer, get/set

No function, ytop and h are used to define the vertical Dialog position and size.

The size calculation of the inner Dialog window area was incorrect in previous JDLG versions. As a consequence, Dialogs were sometimes scaled too big so that they overlapped the window area by a few pixels on the right and/or bottom window edges.

JDLG 1.7.0 solves these layout issues. However, this might cause a different Dialog appearance in certain cases. For example, if a Dialog window is maximized, or if the desktop size limits the Dialog window size, a Dialog might be scaled smaller than before because it is not allowed to overlap the window area.

To compensate for that, width/height overlap attributes were introduced to specify the number of pixels a Dialog is allowed to overlap the window area, as documented below.

Dialog scroll bar:

If a Dialog's size exceeds the size of the window area, JDLG version 1.7.0 or newer allows to scroll the Dialog.

This is new behavior and may be disabled using the scroll attribute as documented below.

w_overlap : integer, get/set

Specifies the number of pixels the Dialog width is allowed to overlap the width of the Dialog window area.

If not set, it defaults to the value of the Application.dialog_w_overlap or System.dialog_w_overlap attribute or eloquence.config.dialog.w_overlap configuration property. If neither is set, the default value is zero.

Notes:

• Setting this to 3 should reproduce the effects of the wrong window area calculation in JDLG versions before 1.7.0.

• Requires JDLG version 1.7.0 or newer.

h_overlap : integer, get/set

Specifies the number of pixels the Dialog height is allowed to overlap the height of the Dialog window area.

If not set, it defaults to the value of the Application.dialog_h_overlap or System.dialog_h_overlap attribute or eloquence.config.dialog.h_overlap configuration property. If neither is set, the default value is zero.

Notes:

• Setting this to 3 should reproduce the effects of the wrong window area calculation in JDLG versions before 1.7.0.

• Requires JDLG version 1.7.0 or newer.

scroll : integer, get/set

Nonzero: Dialog scroll bars are displayed if necessary in case the Dialog size exceeds the Dialog window area.

Zero: Scroll bars are never displayed. If the Dialog is too big, it is clipped.

If not set, it defaults to the value of the Application.dialog_scroll or System.dialog_scroll attribute or eloquence.config.dialog.scroll configuration property. If neither is set, the default value is nonzero (scroll bars are displayed if necessary).

Notes:

• Displaying Dialog scroll bars if necessary is new behavior introduced with JDLG version 1.7.0.

• Requires JDLG version 1.7.0 or newer.