NAME

XmBulletinBoard — the BulletinBoard widget class.

SYNOPSIS

#include <Xm/BulletinB.h>

DESCRIPTION

BulletinBoard is a composite widget that provides simple geometry management for children widgets.  It does not force positioning on its children, but can be set to reject geometry requests that would result in overlapping children.  BulletinBoard is the base widget for most dialog widgets and is also used as a general container widget. 

Modal and modeless dialogs are implemented as collections of widgets that include a DialogShell, a BulletinBoard (or subclass) child of the shell, and various dialog components (buttons, labels, etc.) that are children of BulletinBoard.  BulletinBoard defines callbacks useful for dialogs (focus, map, unmap), which are available for application use.  If its parent is a DialogShell, BulletinBoard will pass title and input mode (based on dialog style) information to the parent, which is responsible for appropriate communication with the window manager. 

Classes

BulletinBoard inherits behavior and resources from Core, Composite, Constraint, and XmManager classes. 

The class pointer is xmBulletinBoardWidgetClass. 

The class name is XmBulletinBoard. 

New Resources

The following table defines a set of widget resources used by the programmer to specify data.  The programmer can also set the resource values for the inherited classes to set attributes for this widget.  To reference a resource by name or by class in a .Xdefaults file, remove the XmN or XmC prefix and use the remaining letters.  To specify one of the defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remaining letters (in either lower case or upper case, but include any underscores between words).  The codes in the access column indicate if the given resource can be set at creation time (C), set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). 

XmNallowOverlap
Controls the policy for overlapping children widgets. If True, BulletinBoard allows geometry requests that result in overlapping children.

XmNautoUnmanage
Controls whether or not BulletinBoard is automatically unmanaged after a button is activated.  If True, BulletinBoard adds a callback to button children (PushButtons, PushButtonGadgets, and DrawnButtons) that unmanages the BulletinBoard when a button is activated; and, the unmap callbacks are called if the parent of the BulletinBoard is a DialogShell.  If False, the BulletinBoard is not automatically unmanaged.

XmNbuttonFontList
Specifies the font list used for BulletinBoard’s button children (PushButtons, PushButtonGadgets, ToggleButtons, and ToggleButtonGadgets).  If NULL, the XmNtextFontList is used for buttons. 

XmNcancelButton
Specifies the widget ID of the Cancel button.  BulletinBoard’s subclasses, which define a Cancel button, set this resource.  BulletinBoard does not directly provide any behavior for that button. 

XmNdefaultButton
Specifies the widget ID of the default button. BulletinBoard’s subclasses, which define a default button, set this resource.  BulletinBoard defines translations and installs accelerators that activate that button when the return key is pressed.

XmNdefaultPosition
Controls whether or not the BulletinBoard is automatically positioned by its parent.  If True, and the parent of the Bulletinboard is a DialogShell, then the BulletinBoard is centered within or around the parent of the DialogShell when the BulletinBoard is mapped and managed.  If False, the Bulletinboard is not automatically positioned.

XmNdialogStyle
Indicates the dialog style associated with BulletinBoard. If the parent of BulletinBoard is a DialogShell, then the parent is configured according to this resource and DialogShell sets the XmNinputMode of VendorShell accordingly.  Possible values for this resource include the following:

•XmDIALOG_SYSTEM_MODAL — used for dialogs that must be responded to before any other interaction in any application. 

•XmDIALOG_APPLICATION_MODAL — used for dialogs that must be responded to before some other interactions in the same application. 

•XmDIALOG_MODELESS — used for dialogs that do not interrupt interaction of any application. 

•XmDIALOG_WORK_AREA — used for non-dialog BulletinBoard widgets (parent is not a subclass of DialogShell). 

XmNdialogTitle
Specifies the dialog title.  If this resource is not NULL, and the parent of the BulletinBoard is a subclass of WMShell, BulletinBoard sets the XmNtitle of its parent to the value of this resource. 

XmNfocusCallback
Specifies the list of callbacks that is called when the BulletinBoard widget or one of its descendants accepts the input focus. The callback reason is XmCR_FOCUS. 

XmNlabelFontList
Specifies the font list used for BulletinBoard’s Label children (Labels and LabelGadgets).  If NULL, XmNtextFontList is used for labels also. 

XmNmapCallback
Specifies the list of callbacks that is called only when the parent of the BulletinBoard is a DialogShell; in which case, this callback list is invoked when the BulletinBoard widget is mapped. The callback reason is XmCR_MAP. 

XmNmarginHeight
Specifies the minimum spacing in pixels between the top or bottom edge of BulletinBoard and any child widget.

XmNmarginWidth
Specifies the minimum spacing in pixels between the left or right edge of BulletinBoard and any child widget.

XmNnoResize
Controls whether or not resize controls are included in the window manager frame around the dialog. If set to True, the Motif window manager does not include resize controls in the window manager frame containing the DialogShell or TopLevelShell parent of the BulletinBoard. If set to False, the window manager frame does include resize controls. The preferred way to manipulate the set of controls provided by the Motif window manager is to specify values for the mwm resources provided by VendorShell.

XmNresizePolicy
Controls the policy for resizing BulletinBoard widgets. Possible values include the following:

•XmRESIZE_NONE — fixed size. 

•XmRESIZE_ANY — shrink or grow as needed. 

•XmRESIZE_GROW — grow only. 

XmNshadowType
Describes the shadow drawing style for BulletinBoard.  This resource can have the following values:

•XmSHADOW_IN — draws the BulletinBoard shadow such that it appears inset.  This means that the bottom shadow visuals and top shadow visuals are reversed. 

•XmSHADOW_OUT — draws the BulletinBoard shadow such that it appears outset. 

•XmSHADOW_ETCHED_IN — draws the BulletinBoard shadow using a double line giving the effect of a line etched into the window, similar to the Separator widget. 

•XmSHADOW_ETCHED_OUT — draws the BulletinBoard shadow using a double line giving the effect of a line coming out of the window, similar to the Separator widget. 

BulletinBoard widgets draw shadows just within their borders if XmNshadowThickness is greater than zero.  If the parent of a BulletinBoard widget is a DialogShell, BulletinBoard dynamically changes the default for XmNshadowThickness from 0 to 1. 

XmNstringDirection
Specifies the initial rendering direction for text within a dialog. BulletinBoard’s subclasses, such as MessageBox and SelectionBox, which create XmString components, such as LabelGadgets, PushButtonGadgets, and Lists, set XmNstringDirection of these components based on the value of this resource.  BulletinBoard does not directly provide any behavior for this resource. 

XmNtextFontList
Specifies the font list used for BulletinBoard’s Text children.  If there is no XmNbuttonFontList, then this resource is used for buttons; and, if there is no XmNlabelFontList, then this resource is used for labels also. 

XmNtextTranslations
Adds translations to any Text widget or Text widget subclass that is added as a child of BulletinBoard.

XmNunmapCallback
Specifies the list of callbacks that is called only when the parent of the BulletinBoard is a DialogShell; in which case, this callback list is invoked when the BulletinBoard widget is unmapped. The callback reason is XmCR_UNMAP. 

Inherited Resources

BulletinBoard inherits behavior and resources from the following superclasses.  For a complete description of these resources, refer to the man page for that superclass. 

Callback Information

The following structure is returned with each callback. 

typedef struct
{
intreason;
XEvent∗ event;
} XmAnyCallbackStruct;

reasonIndicates why the callback was invoked. 

eventPoints to the XEvent that triggered the callback. 

Behavior

BulletinBoard behavior is summarized below. 

<Cancel Button Activated>:
When the Cancel button is pressed, the activate callbacks of the Cancel button are called. 

<Default Button Activated> or <Key>Return:
When the default button or return key is pressed, the activate callbacks of the default button are called.

<Help Button Activated> or <Key>F1:
When the Help button or Function key 1 is pressed, the callbacks for XmNhelpCallback are called. 

<FocusIn>:
When a FocusIn event is generated on the widget window, the callbacks for XmNfocusCallback are called. 

<MapWindow>:
When a BulletinBoard, which is the child of a DialogShell, is mapped, the callbacks for XmNmapCallback are invoked.  When a BulletinBoard that is not the child of a DialogShell is mapped, the callbacks are not invoked. 

<UnmapWindow>:
When a BulletinBoard that is the child of a DialogShell is unmapped, the callbacks for XmNunmapCallback are invoked.  When a BulletinBoard that is not the child of a DialogShell is unmapped, the callbacks are not invoked. 

Default Translations

The following are the default translations defined for BulletinBoard widgets:

<EnterWindow>: Enter()
<FocusIn>:FocusIn()
<Btn1Down>:Arm()
<Btn1Up>:Activate()
<Key>F1:Help()
<Key>Return:Return()
<Key>KP_Enter: Return()

Default Accelerators

The following are the default accelerator translations that are added to descendants of a BulletinBoard if the parent of the BulletinBoard is a DialogShell:

#override
<Key>F1:Help()
<Key>Return:Return()
<Key>KP_Enter: Return()

Keyboard Traversal

By default, if the parent of a BulletinBoard widget is a DialogShell, BulletinBoard uses the Return key for activating the default button and installs accelerators on all descendant widgets to make this possible.  These accelerators disable the normal keyboard traversal behavior of the Return key.  This traversal behavior may be restored (and the default button behavior disabled) by replacing BulletinBoard’s default accelerators with an alternative set of translations which do not specify the Return action.  For more information on keyboard traversal, see the man page for XmManager(3Xm) and its sections on behavior and default translations. 

RELATED INFORMATION

Composite(3Xm), Constraint(3Xm), Core(3Xm), XmCreateBulletinBoard(3Xm), XmCreateBulletinBoardDialog(3Xm), XmDialogShell(3Xm), and XmManager(3Xm). 

7th Edition