XmMessageBox

NAME

XmMessageBox - The MessageBox widget class

SYNOPSIS

#include <Xm/MessageB.h>

DESCRIPTION

MessageBox is a dialog class used for creating simple message dialogs. Convenience dialogs based on MessageBox are provided for several common interaction tasks, which include giving information, asking questions, and reporting errors.

A MessageBox dialog is typically transient in nature, displayed for the duration of a single interaction. MessageBox is a subclass of XmBulletinBoard and depends on it for much of its general dialog behavior.

The default value for XmNinitialFocus is the value of XmNdefaultButton.

A typical MessageBox contains a message symbol, a message, and up to three standard default PushButtons: OK, Cancel, and Help. It is laid out with the symbol and message on top and the PushButtons on the bottom. The help button is positioned to the side of the other push buttons. You can localize the default symbols and button labels for MessageBox convenience dialogs.

The user can specify resources in a resource file for the gadgets created automatically that contain the MessageBox symbol pixmap and separator. The gadget names are "Symbol" and "Separator".

A MessageBox can also be customized by creating and managing new children that are added to the MessageBox children created automatically by the convenience dialogs. In the case of TemplateDialog, only the separator child is created by default. If the callback, string, or pixmap symbol resources are specified, the appropriate child will be created.

Additional children are laid out in the following manner:

The first MenuBar child is placed at the top of the window.
All XmPushButton widgets or gadgets, and their subclasses are placed after the OK button in the order of their creation.
A child that is not in the above categories is placed above the row of buttons. If a message label exists, the child is placed below the label. If a message pixmap exists, but a message label is absent, the child is placed on the same row as the pixmap. The child behaves as a work area and grows or shrinks to fill the space above the row of buttons. The layout of multiple work area children is undefined.

At initialization, MessageBox looks for the following bitmap files:

xm_error
xm_information
xm_question
xm_working
xm_warning

See XmGetPixmap(3X) for a list of the paths that are searched for these files.

Classes

MessageBox inherits behavior and resources from Core, Composite, Constraint, XmManager, and XmBulletinBoard.

The class pointer is xmMessageBoxWidgetClass.

The class name is XmMessageBox.

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 lowercase or uppercase, 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).


XmMessageBox Resource Set
Name                  Class                 Type            Default                Access
XmNcancelCallback     XmCCallback           XtCallbackList  NULL                   C
XmNcancelLabelString  XmCCancelLabelString  XmString        dynamic                CSG
XmNdefaultButtonType  XmCDefaultButtonType  unsigned char   XmDIALOG_OK_BUTTON     CSG
XmNdialogType         XmCDialogType         unsigned char   XmDIALOG_MESSAGE       CSG
XmNhelpLabelString    XmCHelpLabelString    XmString        dynamic                CSG
XmNmessageAlignment   XmCAlignment          unsigned char   XmALIGNMENT_BEGINNING  CSG
XmNmessageString      XmCMessageString      XmString        ""                     CSG
XmNminimizeButtons    XmCMinimizeButtons    Boolean         False                  CSG
XmNokCallback         XmCCallback           XtCallbackList  NULL                   C
XmNokLabelString      XmCOkLabelString      XmString        dynamic                CSG
XmNsymbolPixmap       XmCPixmap             Pixmap          dynamic                CSG

**XmMessageBox Resource Set**
Name	Class	Type	Default	Access
XmNcancelCallback	XmCCallback	XtCallbackList	NULL	C
XmNcancelLabelString	XmCCancelLabelString	XmString	dynamic	CSG
XmNdefaultButtonType	XmCDefaultButtonType	unsigned char	XmDIALOG_OK_BUTTON	CSG
XmNdialogType	XmCDialogType	unsigned char	XmDIALOG_MESSAGE	CSG
XmNhelpLabelString	XmCHelpLabelString	XmString	dynamic	CSG
XmNmessageAlignment	XmCAlignment	unsigned char	XmALIGNMENT_BEGINNING	CSG
XmNmessageString	XmCMessageString	XmString	""	CSG
XmNminimizeButtons	XmCMinimizeButtons	Boolean	False	CSG
XmNokCallback	XmCCallback	XtCallbackList	NULL	C
XmNokLabelString	XmCOkLabelString	XmString	dynamic	CSG
XmNsymbolPixmap	XmCPixmap	Pixmap	dynamic	CSG

XmNcancelCallback

Specifies the list of callbacks that is called when the user clicks on the cancel button. The reason sent by the callback is XmCR_CANCEL.

XmNcancelLabelString

Specifies the string label for the cancel button. The default for this resource depends on the locale. In the C locale the default is "Cancel".

XmNdefaultButtonType

Specifies the default PushButton. A value of XmDIALOG_NONE means that there should be no default PushButton. The following are valid types:

XmDIALOG_CANCEL_BUTTON
XmDIALOG_OK_BUTTON
XmDIALOG_HELP_BUTTON
XmDIALOG_NONE

XmNdialogType

Specifies the type of MessageBox dialog, which determines the default message symbol. The following are the possible values for this resource:

XmDIALOG_ERROR - indicates an ErrorDialog
XmDIALOG_INFORMATION - indicates an InformationDialog
XmDIALOG_MESSAGE - indicates a MessageDialog. This is the default MessageBox dialog type. It does not have an associated message symbol.
XmDIALOG_QUESTION - indicates a QuestionDialog
XmDIALOG_TEMPLATE - indicates a TemplateDialog. The TemplateDialog contains only a separator child. It does not have an associated message symbol.
XmDIALOG_WARNING - indicates a WarningDialog
XmDIALOG_WORKING - indicates a WorkingDialog

If this resource is changed via XtSetValues, the symbol bitmap is modified to the new XmNdialogType bitmap unless XmNsymbolPixmap is also being set in the call to XtSetValues. If the dialog type does not have an associated message symbol, then no bitmap will be displayed.

XmNhelpLabelString

Specifies the string label for the help button. The default for this resource depends on the locale. In the C locale the default is "Help".

XmNmessageAlignment

Controls the alignment of the message Label. Possible values include the following:

XmALIGNMENT_BEGINNING - the default
XmALIGNMENT_CENTER
XmALIGNMENT_END

XmNmessageString

Specifies the string to be used as the message.

XmNminimizeButtons

Sets the buttons to the width of the widest button and height of the tallest button if False. If True, button width and height are set to the preferred size of each button.

XmNokCallback

Specifies the list of callbacks that is called when the user clicks on the OK button. The reason sent by the callback is XmCR_OK.

XmNokLabelString

Specifies the string label for the OK button. The default for this resource depends on the locale. In the C locale the default is "OK".

XmNsymbolPixmap

Specifies the pixmap label to be used as the message symbol.

Inherited Resources

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


XmBulletinBoard Resource Set
Name                 Class               Type            Default        Access
XmNallowOverlap      XmCAllowOverlap     Boolean         True           CSG
XmNautoUnmanage      XmCAutoUnmanage     Boolean         True           CG
XmNbuttonFontList    XmCButtonFontList   XmFontList      dynamic        CSG
XmNcancelButton      XmCWidget           Widget          Cancel button  SG
XmNdefaultButton     XmCWidget           Widget          dynamic        SG
XmNdefaultPosition   XmCDefaultPosition  Boolean         True           CSG
XmNdialogStyle       XmCDialogStyle      unsigned char   dynamic        CSG
XmNdialogTitle       XmCDialogTitle      XmString        NULL           CSG
XmNfocusCallback     XmCCallback         XtCallbackList  NULL           C
XmNlabelFontList     XmCLabelFontList    XmFontList      dynamic        CSG
XmNmapCallback       XmCCallback         XtCallbackList  NULL           C
XmNmarginHeight      XmCMarginHeight     Dimension       10             CSG
XmNmarginWidth       XmCMarginWidth      Dimension       10             CSG
XmNnoResize          XmCNoResize         Boolean         False          CSG
XmNresizePolicy      XmCResizePolicy     unsigned char   XmRESIZE_ANY   CSG
XmNshadowType        XmCShadowType       unsigned char   XmSHADOW_OUT   CSG
XmNtextFontList      XmCTextFontList     XmFontList      dynamic        CSG
XmNtextTranslations  XmCTranslations     XtTranslations  NULL           C    
XmNunmapCallback     XmCCallback         XtCallbackList  NULL           C

**XmBulletinBoard Resource Set**
Name	Class	Type	Default	Access
XmNallowOverlap	XmCAllowOverlap	Boolean	True	CSG
XmNautoUnmanage	XmCAutoUnmanage	Boolean	True	CG
XmNbuttonFontList	XmCButtonFontList	XmFontList	dynamic	CSG
XmNcancelButton	XmCWidget	Widget	Cancel button	SG
XmNdefaultButton	XmCWidget	Widget	dynamic	SG
XmNdefaultPosition	XmCDefaultPosition	Boolean	True	CSG
XmNdialogStyle	XmCDialogStyle	unsigned char	dynamic	CSG
XmNdialogTitle	XmCDialogTitle	XmString	NULL	CSG
XmNfocusCallback	XmCCallback	XtCallbackList	NULL	C
XmNlabelFontList	XmCLabelFontList	XmFontList	dynamic	CSG
XmNmapCallback	XmCCallback	XtCallbackList	NULL	C
XmNmarginHeight	XmCMarginHeight	Dimension	10	CSG
XmNmarginWidth	XmCMarginWidth	Dimension	10	CSG
XmNnoResize	XmCNoResize	Boolean	False	CSG
XmNresizePolicy	XmCResizePolicy	unsigned char	XmRESIZE_ANY	CSG
XmNshadowType	XmCShadowType	unsigned char	XmSHADOW_OUT	CSG
XmNtextFontList	XmCTextFontList	XmFontList	dynamic	CSG
XmNtextTranslations	XmCTranslations	XtTranslations	NULL	C
XmNunmapCallback	XmCCallback	XtCallbackList	NULL	C


XmManager Resource Set
Name                   Class                  Type               Default               Access
XmNbottomShadowColor   XmCBottomShadowColor   Pixel              dynamic               CSG
XmNbottomShadowPixmap  XmCBottomShadowPixmap  Pixmap             XmUNSPECIFIED_PIXMAP  CSG
XmNforeground          XmCForeground          Pixel              dynamic               CSG
XmNhelpCallback        XmCCallback            XtCallbackList     NULL                  C
XmNhighlightColor      XmCHighlightColor      Pixel              dynamic               CSG
XmNhighlightPixmap     XmCHighlightPixmap     Pixmap             dynamic               CSG
XmNinitialFocus        XmCInitialFocus        Widget             dynamic               CSG
XmNnavigationType      XmCNavigationType      XmNavigationType   XmTAB_GROUP           CSG
XmNshadowThickness     XmCShadowThickness     Dimension          dynamic               CSG
XmNstringDirection     XmCStringDirection     XmStringDirection  dynamic               CG
XmNtopShadowColor      XmCTopShadowColor      Pixel              dynamic               CSG
XmNtopShadowPixmap     XmCTopShadowPixmap     Pixmap             dynamic               CSG
XmNtraversalOn         XmCTraversalOn         Boolean            True                  CSG
XmNunitType            XmCUnitType            unsigned char      dynamic               CSG
XmNuserData            XmCUserData            XtPointer          NULL                  CSG

**XmManager Resource Set**
Name	Class	Type	Default	Access
XmNbottomShadowColor	XmCBottomShadowColor	Pixel	dynamic	CSG
XmNbottomShadowPixmap	XmCBottomShadowPixmap	Pixmap	XmUNSPECIFIED_PIXMAP	CSG
XmNforeground	XmCForeground	Pixel	dynamic	CSG
XmNhelpCallback	XmCCallback	XtCallbackList	NULL	C
XmNhighlightColor	XmCHighlightColor	Pixel	dynamic	CSG
XmNhighlightPixmap	XmCHighlightPixmap	Pixmap	dynamic	CSG
XmNinitialFocus	XmCInitialFocus	Widget	dynamic	CSG
XmNnavigationType	XmCNavigationType	XmNavigationType	XmTAB_GROUP	CSG
XmNshadowThickness	XmCShadowThickness	Dimension	dynamic	CSG
XmNstringDirection	XmCStringDirection	XmStringDirection	dynamic	CG
XmNtopShadowColor	XmCTopShadowColor	Pixel	dynamic	CSG
XmNtopShadowPixmap	XmCTopShadowPixmap	Pixmap	dynamic	CSG
XmNtraversalOn	XmCTraversalOn	Boolean	True	CSG
XmNunitType	XmCUnitType	unsigned char	dynamic	CSG
XmNuserData	XmCUserData	XtPointer	NULL	CSG


Composite Resource Set
Name               Class              Type         Default  Access
XmNchildren        XmCReadOnly        WidgetList   NULL     G
XmNinsertPosition  XmCInsertPosition  XtOrderProc  NULL     CSG
XmNnumChildren     XmCReadOnly        Cardinal     0        G

**Composite Resource Set**
Name	Class	Type	Default	Access
XmNchildren	XmCReadOnly	WidgetList	NULL	G
XmNinsertPosition	XmCInsertPosition	XtOrderProc	NULL	CSG
XmNnumChildren	XmCReadOnly	Cardinal	0	G


Core Resource Set
Name                           Class                          Type            Default               Access
XmNaccelerators                XmCAccelerators                XtAccelerators  dynamic               N/A
XmNancestorSensitive           XmCSensitive                   Boolean         dynamic               G
XmNbackground                  XmCBackground                  Pixel           dynamic               CSG
XmNbackgroundPixmap            XmCPixmap                      Pixmap          XmUNSPECIFIED_PIXMAP  CSG
XmNborderColor                 XmCBorderColor                 Pixel           XtDefaultForeground   CSG
XmNborderPixmap                XmCPixmap                      Pixmap          XmUNSPECIFIED_PIXMAP  CSG
XmNborderWidth                 XmCBorderWidth                 Dimension       0                     CSG
XmNcolormap                    XmCColormap                    Colormap        dynamic               CG
XmNdepth                       XmCDepth                       int             dynamic               CG
XmNdestroyCallback             XmCCallback                    XtCallbackList  NULL                  C
XmNheight                      XmCHeight                      Dimension       dynamic               CSG
XmNinitialResourcesPersistent  XmCInitialResourcesPersistent  Boolean         True                  C
XmNmappedWhenManaged           XmCMappedWhenManaged           Boolean         True                  CSG
XmNsensitive                   XmCSensitive                   Boolean         True                  CSG
XmNtranslations                XmCTranslations                XtTranslations  dynamic               CSG
XmNwidth                       XmCWidth                       Dimension       dynamic               CSG
XmNx                           XmCPosition                    Position        0                     CSG
XmNy                           XmCPosition                    Position        0                     CSG

**Core Resource Set**
Name	Class	Type	Default	Access
XmNaccelerators	XmCAccelerators	XtAccelerators	dynamic	N/A
XmNancestorSensitive	XmCSensitive	Boolean	dynamic	G
XmNbackground	XmCBackground	Pixel	dynamic	CSG
XmNbackgroundPixmap	XmCPixmap	Pixmap	XmUNSPECIFIED_PIXMAP	CSG
XmNborderColor	XmCBorderColor	Pixel	XtDefaultForeground	CSG
XmNborderPixmap	XmCPixmap	Pixmap	XmUNSPECIFIED_PIXMAP	CSG
XmNborderWidth	XmCBorderWidth	Dimension	0	CSG
XmNcolormap	XmCColormap	Colormap	dynamic	CG
XmNdepth	XmCDepth	int	dynamic	CG
XmNdestroyCallback	XmCCallback	XtCallbackList	NULL	C
XmNheight	XmCHeight	Dimension	dynamic	CSG
XmNinitialResourcesPersistent	XmCInitialResourcesPersistent	Boolean	True	C
XmNmappedWhenManaged	XmCMappedWhenManaged	Boolean	True	CSG
XmNsensitive	XmCSensitive	Boolean	True	CSG
XmNtranslations	XmCTranslations	XtTranslations	dynamic	CSG
XmNwidth	XmCWidth	Dimension	dynamic	CSG
XmNx	XmCPosition	Position	0	CSG
XmNy	XmCPosition	Position	0	CSG

Callback Information

A pointer to the following structure is passed to 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

Translations

XmMessageBox includes the translations from XmManager.

Additional Behavior

The XmMessageBox widget has the additional behavior described below:

MAny KCancel:: Calls the activate callbacks for the cancel button if it is sensitive.
KActivate:: Calls the activate callbacks for the button with the keyboard focus. If no button has the keyboard focus, calls the activate callbacks for the default button if it is sensitive.
<Ok Button Activated>:: Calls the callbacks for XmNokCallback.
<Cancel Button Activated>:: Calls the callbacks for XmNcancelCallback.
<Help Button Activated>:: Calls the callbacks for XmNhelpCallback.
<FocusIn>:: Calls the callbacks for XmNfocusCallback.
<Map>:: Calls the callbacks for XmNmapCallback if the parent is a DialogShell.
<Unmap>:: Calls the callbacks for XmNunmapCallback if the parent is a DialogShell.

Virtual Bindings

The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see VirtualBindings(3X).

RELATED INFORMATION

Composite(3X), Constraint(3X), Core(3X), XmBulletinBoard(3X), XmCreateErrorDialog(3X), XmCreateInformationDialog(3X), XmCreateMessageBox(3X), XmCreateMessageDialog(3X), XmCreateQuestionDialog(3X), XmCreateTemplateDialog(3X), XmCreateWarningDialog(3X), XmCreateWorkingDialog(3X), XmManager(3X), and XmMessageBoxGetChild(3X).