GoFiler Legato Script Reference   Legato v 1.5b Application v 5.24b

Table of Contents	< < Previous	Next >>

 

Chapter Nine — Dialog Functions (continued) 

9.9 Dialog Functions

9.9.1 Overview

There are a series of functions and callback procedures specifically designed for dialogs. In most cases once a dialog has been opened with the DialogBox function, the serving procedures will automatically know to which dialog page they belong.

Data can be passed to and from the dialog procedures using global data (while not elegant from structured programming stand point, it is effective.

When a dialog exits, either from OK/Cancel or a procedure, control will return to the next statement after the DialogBox function. 

9.9.2 Dialog Procedures

When a dialog box is defined and opened, various “procedures” will be run. While the most basic are the loading of controls and the retrieval and validation of controls, there are a number of procedures that can be hooked.

If a script chooses to accept the procedure, it need only name a function with a combination of the programmer defined prefix and a predefined suffix. For example:

rc = DialogBox(“MyQueryDialog”, “query_”);

...

int query_load() {

    (... load controls ...)

    return ERROR_NONE;
}

In the above example, the DialogBox function has the prefix defined as “query_”. A function has been defined as “query_load” which will be called once to load the controls.

Misspelled procedure names will not result is errors. Rather, the dialog processor will not locate a matching function for a procedure and as a result required procedure will perform default processing.

The procedures are as follows:

void action (int c_id, int c_ac) {...}

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. The c_id and c_ac are set for the control’s ID and the submessage; respectively.

The action procedure can be used to start other functions (such as a tool button press) or process a list or combo box change. The state of controls are also changed in response to an action call. This is one of the only procedures that is repeatedly called from the dialog page. Programmers should use caution in setting control actions as they may cause an endless loop with an action-set state-action cycle.

The c_ac parameter is the lParam for the message which is normally the sending window’s handle but can be another value for certain controls. The return value is not used.

Some controls will use the more sophisticated notify procedure. If the notify procedure is not present, then it will default to the action procedure in a limited basis.

Note that some controls (notably original controls such as edit and list box) send focus message via actions such as EN_SETFOCUS (edit notification, set focus). Later controls will send notifications for focus change and are more uniform using NM_SETFOCUS. In addition, as an expansion, some controls use expanded notifications. Such messages must be processed by the notify procedure.

allow_next (--)‡

[This wizard procedure is called after enter page when the Next button is available. Returning an ERROR_ mode causes the next button to gray.]

button_a (--)‡

[This tools button procedures is when the user presses the tools button on a property sheet or wizard. This button is only available if flags are set when the dialog is created.]

button_b (00)‡

[This tools button procedures is when the user presses the tools button on a property sheet or wizard. This button is only available if flags are set when the dialog is created.]

can_finish (--)‡

[This wizard procedure is called after enter page when the DIALOG_WIZ_EARLY_FINISH flag is on. Returning an ERROR_ mode causes the finish button to gray except on the last page.]

int cancel (int c_id) {...}

This procedure is called on close or cancel of a basic dialog (single page). The c_id parameter contains the source id. This function is not called on property sheet dialogs. The caller returns an ERROR_ to keep the dialog from closing. Returning any other value will stop the dialog from closing. A cancel event can occur from a button with the control id as IDCANCEL (2), the user pressing the Esc key, pressing the [X] close icon in the upper right corner or selects ‘Close’ from the system menu or double clicks on the window icon.

A system menu close command will set the id to SC_CLOSE (0xF060). The return value in this context is ignored. However, this allows the dialog to exit, if desired, when other close options are be prevented.

control_measure (--)‡

[These functions process owner draw controls. The function should return non-zero if it processed the drawing.]

control_min_max (--) ‡

[This function is called by Windows when the user sizes a window to determine what the minimum and maximum window sizes are]

control_size (--) ‡

[This function is called by Windows when the user sizes to inform the window of the new size and allow it to adjust accordingly]

control_sizing (--) ‡

[This function is called by Windows when the user sizes a window to allow the window to override the dragged size]

ctlcolordlg (--)‡

[This function is called when the dialog is about to be painted. Return a brush handle or false to use default processing]

int destroy (--) {...}

This function is called on the close of the page to allow the script to release any resources created for the page. The return value is not used.

draw_control (--) ‡ (change to control_paint?

[These functions process owner draw controls. The function should return non-zero if it processed the drawing.]

int enter_page (--) {...}

On property sheet dialogs, this procedure is called as the page is “entered" when the user clicks on a tab or "Next" button. The call is performed prior to page load (if the page has not been loaded) and gives the caller the option of stopping the page from displaying. Return ERROR_NONE to allow the page to be entered.

This procedure is not called for basic dialogs. Do not add or delete pages within this function.

int exit_page (--) {--}

On property sheet dialogs, this function is called as the page is “exited” or when “OK” or apply is pressed. It gives the caller 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 LOWORD can contain a control ID to set focus on.

Do not add or delete pages within this function.

finish (--)‡

[On wizard page dialogs, this function is called when "Finish" is pressed. It gives the caller 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 LOWORD can contain a control to set focus on. Do not add or delete pages within this function.]

int help (--) {...}

When either the F1 key or the Help button is pressed, this procedure is called. If FALSE or ERROR_NONE is returned, default help processing is performed.

int load (--) {...}

The “load” procedure hooks is the first item called to allow the script to load the dialog (layers the Window WM_INITDIALOG message).

For basic dialogs, returning TRUE will force windows set the default control focus (the first control that can accept input receives focus). If FALSE / ERROR_NONE is returned, the caller can set the focus within this function. If focus is not set, the first control that can accept keyboard input will receive focus.

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.

The load is called before a dialog box or page is displayed. Note that when using Property Sheets, the load is only called the first time a page is activated. Therefore, the first tab will cause a load while subsequent tabs will call their load function only when the tab is displayed.

Returning a formatted error code will abort the dialog load. This is not considered best practice for property sheets. 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.

next_page (tbd)‡

[This a wizard procedure (along with previous_page) that are called on next and back back action to set the new page index to be displayed. Returning an ERROR_ mode causes the normal page order to be used. Returning ERROR_NONE will override the default page ordering. [The LOWORD (value) contains the dialog ID.]]

void notify (int c_id, int c_ac) {...}

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. These are as follows:

	SDK Definition		Comment
	NM_CHAR		A character key is processed.
	NM_CLICK		User clicked with the left mouse button.
	NM_CUSTOMDRAW		A control is about to engage in a drawing operation.
	NM_CUSTOMTEXT		Notifies that a custom text operation is beginning.
	NM_DBLCLK		Sent on a user double-clicked of the left mouse button.
	NM_FONTCHANGED		Sent by a control when the control has changed a font.
	NM_HOVER		Sent by a control when the mouse hovers over an item.
	NM_KEYDOWN		User pressesed a key.
	NM_KILLFOCUS		Control has lost keyboard focus.
	NM_LDOWN		Sent on a left mouse button down press.
	NM_NCHITTEST		Sent by a control when the control receives an internal WM_NCHITTEST window message.
	NM_OUTOFMEMORY		Notifies a control control could not complete an operation because there was not enough memory available.
	NM_RCLICK		Sent on a right mouse button click.
	NM_RDBLCLK		Sent on a right mouse button click.
	NM_RDOWN		Sent on a left mouse button down press.
	NM_RETURN		Notifies a tree-view control's parent window that the control has the input focus and that the user has pressed the key.
	NM_RELEASEDCAPTURE		Notifies a toolbar control's parent window that the control is releasing mouse capture.
	NM_SETCURSOR		Notifies a tree-view control's parent window that the control is setting the cursor in response to a WM_SETCURSOR message.
	NM_SETFOCUS		A control has received the input focus.
	NM_THEMECHANGED		Notifies a by a control when the theme has changed.
	NM_TOOLTIPSCREATED		Notifies a toolbar's parent window that the toolbar has created a tooltip control.
	NM_TVSTATEIMAGECHANGING		Sent by a tree-view control to its parent window that the state image is changing.

 

Check the individual control’s documentation for more information.

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.

int ok (--) {...}

On a basic dialog (with one page), this procedure is called on processing the OK button. For a multiple page dialog, this function is called when the last active page is closing on an OK or Apply. Programmers can use this function to perform any final or cross-page validation and data retrieval. Returning ERROR_NONE allows the dialog to close. Return any other value prevents close. If an ERROR_ mode is not set, then LOWORD of the value is used as the control ID to set focus on (offending value). If non-zero, the HIWORD can be used to change the active page for the control. The page value must be non-zero inclusive (1 is the first page).

paint (--)‡

[This function is called when a paint message is received for a page. Callers may get a DC and perform paint operation directly to the dialog. The Begin and EndPaint function do not have to be called.]

pre_message (--)‡

[This function is called prior to processing all messages except the "load" call. The caller may intercept and process any dialog message. Return non-zero to indicate that the message has been processed and further processing by the dialog functions is not required.]

previous_page (--)‡

[See next_page.]

void size_changed (int width, int height, int mode) {...}

This procedure is called any time the window size is change. The width and height are the new client area for the dialog page. The mode specifies the type of sizing requested as SIZE_RESTORED, SIZE_MINIMIZED, SIZE_MAXIMIZED, SIZE_MAXSHOW, or SIZE_MAXHIDE. When dragging, the frequency of the calls is related to how quickly the script responds to the size messages.

The size procedure can be used to resize or reposition the contents of a dialog. Use the scrollbar common control to add a resize grip to the corner of a dialog box to resize a basic dialog.

theme_changed (--)‡

[This function is called by Windows when the theme of the application changes. Overrides should call the parent function as well as their own processing.]

void timer (int id) {...}

The timer procedure is called when a timer event has expired. The id parameter is the same value as supplied to the DialogSetTimer function. The return value is ignored.

tools_button (--)‡

[This tools button procedures is when the user presses the tools button on a property sheet or wizard. This button is only available if flags are set when the dialog is created.]

int validate (--) {...}

This procedure is called when a page is ready to be validated prior to exit. This 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 “ok”. Return any other value prevents close. If an ERROR_ mode is not set, then LOWORD of the value is used as the control ID to set focus on (offending value). If non-zero, the HIWORD can be used to change the active page for the control. The page value must be non-zero inclusive (1 is first page). Otherwise the offending page will be brought into view.

int wrap_up (--) {...}

This procedure is called when all pages have been validated and the final ok processor has completed for a property sheet. It is not called on a basic dialog. The wrap up allows the tab to perform any data cleanup, transfer or cancel processing (release data saved for a cancel processor). The wrap cannot stop the close process and should not report errors except internal or fatal errors. Note that wrap up function can be called even if the page was NOT activated.

9.9.3 Default Control Error Codes

All dialog control level functions will return error codes (or have them set for retrieval by the GetLastError function) that are common. Any other errors are specified in the individual functions.

ERROR_CONTEXT | ERROR_INVALID_HANDLE

Indicates that the call was made outside the context of a dialog procedure.

ERROR_RANGE | 1

Indicates the control ID specified is invalid (the window does not exist).

9.9.4 Dialog Box Functions

Dialog Creation:

DialogBox — Opens a single or multi-page modal dialog box using the resources and procedures.

Dialog Position:

DialogGetFrameHeight — Gets the height dimension of the frame for an open dialog.

DialogGetFrameWidth — Gets the width dimension of the frame for an open dialog.

DialogGetFrameXPosition — Gets the X screen position of an open dialog container.

DialogGetFrameYPosition — Gets the Y screen position of an open dialog container.

DialogGetPageHandle — Gets the window handle of a page in the current procedure.

DialogGetPageHeight — Gets the height dimension of the client area of the open dialog.

DialogGetPageWidth — Gets the width dimension of the client area of the open dialog.

DialogGetPageXPosition — Gets the X screen position of an open dialog client page.

DialogGetPageYPosition — Gets the Y screen position of an open dialog client page.

DialogPositionAtMouse — Positions the top left of the current dialog to the current mouse position.

DialogPositionCenter — Centers the current dialog.

DialogPositionLeft — Positions the current dialog to the left.

DialogPositionRight — Positions the current dialog to the right.

DialogSetPosition — Sets the dialog position to an absolute screen position.

Dialog Control:

DialogEnumerateControls — Enumerates all the controls on the current or specified dialog page.

DialogGetCaption — Gets the dialog caption.

DialogGetResourceName — Returns the name of resource for the current dialog.

DialogSetCaption — Sets the caption for the current dialog.

DialogSetIcon — Sets an icon for a dialog caption from a file or Resource Object.

DialogSetReturnValue — Sets the return value for a single page dialog and forces the dialog to exit.

DialogPostCancel — Posts condition as if user pressed Cancel.

DialogPostOK — Posts condition as if user pressed OK.

IsDialogPropertySheet — Checks whether the current dialog is a property sheet style dialog.

Dialog Help:

DialogSetHelp — Sets a CHM or URL for help reference for a dialog.

Menus:

DialogSetAdHocMenu — Sets an ad hoc menu using a string array of menu items.

DialogSetMenu — Sets a menu using a string array of defined menu functions.

Page revised 2024-10-21

 

Table of Contents	< < Previous	Next >>

GoFiler Legato Script Reference — Generated on 10/21/2024

© 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.