Output of prompt_dlg.c
The callback routine for each of the PushButtons, pushed(), creates a PromptDialog that prompts the user to enter a
new name for the PushButton. The PushButton is passed as the client_data to the XmNokCallback routine,
read_name(), so that the routine can set the label of the PushButton directly from inside the callback. The
read_name() function destroys the dialog once it has set the label, since the dialog is no longer needed.
If the Cancel button is pressed, the text is not needed, so we can simply destroy the dialog. Since the first parameter to
a dialog callback routine is the dialog widget, we can use XtDestroyWidget as the callback routine. Since the
function only takes one parameter, and the widget that is to be destroyed is passed as the first parameter, no client data
is needed. We set XmNautoUnmanage to False for the dialog because the application is assuming the
responsibility of managing the dialog. There is no help for the dialog so the Help button is disabled by setting it
The text area in the PromptDialog is a TextField widget, so you can get a handle to it and set TextField widget
resources accordingly. Use XmSelectionBoxGetChild() to access the widget. In order to promote the
single−entity abstraction, the dialog provides two resources that affect the TextField widget. You can set the
XmNtextString resource to change the value of the text string in the widget. Like other string resources, the value
for this resource must be a compound string. The XmNtextColumns resource specifies the width of the TextField in
In Motif 1.1, one frustrating feature of the predefined SelectionDialogs is that when they are popped up, the TextField
widget does not receive the keyboard focus by default. If the user is not paying attention, starts typing, and then
presses the RETURN key, all of the keystrokes will be thrown away except the RETURN, which will activate the OK
button. Motif 1.2 solves this problem by introducing the XmNinitialFocus resource. This resource specifies the
widget that has the keyboard focus the first time that the dialog is popped up. The text entry area is the default value
of the resource for SelectionDialogs. If you are using Motif 1.1, you need to warn your users about the problem. You
can also program around the problem by using XmProcessTraversal() to set the focus to a particular widget.
7.4 The Command Widget
A Command widget allows the user to enter commands and have them saved in a history list widget for later
reference. The Command widget is composed of a text entry area and a command history list. Unlike all of the other
predefined Motif dialogs, this widget does not provide any action area buttons. The widget does provide a convenient
interface for applications that have a command−driven interface, such as a debugger.
7 Selection Dialogs 7.4 The Command Widget
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