Updated December 2013; see History
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 CTLOP_DEL 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 a click string to the keyboard buffer, which should generate an exitcode in the dialog's event handler or input routine, allowing the application to close the dialog (with opcode CTLOP_DEL). By default, the click string is a single escape character, i.e. chr(27), which generally translates to exitcode 1. But as of 6.1.1355.0 you can override it by putting the desired click string (e.g. VK_xF999 for exitcode 999) into the cmd parameter and not setting the MBF_KBD flag in the ctype parameter. If you set the MBF_KBD flag, then clicking anywhere on the dialog will send the click string, as if it were a button or other clickable control.
To simplify programming, if the dialog also has a CANCEL button, you might as well program it to send the same click string 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 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 either of the Command Line Switches -z or -zi (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 XCALL AUI, AUI_WINDOW, SW_HIDE and then proceed to create a dialog normally. |
History
2013 December, A-Shell 6.1.1368: WS_VSCROLL flag in the winstyle parameter allows creation of vertically scrollable dialogs.
2013 July, A-Shell 6.1.1356: Clicks on controls belonging to windows not within the current modal dialog are normally ignored, unless they come from a modeless dialog. The idea is that modeless dialogs operate outside of the normal dialog hierarchy. This rule has now been modified slightly to ignore clicks from a modeless dialog which is a parent of the current modal dialog. In other words, if a modeless dialog launches a modal child dialog, the user will have to terminate that modal child dialog prior to interacting again with the original modeless dialog.
2013 March, A-Shell 6.1.1340: New ctype2 flag MBF2_GLOBAL allows a control to be clickable even if not part of the current modal dialog.
Subtopics
