XmCommand(3X) XmCommand(3X)
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 com-
mand-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
Command 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 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
Class: XmCTextString Default: "" Type: XmString Access: CSG Class: XmCCallback Default: NULL Type: XtCallbackList Access: C Class: XmC-
Callback Default: NULL Type: XtCallbackList Access: C Class: XmCItems Default: NULL Type: XmStringTable Access: CSG Class: XmCItemCount
Default: 0 Type: int Access: CSG Class: XmCMaxItems Default: 100 Type: int Access: CSG Class: XmCVisibleItemCount Default: dynamic Type:
int Access: CSG Class: XmCPromptString Default: dynamic Type: XmString Access: CSG
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. 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 a pointer to an XmCommandCallbackStructure is passed, and the struc-
ture's value member contains the XmString. 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. 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. Speci-
fies the number of XmStrings in XmNhistoryItems. This is the XmNlistItemCount resource in SelectionBox, renamed for Command. The
value must not be negative. 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. 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. The default is
dynamic based on the height of the list. 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 XmNstringDirection 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.
XmSelectionBox Resource Set
Class: XmCCallback Default: NULL Type: XtCallbackList Access: N/A Class: XmCApplyLabelString Default: dynamic Type: XmString Access: N/A
Class: XmCCallback Default: NULL Type: XtCallbackList Access: N/A Class: XmCCancelLabelString Default: dynamic Type: XmString Access: N/A
Class: XmCChildPlacement Default: XmPLACE_ABOVE_SELECTION Type: unsigned char Access: CSG Class: XmCDialogType Default: XmDIALOG_COMMAND
Type: unsigned char Access: G Class: XmCHelpLabelString Default: dynamic Type: XmString Access: N/A Class: XmCItemCount Default: 0 Type:
int Access: CSG Class: XmCItems Default: NULL Type: XmStringTable Access: CSG Class: XmCListLabelString Default: NULL Type: XmString
Access: N/A Class: XmCVisibleItemCount Default: dynamic Type: int Access: CSG Class: XmCMinimizeButtons Default: False Type: Boolean
Access: N/A Class: XmCMustMatch Default: False Type: Boolean Access: N/A Class: XmCCallback Default: NULL Type: XtCallbackList Access:
N/A Class: XmCCallback Default: NULL Type: XtCallbackList Access: N/A Class: XmCOkLabelString Default: dynamic Type: XmString Access: N/A
Class: XmCSelectionLabelString Default: dynamic Type: XmString Access: CSG Class: XmCTextAccelerators Default: default Type: XtAccelera-
tors Access: C Class: XmCColumns Default: dynamic Type: short Access: CSG Class: XmCTextString Default: "" Type: XmString Access: CSG
XmBulletinBoard Resource Set
Class: XmCAllowOverlap Default: True Type: Boolean Access: CSG Class: XmCAutoUnmanage Default: False Type: Boolean Access: N/A Class:
XmCButtonFontList Default: dynamic Type: XmFontList Access: N/A Class: XmCWidget Default: NULL Type: Widget Access: N/A Class: XmCWidget
Default: NULL Type: Widget Access: N/A Class: XmCDefaultPosition Default: False Type: Boolean Access: CSG Class: XmCDialogStyle Default:
dynamic Type: unsigned char Access: CSG Class: XmCDialogTitle Default: NULL Type: XmString Access: CSG Class: XmCCallback Default: NULL
Type: XtCallbackList Access: C Class: XmCLabelFontList Default: dynamic Type: XmFontList Access: CSG Class: XmCCallback Default: NULL
Type: XtCallbackList Access: C Class: XmCMarginHeight Default: 10 Type: Dimension Access: CSG Class: XmCMarginWidth Default: 10 Type:
Dimension Access: CSG Class: XmCNoResize Default: False Type: Boolean Access: CSG Class: XmCResizePolicy Default: XmRESIZE_NONE Type:
unsigned char Access: CSG Class: XmCShadowType Default: XmSHADOW_OUT Type: unsigned char Access: CSG Class: XmCTextFontList Default:
dynamic Type: XmFontList Access: CSG Class: XmCTranslations Default: NULL Type: XtTranslations Access: C Class: XmCCallback Default: NULL
Type: XtCallbackList Access: C
XmManager Resource Set
Class: XmCBottomShadowColor Default: dynamic Type: Pixel Access: CSG Class: XmCBottomShadowPixmap Default: XmUNSPECIFIED_PIXMAP Type:
Pixmap Access: CSG Class: XmCForeground Default: dynamic Type: Pixel Access: CSG Class: XmCCallback Default: NULL Type: XtCallbackList
Access: C Class: XmCHighlightColor Default: dynamic Type: Pixel Access: CSG Class: XmCHighlightPixmap Default: dynamic Type: Pixmap
Access: CSG Class: XmCInitialFocus Default: dynamic Type: Widget Access: CSG Class: XmCNavigationType Default: XmTAB_GROUP Type: XmNavi-
gationType Access: CSG Class: XmCShadowThickness Default: dynamic Type: Dimension Access: CSG Class: XmCStringDirection Default: dynamic
Type: XmStringDirection Access: CG Class: XmCTopShadowColor Default: dynamic Type: Pixel Access: CSG Class: XmCTopShadowPixmap Default:
dynamic Type: Pixmap Access: CSG Class: XmCTraversalOn Default: True Type: Boolean Access: CSG Class: XmCUnitType Default: dynamic Type:
unsigned char Access: CSG Class: XmCUserData Default: NULL Type: XtPointer Access: CSG
Composite Resource Set
Class: XmCReadOnly Default: NULL Type: WidgetList Access: G Class: XmCInsertPosition Default: NULL Type: XtOrderProc Access: CSG Class:
XmCReadOnly Default: 0 Type: Cardinal Access: G
Core Resource Set
Class: XmCAccelerators Default: dynamic Type: XtAccelerators Access: N/A Class: XmCSensitive Default: dynamic Type: Boolean Access: G
Class: XmCBackground Default: dynamic Type: Pixel Access: CSG Class: XmCPixmap Default: XmUNSPECIFIED_PIXMAP Type: Pixmap Access: CSG
Class: XmCBorderColor Default: XtDefaultForeground Type: Pixel Access: CSG Class: XmCPixmap Default: XmUNSPECIFIED_PIXMAP Type: Pixmap
Access: CSG Class: XmCBorderWidth Default: 0 Type: Dimension Access: CSG Class: XmCColormap Default: dynamic Type: Colormap Access: CG
Class: XmCDepth Default: dynamic Type: int Access: CG Class: XmCCallback Default: NULL Type: XtCallbackList Access: C Class: XmCHeight
Default: dynamic Type: Dimension Access: CSG Class: XmCInitialResourcesPersistent Default: True Type: Boolean Access: C Class: XmCMapped-
WhenManaged Default: True Type: Boolean Access: CSG Class: XmCScreen Default: dynamic Type: Screen * Access: CG Class: XmCSensitive
Default: True Type: Boolean Access: CSG Class: XmCTranslations Default: dynamic Type: XtTranslations Access: CSG Class: XmCWidth Default:
dynamic Type: Dimension Access: CSG Class: XmCPosition Default: 0 Type: Position Access: CSG Class: XmCPosition Default: 0 Type: Posi-
tion Access: 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;
Indicates why the callback was invoked Points to the XEvent that triggered the callback Specifies the XmString in the CommandArea Specifies
the size of the command in XmString
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 described below: 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 history list and replaces the text with that item.
When called with a 2 argument, selects the first item in the history list and replaces the text with that item.
When called with a 3 argument, 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 additional behavior described below: If the parent of the Command is a manager, the event is passed to the par-
ent. 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. When any change is made to the text edit widget, this action calls the callbacks
for XmNcommandChangedCallback. 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. Calls the callbacks for XmNfocusCallback. When a Command that is the child of a
DialogShell is mapped, this action calls the callbacks for XmNmapCallback. 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(3X).
SEE ALSO
Composite(3X), Constraint(3X), Core(3X), XmBulletinBoard(3X), XmCommandAppendValue(3X), XmCommandError(3X), XmCommandGetChild(3X), XmCom-
mandSetValue(3X), XmCreateCommand(3X), XmManager(3X), XmSelectionBox(3X)
XmCommand(3X)