You can use the convenience routine XmCreateCommand() to create a Command widget or you can use
XtVaCreateWidget() with the class xmCommandWidgetClass. Motif does not provide a convenience routine
for creating a Command widget in a DialogShell. The rationale is that the Command widget is intended to be used on
a more permanent basis, since it accumulates a history of command input. A Command widget is typically used as
part of a larger interface, such as in a MainWindow, which is why it does not have action buttons. (See Chapter 4,
The Main Window, for an example.) If you want to create a CommandDialog, you will have to create the DialogShell
widget yourself and make the Command widget its immediate child. See Section #sdialogshl in Chapter 5,
Introduction to Dialogs, for more information about DialogShells.
The Command widget class is subclassed from SelectionBox. There are similarities between the two widgets, in that
the user has the ability to select items from a list. However, the list is composed of the commands that have been
previously entered. When the user enters a command, it is added to the list. If the user selects an item from the
command history list, the command is displayed in the text entry area. Although the Command widget inherits
resources from the SelectionBox, many of the resources are not applicable since the Command widget does not have
any action area buttons. All of the SelectionBox resources for setting the labels and callbacks of the buttons do not
apply to the Command widget.
The Command widget provides a number of resources that can be used to control the command history list. The
XmNhistoryItems and XmNhistoryItemCount resources specify the list of commands and the number of
commands in the list. The XmNhistoryVisibleItemCount resource controls the number of items that are
visible in the command history. XmNhistoryMaxItems specifies the maximum number of items in the history list.
When the maximum value is reached, a command is removed from the beginning of the list to make room for each
new command that is entered.
The Command widget provides two callback resources, XmNcommandEnteredCallback and
XmNcommandChangedCallback, for the text entry area. When the user changes the text in the command entry
area, the XmNcommandChangedCallback is invoked. If the user presses the RETURN key or double−clicks on an
item in the command history list, the XmNcommandEnteredCallback is called. The callback routine for each of
the callbacks takes the usual three parameters. The callback structure passed to the routines in the call_data
parameter is of type XmCommandCallbackStruct, which is identical to the
XmSelectionBoxCallbackStruct. The possible values for the reason field in the structure are
XmCR_COMMAND_ENTERED and XmCR_COMMAND_CHANGED.
You can get a handle to the subwidgets of the Command widget using function XmCommandGetChild(). The
function takes the following form:
unsigned char child;
The widget parameter is a handle to a dialog widget. The child parameter is an enumerated value that specifies a
particular subwidget in the dialog. The parameter can have any one of the following values:
The values refer to the different widgets in the Command widget and they should be self−explanatory.
7 Selection Dialogs 7.4 The Command Widget