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 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
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
NameClassTypeDefaultAccess
XmNcommandXmCTextStringXmString""CSG
XmNcommandChangedCallbackXmCCallbackXtCallbackListNULLC
XmNcommandEnteredCallbackXmCCallbackXtCallbackListNULLC
XmNhistoryItemsXmCItemsXmStringTableNULLCSG
XmNhistoryItemCountXmCItemCountint0CSG
XmNhistoryMaxItemsXmCMaxItemsint100CSG
XmNhistoryVisibleItemCountXmCVisibleItemCountintdynamicCSG
XmNpromptStringXmCPromptStringXmStringdynamicCSG
XmNcommandContains 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.
XmNcommandChangedCallbackSpecifies 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 structure’s value member contains the
XmString.
XmNcommandEnteredCallbackSpecifies 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.
XmNhistoryItemsLists 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.
XmNhistoryItemCountSpecifies the number of XmStrings in XmNhistoryItems. This is
the XmNlistItemCount resource in SelectionBox, renamed for Command.
The value must not be negative.
XmNhistoryMaxItemsSpecifies 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.
XmNhistoryVisibleItemCountSpecifies 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.
XmNpromptStringSpecifies 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
NameClassTypeDefaultAccess
XmNapplyCallbackXmCCallbackXtCallbackListNULLN/A
XmNapplyLabelStringXmCApplyLabelStringXmStringdynamicN/A
XmNcancelCallbackXmCCallbackXtCallbackListNULLN/A
XmNcancelLabelStringXmCCancelLabelStringXmStringdynamic N/A
XmNchildPlacementXmCChildPlacementunsigned charXmPLACE_ABOVE_SELECTIONCSG
XmNdialogTypeXmCDialogTypeunsigned charXmDIALOG_COMMAND G
XmNhelpLabelStringXmCHelpLabelStringXmStringdynamic N/A
XmNlistItemCountXmCItemCountint0 CSG
XmNlistItemsXmCItemsXmStringTableNULLCSG
XmNlistLabelStringXmCListLabelStringXmStringNULLN/A
XmNlistVisibleItemCountXmCVisibleItemCountintdynamic CSG
XmNminimizeButtonsXmCMinimizeButtonsBooleanFalseN/A
XmNmustMatchXmCMustMatchBooleanFalse N/A
XmNnoMatchCallbackXmCCallbackXtCallbackListNULLN/A
XmNokCallbackXmCCallbackXtCallbackListNULLN/A
XmNokLabelStringXmCOkLabelStringXmStringdynamicN/A
XmNselectionLabelStringXmCSelectionLabelStringXmStringdynamicCSG
XmNtextAcceleratorsXmCTextAcceleratorsXtAcceleratorsdefaultC
XmNtextColumnsXmCColumnsshortdynamicCSG
XmNtextStringXmCTextStringXmString""CSG
XmBulletinBoard Resource Set
NameClassTypeDefaultAccess
XmNallowOverlapXmCAllowOverlapBooleanTrueCSG
XmNautoUnmanageXmCAutoUnmanageBooleanFalseN/A
XmNbuttonFontListXmCButtonFontListXmFontListdynamicN/A
XmNcancelButtonXmCWidgetWidgetNULLN/A
XmNdefaultButtonXmCWidgetWidgetNULLN/A
XmNdefaultPositionXmCDefaultPositionBooleanFalseCSG
XmNdialogStyleXmCDialogStyleunsigned chardynamicCSG
XmNdialogTitleXmCDialogTitleXmStringNULLCSG
XmNfocusCallbackXmCCallbackXtCallbackListNULLC
XmNlabelFontListXmCLabelFontListXmFontListdynamicCSG
XmNmapCallbackXmCCallbackXtCallbackListNULLC
XmNmarginHeightXmCMarginHeightDimension10CSG
XmNmarginWidthXmCMarginWidthDimension10 CSG
XmNnoResizeXmCNoResizeBooleanFalseCSG
XmNresizePolicyXmCResizePolicyunsigned charXmRESIZE_NONECSG
XmNshadowTypeXmCShadowTypeunsigned charXmSHADOW_OUTCSG
XmNtextFontListXmCTextFontListXmFontListdynamicCSG
XmNtextTranslationsXmCTranslationsXtTranslationsNULLC
XmNunmapCallbackXmCCallbackXtCallbackListNULLC
XmManager Resource Set
NameClassTypeDefaultAccess
XmNbottomShadowColorXmCBottomShadowColorPixeldynamicCSG
XmNbottomShadowPixmapXmCBottomShadowPixmapPixmapXmUNSPECIFIED_PIXMAPCSG
XmNforegroundXmCForegroundPixeldynamicCSG
XmNhelpCallbackXmCCallbackXtCallbackListNULLC
XmNhighlightColorXmCHighlightColorPixeldynamicCSG
XmNhighlightPixmapXmCHighlightPixmapPixmapdynamicCSG
XmNinitialFocusXmCInitialFocusWidgetdynamicCSG
XmNnavigationTypeXmCNavigationTypeXmNavigationTypeXmTAB_GROUPCSG
XmNshadowThicknessXmCShadowThicknessDimensiondynamicCSG
XmNstringDirectionXmCStringDirectionXmStringDirectiondynamicCG
XmNtopShadowColorXmCTopShadowColorPixeldynamicCSG
XmNtopShadowPixmapXmCTopShadowPixmapPixmapdynamicCSG
XmNtraversalOnXmCTraversalOnBooleanTrueCSG
XmNunitTypeXmCUnitTypeunsigned chardynamicCSG
XmNuserDataXmCUserDataXtPointerNULLCSG
Composite Resource Set
NameClassTypeDefaultAccess
XmNchildrenXmCReadOnlyWidgetListNULLG
XmNinsertPositionXmCInsertPositionXtOrderProcNULLCSG
XmNnumChildrenXmCReadOnlyCardinal0G
Core Resource Set
NameClassTypeDefaultAccess
XmNacceleratorsXmCAcceleratorsXtAcceleratorsdynamicN/A
XmNancestorSensitiveXmCSensitiveBooleandynamicG
XmNbackgroundXmCBackgroundPixeldynamicCSG
XmNbackgroundPixmapXmCPixmapPixmapXmUNSPECIFIED_PIXMAPCSG
XmNborderColorXmCBorderColorPixelXtDefaultForegroundCSG
XmNborderPixmapXmCPixmapPixmapXmUNSPECIFIED_PIXMAPCSG
XmNborderWidthXmCBorderWidthDimension0CSG
XmNcolormapXmCColormapColormapdynamicCG
XmNdepthXmCDepthintdynamicCG
XmNdestroyCallbackXmCCallbackXtCallbackListNULLC
XmNheightXmCHeightDimensiondynamicCSG
XmNinitialResourcesPersistentXmCInitialResourcesPersistentBooleanTrueC
XmNmappedWhenManagedXmCMappedWhenManagedBooleanTrueCSG
XmNscreenXmCScreenScreen ∗dynamicCG
XmNsensitiveXmCSensitiveBooleanTrueCSG
XmNtranslationsXmCTranslationsXtTranslationsdynamicCSG
XmNwidthXmCWidthDimensiondynamicCSG
XmNxXmCPositionPosition0CSG
XmNyXmCPositionPosition0CSG
Callback Information
A pointer to the following structure is passed to each callback:
typedef struct
{
intreason;
XEvent∗ event;
XmStringvalue;
intlength;
} XmCommandCallbackStruct;
reasonIndicates why the callback was invoked
eventPoints to the XEvent that triggered the callback
valueSpecifies the XmString in the CommandArea
lengthSpecifies 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:
SelectionBoxUpOrDown(0|1|2|3):
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:
MAny KCancel:
If the parent of the Command is a manager, the event is passed to the parent.
KActivate 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.
<DoubleClick> or <KActivate> 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(3X).
RELATED INFORMATION
Composite(3X), Constraint(3X), Core(3X), XmBulletinBoard(3X), XmCommandAppendValue(3X), XmCommandError(3X), XmCommandGetChild(3X), XmCommandSetValue(3X), XmCreateCommand(3X), XmManager(3X), and XmSelectionBox(3X).
SunOS — Last change: