[Contents] [Index] [Next] [Previous]

XmCommand

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 XmCR_COMMAND_CHANGED. This is equivalent to the XmNvalueChangedCallback of the Text widget, except that a pointer to an XmCommandCallback structure 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

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