XmCommand(library call) XmCommand(library call)

XmCommand — The Command widget class

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

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

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

The class pointer is xmCommandWidgetClass.

The class name is XmCommand.

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

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

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

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 in bytes of the XmString value. This member is obsolete and exists for compatibility with earlier releases.

XmCommand inherits translations from XmSelectionBox.

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

The XmCommand action routines are:

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.

The Command widget has the following additional behavior:

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

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