Definition

Define a dialog region.

[enabled|disabled] [visible|invisible]

[[color] COLOR] [temporary|permanent]

[primary] dialog region DR_NAME

size XSIZE YSIZE

at {default position|[position] X Y}

[in PARENT_NAME1 [in PARENT_NAME2] ...]

[priority is PRIORITY_NO]

[parameter is PAR_STRING]

[[extended] helpid is HELP_ID]

[[size] border]

[title bar TITLE_STRING]

[system menu]

[horizontal scroll bar [scroll by SCROLL_INC]]

[vertical scroll bar [scroll by SCROLL_INC]]

[action bar AB_NAME]

[popup menu STANDALONE_PULLDOWN_NAME]

[minimize button [using MINIMIZE_ICON_FILE]]

[maximize button]

enabled | disabled

Define the dialog region as selectable or not. If you define it as disabled, it is displayed grayed and cannot be selected. The default is enabled.

visible|invisible

A visible object is displayed when it is defined. An invisible object is not displayed until you specifically make it visible. The default is visible.

color COLOR

A color keyword, a string value representing a color keyword, or an integer value representing a color number corresponding to a color available on your system.

temporary

Create the window and controls dynamically when the dialog region becomes visible. Destroy the windows and controls when the dialog region becomes invisible. You cannot query their contents when they are invisible. This is the default.

permanent

Create windows and controls when the program begins to execute. The existence of permanent windows and controls does not depend upon the visibility of the dialog region; their contents can be queried when invisible.

primary

This region is the program's primary region.

DR_NAME

The identifier for the dialog region you are defining.

size XSIZE YSIZE

Integer values representing the dimensions of the region's viewport in dialog units, relative to the origin of the parent's coordinate system.

at X Y

Integer values representing the position of the viewport in dialog units, relative to the origin of the parent's coordinate system, not the position of the outside frame.

in PARENT_NAMEn

Identifiers for parent objects. If the region is primary, you cannot specify ancestry; the region's parent is always in desktop. To place a region outside of a primary region, specify its ancestry as in desktop.

The default ancestry for a windowed dialog region is in the primary region; for a fullscreen dialog region, the default ancestry is in master.

priority is PRIORITY_NO

An integer value representing the priority of the region. The default priority is 0. You cannot assign a priority to a primary region and regions whose ancestry is in desktop.

parameter is PAR_STRING

A string value representing the parameter of the region. The default value is "".

extended

This is the extended help panel ID for this region and its children.

helpid is HELP_ID

A string or integer value representing the identifier for the help panel that you want displayed when the user requests help for this region. This should match the help panel defined in the library specified by the help library declaration. The default HELP_ID is "".

border

Draw a one-pixel border around the region. The default border is invisible.

size border

Surround the region with a sizing border that can be used to resize the region.

title bar TITLE_STRING

A string value representing the title that will appear in the region's title bar, which can be used for repositioning the region.

system menu

The region contains a system menu. The system menu button will be in the upper left corner.

horizontal scroll bar

ESL gives the region a horizontal scroll bar, with solid arrows and a slider, whether or not there is information outside the region window.

The scroll bar will be located along the bottom edge of the region just inside the border, if one exists. The region's contents will be scrolled as specified by SCROLL_INC.

SCROLL_INC

An integer value representing the number of units in the region's co-ordinate system by which the region's window position will be changed when one of the arrows in the scroll bar is pressed. When paging, the page increment is the X or Y window size minus one scroll increment. The default SCROLL_INC is one dialog unit.

vertical scroll bar

ESL gives the region a vertical scroll bar with solid scroll arrows and a slider, whether or not there is information outside the region's window.

The scroll bar will be located along the far right edge of the region, just inside the border, if one exists. The region's contents will be scrolled as specified by SCROLL_INC.

action bar AB_NAME

The identifier for the action bar template. Only those regions that are children of the desktop can have action bars.

popup menu STANDALONE_PULLDOWN_NAME

The identifier for the standalone pulldown template.

minimize button

Give the region a minimize button in the upper right corner.

using MINIMIZE_ICON_FILE

A string value representing the name, including the extension, of the file containing the icon to use when the region is minimized.

maximize button

Give the region a maximize button in the upper right corner. (The maximize button will turn into a restore button when the region is maximized.)

Description

Use this statement to create a dialog region. Only the dialog region specification, the identifier, the size specifications, and the at [position] specification are required, and you must specify them in the order shown in the model. Other attributes are optional. You can specify the attributes after in PARENT_NAMEn in any order.

You can use a dialog region wherever you can use a graphical, image, or textual region, and it can have any of the window frame attributes (title bar, action bar, etc.) that you can use in these regions.

The coordinates used in the definition of a dialog region, and therefore its children, are dialog units ¾ regardless of the coordinate system of their ancestry. Therefore, you cannot scale a dialog region.

Dialog regions always resize by clipping rather than by scaling.

Dialog controls can be placed directly into a dialog region. Dialog regions cannot have any other contents.

In a windowed application, if the dialog region is the primary region, it must be the first object you define. There can be only one primary region.

The region size only includes the area of the viewport itself. It does not include the frame attributes, which are external to the viewport. If the size of the primary dialog region is the same as the screen size, you will not be able to see any frame attributes.

Pressing the escape (Esc) key, double-clicking on the system menu, or selecting Close from the system menu invokes a response to the Cancel push button. If ESL cannot find a response to the Cancel push button, it looks for and invokes an on close response for that region. If there is no Cancel push button and no on close response to invoke, ESL destroys the dialog region.

In a windowed application, disabling a primary dialog region disables its viewport and its frame, and also disables the dialog region's children.

Note that a response to char or response to line from keyboard cannot be taken while a dialog region has the focus.

When taking a response to a dialog region, the response to statement must always include an on clause for any action you want taken. This applies to responses to individual dialog regions, generic responses (response to dialog region), and classes where an object resolves to a dialog region.

Only a limited number of windows can exist at one time. Windows and controls can be dynamically created and destroyed by selecting temporary, which is also the default.

The scroll arrow and the slider in the horizontal and vertical scroll bars are disabled if there is nothing to be scrolled into the window.

Windows Limitations

Due to some limitations of Microsoft Windows, version 3.1, we recommend that you specify the following coding standards when creating dialog regions in ESL for Windows applications:

Initially define all dialog regions as invisible temporary objects. If you do not, ESL for Windows will display a warning message.

To view the dialog region, use the following syntax:

make DIALOG_NAME_DR permanent

make DIALOG_NAME_DR visible

where DIALOG_NAME is the name of the dialog region.

To display the dialog region at the start of a program, execute the make permanent and make visible statements on response to start. If you try to make a dialog region visible without making it permanent, ESL for Windows will display a warning message at runtime.

When the data in a dialog region is no longer needed for the application, make the dialog region invisible and temporary again. This frees all the associated window handles for the dialog region. Any data stored with the object is lost when it is made temporary.

If you do not follow these guide lines, you may experience the following:

Static text and/or multiple- line entry fields do not display.

Entry field cursor freezes.

General Protection Faults (GPFs) occur.

For individual controls within a dialog region, we strongly recommend that you use the enable and disable statements, rather than using add and delete.

In ESL for Windows, when you specify a system menu, minimize and/or maximize button, and do not specify a title bar, a title bar with the name of the program executable is added.

Example

primary dialog region EntryScreen_DR

size 200 160 at 100 100

system menu

title bar "Shipping Information System"

border