XmCommand(library call) XmCommand(library call)
NAME [Toc] [Back]
XmCommand - The Command widget class
SYNOPSIS [Toc] [Back]
#include <Xm/Command.h>
DESCRIPTION [Toc] [Back]
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 commandhistory
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.
Descendants [Toc] [Back]
Command automatically creates the descendants shown in the following
table. An application can use XtNameToWidget to gain access to the
named descendant. In addition, a user or an application can use the
named descendant when specifying resource values.
_____________________________________________________________________
|Named Descendant | Class | Identity |
|_________________|__________________|_______________________________|
|_________________|__________________|_______________________________|
|_________________|__________________|_______________________________|
|ItemsList | XmList | command-history list region |
|_________________|__________________|_______________________________|
|ItemsListSW | XmScrolledWindow | the ScrolledWindow parent of |
| | | ItemsList |
|_________________|__________________|_______________________________|
|Selection | XmLabelGadget | command-line prompt |
|_________________|__________________|_______________________________|
|Text | XmTextField | command-line text-input field |
|_________________|__________________|_______________________________|
|_________________|__________________|_______________________________|
Classes [Toc] [Back]
Command inherits behavior, resources, and traits from Core, Composite,
Constraint, XmManager, XmBulletinBoard, and XmSelectionBox.
The class pointer is xmCommandWidgetClass.
- 1 - Formatted: January 24, 2005
XmCommand(library call) XmCommand(library call)
The class name is XmCommand.
New Resources [Toc] [Back]
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 [Toc] [Back]
Contains the current command-line text. This is the
XmNtextString resource in SelectionBox, renamed for Command.
This resource can also be modified with XmCommandSetValue
and XmCommandAppendValue functions. The command area is a
Text widget.
XmNcommandChangedCallback [Toc] [Back]
Specifies the list of callbacks that is called after each
time 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.
- 2 - Formatted: January 24, 2005
XmCommand(library call) XmCommand(library call)
XmNcommandEnteredCallback [Toc] [Back]
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 [Toc] [Back]
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 [Toc] [Back]
Specifies the number of XmStrings in XmNhistoryItems. This
is the XmNlistItemCount resource in SelectionBox, renamed
for Command. The value must not be negative.
XmNhistoryMaxItems [Toc] [Back]
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 (zero).
XmNhistoryVisibleItemCount [Toc] [Back]
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 (zero). The
default is dynamic based on the height of the list.
XmNpromptString [Toc] [Back]
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 XmNlayoutDirection resource and the locale. In the C
locale the default is > (right angle bracket).
Now that some default localized label strings are provided
through message catalogs for the children of composite
widgets, the labelString resources cannot be set on the
child through default resource files. Instead, the resource
provided at the parent level must be used.
Inherited Resources [Toc] [Back]
Command inherits behavior and resources from the superclasses
described in the following tables. For a complete description of each
- 3 - Formatted: January 24, 2005
XmCommand(library call) XmCommand(library call)
resource, refer to the reference 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 |
|________________________|_________________________|________________|_________________________|________|
|________________________|_________________________|________________|_________________________|________|
- 4 - Formatted: January 24, 2005
XmCommand(library call) XmCommand(library call)
_______________________________________________________________________________________
| 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 |
|_____________________|______________________|________________|_______________|________|
|XmNbuttonRenderTable | XmCButtonRenderTable | XmRenderTable | dynamic | CSG |
|_____________________|______________________|________________|_______________|________|
|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 |
|_____________________|______________________|________________|_______________|________|
|XmNlabelRenderTable | XmCLabelRenderTable | XmRenderTable | 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 |
|_____________________|______________________|________________|_______________|________|
|XmNtextRenderTable | XmCTextRenderTable | XmRenderTable | dynamic | CSG |
|_____________________|______________________|________________|_______________|________|
|XmNtextTranslations | XmCTranslations | XtTranslations | NULL | C |
|_____________________|______________________|________________|_______________|________|
|XmNunmapCallback | XmCCallback | XtCallbackList | NULL | C |
|_____________________|______________________|________________|_______________|________|
|_____________________|______________________|________________|_______________|________|
- 5 - Formatted: January 24, 2005
XmCommand(library call) XmCommand(library call)
_____________________________________________________________________________________________________
| 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 |
|________________________|_______________________|___________________|______________________|________|
|XmNlayoutDirection | XmCLayoutDirection | XmDirection | dynamic | CG |
|________________________|_______________________|___________________|______________________|________|
|XmNnavigationType | XmCNavigationType | XmNavigationType | XmTAB_GROUP | CSG |
|________________________|_______________________|___________________|______________________|________|
|XmNpopupHandlerCallback | XmCCallback | XtCallbackList | NULL | C |
|________________________|_______________________|___________________|______________________|________|
|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
________________________________________________________________________
________________________________________________________________________
- 6 - Formatted: January 24, 2005
XmCommand(library call) XmCommand(library call)
| | | | | |
________________________________________________________________________________________________________________
| | | 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 [Toc] [Back]
A pointer to the following structure is passed to each callback:
typedef struct
{
- 7 - Formatted: January 24, 2005
XmCommand(library call) XmCommand(library call)
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 in bytes of the XmString value. This
member is obsolete and exists for compatibility with earlier
releases.
Translations [Toc] [Back]
XmCommand inherits translations from XmSelectionBox.
Accelerators [Toc] [Back]
The XmNtextAccelerators from XmSelectionBox are added to the Text
descendant of XmCommand.
Action Routines [Toc] [Back]
The XmCommand action routines are:
SelectionBoxUpOrDown(Previous|Next|First|Last):
When called with an argument of Previous, or 0 (zero) for
compatibility, selects the previous item in the history list
and replaces the text with that item.
When called with an argument of Next, or 1 for
compatibility, selects the next item in the history list and
replaces the text with that item.
When called with an argument of First, or 2 for
compatibility, selects the first item in the history list
and replaces the text with that item.
When called with an argument of Last, or 3 for
compatibility, selects the last item in the history list and
replaces the text with that item.
Calls the callbacks for XmNcommandChangedCallback.
Additional Behavior [Toc] [Back]
The Command widget has the following additional behavior:
<Key><osfCancel>:
If the parent of the Command is a manager, the event is
passed to the parent.
- 8 - Formatted: January 24, 2005
XmCommand(library call) XmCommand(library call)
<Key><osfActivate> 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.
<BtnDown>(2+) or <Key><osfActivate> 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 [Toc] [Back]
The bindings for virtual keys are vendor specific. For information
about bindings for virtual buttons and keys, see VirtualBindings(3).
RELATED [Toc] [Back]
Composite(3), Constraint(3), Core(3), XmBulletinBoard(3),
XmCommandAppendValue(3), XmCommandError(3), XmCommandGetChild(3),
XmCommandSetValue(3), XmCreateCommand(3), XmManager(3), and
XmSelectionBox(3).
- 9 - Formatted: January 24, 2005 [ Back ] |
