XmCommand(3X) SDK X11 R4.11MU05 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 |
+---------------------------+---------------------+----------------+---------+--------+
|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
XmCRCOMMANDCHANGED. 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
XmCRCOMMANDENTERED. 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 |
+------------------------+-------------------------+----------------+-------------------------+--------+
|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:
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).
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).
Licensed material--property of copyright holder(s)