Volume 6A: Motif Programming Manual

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

insensitive.

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

columns.

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

152

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:

Widget

XmCommandGetChild(widget, child)

Widget widget;

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:

XmDIALOG_COMMAND_TEXT

XmDIALOG_HISTORY_LIST

XmDIALOG_PROMPT_LABEL

XmDIALOG_WORK_AREA

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

153