'\" t

...\" Command.sgm /main/12 1996/09/26 14:53:59 cdedoc $

.de P!

.fl

\!!1 setgray

.fl

\\&.\"

.fl

\!!0 setgray

.fl			\" force out current output buffer

\!!save /psv exch def currentpoint translate 0 0 moveto

\!!/showpage{}def

.fl			\" prolog

.sy sed -e 's/^/!/' \\$1\" bring in postscript file

\!!psv restore

.

.de pF

.ie     ?\\*(f1?? .ds f1 \\n(.f

.el .ie ?\\*(f2?? .ds f2 \\n(.f

.el .ie ?\\*(f3?? .ds f3 \\n(.f

.el .ie ?\\*(f4?? .ds f4 \\n(.f

.el .tm ? font overflow

.ft \\$1

..

.de fP

.ie     !?\\*(f4?? \{\

.	ft \\*(f4

.	ds f4\"

'	br \}

.el .ie !?\\*(f3?? \{\

.	ft \\*(f3

.	ds f3\"

'	br \}

.el .ie !?\\*(f2?? \{\

.	ft \\*(f2

.	ds f2\"

'	br \}

.el .ie !?\\*(f1?? \{\

.	ft \\*(f1

.	ds f1\"

'	br \}

.el .tm ? font underflow

..

.ds f1\"

.ds f2\"

.ds f3\"

.ds f4\"

.ta 8n 16n 24n 32n 40n 48n 56n 64n 72n 

.TH "XmCommand" "library call"

.SH "NAME"

\fBXmCommand\fP \(em The Command widget class

.iX "XmCommand"

.iX "widget class" "Command"

.SH "SYNOPSIS"

.PP

.nf

#include <Xm/Command\&.h>

.fi

.SH "DESCRIPTION"

.PP

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\&.

.PP

One additional \fBWorkArea\fP child may be added to the Command after

creation\&.

.PP

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\&.

.PP

Many of the new resources specified for Command are actually SelectionBox

resources that have been renamed for clarity and ease of use\&.

.SS "Descendants"

.PP

Command automatically creates the descendants shown in the

following table\&.

An application can use \fBXtNameToWidget\fP to gain access

to the named descendant\&. In addition, a user or an application

can use the named descendant when specifying resource values\&.

.TS

tab(?) box;

l| l| l.

\fBNamed Descendant\fP?\fBClass\fP?\fBIdentity\fP

_?_?_?

=

_?_?_?

\fBItemsList\fP?\fBXmList\fP?command-history list region

_?_?_?

\fBItemsListSW\fP?\fBXmScrolledWindow\fP?T{

the ScrolledWindow parent of \fBItemsList\fP

T}

_?_?_?

\fBSelection\fP?\fBXmLabelGadget\fP?command-line prompt

_?_?_?

\fBText\fP?\fBXmTextField\fP?command-line text-input field

_?_?_?

.TE

.SS "Classes"

.PP

Command inherits behavior, resources, and traits from \fBCore\fP,

\fBComposite\fP, \fBConstraint\fP, \fBXmManager\fP,

\fBXmBulletinBoard\fP, and \fBXmSelectionBox\fP\&.

.PP

The class pointer is \fBxmCommandWidgetClass\fP\&.

.PP

The class name is \fBXmCommand\fP\&.

.SS "New Resources"

.PP

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 \fB\&.Xdefaults\fP file, remove the \fBXmN\fP or

\fBXmC\fP prefix and use the remaining letters\&.

To specify one of the defined

values for a resource in a \fB\&.Xdefaults\fP file,

remove the \fBXm\fP 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 \fBXtSetValues\fP (S),

retrieved by using \fBXtGetValues\fP (G), or is not applicable (N/A)\&.

.PP

.TS

tab(?) box;

c s s s s

l| l| l| l| l.

\fBXmCommand Resource Set\fP

\fBName\fP?\fBClass\fP?\fBType\fP?\fBDefault\fP?\fBAccess\fP

_?_?_?_?_?

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

_?_?_?_?_?

.TE

.IP "\fBXmNcommand\fP" 10

Contains the current command-line text\&. This is the \fBXmNtextString\fP

resource in SelectionBox, renamed for Command\&.

This resource can also be modified with

\fBXmCommandSetValue\fP and \fBXmCommandAppendValue\fP functions\&.

The command area is a Text widget\&.

.IP "\fBXmNcommandChangedCallback\fP" 10

Specifies the list of callbacks that is called after

each time the value of the command changes\&.

The callback reason is \fBXmCR_COMMAND_CHANGED\fP\&.

This is equivalent to the \fBXmNvalueChangedCallback\fP of the Text

widget, except that a pointer to an \fBXmCommandCallbackStructure\fP is

passed, and the structure\&'s \fIvalue\fP member contains the

\fBXmString\fR\&.

.IP "\fBXmNcommandEnteredCallback\fP" 10

Specifies the list of callbacks that is called

when a command is entered in the Command\&.

The callback reason is \fBXmCR_COMMAND_ENTERED\fP\&. A pointer to an

\fBXmCommandCallback\fP structure is passed\&.

.IP "\fBXmNhistoryItems\fP" 10

Lists \fBXmString\fR items that make up the contents

of the history list\&. This is the \fBXmNlistItems\fP resource in

SelectionBox, renamed for Command\&.

\fBXtGetValues\fP for this resource returns the list items themselves,

not a copy of the list items\&.

The application must not free the returned items\&.

.IP "\fBXmNhistoryItemCount\fP" 10

Specifies the number of \fBXmStrings\fP in \fBXmNhistoryItems\fP\&. This is

the \fBXmNlistItemCount\fP resource in SelectionBox, renamed for Command\&.

The value must not be negative\&.

.IP "\fBXmNhistoryMaxItems\fP" 10

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

.IP "\fBXmNhistoryVisibleItemCount\fP" 10

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 \fBXmNlistVisibleItemCount\fP 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\&.

.IP "\fBXmNpromptString\fP" 10

Specifies a prompt for the command line\&.

This is the \fBXmNselectionLabelString\fP

resource in SelectionBox, renamed for Command\&.

The default may vary depending on the value of the

\fBXmNlayoutDirection\fP

resource and the locale\&.

In the C locale the default is > (right angle bracket)\&.

.IP "" 10

Now that some default localized label strings are provided through

message catalogs for the children of composite widgets, the

\fBlabelString\fP resources

cannot be set on the child through default resource files\&.

Instead, the resource provided at the parent level must be used\&.

.SS "Inherited Resources"

.PP

Command inherits behavior and resources from the

superclasses described in the following tables\&.

For a complete description of each resource, refer to the

reference page for that superclass\&.

.PP

.TS

tab(?) box;

c s s s s

l| l| l| l| l.

\fBXmSelectionBox Resource Set\fP

\fBName\fP?\fBClass\fP?\fBType\fP?\fBDefault\fP?\fBAccess\fP

_?_?_?_?_?

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

_?_?_?_?_?

.TE

.PP

.TS

tab(?) box;

c s s s s

l| l| l| l| l.

\fBXmBulletinBoard Resource Set\fP

\fBName\fP?\fBClass\fP?\fBType\fP?\fBDefault\fP?\fBAccess\fP

_?_?_?_?_?

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

_?_?_?_?_?

.TE

.PP

.TS

tab(?) box;

c s s s s

l| l| l| l| l.

\fBXmManager Resource Set\fP

\fBName\fP?\fBClass\fP?\fBType\fP?\fBDefault\fP?\fBAccess\fP

_?_?_?_?_?

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

_?_?_?_?_?

.TE

.PP

.TS

tab(?) box;

c s s s s

l| l| l| l| l.

\fBComposite Resource Set\fP

\fBName\fP?\fBClass\fP?\fBType\fP?\fBDefault\fP?\fBAccess\fP

_?_?_?_?_?

XmNchildren?XmCReadOnly?WidgetList?NULL?G

_?_?_?_?_?

XmNinsertPosition?XmCInsertPosition?XtOrderProc?NULL?CSG

_?_?_?_?_?

XmNnumChildren?XmCReadOnly?Cardinal?0?G

_?_?_?_?_?

.TE

.PP

.TS

tab(?) box;

c s s s s

l| l| l| l| l.

\fBCore Resource Set\fP

\fBName\fP?\fBClass\fP?\fBType\fP?\fBDefault\fP?\fBAccess\fP

_?_?_?_?_?

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

_?_?_?_?_?

.TE

.SS "Callback Information"

.PP

A pointer to the following structure is passed to each callback:

.PP

.nf

typedef struct

{

        int \fIreason\fP;

        XEvent \fI* event\fP;

        XmString \fIvalue\fP;

        int \fIlength\fP;

} XmCommandCallbackStruct;

.fi

.IP "\fIreason\fP" 10

Indicates why the callback was invoked

.IP "\fIevent\fP" 10

Points to the \fBXEvent\fP that triggered the callback

.IP "\fIvalue\fP" 10

Specifies the \fBXmString\fR in the CommandArea

.IP "\fIlength\fP" 10

Specifies the size in bytes of the \fBXmString\fR value\&.

This member is obsolete and exists for compatibility with

earlier releases\&.

.SS "Translations"

.PP

\fBXmCommand\fP inherits translations from \fBXmSelectionBox\fP\&.

.SS "Accelerators"

.PP

The \fBXmNtextAccelerators\fP from \fBXmSelectionBox\fP are added to the Text

descendant of \fBXmCommand\fP\&.

.SS "Action Routines"

.PP

The \fBXmCommand\fP action routines are:

.IP "SelectionBoxUpOrDown(\fBPrevious|Next|First|Last\fP):" 10

When called with an argument of \fBPrevious\fP, or 0 (zero) for

compatibility,

selects the previous item in the history

list and replaces the text with that item\&.

.IP "" 10

When called with an argument of \fBNext\fP, or 1 for

compatibility, selects the next item in the history

list and replaces the text with that item\&.

.IP "" 10

When called with an argument of \fBFirst\fP, or 2 for

compatibility, selects the first item in the history

list and replaces the text with that item\&.

.IP "" 10

When called with an argument of \fBLast\fP, or 3 for

compatibility, selects the last item in the history

list and replaces the text with that item\&.

.IP "" 10

Calls the callbacks for \fBXmNcommandChangedCallback\fP\&.

.SS "Additional Behavior"

.PP

The Command widget has the following additional behavior:

.IP "\fB<Key>\fP\fB<osfCancel>\fP:" 10

If the parent of the Command is a manager, the event is passed to the parent\&.

.IP "\fB<Key>\fP\fB<osfActivate>\fP\ in\ Text:" 10

Calls the Text widget\&'s \fBXmNactivateCallback\fP callbacks\&.

If the text is empty, this action then returns\&.

Otherwise, if the history list has \fBXmNhistoryMaxItems\fP 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 \fBXmNcommandEnteredCallback\fP callbacks\&.

.IP "\fB<Key>\fP\ in\ Text:" 10

When any change is made to the text edit widget, this action

calls the callbacks for

\fBXmNcommandChangedCallback\fP\&.

.IP "\fB<BtnDown>\fP\fB(2+)\fP\ or\ \fB<Key>\fP\fB<osfActivate>\fP\ in\ List:" 10

Calls the List widget\&'s \fBXmNdefaultActionCallback\fP callbacks\&.

If the history list has \fBXmNhistoryMaxItems\fP 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 \fBXmNcommandEnteredCallback\fP

callbacks\&.

.IP "\fB<FocusIn>\fP:" 10

Calls the callbacks for \fBXmNfocusCallback\fP\&.

.IP "\fB<MapWindow>\fP:" 10

When a Command that is the child of a DialogShell is mapped, this action

calls the callbacks for \fBXmNmapCallback\fP\&.

.IP "\fB<UnmapWindow>\fP:" 10

When a Command that is the child of a DialogShell is unmapped, this

action calls the

callbacks for \fBXmNunmapCallback\fP\&.

.SS "Virtual Bindings"

.PP

The bindings for virtual keys are vendor specific\&.

For information about bindings for virtual buttons and keys, see \fBVirtualBindings\fP(3)\&.

.SH "RELATED"

.PP

\fBComposite\fP(3), \fBConstraint\fP(3),

\fBCore\fP(3),

\fBXmBulletinBoard\fP(3),

\fBXmCommandAppendValue\fP(3),

\fBXmCommandError\fP(3),

\fBXmCommandGetChild\fP(3),

\fBXmCommandSetValue\fP(3),

\fBXmCreateCommand\fP(3),

\fBXmManager\fP(3),

\fBXmSelectionBox\fP(3),

\fBXmVaCreateCommand\fP(3), and

\fBXmVaCreateManagedCommand\fP(3)\&.