XmCommand (3)

#include <Xm/Command.h>

Command is a special-purpose composite widget for command entry that provides 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 WorkArea 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.

Descendants

Command automatically creates the descendants shown in the following table. An application can use XtNameToWidget to gain access to the named descendant. In addition, a user or an application can use the named descendant when specifying resource values.

Named Descendant	Class	Identity
_	_	_
	=
	_	_
_		ItemsList
XmList	command-history list region	_
_	_
ItemsListSW	XmScrolledWindow	the ScrolledWindow parent of ItemsList
_	_	_
	Selection	XmLabelGadget
command-line prompt	_	_
_		Text
XmTextField	command-line text-input field	_
_	_

Classes

Command inherits behavior, resources, and traits from Core, Composite, Constraint, XmManager, XmBulletinBoard, and XmSelectionBox.

The class pointer is xmCommandWidgetClass.

The class name is XmCommand.

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).

XmCommand Resource Set
Name	Class	Type	Default	Access
_	_	_	_	_
	XmNcommand	XmCTextString	XmString	""
CSG	_	_	_	_
_		XmNcommandChangedCallback	XmCCallback	XtCallbackList
NULL	C	_	_	_
_	_		XmNcommandEnteredCallback	XmCCallback
XtCallbackList	NULL	C	_	_
_	_	_		XmNhistoryItems
XmCItems	XmStringTable	NULL	CSG	_
_	_	_	_
XmNhistoryItemCount	XmCItemCount	int	0	CSG
_	_	_	_	_
	XmNhistoryMaxItems	XmCMaxItems	int	100
CSG	_	_	_	_
_		XmNhistoryVisibleItemCount	XmCVisibleItemCount	int
dynamic	CSG	_	_	_
_	_		XmNpromptString	XmCPromptString
XmString	dynamic	CSG	_	_
_	_	_

XmNcommand

Contains the current command-line text. This is the XmNtextString resource in SelectionBox, renamed for Command. This resource can also be modified with XmCommandSetValue and XmCommandAppendValue functions. The command area is a Text widget.

XmNcommandChangedCallback

Specifies the list of callbacks that is called after each time the value of the command changes. The callback reason is XmCR_COMMAND_CHANGED. This is equivalent to the XmNvalueChangedCallback of the Text widget, except that a pointer to an XmCommandCallbackStructure is passed, and the structure's value member contains the XmString.

XmNcommandEnteredCallback

Specifies the list of callbacks that is called when a command is entered in the Command. The callback reason is XmCR_COMMAND_ENTERED. A pointer to an XmCommandCallback structure is passed.

XmNhistoryItems

Lists XmString items that make up the contents of the history list. This is the XmNlistItems resource in SelectionBox, renamed for Command. XtGetValues for this resource returns the list items themselves, not a copy of the list items. The application must not free the returned items.

XmNhistoryItemCount

Specifies the number of XmStrings in XmNhistoryItems. This is the XmNlistItemCount resource in SelectionBox, renamed for Command. The value must not be negative.

XmNhistoryMaxItems

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 (zero).

XmNhistoryVisibleItemCount

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 XmNlistVisibleItemCount resource in SelectionBox, renamed for Command. The value must be greater than 0 (zero). The default is dynamic based on the height of the list.

XmNpromptString

Specifies a prompt for the command line. This is the XmNselectionLabelString resource in SelectionBox, renamed for Command. The default may vary depending on the value of the XmNlayoutDirection resource and the locale. In the C locale the default is > (right angle bracket).

Now that some default localized label strings are provided through message catalogs for the children of composite widgets, the labelString resources cannot be set on the child through default resource files. Instead, the resource provided at the parent level must be used.

Inherited Resources

Command inherits behavior and resources from the superclasses described in the following tables. For a complete description of each resource, refer to the reference page for that superclass.

XmSelectionBox Resource Set
Name	Class	Type	Default	Access
_	_	_	_	_
	XmNapplyCallback	XmCCallback	XtCallbackList	NULL
N/A	_	_	_	_
_		XmNapplyLabelString	XmCApplyLabelString	XmString
dynamic	N/A	_	_	_
_	_		XmNcancelCallback	XmCCallback
XtCallbackList	NULL	N/A	_	_
_	_	_		XmNcancelLabelString
XmCCancelLabelString	XmString	dynamic	N/A	_
_	_	_	_
XmNchildPlacement	XmCChildPlacement	unsigned char	XmPLACE_ABOVE_SELECTION	CSG
_	_	_	_	_
	XmNdialogType	XmCDialogType	unsigned char	XmDIALOG_COMMAND
G	_	_	_	_
_		XmNhelpLabelString	XmCHelpLabelString	XmString
dynamic	N/A	_	_	_
_	_		XmNlistItemCount	XmCItemCount
int	0	CSG	_	_
_	_	_		XmNlistItems
XmCItems	XmStringTable	NULL	CSG	_
_	_	_	_
XmNlistLabelString	XmCListLabelString	XmString	NULL	N/A
_	_	_	_	_
	XmNlistVisibleItemCount	XmCVisibleItemCount	int	dynamic
CSG	_	_	_	_
_		XmNminimizeButtons	XmCMinimizeButtons	Boolean
False	N/A	_	_	_
_	_		XmNmustMatch	XmCMustMatch
Boolean	False	N/A	_	_
_	_	_		XmNnoMatchCallback
XmCCallback	XtCallbackList	NULL	N/A	_
_	_	_	_
XmNokCallback	XmCCallback	XtCallbackList	NULL	N/A
_	_	_	_	_
	XmNokLabelString	XmCOkLabelString	XmString	dynamic
N/A	_	_	_	_
_		XmNselectionLabelString	XmCSelectionLabelString	XmString
dynamic	CSG	_	_	_
_	_		XmNtextAccelerators	XmCTextAccelerators
XtAccelerators	default	C	_	_
_	_	_		XmNtextColumns
XmCColumns	short	dynamic	CSG	_
_	_	_	_
XmNtextString	XmCTextString	XmString	""	CSG
_	_	_	_	_

XmBulletinBoard Resource Set
Name	Class	Type	Default	Access
_	_	_	_	_
	XmNallowOverlap	XmCAllowOverlap	Boolean	True
CSG	_	_	_	_
_		XmNautoUnmanage	XmCAutoUnmanage	Boolean
False	N/A	_	_	_
_	_		XmNbuttonFontList	XmCButtonFontList
XmFontList	dynamic	N/A	_	_
_	_	_		XmNbuttonRenderTable
XmCButtonRenderTable	XmRenderTable	dynamic	CSG	_
_	_	_	_
XmNcancelButton	XmCWidget	Widget	NULL	N/A
_	_	_	_	_
	XmNdefaultButton	XmCWidget	Widget	NULL
N/A	_	_	_	_
_		XmNdefaultPosition	XmCDefaultPosition	Boolean
False	CSG	_	_	_
_	_		XmNdialogStyle	XmCDialogStyle
unsigned char	dynamic	CSG	_	_
_	_	_		XmNdialogTitle
XmCDialogTitle	XmString	NULL	CSG	_
_	_	_	_
XmNfocusCallback	XmCCallback	XtCallbackList	NULL	C
_	_	_	_	_
	XmNlabelFontList	XmCLabelFontList	XmFontList	dynamic
CSG	_	_	_	_
_		XmNlabelRenderTable	XmCLabelRenderTable	XmRenderTable
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_NONE	CSG	_	_	_
_	_		XmNshadowType	XmCShadowType
unsigned char	XmSHADOW_OUT	CSG	_	_
_	_	_		XmNtextFontList
XmCTextFontList	XmFontList	dynamic	CSG	_
_	_	_	_
XmNtextRenderTable	XmCTextRenderTable	XmRenderTable	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	_	_	_
_	_		XmNlayoutDirection	XmCLayoutDirection
XmDirection	dynamic	CG	_	_
_	_	_		XmNnavigationType
XmCNavigationType	XmNavigationType	XmTAB_GROUP	CSG	_
_	_	_	_
XmNpopupHandlerCallback	XmCCallback	XtCallbackList	NULL	C
_	_	_	_	_
	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	_	_
_	_	_

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	_	_
_	_	_		XmNscreen
XmCScreen	Screen *	dynamic	CG	_
_	_	_	_
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;
        XmString value;
        int length;
} XmCommandCallbackStruct;

reason

Indicates why the callback was invoked

event

Points to the XEvent that triggered the callback

value

Specifies the XmString in the CommandArea

length

Specifies the size in bytes of the XmString value. This member is obsolete and exists for compatibility with earlier releases.

Translations

XmCommand inherits translations from XmSelectionBox.

Accelerators

The XmNtextAccelerators from XmSelectionBox are added to the Text descendant of XmCommand.

Action Routines

The XmCommand action routines are:

SelectionBoxUpOrDown(Previous|Next|First|Last):

When called with an argument of Previous, or 0 (zero) for compatibility, selects the previous item in the history list and replaces the text with that item.

When called with an argument of Next, or 1 for compatibility, selects the next item in the history list and replaces the text with that item.

When called with an argument of First, or 2 for compatibility, selects the first item in the history list and replaces the text with that item.

When called with an argument of Last, or 3 for compatibility, selects the last item in the history list and replaces the text with that item.

Calls the callbacks for XmNcommandChangedCallback.

Additional Behavior

The Command widget has the following additional behavior:

<Key><osfCancel>:

If the parent of the Command is a manager, the event is passed to the parent.

<Key><osfActivate> in Text:

Calls the Text widget's XmNactivateCallback callbacks. If the text is empty, this action then returns. Otherwise, if the history list has XmNhistoryMaxItems 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 XmNcommandEnteredCallback callbacks.

<Key> in Text:

When any change is made to the text edit widget, this action calls the callbacks for XmNcommandChangedCallback.

<BtnDown>(2+) or <Key><osfActivate> in List:

Calls the List widget's XmNdefaultActionCallback callbacks. If the history list has XmNhistoryMaxItems 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 XmNcommandEnteredCallback callbacks.

<FocusIn>:

Calls the callbacks for XmNfocusCallback.

<MapWindow>:

When a Command that is the child of a DialogShell is mapped, this action calls the callbacks for XmNmapCallback.

<UnmapWindow>:

When a Command that is the child of a DialogShell is unmapped, this action calls the callbacks for XmNunmapCallback.

Virtual Bindings

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

Composite(3), Constraint(3), Core(3), XmBulletinBoard(3), XmCommandAppendValue(3), XmCommandError(3), XmCommandGetChild(3), XmCommandSetValue(3), XmCreateCommand(3), XmManager(3), XmSelectionBox(3), XmVaCreateCommand(3), and XmVaCreateManagedCommand(3).