XmCommand(3X)
XmCommand --The Command widget class
Showing IRIX 6.5.30 (default release). Unchanged since IRIX 6.5.
NAME XmCommand --The Command widget class SYNOPSIS #include <Xm/Command.h> VERSION This page documents version 1.2 of the Motif library. DESCRIPTION Command is a special-purpose composite widget for command entry that pro- vides 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 program- mer 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 re- maining letters (in either lowercase or uppercase, but include any under- scores 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 XmNcommandContains the current command-line text. This is the XmN- textString resource in SelectionBox, renamed for Command. This resource can also be modified via XmCommandSetValue and XmComman- dAppendValue 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_COM- MAND_CHANGED. This is equivalent to the XmNvalueChangedCallback of the Text widget, except that a pointer to an XmCommandCall- backStructure is passed, and the structure's value member con- tains 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_EN- TERED. 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 Com- mand. 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 re- source 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 XmNselec- tionLabelString resource in SelectionBox, renamed for Command. The default may vary depending on the value of the XmNstringDi- rection 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 descen- dant 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 his- tory 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 re- moves 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), XmCommandAp- pendValue(3X), XmCommandError(3X), XmCommandGetChild(3X), XmCommandSet- Value(3X), XmCreateCommand(3X), XmManager(3X), and XmSelectionBox(3X). XmCommand(3X)