


XmMessageBox(3X)					     XmMessageBox(3X)
OSF/Motif							    OSF/Motif



NAME
  XXmmMMeessssaaggeeBBooxx - The MessageBox	widget class

SYNOPSIS


  ##iinncclluuddee <<XXmm//MMeessssaaggeeBB..h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 XmBulletin-
  Board	and depends on it for much of its general dialog behavior.

  The default value for	XXmmNNiinniittiiaallFFooccuuss	is the value of	XXmmNNddeeffaauullttBBuuttttoonn.

  A typical MessageBox contains	a message symbol, a message, and up to three
  standard default PushButtons:	 OOKK,, CCaanncceell, and HHeellpp.	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 local-
  ize the default symbols and button labels for	MessageBox convenience dia-
  logs.

  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 con-
  venience 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:

    oo++  The first MenuBar child is placed at the	top of the window.

    oo++  All XXmmPPuusshhBBuuttttoonn	widgets	or gadgets, and	their subclasses are placed
       after the OOKK button in the order	of their creation.

    oo++  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 but-
       tons.  The layout of multiple work area children	is undefined.








  At initialization, MessageBox	looks for the following	bitmap files:

    oo++  xm_error

    oo++  xm_information

    oo++  xm_question

    oo++  xm_working

    oo++  xm_warning

  See XXmmGGeettPPiixxmmaapp((33XX)) for a list of the	paths that are searched	for these
  files.

  Classes

  MessageBox inherits behavior and resources from CCoorree,	CCoommppoossiittee, CCoonn--
  ssttrraaiinntt, XXmmMMaannaaggeerr, and XXmmBBuulllleettiinnBBooaarrdd.

  The class pointer is xxmmMMeessssaaggeeBBooxxWWiiddggeettCCllaassss.

  The class name is XXmmMMeessssaaggeeBBooxx.

  New Resources

  The following	table defines a	set of widget resources	used by	the program-
  mer 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	XXmmNN or XXmmCC
  prefix and use the remaining letters.	 To specify one	of the defined values
  for a	resource in a .Xdefaults file, remove the XXmm prefix and	use the
  remaining letters (in	either lowercase or uppercase, but include any under-
  scores between words).  The codes in the access column indicate if the
  given	resource can be	set at creation	time (C), set by using XXttSSeettVVaalluueess
  (S), retrieved by using XXttGGeettVVaalluueess (G), or is not applicable	(N/A).

			   XXmmMMeessssaaggeeBBooxx	RReessoouurrccee SSeett
	  ___________________________________________________________
	  NNaammee			       DDeeffaauulltt		       AAcccceessss
		CCllaassss			     TTyyppee
	  ___________________________________________________________
	  ___________________________________________________________
	  XmNcancelCallback	       NULL		       C
		XmCCallback		      XtCallbackList
	  ___________________________________________________________
	  XmNcancelLabelString	       dynamic		       CSG
		XmCCancelLabelString	      XmString
	  ___________________________________________________________
	  XmNdefaultButtonType	       XmDIALOG_OK_BUTTON      CSG
		XmCDefaultButtonType	      unsigned char
	  ___________________________________________________________
	  XmNdialogType		       XmDIALOG_MESSAGE	       CSG
		XmCDialogType		      unsigned char
	  ___________________________________________________________
	  XmNhelpLabelString	       dynamic		       CSG
		XmCHelpLabelString	      XmString
	  ___________________________________________________________
	  XmNmessageAlignment	       XmALIGNMENT_BEGINNING   CSG
		XmCAlignment		      unsigned char
	  ___________________________________________________________
	  XmNmessageString	       ""		       CSG
		XmCMessageString	      XmString
	  ___________________________________________________________
	  XmNminimizeButtons	       False		       CSG
		XmCMinimizeButtons	      Boolean
	  ___________________________________________________________
	  XmNokCallback		       NULL		       C
		XmCCallback		      XtCallbackList
	  ___________________________________________________________
	  XmNokLabelString	       dynamic		       CSG
		XmCOkLabelString	      XmString
	  ___________________________________________________________
	  XmNsymbolPixmap	       dynamic		       CSG
		XmCPixmap		      Pixmap
	  ___________________________________________________________

  XXmmNNccaanncceellCCaallllbbaacckk
	    Specifies the list of callbacks that is called when	the user
	    clicks on the cancel button.  The reason sent by the callback is
	    XXmmCCRR__CCAANNCCEELL.

  XXmmNNccaanncceellLLaabbeellSSttrriinngg
	    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".

  XXmmNNddeeffaauullttBBuuttttoonnTTyyppee
	    Specifies the default PushButton.  A value of XXmmDDIIAALLOOGG__NNOONNEE	means
	    that there should be no default PushButton.	 The following are
	    valid types:

	      oo++
	      XXmmDDIIAALLOOGG__CCAANNCCEELL__BBUUTTTTOONN

	      oo++
	      XXmmDDIIAALLOOGG__OOKK__BBUUTTTTOONN

	      oo++
	      XXmmDDIIAALLOOGG__HHEELLPP__BBUUTTTTOONN

	      oo++
	      XXmmDDIIAALLOOGG__NNOONNEE

  XXmmNNddiiaallooggTTyyppee
	    Specifies the type of MessageBox dialog, which determines the
	    default message symbol.  The following are the possible values
	    for	this resource:

	      oo++
	      XXmmDDIIAALLOOGG__EERRRROORR-indicates an ErrorDialog

	      oo++
	      XXmmDDIIAALLOOGG__IINNFFOORRMMAATTIIOONN-indicates an	InformationDialog

	      oo++
	      XXmmDDIIAALLOOGG__MMEESSSSAAGGEE-indicates a MessageDialog.  This	is the
	      default MessageBox dialog	type.  It does not have	an associated
	      message symbol.

	      oo++
	      XXmmDDIIAALLOOGG__QQUUEESSTTIIOONN-indicates a QuestionDialog

	      oo++
	      XXmmDDIIAALLOOGG__TTEEMMPPLLAATTEE-indicates a TemplateDialog.  The TemplateDia-
	      log contains only	a separator child.  It does not	have an
	      associated message symbol.

	      oo++
	      XXmmDDIIAALLOOGG__WWAARRNNIINNGG-indicates a WarningDialog

	      oo++
	      XXmmDDIIAALLOOGG__WWOORRKKIINNGG-indicates a WorkingDialog

  If this resource is changed via XXttSSeettVVaalluueess, the symbol bitmap is modified
  to the new XXmmNNddiiaallooggTTyyppee bitmap unless XXmmNNssyymmbboollPPiixxmmaapp is also being set in
  the call to XXttSSeettVVaalluueess.  If the dialog type does not	have an	associated
  message symbol, then no bitmap will be displayed.

  XXmmNNhheellppLLaabbeellSSttrriinngg
	    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".

  XXmmNNmmeessssaaggeeAAlliiggnnmmeenntt
	    Controls the alignment of the message Label.  Possible values
	    include the	following:

	      oo++
	      XXmmAALLIIGGNNMMEENNTT__BBEEGGIINNNNIINNGG-the	default

	      oo++
	      XXmmAALLIIGGNNMMEENNTT__CCEENNTTEERR

	      oo++
	      XXmmAALLIIGGNNMMEENNTT__EENNDD

  XXmmNNmmeessssaaggeeSSttrriinngg
	    Specifies the string to be used as the message.

  XXmmNNmmiinniimmiizzeeBBuuttttoonnss
	    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.

  XXmmNNookkCCaallllbbaacckk
	    Specifies the list of callbacks that is called when	the user
	    clicks on the OK button.  The reason sent by the callback is
	    XXmmCCRR__OOKK.

  XXmmNNookkLLaabbeellSSttrriinngg
	    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".

  XXmmNNssyymmbboollPPiixxmmaapp
	    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.

			 XXmmBBuulllleettiinnBBooaarrdd RReessoouurrccee SSeett
	   _________________________________________________________
	   NNaammee			      DDeeffaauulltt		      AAcccceessss
		 CCllaassss			    TTyyppee
	   _________________________________________________________
	   _________________________________________________________
	   XmNallowOverlap	      True		      CSG
		 XmCAllowOverlap	     Boolean
	   _________________________________________________________
	   XmNautoUnmanage	      True		      CG
		 XmCAutoUnmanage	     Boolean
	   _________________________________________________________
	   XmNbuttonFontList	      dynamic		      CSG
		 XmCButtonFontList	     XmFontList
	   _________________________________________________________
	   XmNcancelButton	      Cancel button	      SG
		 XmCWidget		     Widget
	   _________________________________________________________
	   XmNdefaultButton	      dynamic		      SG
		 XmCWidget		     Widget
	   _________________________________________________________
	   XmNdefaultPosition	      True		      CSG
		 XmCDefaultPosition	     Boolean
	   _________________________________________________________
	   XmNdialogStyle	      dynamic		      CSG
		 XmCDialogStyle		     unsigned char
	   _________________________________________________________
	   XmNdialogTitle	      NULL		      CSG
		 XmCDialogTitle		     XmString
	   _________________________________________________________
	   XmNfocusCallback	      NULL		      C
		 XmCCallback		     XtCallbackList
	   _________________________________________________________
	   XmNlabelFontList	      dynamic		      CSG
		 XmCLabelFontList	     XmFontList
	   _________________________________________________________
	   XmNmapCallback	      NULL		      C
		 XmCCallback		     XtCallbackList
	   _________________________________________________________
	   XmNmarginHeight	      10		      CSG
		 XmCMarginHeight	     Dimension
	   _________________________________________________________
	   XmNmarginWidth	      10		      CSG
		 XmCMarginWidth		     Dimension
	   _________________________________________________________
	   XmNnoResize		      False		      CSG
		 XmCNoResize		     Boolean
	   _________________________________________________________
	   XmNresizePolicy	      XmRESIZE_ANY	      CSG
		 XmCResizePolicy	     unsigned char
	   _________________________________________________________
	   XmNshadowType	      XmSHADOW_OUT	      CSG
		 XmCShadowType		     unsigned char
	   _________________________________________________________
	   XmNtextFontList	      dynamic		      CSG
		 XmCTextFontList	     XmFontList
	   _________________________________________________________
	   XmNtextTranslations	      NULL		      C
		 XmCTranslations	     XtTranslations
	   _________________________________________________________
	   XmNunmapCallback	      NULL		      C
		 XmCCallback		     XtCallbackList
	   _________________________________________________________

			    XXmmMMaannaaggeerr RReessoouurrccee SSeett
	_______________________________________________________________
	NNaammee			      DDeeffaauulltt			 AAcccceessss
	      CCllaassss			    TTyyppee
	_______________________________________________________________
	_______________________________________________________________
	XmNbottomShadowColor	      dynamic			 CSG
	      XmCBottomShadowColor	     Pixel
	_______________________________________________________________
	XmNbottomShadowPixmap	      XmUNSPECIFIED_PIXMAP	 CSG
	      XmCBottomShadowPixmap	     Pixmap
	_______________________________________________________________
	XmNforeground		      dynamic			 CSG
	      XmCForeground		     Pixel
	_______________________________________________________________
	XmNhelpCallback		      NULL			 C
	      XmCCallback		     XtCallbackList
	_______________________________________________________________
	XmNhighlightColor	      dynamic			 CSG
	      XmCHighlightColor		     Pixel
	_______________________________________________________________
	XmNhighlightPixmap	      dynamic			 CSG
	      XmCHighlightPixmap	     Pixmap
	_______________________________________________________________
	XmNinitialFocus		      dynamic			 CSG
	      XmCInitialFocus		     Widget
	_______________________________________________________________
	XmNnavigationType	      XmTAB_GROUP		 CSG
	      XmCNavigationType		     XmNavigationType
	_______________________________________________________________
	XmNshadowThickness	      dynamic			 CSG
	      XmCShadowThickness	     Dimension
	_______________________________________________________________
	XmNstringDirection	      dynamic			 CG
	      XmCStringDirection	     XmStringDirection
	_______________________________________________________________
	XmNtopShadowColor	      dynamic			 CSG
	      XmCTopShadowColor		     Pixel
	_______________________________________________________________
	XmNtopShadowPixmap	      dynamic			 CSG
	      XmCTopShadowPixmap	     Pixmap
	_______________________________________________________________
	XmNtraversalOn		      True			 CSG
	      XmCTraversalOn		     Boolean
	_______________________________________________________________
	XmNunitType		      dynamic			 CSG
	      XmCUnitType		     unsigned char
	_______________________________________________________________
	XmNuserData		      NULL			 CSG
	      XmCUserData		     XtPointer
	_______________________________________________________________

			    CCoommppoossiittee RReessoouurrccee SSeett
	     _____________________________________________________
	     NNaammee		       DDeeffaauulltt		    AAcccceessss
		   CCllaassss		     TTyyppee
	     _____________________________________________________
	     _____________________________________________________
	     XmNchildren	       NULL		    G
		   XmCReadOnly		      WidgetList
	     _____________________________________________________
	     XmNinsertPosition	       NULL		    CSG
		   XmCInsertPosition	      XtOrderProc
	     _____________________________________________________
	     XmNnumChildren	       0		    G
		   XmCReadOnly		      Cardinal
	     _____________________________________________________

			      CCoorree RReessoouurrccee SSeett
     ____________________________________________________________________
     NNaammee				   DDeeffaauulltt		   AAcccceessss
	   CCllaassss				 TTyyppee
     ____________________________________________________________________
     ____________________________________________________________________
     XmNaccelerators			   dynamic		   N/A
	   XmCAccelerators			  XtAccelerators
     ____________________________________________________________________
     XmNancestorSensitive		   dynamic		   G
	   XmCSensitive				  Boolean
     ____________________________________________________________________
     XmNbackground			   dynamic		   CSG
	   XmCBackground			  Pixel
     ____________________________________________________________________
     XmNbackgroundPixmap		   XmUNSPECIFIED_PIXMAP	   CSG
	   XmCPixmap				  Pixmap
     ____________________________________________________________________
     XmNborderColor			   XtDefaultForeground	   CSG
	   XmCBorderColor			  Pixel
     ____________________________________________________________________
     XmNborderPixmap			   XmUNSPECIFIED_PIXMAP	   CSG
	   XmCPixmap				  Pixmap
     ____________________________________________________________________
     XmNborderWidth			   0			   CSG
	   XmCBorderWidth			  Dimension
     ____________________________________________________________________
     XmNcolormap			   dynamic		   CG
	   XmCColormap				  Colormap
     ____________________________________________________________________
     XmNdepth				   dynamic		   CG
	   XmCDepth				  int
     ____________________________________________________________________
     XmNdestroyCallback			   NULL			   C
	   XmCCallback				  XtCallbackList
     ____________________________________________________________________
     XmNheight				   dynamic		   CSG
	   XmCHeight				  Dimension
     ____________________________________________________________________
     XmNinitialResourcesPersistent	   True			   C
	   XmCInitialResourcesPersistent	  Boolean
     ____________________________________________________________________
     XmNmappedWhenManaged		   True			   CSG
	   XmCMappedWhenManaged			  Boolean
     ____________________________________________________________________
     XmNscreen				   dynamic		   CG
	   XmCScreen				  Screen *
     ____________________________________________________________________
     XmNsensitive			   True			   CSG
	   XmCSensitive				  Boolean
     ____________________________________________________________________
     XmNtranslations			   dynamic		   CSG
	   XmCTranslations			  XtTranslations
     ____________________________________________________________________
     XmNwidth				   dynamic		   CSG
	   XmCWidth				  Dimension
     ____________________________________________________________________
     XmNx				   0			   CSG
	   XmCPosition				  Position
     ____________________________________________________________________
     XmNy				   0			   CSG
	   XmCPosition				  Position
     ____________________________________________________________________

  Callback Information

  A pointer to the following structure is passed to each callback:


  ttyyppeeddeeff ssttrruucctt
  {{
    iinntt		 _r_e_a_s_o_n;;
    XXEEvveenntt	 * _e_v_e_n_t;;
  }} XXmmAAnnyyCCaallllbbaacckkSSttrruucctt;;

  _r_e_a_s_o_n Indicates why the callback was	invoked

  _e_v_e_n_t	 Points	to the XXEEvveenntt that triggered the callback


  Translations

  XmMessageBox includes	the translations from XmManager.

  Additional Behavior

  The XmMessageBox widget has the additional behavior described	below:

  MMAAnnyy KKCCaanncceell:
	    Calls the activate callbacks for the cancel	button if it is	sen-
	    sitive.

  KKAAccttiivvaattee:
	    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.

  <<OOkk BBuuttttoonn AAccttiivvaatteedd>>:
	    Calls the callbacks	for XXmmNNookkCCaallllbbaacckk.

  <<CCaanncceell BBuuttttoonn AAccttiivvaatteedd>>:
	    Calls the callbacks	for XXmmNNccaanncceellCCaallllbbaacckk.

  <<HHeellpp	BBuuttttoonn AAccttiivvaatteedd>>:
	    Calls the callbacks	for XXmmNNhheellppCCaallllbbaacckk.

  <<FFooccuussIInn>>:
	    Calls the callbacks	for XXmmNNffooccuussCCaallllbbaacckk.

  <<MMaapp>>:    Calls the callbacks	for XXmmNNmmaappCCaallllbbaacckk if the parent is a Dialog-
	    Shell.

  <<UUnnmmaapp>>:  Calls the callbacks	for XXmmNNuunnmmaappCCaallllbbaacckk if	the parent is a	Dia-
	    logShell.

  Virtual Bindings

  The bindings for virtual keys	are vendor specific.  For information about
  bindings for virtual buttons and keys, see VViirrttuuaallBBiinnddiinnggss((33XX)).

RELATED	INFORMATION
  CCoommppoossiittee((33XX)), CCoonnssttrraaiinntt((33XX)), CCoorree((33XX)), XXmmBBuulllleettiinnBBooaarrdd((33XX)),
  XXmmCCrreeaatteeEErrrroorrDDiiaalloogg((33XX)), XXmmCCrreeaatteeIInnffoorrmmaattiioonnDDiiaalloogg((33XX)),
  XXmmCCrreeaatteeMMeessssaaggeeBBooxx((33XX)), XXmmCCrreeaatteeMMeessssaaggeeDDiiaalloogg((33XX)),
  XXmmCCrreeaatteeQQuueessttiioonnDDiiaalloogg((33XX)), XXmmCCrreeaatteeTTeemmppllaatteeDDiiaalloogg((33XX)),
  XXmmCCrreeaatteeWWaarrnniinnggDDiiaalloogg((33XX)), XXmmCCrreeaatteeWWoorrkkiinnggDDiiaalloogg((33XX)),	XXmmMMaannaaggeerr((33XX)), and
  XXmmMMeessssaaggeeBBooxxGGeettCChhiilldd((33XX)).



















