XmCommand(3X) UNIX System V 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).
10/89 Page 1
XmCommand(3X) UNIX System V XmCommand(3X)
______________________________________________________________________________________
| 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 |
|__________________________|_____________________|________________|_________|________|
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.
Page 2 10/89
XmCommand(3X) UNIX System V XmCommand(3X)
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.
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.
10/89 Page 3
XmCommand(3X) UNIX System V XmCommand(3X)
_________________________________________________________________________________________________
| XmSelectionBox Resource Set |
|_______________________|_________________________|________________|___________________|________|
|Name | Class | Type | Default | Access|
|_______________________|_________________________|________________|___________________|________|
|_______________________|_________________________|________________|___________________|________|
|XmNapplyCallback | XmCCallback | XtCallbackList| NULL | N/A |
|_______________________|_________________________|________________|___________________|________|
|XmNapplyLabelString | XmCApplyLabelString | XmString | "Apply" | N/A |
|_______________________|_________________________|________________|___________________|________|
|XmNcancelCallback | XmCCallback | XtCallbackList| NULL | N/A |
|_______________________|_________________________|________________|___________________|________|
|XmNcancelLabelString | XmCCancelLabelString | XmString | "Cancel" | N/A |
|_______________________|_________________________|________________|___________________|________|
|XmNdialogType | XmCDialogType | unsigned char | XmDIALOG_COMMAND | G |
|_______________________|_________________________|________________|___________________|________|
|XmNhelpLabelString | XmCHelpLabelString | XmString | "Help" | 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 | "OK" | N/A |
|_______________________|_________________________|________________|___________________|________|
|XmNselectionLabelString| XmCSelectionLabelString| XmString | ">" | CSG |
|_______________________|_________________________|________________|___________________|________|
|XmNtextAccelerators | XmCTextAccelerators | XtAccelerators| default | C |
|_______________________|_________________________|________________|___________________|________|
|XmNtextColumns | XmCColumns | short | dynamic | CSG |
|_______________________|_________________________|________________|___________________|________|
|XmNtextString | XmCTextString | XmString | "" | CSG |
|_______________________|_________________________|________________|___________________|________|
Page 4 10/89
XmCommand(3X) UNIX System V XmCommand(3X)
____________________________________________________________________________________
| 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 |
|___________________|____________________|________________|_______________|________|
10/89 Page 5
XmCommand(3X) UNIX System V XmCommand(3X)
_________________________________________________________________________________________________________
| 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 |
|_____________________|_____________________________|___________________|______________________|________|
|XmNnavigationType | XmCNavigationType | XmNavigationType | dynamic | CSG |
|_____________________|_____________________________|___________________|______________________|________|
|XmNshadowThickness | XmCShadowThickness | Dimension | dynamic | CSG |
|_____________________|_____________________________|___________________|______________________|________|
|XmNstringDirection | XmCStringDirection | XmStringDirection| dynamic | CG |
|_____________________|_____________________________|___________________|______________________|________|
|XmNtopShadowColor | XmCBackgroundTopShadowColor| Pixel | dynamic | CSG |
|_____________________|_____________________________|___________________|______________________|________|
|XmNtopShadowPixmap | XmCTopShadowPixmap | Pixmap | dynamic | CSG |
|_____________________|_____________________________|___________________|______________________|________|
|XmNtraversalOn | XmCTraversalOn | Boolean | True | CSG |
|_____________________|_____________________________|___________________|______________________|________|
|XmNunitType | XmCUnitType | unsigned char | dynamic | CSG |
|_____________________|_____________________________|___________________|______________________|________|
|XmNuserData | XmCUserData | Pointer | NULL | CSG |
|_____________________|_____________________________|___________________|______________________|________|
_______________________________________________________________________
| Composite Resource Set |
|__________________|___________________|____________|_________|________|
| Name | Class | Type | Default| Access|
|__________________|___________________|____________|_________|________|
|__________________|___________________|____________|_________|________|
| XmNchildren | XmCReadOnly | WidgetList| NULL | G |
|__________________|___________________|____________|_________|________|
| XmNinsertPosition| XmCInsertPosition| (*)() | NULL | CSG |
|__________________|___________________|____________|_________|________|
| XmNnumChildren | XmCReadOnly | Cardinal | 0 | G |
|__________________|___________________|____________|_________|________|
Page 6 10/89
XmCommand(3X) UNIX System V XmCommand(3X)
________________________________________________________________________________________________________________
| 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:
typedef struct
{
int reason;
10/89 Page 7
XmCommand(3X) UNIX System V XmCommand(3X)
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:
<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
Page 8 10/89
XmCommand(3X) UNIX System V XmCommand(3X)
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).
10/89 Page 9