XmCommand(3Xm)

NAME
XmCommand — the Command widget class.

SYNOPSIS
#include <Xm/Command.h>

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

  Classes
XmCommand inherits behavior and resources from Core, Composite, Constraint, XmManager, XmBulletinBoard, and XmSelectionBox classes.

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

XmCommand Resource Set
Name | Class | Type | Default | Access
XmNcommand | XmCTextString | XmString | NULL | 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 | 8 | CSG
XmNpromptString | XmCXmString | XmString | ">" | CSG

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

XmNcommandChangedCallback
    Specifies the list of callbacks that is called when 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 an XmCommandCallbackStructure is returned, loaded with 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. An XmCommandCallback structure is returned.

XmNhistoryItems
    Lists XmString items that make up the contents of the history list. This is the XmNlistItems resource in SelectionBox, renamed for Command.

XmNhistoryItemCount
    Specifies the number of XmStrings in XmNhistoryItems. This is the XmNlistItemCount resource in SelectionBox, renamed for Command.

XmNhistoryMaxItems
    Specifies the maximum number of items allowed in the history list. Once this number is reached, the first list item is removed from the list for each new item added to the list, that is, for each command entered.

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 XmNvisibleItemCount resource in SelectionBox, renamed for Command.

XmNpromptString
    Prompts for the command line. This is the XmNselectionLabelString resource in SelectionBox, renamed for Command.

  Inherited Resources
Command inherits behavior and resources from the following superclasses. For a complete description of these resources, refer to the man page for that superclass.

XmSelectionBox Resource Set
Name | Class | Type | Default | Access
XmNapplyCallback | XmCCallback | XtCallbackList | NULL | N/A
XmNapplyLabelString | XmCApplyLabelString | XmString | "Apply" | N/A
XmNcancelCallback | XmCCallback | XtCallbackList | NULL | N/A
XmNcancelLabelString | XmCXmString | XmString | "Cancel" | N/A
XmNdialogType | XmCDialogType | unsigned char | XmDIALOG_COMMAND | G
XmNhelpLabelString | XmCXmString | XmString | "Help" | N/A
XmNlistItemCount | XmCItemCount | int | 0 | N/A
XmNlistItems | XmCItems | XmStringList | NULL | N/A
XmNlistLabelString | XmCXmString | XmString | NULL | N/A
XmNlistVisibleItemCount | XmCVisibleItemCount | int | 8 | N/A
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 | XmCXmString | XmString | "OK" | N/A
XmNselectionLabelString | XmCXmString | XmString | "Selection" | CSG
XmNtextAccelerators | XmCTextAccelerators | XtTranslations | see description | C
XmNtextColumns | XmCTextColumns | int | 20 | CSG
XmNtextValue | XmCTextValue | XmString | NULL | N/A

XmBulletinBoard Resource Set
Name | Class | Type | Default | Access
XmNallowOverlap | XmCAllowOverlap | Boolean | True | N/A
XmNautoUnmanage | XmCAutoUnmanage | Boolean | False | CSG
XmNbuttonFontList | XmCButtonFontList | XmFontList | NULL | N/A
XmNcancelButton | XmCWidget | Widget | NULL | N/A
XmNdefaultButton | XmCWidget | Widget | NULL | N/A
XmNdefaultPosition | XmCDefaultPosition | Boolean | False | 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_NONE | CSG
XmNshadowType | XmCShadowType | unsigned char | XmSHADOW_OUT | CSG
XmNstringDirection | XmCStringDirection | XmStringDirection | XmSTRING_DIRECTION_L_TO_R | CSG
XmNtextFontList | XmCTextFontList | XmFontList | NULL | CSG
XmNtextTranslations | XmCTranslations | XtTranslations | NULL | C
XmNunmapCallback | XmCCallback | XtCallbackList | NULL | C

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
XmNunitType | XmCUnitType | unsigned char | XmPIXELS | 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;
	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 of the command in XmString.

  Behavior
Command behavior is summarized below.

<Key>:
    When any change is made to the text edit widget, the callbacks for XmNcommandChangedCallback are called.

<Key>Return:
    When the Return key is pressed, the callbacks for XmNcommandEnteredCallback and XmNcommandChangedCallback are called.

<Key>Up or <Key>Down:
    When the up or down key is pressed within the Text subwidget of Command, the text value is replaced with the previous or next item in the List subwidget. The selected item in the list is also changed to the previous or the next item. The callbacks for XmNcommandChangedCallback are called.

<DoubleClick>:
    When an item in the List subwidget is double clicked, that item is selected and added to the end of the list in one action. The callbacks for XmNcommandEnteredCallback and XmNcommandChangedCallback are called.

<Key>F1:
    When the 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 Command that is the child of a DialogShell is mapped, the callbacks for XmNmapCallback are invoked. When a Command that is not the child of a DialogShell is mapped, the callbacks are not invoked.

<UnmapWindow>:
    When a Command that is the child of a Dialogshell is unmapped, the callbacks for XmNunmapCallback are invoked. When a Command that is not the child of a DialogShell is unmapped, the callbacks are not invoked.

  Default Translations
Command inherits default translations from SelectionBox.

  Default Accelerators
The default accelerator translations added to descendants of a BulletinBoard if the parent of the BulletinBoard is a DialogShell are:
#override
<Key>F1:	Help()
<Key>Return:	Return()
<Key>KP_Enter:	Return()

  Default Text Accelerators
The default text accelerators inherited from SelectionBox are:
#override
<Key>Up:	UpOrDown(0)
<Key>Down:	UpOrDown(1)
<Key>F1:	Help()
<Key>Return:	Return()
<Key>KP_Enter:	Return()

  Keyboard Traversal
For information on keyboard traversal, see the man page for XmManager(3Xm) and its sections on behavior and default translations.

RELATED INFORMATION
Composite(3Xm), Constraint(3Xm), Core(3Xm), XmBulletinBoard(3Xm), XmCommandAppendValue(3Xm), XmCommandError(3Xm), XmCommandGetChild(3Xm), XmCommandSetValue(3Xm), XmCreateCommand(3Xm), XmManager(3Xm), and XmSelectionBox(3Xm).