WwFileSelection Function

Creates a file selection widget, which lets the user display the contents of directories and select files.

Usage

wid = WwFileSelection(parent, OKCallback, CancelCallback[, HelpCallback])

Input Parameters

parent — The widget ID of the parent widget.

OKCallback — A string containing the name of the callback that is executed when the OK button is selected.

CancelCallback — A string containing the name of the callback procedure that is called when the file selection widget is dismissed.

HelpCallback — (optional) A string containing the name of the callback routine that is called when the Help button is selected. The Help keyword can be used instead of this parameter.

Returned Value

wid — The file selection widget ID.

Keywords

Block — Creates a blocking file selection window (the default).

Dir — Specifies a string containing the directory path.

File — Specifies a string containing the default file selection.

Help — Use this keyword to specify a help topic when the HelpCallback parameter is not specified. This keyword can specify a two-element or one-element string array. If it is a two-element array, the first element is the name of a help topic and the second is the filename of the help file containing the topic. A one-element array specifies only the name of a help topic. In this case the default help file is used. For information on the location of the default help file, refer to the HELP command. The specified help topic is displayed in the online help viewer when the Help button is pressed.

Icon_file — A string containing either the full pathname or the filename of the icon file. If the icon file is not found, then the warning message, "Unable to find specified icon file: filename, using default icon file." appears.

Note:

The default icon definition is based on Windows vs. Motif as the window manager. On Windows, the default becomes the parent icon definition or the system icon if no parent has defined a unique window icon. On Motif, the default becomes the icon defined by !WIDGET_ICON.

Multi — (Windows Only) If set, multiple file selection is enabled for the file selection dialog box. The selected files are returned as a string with the following format:

DirectoryName:file1:file2:...filen

Name — A string containing the name of the file selection box widget. The Name specified is the widget name used as part of the resource specification. (Default: file.)

NonBlock — Creates a nonblocking file selection window. (This keyword has no effect under Microsoft Windows.)

Pattern — Specifies the search pattern used in combination with the directory in determining files to be displayed.

Position — Specifies the position of the upper-left corner of the file selection window on the screen in pixels.

Shell_name — Specifies the name of the TopLevelShell container widget used to hold the file selection box widget. The Shell_name specified is the top-level widget shell name used as part of the resource specification. (Default: fileshell.)

Title — Specifies a string containing the file selection widget’s title.

Color/Font Keywords

Background — Specifies the background color name.

Font — Specifies the name of the font used for text.

MSFont — Adds support for Windows fonts.

Foreground — Specifies the foreground color name.

Get/Set Value

getvalue — Gets the selected file specification.

setvalue — Sets a three-element array of strings:

0 — Determines the files and directories displayed in the directory list. For example, /usr/home/mydir/*.c.

1 — Directory: specifies the base directory.

2 — Pattern: specifies the search pattern to be used to select files.

Callback Parameters

Any file selection widget callback procedure must have the following two parameters:

wid — File selection widget ID.

shell — The ID of the top-level shell.

Discussion

A file selection widget is a popup window. This means that it cannot be the child of the top-level shell or the layout widget. Usually, a file selection widget is activated by a pushbutton or menu button, as in the following example.

Example

This example creates a button labeled File Selection. When the user selects this button, a file selection widget appears. When the user selects a file, the callback is executed.

Enter the callback procedure into a file, and compile the procedure with the .RUN command. Then, enter the widget commands at the WAVE> prompt. To dismiss the widget, select the appropriate function (such as Close) from the window manager menu of the File Selection button (the parent widget).

Callback Procedure

PRO FbuttonCB, wid, data

   file = WwFileSelection(wid,'FileOK', 'FileCancel', $

      Title='Search')

END

PRO FileOK, wid, shell

   value = WwGetValue(wid)

   PRINT, value

   status = WwSetValue(shell, /Close)

END

PRO FileCancel, wid, shell

   PRINT, 'File Cancel'

END

Widget Commands

top = WwInit('ww_ex25', 'Examples', layout)

button = WwButtonBox(layout, 'File Tool', 'FbuttonCB')

status = WwSetValue(top, /Display)

WwLoop