Volume 6A: Motif Programming Manual

In order to support the idea that the dialog is a single widget, the toolkit also provides a number of convenience

routines that you can use to modify the Command widget. The function XmCommandSetValue() sets the text in

the command entry area of the dialog. The function takes the following form:

void

XmCommandSetValue(widget, command)

Widget widget;

XmString command;

The command is displayed in the command entry area. The Command widget resource XmNcommand specifies the

text for the command entry area, so you can also set this resource directly. Alternatively, you can use

XmTextSetString() on the Text widget in the dialog to set the command. However, note that the string you

specify to this function is a regular character string, not a compound string.

If you want to append some text to the string in the command entry area, you can use the routine

XmCommandAppendValue(), which takes the following form:

void

XmCommandAppendValue(widget, command)

Widget widget;

XmString command;

The command is added to the end of the string in the command entry area. The function XmCommandError()

displays an error message in the history area of the Command widget. The function takes the following form:

void

XmCommandError(widget, message)

Widget widget;

XmString message;

The error message is displayed until the user enters the next command.

7.5 FileSelectionDialogs

Like the Command widget, the FileSelectionBox is subclassed from SelectionBox. The FileSelectionDialog looks

somewhat different than the other selection dialogs because of its complexity and its unusual widget layout and

architecture. Functionally, the FileSelectionDialog allows the user to move through the file system and select a file or

a directory for use by the application. The dialog also lets the user specify a filter that controls the files that are

displayed in the dialog. This filter is generally specified as a regular expression reminiscent of the classic UNIX

meta−characters (e.g., * matches all files, while *.c matches all files that end in .c). the figure shows a

FileSelectionDialog.

7 Selection Dialogs 7.5 FileSelectionDialogs

154

A typical FileSelectionDialog

The control area of the FileSelectionDialog has four components. The filter text entry area specifies the directory and

the filter. The directories list displays the directories in the current directory specified by the filter. If the user selects a

directory, the filter is modified to reflect the selection. The files list shows the files in the current directory. The

selection text entry area specifies the file selected by the user. If the user selects a file from the file list, the full

pathname is displayed in the selection text entry area.

The FileSelectionDialog has four buttons in its action area. The OK, Cancel, and Help buttons are the same as for

other SelectionDialogs. The Filter button acts on the directory and pattern specified in the filter text entry area. For

example, the user could enter /usr/src/motif/lib/Xm/* as the filter. In this case, the directory is /usr/src/motif/lib/Xm

and the pattern is the "*". When the user selects the Filter button or presses RETURN in the Text widget, the

directory part of the filter is searched and all of the directories within that directory are displayed in the directories list.

The pattern part is then used to find all of the matching files in the directory and the files are shown in the files list.

Only files are placed in this list; directories are excluded since they are listed separately.

While this process seems straightforward, it can become confusing for users and programmers alike because of the

way that the widget parses the filter. For example, consider the following string: /usr/src/motif/lib/Xm. This pathname

appears to be a common directory path, but in fact, the widget interprets the filter so that the directory is

/usr/src/motif/lib and the pattern is Xm. If searched, the directories list will contain all the directories in

/usr/src/motif/lib and the files list won't contain anything because Xm is a directory, not a pattern that matches any

files. Since users frequently make this mistake when using the FileSelectionDialog, you should be sure to explain the

operation of the dialog in the documentation for your application.

The convention that the widget follows is to use the last / in the filter to separate the directory part from the pattern

part. Fortunately, the FileSelectionDialog provides resources and other mechanisms to retrieve the proper parts of the

filter specification. We will demonstrate how to use these mechanisms in the next few subsections.

7 Selection Dialogs 7.5 FileSelectionDialogs

155