Definition
Define a dialog box.
[enabled|disabled] [visible|invisible][[color] COLOR]
[temporary|permanent] [modal|modeless]
dialog box DB_NAME
size WIDTH HEIGHT at [position] X Y
[parameter is PAR_STRING]
[[extended] helpid is HELP_ID]
[[dialog] border]
[title bar TITLE_STRING]
[system menu]
enabled | disabled
Define the dialog box 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 windows and controls dynamically when the dialog box becomes visible. The windows and controls are destroyed when the dialog box becomes invisible. Their contents cannot be queried when invisible. This is the default.
permanent
Create windows and controls when the program begins to execute. Their existence does not depend on the visibility of the dialog box. Their contents can be queried when invisible.
modal
Make the dialog box modal. When the box is made visible, objects outside of the box cannot be selected until the box is made invisible or deleted. This is the default.
modeless
The dialog box will have no modes. This allows the user to interact with visible objects outside of the dialog box, while the dialog box is still visible.
DB_NAME
The identifier for the dialog box you are defining.
size WIDTH HEIGHT
Integer values representing the dimensions of the viewport, in dialog units.
at position X Y
Integer values representing the position of the dialog box, in dialog units.
parameter is PAR_STRING
A string value representing the parameter of the dialog box. The default value is "".
extended helpid is HELP_ID
A string or integer value representing the identifier for the help panel you want displayed when the user requests help for this region. The default value is "". This should match the help panel defined in the library specified by the help library declaration. The extended keyword indicates that you want HELP_ID to be the extended help panel ID for this dialog box and its children.
border
Draw a border around the dialog box. If you specify only border or dialog border, the standard Windows or PM dialog border is drawn. Note that you must include this attribute to have ESL draw a border.
title bar TITLE_STRING
A string value representing the text that will appear in the standard Windows or PM title bar that will be added to the dialog box.
system menu
Include the standard Windows or PM system menu icon in the dialog box.
Description
Use this statement to define a dialog box. Only the dialog box keywords, the identifier, the size specification, and the at [position] specification are required in the definition.
You can specify the parameter, helpid, border, title bar, and system menu attributes in any order; you must specify all other attributes in the order shown.
Dialog boxes can have only dialog control objects as children.
Note that a response to char or response to line from keyboard cannot be taken while a dialog box has the focus.
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 there is one.
The ancestry of a dialog box is always in desktop.
When taking a response to a dialog box, the response to statement must always include an on clause for any action you want taken. This applies to responses to individual dialog boxes, generic responses (response to dialog box), and classes where an object resolves to a dialog box.
Due to operating environment resource limitations, only a certain number of windows can exist at one time. You can reduce the number of windows in existence at any time by selecting the temporary attribute. Remember also that invisible windows are temporary by default.
When users press the Tab key to move from a push button group to a non-push button group in a dialog box, pressing the Enter key selects the default push button. The following limitations were checked with Mike Czitrom to see if they are Win 3.1 appropriate. They were. 3/93 PB
Windows Limitations
Due to some limitations of Microsoft Windows, version 3.1, we recommend that you specify the following coding standards when creating dialog boxes and dialog regions in ESL for Windows:
Initially define all dialog boxes and dialog regions as invisible temporary objects. If you do not, ESL for Windows will display a warning message at both compile-time and runtime.
To view the dialog box or region, use the following syntax:
make DIALOG_NAME permanent
make DIALOG_NAME visible
where DIALOG_NAME is the name of the dialog box or dialog region.
To display the dialog box or 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 box or region visible without making it permanent, ESL for Windows will display a warning message at runtime.
When the data in a dialog box or dialog region is no longer needed for the application, make the dialog box or region invisible and temporary again. This frees all the associated window handles for the dialog box or 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 box or dialog region, we strongly recommend that you use the enable and disable statements, rather than using add and delete.
Example
invisible dialog box SaveFile_DB
size 160 100 at position 200 200
dialog border
title bar "Save Output File"
system menu
