XmBulletinBoard(3Xm) XmBulletinBoard(3Xm)
NAME
XmBulletinBoard - the BulletinBoard widget class.
AES SUPPORT LEVEL
full-use
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
- 1 -
XmBulletinBoard(3Xm) XmBulletinBoard(3Xm)
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
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.
- 2 -
XmBulletinBoard(3Xm) XmBulletinBoard(3Xm)
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
- 3 -
XmBulletinBoard(3Xm) XmBulletinBoard(3Xm)
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.
- 4 -
XmBulletinBoard(3Xm) XmBulletinBoard(3Xm)
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.
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.
- 5 -
XmBulletinBoard(3Xm) XmBulletinBoard(3Xm)
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
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;
- 6 -
XmBulletinBoard(3Xm) XmBulletinBoard(3Xm)
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()
- 7 -
XmBulletinBoard(3Xm) XmBulletinBoard(3Xm)
<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(3X) and its sections on behavior and default
translations.
RELATED INFORMATION
Composite(3X), Constraint(3X), Core(3X),
XmCreateBulletinBoard(3X),
XmCreateBulletinBoardDialog(3X), XmDialogShell(3X), and
XmManager(3X).
- 8 -