


XmCommand(3X)							XmCommand(3X)
OSF/Motif							    OSF/Motif



NAME
  XXmmCCoommmmaanndd - The Command widget class

SYNOPSIS


  ##iinncclluuddee <<XXmm//CCoommmmaanndd..hh>>

DESCRIPTION
  Command is a special-purpose composite widget	for command entry that pro-
  vides	a built-in command-history mechanism.  Command includes	a command-
  line text-input field, a command-line	prompt,	and a command-history list
  region.

  One additional WWoorrkkAArreeaa child	may be added to	the Command after creation.

  Whenever a command is	entered, it is automatically added to the end of the
  command-history list and made	visible.  This does not	change the selected
  item in the list, if there is	one.

  Many of the new resources specified for Command are actually SelectionBox
  resources that have been renamed for clarity and ease	of use.

  Classes

  Command inherits behavior and	resources from CCoorree, CCoommppoossiittee,	CCoonnssttrraaiinntt,
  XXmmMMaannaaggeerr, XXmmBBuulllleettiinnBBooaarrdd, and XXmmSSeelleeccttiioonnBBooxx classes.

  The class pointer is xxmmCCoommmmaannddWWiiddggeettCCllaassss.

  The class name is XXmmCCoommmmaanndd.

  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mCCoommmmaannd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
	  ___________________________________________________________
	  ___________________________________________________________
	  XmNcommand		       ""		       CSG
		XmCTextString		      XmString
	  ___________________________________________________________
	  XmNcommandChangedCallback    NULL		       C
		XmCCallback		      XtCallbackList
	  ___________________________________________________________
	  XmNcommandEnteredCallback    NULL		       C
		XmCCallback		      XtCallbackList
	  ___________________________________________________________
	  XmNhistoryItems	       NULL		       CSG
		XmCItems		      XmStringTable
	  ___________________________________________________________
	  XmNhistoryItemCount	       0		       CSG
		XmCItemCount		      int
	  ___________________________________________________________
	  XmNhistoryMaxItems	       100		       CSG
		XmCMaxItems		      int
	  ___________________________________________________________
	  XmNhistoryVisibleItemCount   dynamic		       CSG
		XmCVisibleItemCount	      int
	  ___________________________________________________________
	  XmNpromptString	       dynamic		       CSG
		XmCPromptString		      XmString
	  ___________________________________________________________

  XXmmNNccoommmmaanndd
	    Contains the current command-line text.  This is the XXmmNNtteexxtt--
	    SSttrriinngg resource in SelectionBox, renamed for Command.  This
	    resource can also be modified via XXmmCCoommmmaannddSSeettVVaalluuee	and XXmmCCoommmmaann--
	    ddAAppppeennddVVaalluuee functions.  The command area is a Text	widget.

  XXmmNNccoommmmaannddCChhaannggeeddCCaallllbbaacckk
	    Specifies the list of callbacks that is called when	the value of
	    the	command	changes.  The callback reason is
	    XXmmCCRR__CCOOMMMMAANNDD__CCHHAANNGGEEDD.  This	is equivalent to the XXmmNNvvaalluueeCChhaannggeedd--
	    CCaallllbbaacckk of	the Text widget, except	that a pointer to an XXmmCCoomm--
	    mmaannddCCaallllbbaacckkSSttrruuccttuurree is passed, and the structure's _v_a_l_u_e member
	    contains the XXmmSSttrriinngg.

  XXmmNNccoommmmaannddEEnntteerreeddCCaallllbbaacckk
	    Specifies the list of callbacks that is called when	a command is
	    entered in the Command.  The callback reason is
	    XXmmCCRR__CCOOMMMMAANNDD__EENNTTEERREEDD.  A pointer to	an XXmmCCoommmmaannddCCaallllbbaacckk struc-
	    ture is passed.

  XXmmNNhhiissttoorryyIItteemmss
	    Lists XXmmSSttrriinngg items that make up the contents of the history
	    list.  This	is the XXmmNNlliissttIItteemmss resource in	SelectionBox, renamed
	    for	Command.  XXttGGeettVVaalluueess for this resource	returns	the list
	    items themselves, not a copy of the	list items.  The application
	    must not free the returned items.

  XXmmNNhhiissttoorryyIItteemmCCoouunntt
	    Specifies the number of XXmmSSttrriinnggss in XXmmNNhhiissttoorryyIItteemmss.  This	is
	    the	XXmmNNlliissttIItteemmCCoouunntt resource in SelectionBox, renamed for Com-
	    mand.  The value must not be negative.

  XXmmNNhhiissttoorryyMMaaxxIItteemmss
	    Specifies the maximum number of items allowed in the history
	    list.  Once	this number is reached,	an existing list item must be
	    removed before a new item can be added to the list.	 For each
	    command entered, the first list item is removed from the list, so
	    the	new command can	be added to the	list.  The value must be
	    greater than 0.

  XXmmNNhhiissttoorryyVViissiibblleeIItteemmCCoouunntt
	    Specifies the number of items in the history list that should be
	    visible at one time.  In effect, it	sets the height	(in lines) of
	    the	history	list window.  This is the XXmmNNlliissttVViissiibblleeIItteemmCCoouunntt
	    resource in	SelectionBox, renamed for Command.  The	value must be
	    greater than 0.  The default is dynamic based on the height	of
	    the	list.

  XXmmNNpprroommppttSSttrriinngg
	    Specifies a	prompt for the command line.  This is the XXmmNNsseelleecc--
	    ttiioonnLLaabbeellSSttrriinngg resource in	SelectionBox, renamed for Command.
	    The	default	may vary depending on the value	of the XXmmNNssttrriinngg--
	    DDiirreeccttiioonn resource and the locale.	In the C locale	the default
	    is ">".

  Inherited Resources

  Command 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mSSeelleeccttiioonnB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
       ________________________________________________________________
       ________________________________________________________________
       XmNapplyCallback		       NULL			 N/A
	     XmCCallback		      XtCallbackList
       ________________________________________________________________
       XmNapplyLabelString	       dynamic			 N/A
	     XmCApplyLabelString	      XmString
       ________________________________________________________________
       XmNcancelCallback	       NULL			 N/A
	     XmCCallback		      XtCallbackList
       ________________________________________________________________
       XmNcancelLabelString	       dynamic			 N/A
	     XmCCancelLabelString	      XmString
       ________________________________________________________________
       XmNchildPlacement	       XmPLACE_ABOVE_SELECTION	 CSG
	     XmCChildPlacement		      unsigned char
       ________________________________________________________________
       XmNdialogType		       XmDIALOG_COMMAND		 G
	     XmCDialogType		      unsigned char
       ________________________________________________________________
       XmNhelpLabelString	       dynamic			 N/A
	     XmCHelpLabelString		      XmString
       ________________________________________________________________
       XmNlistItemCount		       0			 CSG
	     XmCItemCount		      int
       ________________________________________________________________
       XmNlistItems		       NULL			 CSG
	     XmCItems			      XmStringTable
       ________________________________________________________________
       XmNlistLabelString	       NULL			 N/A
	     XmCListLabelString		      XmString
       ________________________________________________________________
       XmNlistVisibleItemCount	       dynamic			 CSG
	     XmCVisibleItemCount	      int
       ________________________________________________________________
       XmNminimizeButtons	       False			 N/A
	     XmCMinimizeButtons		      Boolean
       ________________________________________________________________
       XmNmustMatch		       False			 N/A
	     XmCMustMatch		      Boolean
       ________________________________________________________________
       XmNnoMatchCallback	       NULL			 N/A
	     XmCCallback		      XtCallbackList
       ________________________________________________________________
       XmNokCallback		       NULL			 N/A
	     XmCCallback		      XtCallbackList
       ________________________________________________________________
       XmNokLabelString		       dynamic			 N/A
	     XmCOkLabelString		      XmString
       ________________________________________________________________
       XmNselectionLabelString	       dynamic			 CSG
	     XmCSelectionLabelString	      XmString
       ________________________________________________________________
       XmNtextAccelerators	       default			 C
	     XmCTextAccelerators	      XtAccelerators
       ________________________________________________________________
       XmNtextColumns		       dynamic			 CSG
	     XmCColumns			      short
       ________________________________________________________________
       XmNtextString		       ""			 CSG
	     XmCTextString		      XmString
       ________________________________________________________________

			 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	      False		      N/A
		 XmCAutoUnmanage	     Boolean
	   _________________________________________________________
	   XmNbuttonFontList	      dynamic		      N/A
		 XmCButtonFontList	     XmFontList
	   _________________________________________________________
	   XmNcancelButton	      NULL		      N/A
		 XmCWidget		     Widget
	   _________________________________________________________
	   XmNdefaultButton	      NULL		      N/A
		 XmCWidget		     Widget
	   _________________________________________________________
	   XmNdefaultPosition	      False		      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_NONE	      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mSSttrriinngg _v_a_l_u_e;;
    iinntt	     _l_e_n_g_t_h;;
  }} XXmmCCoommmmaannddC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

  _v_a_l_u_e	 Specifies the XXmmSSttrriinngg	in the CommandArea

  _l_e_n_g_t_h Specifies the size of the command in XXmmSSttrriinngg

  Translations

  XmCommand inherits translations from XmSelectionBox.

  Accelerators

  The XXmmNNtteexxttAAcccceelleerraattoorrss from XmSelectionBox are added	to the Text descen-
  dant of XmCommand.

  Action Routines

  The XmCommand	action routines	are described below:

  SSeelleeccttiioonnBBooxxUUppOOrrDDoowwnn((00||11||22||33)):
	    When called	with a 0 argument, selects the previous	item in	the
	    history list and replaces the text with that item.
	    When called	with a 1 argument, selects the next item in the	his-
	    tory list and replaces the text with that item.
	    When called	with a 2 argument, selects the first item in the his-
	    tory list and replaces the text with that item.
	    When called	with a 3 argument, selects the last item in the	his-
	    tory list and replaces the text with that item.
	    Calls the callbacks	for XXmmNNccoommmmaannddCChhaannggeeddCCaallllbbaacckk.



  Additional Behavior

  The Command widget has the additional	behavior described below:

  MMAAnnyy KKCCaanncceell:
	    If the parent of the Command is a manager, the event is passed to
	    the	parent.

  KKAAccttiivvaattee in Text:
	    Calls the Text widget's XXmmNNaaccttiivvaatteeCCaallllbbaacckk	callbacks.  If the
	    text is empty, this	action then returns.  Otherwise, if the	his-
	    tory list has XXmmNNhhiissttoorryyMMaaxxIItteemmss items, it removes the first item
	    in the list.  It adds the text to the history list as the last
	    item, clears the text, and calls the XXmmNNccoommmmaannddEEnntteerreeddCCaallllbbaacckk
	    callbacks.

  <<KKeeyy>>	in Text:
	    When any change is made to the text	edit widget, this action
	    calls the callbacks	for XXmmNNccoommmmaannddCChhaannggeeddCCaallllbbaacckk.

  <<DDoouubblleeCClliicckk>>	or <<KKAAccttiivvaattee>> in List:
	    Calls the List widget's XXmmNNddeeffaauullttAAccttiioonnCCaallllbbaacckk callbacks.	 If
	    the	history	list has XXmmNNhhiissttoorryyMMaaxxIItteemmss items, this	action
	    removes the	first item in the list.	 It adds the selected List
	    item to the	history	list as	the last item, clears the text,	and
	    calls the XXmmNNccoommmmaannddEEnntteerreeddCCaallllbbaacckk	callbacks.

  <<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pWWiinnddooww>>:
	    When a Command that	is the child of	a DialogShell is mapped, this
	    action calls the callbacks for XXmmNNmmaappCCaallllbbaacckk.

  <<UUnnmmaappWWiinnddooww>>:
	    When a Command that	is the child of	a DialogShell is unmapped,
	    this action	calls the callbacks for	XXmmNNuunnmmaappCCaallllbbaacckk.

  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CoommmmaannddAAppppeennddVVaalluuee((33XX)), XXmmCCoommmmaannddEErrrroorr((33XX)),	XXmmCCoommmmaannddGGeettCChhiilldd((33XX)),
  XXmmCCoommmmaannddSSeettVVaalluuee((33XX)), XXmmCCrreeaatteeCCoommmmaanndd((33XX)), XXmmMMaannaaggeerr((33XX)), and
  XXmmSSeelleeccttiioonnBBooxx((33XX)).
























