[ Previous | Next | Contents | Glossary | Home | Search ]
Motif 2.1 Programmer's Guide

BulletinBoard and DialogShell

From the application's point of view, a dialog must meet the following criteria:

  1. A dialog is a widget that is a subclass of XmBulletinBoard.

  2. A dialog's parent is a DialogShell.

    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.

  3. BulletinBoard

    BulletinBoard provides the following resources and behavior:

    1. Activation and cancellation of the dialog. BulletinBoard installs accelerators for osfActivate and osfCancel. Unless focus is in another button, osfActivate activates the XmNdefaultButton if it is sensitive. The osfCancel activates the XmNcancelButton if it is sensitive. Subclasses set the XmNdefaultButton and XmNcancelButton.

    2. A resource, XmNdialogStyle, that determines whether the dialog is modal or modeless. Three modal styles exist:

      primary application modal
      Among the dialog and its ancestors, input goes only to the dialog, but the user can interact with other parts of the application or with other applications.

      full application modal
      Within the application, input goes only to the dialog, but the user can interact with other applications.

      system modal
      Input goes only to the dialog; the user cannot interact with other applications. System modal should seldom be used.

    3. Callbacks invoked when the BulletinBoard is mapped and unmapped and when it gains input focus.

    4. Geometry-management resources and class methods that implement several resizing policies and that allow the BulletinBoard to interact with its subclasses in managing complex collections of descendant widgets. The geometry-related resources are XmNmarginHeight, XmNmarginWidth and XmNresizePolicy. For more information on BulletinBoard's geometry management, see Chapter 10.

    5. Activation, Cancellation, and Help

      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.

      Initial Focus

      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:

      1. When the manager is the child of a shell and the shell hierarchy receives focus for the first time

      2. When focus is inside the shell hierarchy, the manager is a composite tab group, and the user traverses to the manager using the keyboard

        Following are the default values of XmNinitialFocus for BulletinBoard and its subclasses:

        1. For BulletinBoard, Form, and MessageBox, the default is the value of XmNdefaultButton

        2. For SelectionBox and its subclasses, the default is the text edit area

        3. [ Previous | Next | Contents | Glossary | Home | Search ]