|
Purpose |
Display and activate a dialog, allowing it to receive user input and messages. The DIALOG SHOW MODAL statement blocks (halts) until the dialog is destroyed with DIALOG END. |
|
Syntax |
DIALOG SHOW MODAL hDlg [[,] CALL callback] [TO lResult&] |
|
Remarks |
hDlg identifies a dialog created using DIALOG NEW. You can specify a Callback Function for all dialog messages using the CALL keyword, followed by the name of the Callback Function. When a modal dialog is displayed, the DIALOG SHOW MODAL statement is blocked until the dialog is destroyed with DIALOG END. During the duration of the dialog, the Callback Function code is executed in response to messages for the dialog. If a parent was specified in the DIALOG NEW statement, the parent window is disabled until the modal dialog is destroyed. |
|
callback |
If specified, dialog messages are routed to the nominated Callback Function. Just before a dialog is initially displayed, the dialog Callback Function is sent a %WM_INITDIALOG message. By processing this message within the dialog callback, an application can take the opportunity to load controls with data before the controls become visible to the user. For example, a list box control could be loaded with a list of items so that the control appears populated with data when initially displayed. The nominated callback function name must be a CALLBACK FUNCTION or a compile-time Error 547 ("Callback function required") will occur. |
|
lResult& |
When the modal dialog is destroyed using the DIALOG END statement, the resulting value is assigned to the lResult& variable, if specified. lResult& is excluded from becoming a Register variable by the compiler, since this value can be assigned from outside of the function containing the DIALOG SHOW MODAL statement, and this may only be performed with a memory variable. However, if the target variable is explicitly declared as a register variable, PowerBASIC raises a compile-time Error 491 ("Invalid register variable"). |
|
See also |
Dynamic Dialog Tools, DIALOG END, DIALOG NEW, DIALOG SHOW MODELESS |