XmBulletinBoard(Xm) UNIX System V
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).
XmBulletinBoard Resource Set
Name Class Type Default Access
_________________________________________________________________________________________________
XmNallowOverlap XmCAllowOverlap Boolean True CSG
XmNautoUnmanage XmCAutoUnmanage Boolean True CSG
XmNbuttonFontList XmCButtonFontList XmFontList NULL CSG
XmNcancelButton XmCWidget Widget NULL SG
XmNdefaultButton XmCWidget Widget NULL SG
XmNdefaultPosition XmCDefaultPosition Boolean True CSG
XmNdialogStyle XmCDialogStyle unsigned char dynamic CSG
XmNdialogTitle XmCXmString XmString NULL CSG
XmNfocusCallback XmCCallback XtCallbackList NULL C
XmNlabelFontList XmCLabelFontList XmFontList NULL CSG
XmNmapCallback XmCCallback XtCallbackList NULL C
XmNmarginHeight XmCMarginHeight short 10 CSG
XmNmarginWidth XmCMarginWidth short 10 CSG
XmNnoResize XmCNoResize Boolean False CSG
XmNresizePolicy XmCResizePolicy unsigned char XmRESIZE_ANY CSG
XmNshadowType XmCShadowType unsigned char XmSHADOW_OUT CSG
XmNstringDirection XmCStringDirection XmStringDirection XmSTRING_DIRECTION_L_TO_R CSG
XmNtextFontList XmCTextFontList XmFontList NULL CSG
XmNtextTranslations XmCTranslations XtTranslations NULL C
XmNunmapCallback XmCCallback XtCallbackList NULL C
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:
⊕ XmDIALOGSYSTEMMODAL - used for dialogs that must be
responded to before any other interaction in any
application.
⊕ XmDIALOGAPPLICATIONMODAL - used for dialogs that must
be responded to before some other interactions in the
same application.
⊕ XmDIALOGMODELESS - used for dialogs that do not
interrupt interaction of any application.
⊕ XmDIALOGWORKAREA - 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 XmCRFOCUS.
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
XmCRMAP.
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:
⊕ XmRESIZENONE - fixed size.
⊕ XmRESIZEANY - shrink or grow as needed.
⊕ XmRESIZEGROW - grow only.
XmNshadowType
Describes the shadow drawing style for BulletinBoard.
This resource can have the following values:
⊕ XmSHADOWIN - draws the BulletinBoard shadow such that it
appears inset. This means that the bottom shadow visuals
and top shadow visuals are reversed.
⊕ XmSHADOWOUT - draws the BulletinBoard shadow such that
it appears outset.
⊕ XmSHADOWETCHEDIN - draws the BulletinBoard shadow using
a double line giving the effect of a line etched into the
window, similar to the Separator widget.
⊕ XmSHADOWETCHEDOUT - 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
XmCRUNMAP.
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.
XmManager Resource Set
Name Class Type Default Access
______________________________________________________________________________________
XmNbottomShadowColor XmCForeground Pixel dynamic CSG
XmNbottomShadowPixmap XmCBottomShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
XmNforeground XmCForeground Pixel dynamic CSG
XmNhelpCallback XmCCallback XtCallbackList NULL C
XmNhighlightColor XmCForeground Pixel Black CSG
XmNhighlightPixmap XmCHighlightPixmap Pixmap dynamic CSG
XmNshadowThickness XmCShadowThickness short dynamic CSG
XmNtopShadowColor XmCBackground Pixel dynamic CSG
XmNtopShadowPixmap XmCTopShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
XmNunitType XmCUnitType unsigned char XmPIXELS CSG
XmNuserData XmCUserData caddr_t NULL CSG
Composite Resource Set
Name Class Type Default Access
______________________________________________________________________
XmNinsertPosition XmCInsertPosition XmRFunction NULL CSG
Core Resource Set
Name Class Type Default Access
____________________________________________________________________________________
XmNaccelerators XmCAccelerators XtTranslations NULL CSG
XmNancestorSensitive XmCSensitive Boolean True G
XmNbackground XmCBackground Pixel dynamic CSG
XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
XmNborderColor XmCBorderColor Pixel Black CSG
XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
XmNborderWidth XmCBorderWidth Dimension 0 CSG
XmNcolormap XmCColormap Colormap XtCopyFromParent CG
XmNdepth XmCDepth int XtCopyFromParent CG
XmNdestroyCallback XmCCallback XtCallbackList NULL C
XmNheight XmCHeight Dimension 0 CSG
XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG
XmNscreen XmCScreen Pointer XtCopyScreen CG
XmNsensitive XmCSensitive Boolean True CSG
XmNtranslations XmCTranslations XtTranslations NULL CSG
XmNwidth XmCWidth Dimension 0 CSG
XmNx XmCPosition Position 0 CSG
XmNy XmCPosition Position 0 CSG
Callback Information
The following structure is returned with each callback.
typedef struct
{
int reason;
XEvent * event;
} XmAnyCallbackStruct;
reason Indicates why the callback was invoked.
event Points 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>KPEnter: 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>KPEnter: 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(Xm) and its sections on behavior and default
translations.
RELATED INFORMATION
Composite(Xm), Constraint(Xm), Core(Xm),
XmCreateBulletinBoard(Xm), XmCreateBulletinBoardDialog(Xm),
XmDialogShell(Xm), and XmManager(Xm).
(printed 2/14/90) XmBulletinBoard(Xm)