9.4 DUIM-Frames Module
<dialog-frame>
Open abstract instantiable class
Summary
The class of dialog frames.
Superclasses
Init-keywords
mode:- An instance of type
one-of("modal", #"modeless", #"system-modal"). Default value:#"modal". exit-callback:- An instance of type
false-or(type-union(<command>, <function>)). Default value:exit-dialog. exit-button:- An instance of type
false-or(<button>). Default value:#f. exit-enabled?:- An instance of type
<boolean>. Default value:#t. cancel-callback-
An instance of type
false-or(type-union(<command>, <function>)). Default value:cancel-dialog. cancel-button:- An instance of type
false-or(<button>). Default value:#f. help-callback:- An instance of type
false-or(type-union(<command>, <function>)). Default value:#f. help-button:- An instance of type
false-or(<button>). Default value:#f. exit-buttons-position:-
An instance of type
one-of(#"top", #"bottom", #"left", #"right"). Default value:#"bottom". pages:- An instance of type
false-or(<sequence>). Default value:#f. page-changed-callback:-
An instance of type
false-or(<function>). Default value:#f.
Library
duim-frames
Module
duim-frames
Description
The class of dialog frames. These frames let you create dialog boxes for use in your applications. All buttons in a dialog frame are automatically made the same size, and are placed at the bottom of the dialog by default. When at the bottom of the dialog, buttons are right-aligned.
By default, all dialogs are modal, that is, when displayed, they take over the entire application thread, preventing the user from using any other part of the application until the dialog has been removed from the screen. To create a modeless dialog (that is, one that can remain displayed on the screen while the user interacts with the application in other ways) you should set the mode: keyword to #"modeless". Note, however, that you should not normally need to do this: if you need to create a modeless dialog, then you should consider using a normal DUIM frame, rather than a dialog frame.
The init-keywords exit-button:, and cancel-button: specify the exit and cancel buttons in the dialog. The user clicks on the exit button to dismiss the dialog and save any changes that have been made as a result of editing the information in the dialog. The user clicks on the cancel button in order to dismiss the dialog and discard any changes that have been made.
In addition, the exit-callback: and cancel-callback: init-keywords specify the callback that is invoked when the Exit or Cancel buttons in the dialog are clicked on. These both default to the appropriate function for each button, but you have the flexibility to specify an alternative if you wish. If you do not require a Cancel button in your dialog, specify cancel-callback: #f. Similarly, specify exit-callback: #f if you do not require an Exit button.
All dialogs should have an exit button, and most dialogs should have a cancel button too. You should only omit the cancel button in cases when the information being displayed in the dialog cannot be changed by the user. For example, a dialog containing an error message can have only an exit button, but any dialog that contains information the user can edit should have both exit and cancel buttons.
Two init-keywords are available for each button so that a given button may be specified for a particular dialog, but need only be displayed in certain circumstances. This lets you define subtly different behavior in different situations.
The exit-enabled?: init-keyword is used to specify whether the exit button on the dialog is enabled or not. If #f, then the exit button is displayed on the dialog, but it is grayed out.
The help-button: init-keyword specifies the help button in the dialog. Note that, in contrast to the exit and cancel buttons, specifying the button gadget to use in a dialog determines its presence in the dialog: it is not possible to define a help button and then only display it in certain circumstances. You are strongly encouraged to provide a help button in all but the most trivial dialogs.
The help-callback: init-keyword defines a callback function that is invoked when the help button is clicked. This should normally display a context-sensitive help topic from the help file supplied with the application, although you might also choose to display an alert box with the relevant information.
The exit-buttons-position: init-keyword defines the position in the dialog that the exit and cancel buttons occupy (and any other standard buttons, if they have been specified). By default, buttons are placed where the interface guidelines for the platform recommend, and this position is encouraged in most interface design guidelines. Usually, this means that buttons are placed at the bottom of the dialog. Less commonly, buttons may also be placed on the right side of the dialog. Buttons are not normally placed at the top or on the left of the dialog, though this is possible if desired.
The pages: init-keyword is used for multi-page dialogs such as property frames and wizard frames. If used, it should be a sequence of elements, each of which evaluates to an instance of a page.
The page-changed-callback: is a callback function that is invoked when a different page in a multi-page dialog is displayed.
Operations
The following operations are exported from the DUIM-Frames module.
cancel-dialog dialog-cancel-button dialog-cancel-button-setter dialog-cancel-callback dialog-cancel-callback-setter dialog-exit-button dialog-exit-button-setter dialog-exit-callback dialog-exit-callback-setter dialog-exit-enabled? dialog-exit-enabled?-setter dialog-exit-callback dialog-exit-callback-setter dialog-help-button dialog-help-button-setter dialog-help-callback exit-dialog start-dialog
Example
The following example creates and displays a simple dialog that contains only an exit button, cancel button, and help button, and assigns a callback to the help button.
define variable *dialog* = make(<dialog-frame>, exit-button?: #t, cancel-button?: #t, help-callback: method (gadget) notify-user (format-to-string ("Here is some help", gadget)) end);
start-frame(*dialog*);