A "modal" dialog (MBF_DIALOG) is a popup window that holds on to the keyboard focus, making it impossible to type in any other window owned by the current application, until the modal dialog is closed. You can, however, drag the dialog around, access the main A-Shell menu bar, and even pop up nested modal dialogs. They are quite handy when you want to interrupt the context of the current operation to display or input a collection of related fields.

When creating a dialog box, you should save its ctlid parameter so that it can be used later with opcode 3 to delete the dialog box. Deleting the dialog box will automatically delete the controls within it.

Once a modal dialog is opened with A-Shell, any subsequently created child controls (buttons, static text, edit prompts, etc.) will be, by default, owned by the dialog box, and their coordinates will be taken as relative to the dialog box. (In other words, the parentid parameter will automatically be set to the dialog box ctlid.) However, it is probably still a good idea for you to manually set the parentid , as it probably will make your programs easier to follow, and will be indispensable if you want to implement a text version of a dialog using MSBOXX. Ordinary text output (e.g. PRINT statements, unless SET AUTOTPRINT is enabled) will ignore the dialog box and appear in the main A-Shell window. (In other words, you can only place Windows control-objects within these dialog boxes.)

Typically, a dialog box should have one or more buttons which notify the program (via a keyboard sequence) to close the dialog (for example, “OK”, and “CANCEL”). You may also include an “X” in the upper right corner of the dialog by adding the MBF_SYSMENU flag to ctype, which the user can click on to close the dialog.

Note that clicking on the “X” to close a dialog does not directly close it. Instead, it sends an Escape character to the keyboard buffer, which the dialog’s input routine should process by closing the dialog (with opcode 3). To simplify programming, if the dialog also has a CANCEL button, you might as well program it to send Escape as well, so that pressing on the CANCEL button or “X” has the same effect. Also note that you are not obligated to close the dialog just because the user clicked on either of these buttons. If there is a problem needing resolution by the user, you can ignore the clicks or pop up a message box (another modal dialog) to tell the user what they must do before closing the dialog.

To display a dialog by itself, without the main window behind it, using one of the following techniques:

• You can launch a new session of A-Shell with the -z or -zi switch (both of which make the main window invisible) and use a startup command that launches a program which shows a dialog. Note however, that the dialog should be created with MBF_ALTPOS flag or else it will likely be sized inappropriately.

• You can hide the main window on demand using the XCALL AUI,AUI_WINDOW,0 and then proceed to create a dialog normally.

There are several sample programs which contain dialogs, including XTRA2, XTRA3, and TABDLG. See the sample screen shot in the Tab Control Example below for an example of a dialog.  Also see the sample program DLGCTR, which illustrates using AUI_WINDOW to hide the main window and retrieve information about the screen dimensions for creating a centered dialog manually.

(Windows/ATE) When a dialog box is created and the main window is invisible (e.g. was launched with -z or made invisible by an AUI_WINDOW call), the dialog box is made into a top level window so that it shows on the task bar. You can also force a dialog to have the top level property by adding the flag MBF_DLGNOPARENT (32, same as MBF_LFTEXT) when it is created. But in that case, both the main window and the dialog will appear on the task bar. Currently there no way to convert an existing standard dialog to a top level one.