XmCommand(3X)XmCommand(3X)NAMEXmCommand — The Command widget class
SYNOPSIS
#include <Xm/Command.h>
VERSION
This page documents version 1.2 of the Motif library.
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-his‐
tory list region.
One additional WorkArea child may be added to the Command after cre‐
ation.
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 Selection‐
Box resources that have been renamed for clarity and ease of use.
Classes
Command inherits behavior and resources from Core, Composite, Con‐
straint, 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 pro‐
grammer to specify data. The programmer can also set the resource val‐
ues 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
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 XmNval‐
ueChangedCallback of the Text widget, except that a pointer to an
XmCommandCallbackStructure is passed, and the structure'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 them‐
selves, not a copy of the list items. The application must not free
the returned items. Specifies the number of XmStrings in XmNhisto‐
ryItems. 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 XmN‐
listVisibleItemCount 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 Com‐
mand. The default may vary depending on the value of the XmNstringDi‐
rection resource and the locale. In the C locale the default is ">".
Inherited Resources
Command inherits behavior and resources from the following super‐
classes. For a complete description of each resource, 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 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
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
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
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
XmNnavigationType XmCNavigationType XmNavigationType XmTAB_GROUP CSG
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: type‐
def struct { int reason; XEvent * event; XmString value;
int length; } XmCommandCallbackStruct; Indicates why the call‐
back was invoked Points to the XEvent that triggered the callback Spec‐
ifies 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 parent.
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 XmN‐
commandChangedCallback. Calls the List widget's XmNdefaultActionCall‐
back 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 XmN‐
focusCallback. 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).
RELATED INFORMATIONComposite(3X), Constraint(3X), Core(3X), XmBulletinBoard(3X), XmComman‐
dAppendValue(3X), XmCommandError(3X), XmCommandGetChild(3X), XmCommand‐
SetValue(3X), XmCreateCommand(3X), XmManager(3X), and XmSelection‐
Box(3X).
XmCommand(3X)
