From the application's point of view, a dialog must meet the following criteria:
BulletinBoard is intended to be the usual superclass for a dialog widget. The dialog widget can be either a BulletinBoard itself or one of its more specialized subclasses. BulletinBoard is a container with no automatically created children; it supplies general behavior needed by most dialogs. Its subclasses provide child widgets and specific behavior tailored to particular types of dialogs.
BulletinBoard and its subclasses can also function outside a DialogShell, as part of the application's main window. One subclass, Form, is particularly useful in providing constraint-based geometry management for a collection of child widgets.
BulletinBoard provides the following resources and behavior:
Often a dialog has one or more actions, associated with buttons, that apply to the dialog as a whole. Some common actions are "activate," "cancel," and "help." BulletinBoard deals specially with activation and cancellation. BulletinBoard allows the user to "activate" or "cancel" the dialog from anywhere within the BulletinBoard (except, in the case of activation, when a button has the focus).
BulletinBoard has a resource, XmNdefaultButton, whose value is a button descendant that represents the default activation action. The dialog renders the default button so that it looks somewhat different from the other buttons. Use the XmNdefaultButtonEmphasis resource of XmDisplay to change the highlighting of this default button. When the user presses osfActivate in a button that has keyboard focus, that button's osfActivate actions are called. If the user presses osfActivate and no button has focus, BulletinBoard calls the osfActivate actions for XmNdefaultButton if it is sensitive. If the user presses osfActivate in a List, Text, or TextField descendant, the osfActivate actions for that widget are invoked first, and then BulletinBoard calls the osfActivate actions for XmNdefaultButton.
BulletinBoard has another resource, XmNcancelButton, whose value is a button descendant that represents the default cancellation action. When the user presses osfCancel anywhere within the BulletinBoard, BulletinBoard calls the osfActivate actions for XmNcancelButton if it is sensitive.
The help action works differently. Often the application represents help for the dialog as a whole by providing a Help button. When the user activates this button, the application provides help for the dialog. In general, the application can provide help through an XmNactivateCallback procedure for the Help button. Some BulletinBoard subclasses create Help buttons automatically. These widgets add a procedure to the Help button's XmNactivateCallback list that invokes the dialog's XmNhelpCallback procedures when the Help button is activated. In these cases, the application can provide help through the dialog's XmNhelpCallback procedures.
If the user presses osfHelp elsewhere in the BulletinBoard, this action usually invokes the XmNhelpCallback callbacks for the widget with the focus. If this widget has no XmNhelpCallback procedures, Motif looks up the widget hierarchy for the first ancestor with a non-NULL XmNhelpCallback list and invokes those procedures. By providing an XmNhelpCallback procedure for the dialog itself, the application can ensure that the user sees help for the dialog as a whole when the descendant widget with focus has no help information of its own.
DialogShell is the Motif shell widget that contains dialogs. It is a subclass of TransientShell, which is a subclass of VendorShell. DialogShell inherits much of VendorShell's behavior in interacting with the window manager and in providing geometry management for off-the-spot input methods.
DialogShell cooperates extensively with BulletinBoard, and some of DialogShell's features for containing dialogs assume that its child is a BulletinBoard or BulletinBoard subclass. Often the application does not need to deal directly with the DialogShell at all. The Motif convenience routines that create dialogs automatically create a DialogShell as the popup child of the parent shell.
To pop up the dialog, the application does not call XtPopup on the DialogShell, but instead manages the child of the DialogShell. DialogShell's change_managed procedure pops up the dialog when the child is managed and pops it down when the child is unmanaged, providing that the child's XmNmappedWhenManaged resource is True. If a BulletinBoard child's XmNautoUnmanage resource is initialized to True, the BulletinBoard is automatically unmanaged when its OK and cancel buttons are activated.
DialogShell notifies its BulletinBoard child by using the XmNmapCallback and XmNunmapCallback procedures when the child is about to be mapped and unmapped.
Like VendorShell, DialogShell ensures that when no off-the-spot input method exists the DialogShell window remains coincident with the child window. Setting XmNx and XmNy for the child sets these resources for the shell, without changing the child's position relative to the child. Setting XmNheight, XmNwidth and XmNborderWidth for the child usually sets these resources to the same value in the DialogShell. When a BulletinBoard child is managed with its XmNdefaultPosition resource set to True, DialogShell centers the dialog with respect to the parent.
BulletinBoard has two resources that allow the user or application to customize a parent DialogShell's interaction with the window manager. XmNdialogTitle provides a title for the window manager, and XmNnoResize determines whether or not the dialog MWM frame includes resize controls. To affect other aspects of interaction with the window manager, the user or application must set the appropriate DialogShell resources.
XmCreateBulletinBoardDialog creates a BulletinBoard and a parent DialogShell.
When the XmNkeyboardFocusPolicy of a shell is XmEXPLICIT, Motif uses the Manager resource XmNinitialFocus in determining which component of a manager receives initial focus in these circumstances:
Following are the default values of XmNinitialFocus for BulletinBoard and its subclasses: