SelectionBox is a BulletinBoard subclass that generally allows the user to select an item from a list. By default, a SelectionBox includes the following children:
The default buttons 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; otherwise, it is unmanaged.
An application can add additional children to the SelectionBox. The first child is used as a work area. The value of XmNchildPlacement determines whether the work area is placed above or below the Text area, or above or below the List area. Additional children are laid out in the following manner:
The first MenuBar child is placed at the top of the window.
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. SelectionBox installs accelerators, the value of XmNtextAccelerators, on the text edit widget. The default accelerators bind osfUp, osfDown, osfBeginLine, osfEndLine, and osfRestore events in the text edit widget to SelectionBox actions that select an item in the list and replace the text edit widget value with that list item.
SelectionBox provides XmNokCallback, XmNcancelCallback, XmNhelpCallback, and XmNapplyCallback lists, which the SelectionBox invokes when the corresponding button is activated. Activation of the OK button may invoke either the XmNokCallback list or the XmNnoMatchCallback list. When the user activates the OK button and either the XmNmustMatch resource is False or the text in the text edit area matches a list item, SelectionBox invokes the XmNokCallback procedures. When the user activates the OK button, XmNmustMatch is True, and the text in the text edit area does not match a list item, SelectionBox invokes the XmNnoMatchCallback procedures.
SelectionBox has two subclasses, FileSelectionBox and Command, which are described in later sections. XmCreateSelectionDialog creates a standard SelectionBox and a DialogShell parent. XmCreatePromptDialog creates a variant SelectionBox dialog containing a text edit area and label and OK, Cancel, and Help buttons. A PromptDialog has an unmanaged Apply button, and it has no List or List label. It is intended for the application to prompt the user for brief text input.
The XmNdialogType resource determines which of the standard SelectionBox children are created and managed. The value usually depends on the application's use of the SelectionBox:
SelectionBox has resources for supplying text, label strings, and list items for its children. The widget IDs of the children of a SelectionBox and its subclasses are not available as resources. The application can retrieve the widget IDs of the automatically created children by using XtNameToWidget or by calling one of the convenience routines Motif provides for this purpose: XmSelectionBoxGetChild, XmFileSelectionBoxGetChild, and XmCommandGetChild.