  |
GoFiler Legato Script Reference
Legato v 1.5d Application v 5.25a
|
| Table of Contents | < < Previous | Next >> |
Chapter Nine — Dialog Functions (continued)
Overview
The DialogBox function creates a basic dialog or a property sheet dialog and returns when the user presses OK/Cancel or one of the service procedures forces an exit.
Syntax/Parameters
Syntax
int = DialogBox ( string resource | string[] resource | int id,
[string prefix | string[]
prefix ], [string caption] );
Parameters
resource
A string or string array containing the name or names of a dialog resource. The resource must be defined within the script application. This is not a direct symbol for the resource but rather a string literal as the name of the declared resource. For example, if the resource is named ConfirmRequestDlg, the literal parameter would be "ConfirmRequestDlg":
... (code) ...
DialogBox("ConfirmRequestDlg", "cr_");
... (code) ...
#resource
ConfirmRequestDlg DIALOGEX 0, 0, 220, 60
... (resource) ...
#endresource
Or,
id
An optional int value to identify the resource in place of the resource parameter. The id value gets converted to a string to identify the resource. This mode is provided to maintain compatibility with resource editors and other tools that prefer to identify resources by integer using defined values.
prefix
An optional string or string array containing the procedure prefix. This prefix is added to predefine suffix names for various dialog procedures. If a procedure does not exist for the define name, the internal default procedure is executed. When an array is specified for the resource, the prefix should also be an array with each element corresponding to the resource.
caption
An optional string that becomes the caption of the dialog. For basic dialogs, this is an optional parameter. When not specified, the caption from the resource is employed. For property sheet style dialogs, this string is the caption since each resource title/caption becomes the page tab name. The caption may also be changed or set with the DialogSetCaption function.
Return Value
An int containing the return value from the dialog (normally ERROR_NONE or ERROR_CANCEL) or any value assigned by the exit process of the dialog’s procedures. The return value can also be an error code either from the dialog process or from the service routines.
Programmers should avoid using the return code -1 from their dialogs since it conflicts with the Windows SDK error for a dialog box problem.
Remarks
If the resource parameter is a string array, the dialog will be created as a multi-page property sheet style dialog, even if the array has a single entry. Basic and property sheet dialog exhibit different behavior with respect to appearance and handling procedures. See Section 9.4 Dialog Resource Templates for information regarding the construction of resources.
Resource errors will result in a runtime termination of the script. Any Legato script error will cause an exit of the offending procedure, close of the dialog and then a runtime error. On multiple page dialogs, it is not uncommon for the Windows O/S to remove pages that contain bad class names and other problems and then continue.
For multiple page dialogs, procedures for only the first page of the dialog are guaranteed to be called. Other page procedures are called when the tab for that page or the Next button is pressed for a wizard style dialog.
Important note: if a procedure is spelled incorrectly, it is ignored since the dialog procedure manager will not locate the associated function. This is a common problem and can be hard to diagnose at first since the dialog procedure will fall back to the default processing.
To move data into and out of dialog procedures, global variables must be used.
Modal dialog boxes cannot be opened by scripts running in the background.
Procedures
A central part of the dialog process are special routines called dialog procedures. The procedure prefix, as specified above, is used to lead the name of script subroutines to process various dialog events. Events can be broken into three main groups: initialization/loading, control actions and exit/validation. If a routine is not provided by the script, the default action takes place (which is normally no action).
For property sheets, different prefixes should be used for each page. The procedures that can be connected are as follows (see the Section 9.9 Dialog Functions section for additional information):
Page/Tab Control — these procedures are invoked during certain dialog page events:
load
Load Dialog Page — This procedure is called on the initial load of a page. It is called only once and only when a page becomes visible. Within Property Sheet style dialogs (tabbed dialogs), scripts cannot rely on this procedure to be called if the page is not the first to be displayed.
The load procedure is commonly used to load and setup controls and also to set the initial state of controls. For example, combo boxes can be loaded and certain controls disabled depending on conditions.
For basic dialog, the return value can be TRUE or FALSE (ERROR_NONE). If FALSE, keyboard focus is set to the specified control using the ControlSetFocus function or first control that can accept keyboard focus in resource order. If TRUE, focus is set to the first control in the resource order that will accept input without regard any other focus changes.
For property sheet dialogs, focus is always set to the first control in the resource order that will accept input without regard any other focus changes.
Returning a formatted error code will abort the dialog load. This is not considered best practice for property sheets since the load procedure is not called until a page is loaded. If a page tab is clicked on and that load procedure returns an error, the dialog will immediately close and return the error code used to exit the load procedure. For the first tab, a returned error code will cause the page to briefly appear and then close.
For reference purposes, this procedure is called in response to the Windows WM_INITDIALOG message.
destroy
Page Being Destroyed — This is the last procedure called when a dialog is closing. It is mostly used to release global resources that may be used during paint or other advanced operations. Destroy is called without regard to whether the page was ‘OKed’ or ‘Canceled’.
Do not attempt to access controls during a destroy procedure. The return value is not used. If the dialog is in the clipboard chain, it is automatically released.
For reference purposes, this procedure is called in response to the Windows WM_DESTROY message. It is also call after all internal resources have been released.
Control Actions:
ok
Pressed the OK Button (accepted or pressed, or last page in wizard) — On a basic dialog (with one page) this is called on processing OK. For a multiple page dialog, this function is called when last active page is closing on an OK or Apply. Programmers can use this procedure to perform any final or cross-page validation and data retrieval. Returning ERROR_NONE allows the dialog to close. Returning any other value prevents close. If an ERROR_ mode is set, then low word of the value is used as the control ID to set focus on (offending value). If non-zero, the high word can be used to change the active page for the control. The page value must non-zero inclusive (+1). Use the Make32Word function to create the return value.
cancel
Cancel Button (or close) — This procedure is called on close or cancel of a basic dialog (single page). This procedure is not called on property sheet dialogs. The caller returns an ERROR_ to keep the dialog from closing. By default, the Esc (escape) key will normally also issue a cancel.
help
Help Button — When the F1 or the Help button is pressed, this procedure is called. If FALSE or ERROR_NONE is returned, default help processing is performed.
action
Action Message from a Control — This procedure is called for any control action that generates a message such as a button press (except OK, Cancel, Help, etc.) or selection change. (Note this procedure is called frequently including control focus changes.)
The procedure definition should include two int values in the definition, control id and action code, for the control’s ID and the submessage respectively. See each control for submessage values. By convention, submessage values from command actions are positive and messages passed from a notification are negative.
The return value is not used and can be declared as void.
notify
Notify Message from a Control — While similar to action, some controls send a notify message as opposed to a command action message, or segment types messages across notify and action. The notify procedure operates in the same manner as the action procedure but supports certain controls that use the Windows notification. In addition, some controls will send additional notifications (NM_ prefix as well as others) only via the notify procedure. If the notify procedure is not present, the direct user type messages will be routed to the action procedure. In many cases, the action procedure is sufficient to handle control messages. Only supported messages and control types are passed to the action procedure. See the specific control type for further information on notify messages.
The notification call is passed as an int for the control id and an int for the action code. Notification action codes are negative numbers. The return value is not used.
validate
Page Request Validate — This procedure is called when a page is ready to be validated prior to exit. This procedure should be used rather than the ok procedure to get and validate page content. Returning ERROR_NONE allows the dialog to continue to close and eventually proceed to the ok procedure. Return any other value prevents close. If an ERROR_ mode is not set, then low word of the value is used as the control ID to set focus on (offending value). If non-zero, the high word can be used to change the active page for the control. The page value must be non-zero inclusive (+1). Otherwise the current offending page will be brought into view. Use the Make32Word function to create the return value.
wrap_up
All Pages Existing on OK or Apply — This procedure is called when all pages have been validated and the final ok processor has completed. The wrap-up allows the page to perform any data cleanup, transfer or cancel processing (release data saved for a cancel processor). The wrap-up procedure cannot stop the close process and should not report errors except internal or fatal errors. Note that the wrap-up function can be called even if the page was NOT activated.
enter_page
Request Page Enter (enter this page) — On multiple page dialogs, this procedure is called as the page is “entered” when the user clicks on a tab or Next button. The procedure is prior to page load (if the page has not been loaded) and gives the program the option of stopping the page from displaying. Return ERROR_NONE to allow the page to be entered. Do not add or delete pages within this function.
exit_page
Request Page Change (exit this page) — On multiple page dialogs, this procedure is called as the page is exited or when OK or Apply is pressed. It gives the script the option of validating certain information and keeping the user from exiting the page. If the return is ERROR_NONE, the page will be exited, if non-zero and not an error code, the low word can contain a control to set focus on. Do not add or delete pages within this function.
finish
Pressed Finish (wizard button) — On wizard page dialogs, this function is called when the Finish button is pressed. It gives the script the option of validating certain information and keeping the user from exiting the page. If the return is ERROR_NONE, the page will be exited, if non- zero and not an error code, the low word can contain a control to set focus on. Do not add or delete pages within this function.
Windows and controls
clipboard_changed
Clipboard Contents Changed — This procedure is called only if the ClipboardAttachDialog has been called to enable clipboard notifications. Programmers are cautioned about altering the clipboard in the notification procedure which generates another clipboard change message,
timer
Process Timer Message — This procedure is called with a single int value specifying the timer ID. See the DialogSetTimer function for additional information.
size_changed
Dialog Container Window Size Changed — If the dialog has a size grip and the user drags the size or if the dialog size is changed via an API command, this procedure is called.
Related Functions
Platform Support
Go13, Go16, GoFiler Complete, GoFiler Corporate, GoFiler, GoFiler Lite, GoXBRL
Legato IDE, Legato Basic
| Table of Contents | < < Previous | Next >> |
© 2012-2024 Novaworks, LLC. All rights reserved worldwide. Unauthorized use, duplication or transmission prohibited by law. Portions of the software are protected by US Patents 10,095,672, 10,706,221 and 11,210,456. GoFiler™ and Legato™ are trademarks of Novaworks, LLC. EDGAR® is a federally registered trademark of the U.S. Securities and Exchange Commission. Novaworks is not affiliated with or approved by the U.S. Securities and Exchange Commission. All other trademarks are property of their respective owners. Use of the features specified in this language are subject to terms, conditions and limitations of the Software License Agreement.