XmCommand(3X) — Subroutines
OSF/Motif
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
XmNcommand
Class: XmCTextString
Default: ""
Type: XmString
Access: CSG
XmNcommandChangedCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
XmNcommandEnteredCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
XmNhistoryItems
Class: XmCItems
Default: NULL
Type: XmStringTable
Access: CSG
XmNhistoryItemCount
Class: XmCItemCount
Default: 0
Type: int
Access: CSG
XmNhistoryMaxItems
Class: XmCMaxItems
Default: 100
Type: int
Access: CSG
XmNhistoryVisibleItemCount
Class: XmCVisibleItemCount
Default: dynamic
Type: int
Access: CSG
XmNpromptString
Class: XmCPromptString
Default: dynamic
Type: XmString
Access: 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 a pointer to an XmCommandCallbackStructure is passed, and the structure’s value member contains 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. A pointer to an XmCommandCallback structure is passed.
XmNhistoryItems
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.
XmNhistoryItemCount
Specifies the number of XmStrings in XmNhistoryItems. This is the XmNlistItemCount resource in SelectionBox, renamed for Command. The value must not be negative.
XmNhistoryMaxItems
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.
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 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.
XmNpromptString
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
XmNapplyCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: N/A
XmNapplyLabelString
Class: XmCApplyLabelString
Default: dynamic
Type: XmString
Access: N/A
XmNcancelCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: N/A
XmNcancelLabelString
Class: XmCCancelLabelString
Default: dynamic
Type: XmString
Access: N/A
XmNchildPlacement
Class: XmCChildPlacement
Default: XmPLACE_ABOVE_SELECTION
Type: unsigned char
Access: CSG
XmNdialogType
Class: XmCDialogType
Default: XmDIALOG_COMMAND
Type: unsigned char
Access: G
XmNhelpLabelString
Class: XmCHelpLabelString
Default: dynamic
Type: XmString
Access: N/A
XmNlistItemCount
Class: XmCItemCount
Default: 0
Type: int
Access: CSG
XmNlistItems
Class: XmCItems
Default: NULL
Type: XmStringTable
Access: CSG
XmNlistLabelString
Class: XmCListLabelString
Default: NULL
Type: XmString
Access: N/A
XmNlistVisibleItemCount
Class: XmCVisibleItemCount
Default: dynamic
Type: int
Access: CSG
XmNminimizeButtons
Class: XmCMinimizeButtons
Default: False
Type: Boolean
Access: N/A
XmNmustMatch
Class: XmCMustMatch
Default: False
Type: Boolean
Access: N/A
XmNnoMatchCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: N/A
XmNokCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: N/A
XmNokLabelString
Class: XmCOkLabelString
Default: dynamic
Type: XmString
Access: N/A
XmNselectionLabelString
Class: XmCSelectionLabelString
Default: dynamic
Type: XmString
Access: CSG
XmNtextAccelerators
Class: XmCTextAccelerators
Default: default
Type: XtAccelerators
Access: C
XmNtextColumns
Class: XmCColumns
Default: dynamic
Type: short
Access: CSG
XmNtextString
Class: XmCTextString
Default: ""
Type: XmString
Access: CSG
XmBulletinBoard Resource Set
XmNallowOverlap
Class: XmCAllowOverlap
Default: True
Type: Boolean
Access: CSG
XmNautoUnmanage
Class: XmCAutoUnmanage
Default: False
Type: Boolean
Access: N/A
XmNbuttonFontList
Class: XmCButtonFontList
Default: dynamic
Type: XmFontList
Access: N/A
XmNcancelButton
Class: XmCWidget
Default: NULL
Type: Widget
Access: N/A
XmNdefaultButton
Class: XmCWidget
Default: NULL
Type: Widget
Access: N/A
XmNdefaultPosition
Class: XmCDefaultPosition
Default: False
Type: Boolean
Access: CSG
XmNdialogStyle
Class: XmCDialogStyle
Default: dynamic
Type: unsigned char
Access: CSG
XmNdialogTitle
Class: XmCDialogTitle
Default: NULL
Type: XmString
Access: CSG
XmNfocusCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
XmNlabelFontList
Class: XmCLabelFontList
Default: dynamic
Type: XmFontList
Access: CSG
XmNmapCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
XmNmarginHeight
Class: XmCMarginHeight
Default: 10
Type: Dimension
Access: CSG
XmNmarginWidth
Class: XmCMarginWidth
Default: 10
Type: Dimension
Access: CSG
XmNnoResize
Class: XmCNoResize
Default: False
Type: Boolean
Access: CSG
XmNresizePolicy
Class: XmCResizePolicy
Default: XmRESIZE_NONE
Type: unsigned char
Access: CSG
XmNshadowType
Class: XmCShadowType
Default: XmSHADOW_OUT
Type: unsigned char
Access: CSG
XmNtextFontList
Class: XmCTextFontList
Default: dynamic
Type: XmFontList
Access: CSG
XmNtextTranslations
Class: XmCTranslations
Default: NULL
Type: XtTranslations
Access: C
XmNunmapCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
XmManager Resource Set
XmNbottomShadowColor
Class: XmCBottomShadowColor
Default: dynamic
Type: Pixel
Access: CSG
XmNbottomShadowPixmap
Class: XmCBottomShadowPixmap
Default: XmUNSPECIFIED_PIXMAP
Type: Pixmap
Access: CSG
XmNforeground
Class: XmCForeground
Default: dynamic
Type: Pixel
Access: CSG
XmNhelpCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
XmNhighlightColor
Class: XmCHighlightColor
Default: dynamic
Type: Pixel
Access: CSG
XmNhighlightPixmap
Class: XmCHighlightPixmap
Default: dynamic
Type: Pixmap
Access: CSG
XmNinitialFocus
Class: XmCInitialFocus
Default: dynamic
Type: Widget
Access: CSG
XmNnavigationType
Class: XmCNavigationType
Default: XmTAB_GROUP
Type: XmNavigationType
Access: CSG
XmNshadowThickness
Class: XmCShadowThickness
Default: dynamic
Type: Dimension
Access: CSG
XmNstringDirection
Class: XmCStringDirection
Default: dynamic
Type: XmStringDirection
Access: CG
XmNtopShadowColor
Class: XmCTopShadowColor
Default: dynamic
Type: Pixel
Access: CSG
XmNtopShadowPixmap
Class: XmCTopShadowPixmap
Default: dynamic
Type: Pixmap
Access: CSG
XmNtraversalOn
Class: XmCTraversalOn
Default: True
Type: Boolean
Access: CSG
XmNunitType
Class: XmCUnitType
Default: dynamic
Type: unsigned char
Access: CSG
XmNuserData
Class: XmCUserData
Default: NULL
Type: XtPointer
Access: CSG
Composite Resource Set
XmNchildren
Class: XmCReadOnly
Default: NULL
Type: WidgetList
Access: G
XmNinsertPosition
Class: XmCInsertPosition
Default: NULL
Type: XtOrderProc
Access: CSG
XmNnumChildren
Class: XmCReadOnly
Default: 0
Type: Cardinal
Access: G
Core Resource Set
XmNaccelerators
Class: XmCAccelerators
Default: dynamic
Type: XtAccelerators
Access: N/A
XmNancestorSensitive
Class: XmCSensitive
Default: dynamic
Type: Boolean
Access: G
XmNbackground
Class: XmCBackground
Default: dynamic
Type: Pixel
Access: CSG
XmNbackgroundPixmap
Class: XmCPixmap
Default: XmUNSPECIFIED_PIXMAP
Type: Pixmap
Access: CSG
XmNborderColor
Class: XmCBorderColor
Default: XtDefaultForeground
Type: Pixel
Access: CSG
XmNborderPixmap
Class: XmCPixmap
Default: XmUNSPECIFIED_PIXMAP
Type: Pixmap
Access: CSG
XmNborderWidth
Class: XmCBorderWidth
Default: 0
Type: Dimension
Access: CSG
XmNcolormap
Class: XmCColormap
Default: dynamic
Type: Colormap
Access: CG
XmNdepth
Class: XmCDepth
Default: dynamic
Type: int
Access: CG
XmNdestroyCallback
Class: XmCCallback
Default: NULL
Type: XtCallbackList
Access: C
XmNheight
Class: XmCHeight
Default: dynamic
Type: Dimension
Access: CSG
XmNinitialResourcesPersistent
Class: XmCInitialResourcesPersistent
Default: True
Type: Boolean
Access: C
XmNmappedWhenManaged
Class: XmCMappedWhenManaged
Default: True
Type: Boolean
Access: CSG
XmNscreen
Class: XmCScreen
Default: dynamic
Type: Screen ∗
Access: CG
XmNsensitive
Class: XmCSensitive
Default: True
Type: Boolean
Access: CSG
XmNtranslations
Class: XmCTranslations
Default: dynamic
Type: XtTranslations
Access: CSG
XmNwidth
Class: XmCWidth
Default: dynamic
Type: Dimension
Access: CSG
XmNx
Class: XmCPosition
Default: 0
Type: Position
Access: CSG
XmNy
Class: XmCPosition
Default: 0
Type: Position
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;
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
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).
SEE ALSO
Composite(3X), Constraint(3X), Core(3X), XmBulletinBoard(3X), XmCommandAppendValue(3X), XmCommandError(3X), XmCommandGetChild(3X), XmCommandSetValue(3X), XmCreateCommand(3X), XmManager(3X), XmSelectionBox(3X)