MotifEnv

Motif Dialog Patterns

The following figure shows the patterns constituting the MotifEnv dialog patterns. Patterns from XtEnv are shaded gray, and other MotifEnv patterns are shaded light-gray.

The following is a brief presentation of the different patterns:

SelectionBox: a general dialog widget that allows the user to select one item from a list. A SelectionBox includes the following:
1. a scrolling list of alternatives,
2. an editable text field for the selected alternative,
3. labels for the list and text field, and
4. three or four buttons. The default button labels are OK, Cancel, and Help. By default an Apply button is also created; if the parent of the SelectionBox is a DialogShell it is managed, and otherwise it is unmanaged.
One additional WorkArea child may be added to the SelectionBox after creation. The user can select an item in two ways: by scrolling through the list and selecting the desired item or by entering the item name directly into the text edit area. Selecting an item from the list causes that item name to appear in the selection text edit area. The user may select a new item as many times as desired. The item is not actually selected until the user presses the OK PushButton.
PromptDialog: Utility pattern to instantiate a DialogShell and an unmanaged SelectionBox child of the DialogShell. A PromptDialog prompts the user for text input. It includes a message, a text input region, and three managed buttons. The default button labels are OK, Cancel, and Help. An additional button, with Apply as the default label, is created unmanaged; it may be explicitly managed if needed.
SelectionDialog: Utility pattern to instantiate a DialogShell and an unmanaged SelectionBox child of the DialogShell. A SelectionDialog offers the user a choice from a list of alternatives and gets a selection. It includes the following:
1. a scrolling list of alternatives,
2. an editable text field for the selected alternative,
3. labels for the text field, and
4. four buttons. The default button labels are OK, Cancel, Apply, and Help.
FileSelectionBox: used to traverse through directories, view the files and subdirectories in them, and then select files. A FileSelectionBox has five main areas:
1. a text input field for displaying and editing a directory mask used to select the files to be displayed,
2. a scrollable list of filenames,
3. a scrollable list of subdirectories,
4. a text input field for displaying and editing a filename, and
5. a group of PushButtons, labeled OK, Filter, Cancel, and Help.
The list of filenames, the list of subdirectories, or both can be removed from the FileSelectionBox after creation by using the patterns unmanageFileNames and unmanageSubdirectories.
FileSelectionDialog: utility pattern to instantiate a DialogShell and an unmanaged FileSelectionBox child of the DialogShell.
Command: a special-purpose composite widget for command entry that provides a built-in command-history mechanism. Command includes a command-line text-input field, a command-line prompt, and a command history list region. Whenever a command is entered, it is automatically added to the end of the command-history list and made visible. This does not change the selected item in the list, if there is one.
MessageBox: MessageBox is a dialog pattern used for creating simple message dialogs. Specializations based on MessageBox are provided for several common interaction tasks, which include giving information, asking questions, and reporting errors. A MessageBox dialog is typically transient in nature, displayed for the duration of a single interaction. A MessageBox can contain a message symbol, a message, and up to three standard default PushButtons: OK, Cancel, and Help. It is laid out with the symbol and message on top and the PushButtons on the bottom. The Help button is positioned to the side of the other push buttons.
ErrorDialog: Utility pattern to instantiate a DialogShell and an unmanaged MessageBox child of the DialogShell. An ErrorDialog warns the user of an invalid or potentially dangerous condition. It includes a symbol, a message, and three buttons. The default symbol is an octagon with a diagonal slash. The default button labels are OK, Cancel, and Help.
InformationDialog: Utility pattern to instantiate a DialogShell and an unmanaged MessageBox child of the DialogShell. An InformationDialog presents a short information to the user. It includes a symbol, a message, and three buttons. The default symbol is lower case i. The default button labels are OK, Cancel, and Help.
MessageDialog: Utility pattern to instantiate a DialogShell and an unmanaged MessageBox child of the DialogShell. A MessageDialog gives the user some message. It includes a symbol, a message, and three buttons. By default there is no symbol. The default button labels are OK, Cancel, and Help.
QuestionDialog: Utility pattern to instantiate a DialogShell and an unmanaged MessageBox child of the DialogShell. A QuestionDialog asks the user a question. It includes a symbol, a message, and three buttons. The default symbol is a question mark. The default button labels are OK, Cancel, and Help.
WarningDialog: Utility pattern to instantiate a DialogShell and an unmanaged MessageBox child of the DialogShell. A WarningDialog warns the user of an invalid or potentially dangerous condition. It includes a symbol, a message, and three buttons. The default symbol is an exclamation point. The default button labels are OK, Cancel, and Help.
WorkingDialog: Utility pattern to instantiate a DialogShell and an unmanaged MessageBox child of the DialogShell. A WorkingDialog informs the user, that some lengthy computations is going on, for instance. It includes a symbol, a message, and three buttons. The default symbol is an hourglass. The default button labels are OK, Cancel, and Help.
FormDialog: Utility pattern to instantiate a DialogShell and an unmanaged Form child of the DialogShell. A FormDialog is used for interactions not supported by the standard dialog set. It does not include any labels, buttons, or other dialog components. Such components should be added to the FormDialog by the application.
BulletinBoardDialog: Utility pattern to instantiate a DialogShell and an unmanaged BulletinBoard child of the DialogShell. A BulletinBoardDialog is used for interactions not supported by the standard dialog set. It does not include any labels, buttons, or other dialog components. Such components should be added to the BulletinBoardDialog by the application.

Examples using Motif Dialog Patterns

The following example completes the MainWindow example shown earlier, by adding the menu bar, and creating a MessageDialog to pop up when the help button in the menu bar is activated.

mainwindow.bet, continued

mbar: @MenuBar
  (# fileButton: @CascadeButton
       (# init::< 
            (# do 'File' -> labelString; 'F' -> mnemonic #)
       #);
     fileMenu: @PullDownMenu
       (# quit: @PushButtonGadget
            (# init::<
                 (# 
                 do 'Quit' -> labelString;
                    'Q' -> mnemonic;
                    'Ctrl<Key>q' -> accelerator;
                    'Ctrl+q' -> acceleratorText;
                 #);
               activateCallBack::< (# do stop #);
            #);
          init::< (# do quit.init #);
       #);
     helpButton: @CascadeButton
       (* The button in the MenuBar that activates the HelpBox *)
       (# helpBox: @MessageDialog
            (* The dialog that displays the help message *)
            (# init::<
                 (#
                 do 'This "help" should be extended!'
                       -> messageString;
                    'Help' -> dialogTitle;
                    unManageCancel; unManageHelp;
                 #);
            #);
          activateCallback::< (# do helpBox.manageChild #);
          init::< 
            (# 
            do 'Help' -> labelString; 'H' -> mnemonic;
               helpBox.init 
            #);
       #);
     init::< 
       (# 
       do fileButton.init;  fileMenu.init; 
          fileMenu -> fileButton.subMenuId;
          helpButton.init;
          helpButton -> menuHelpWidget;
       #);
  #);

The example shows how to create the MenuBar and File menu for the MainWindow. Except for the use of mnemonics and accellerators, this has been explained in the section on Menus earlier in the manual. A mnemonic is a "keyboard equivalent", which can be used to invoke menus and menu items, when the menus are posted. Accelerators can be used to invoke menu items even when the menu containing the item is not posted.

The help dialog is invoked from a CascadeButton called helpButton in the MenuBar. Two special things happen in the init virtual of the MessageDialog:

The dialogTitle resource is set to the text "Help". This is because some window managers decorate the dialogs with title bar etc. The dialogTitle resource determines what will appear in the title bar in that case.
A MessageDialog by default contains three buttons: an OK button, a Cancel button, and a Help button. The Cancel and Help buttons do not make much sence within a help dialog, so these are removed using the unmanageCancel and unmanageHelp patterns. This is the easiest way to make a dialog with just an OK button, since, unfortunately, Motif does not include such a dialog.

The windows below show how the help dialog looks, when popped up from the mainwindow application.

The following example shows how to use the FileSelectionBox pattern to invoke a standard file specification dialog:

filedialog.bet

ORIGIN '~beta/Xt/motifenv';
INCLUDE '~beta/Xt/motif/fileselectionbox';
INCLUDE '~beta/Xt/motif/rowcolumn';
INCLUDE '~beta/Xt/motif/pushbutton';

-- PROGRAM: descriptor --
MotifEnv
(# 
   buttons: @RowColumn
     (# fs: @FileSelectionDialog
          (# init::< (# do 'Enter File' -> dialogTitle #);
             OkCallback::< 
               (# do dirSpec->putline; fs.unManageChild #);
             CancelCallback::< 
               (# do 'Cancel'->putline; fs.unManageChild #);
             HelpCallback::< 
               (# do 'Sorry, no help available'->putline #);
          #);
        getfile: @PushButton
          (# activateCallBack::< (# do fs.manageChild #)#);
        quit: @PushButton
          (# activateCallBack::< (# do stop #)#);
        init::< 
          (# 
          do fs.init; getfile.init; quit.init; 
          #);
     #);
do buttons.init;
#)

The main RowColumn contains two PushButtons:

The FileSelectionBox is popped up using the manageChild attribute. The dialog looks like this:

Three callbacks are further bound in the FileSelectionDialog: When OK is pushed, the file name selected is printed out. This is obtained using the dirSpec resource. Then the dialog is popped down using the unmanageChild attributes. If Cancel is pushed, "Cancel" is printed, and the dialog is popped down. If Help is pushed, a small disclaimer is printed out. This could easily be changed to pop up a real help dialog as in the previous example. The Filter button is used to apply the regular expression in the topmost text entry field to the list of files displayed in the dialog.