FileSelectionDialog

The FileSelectionDialog is a standard Motif Dialog that contains a Motif widget
for choosing a file, the FileSelectionBox from the host machines file system.
The FileSelectionBox contains three main sections: the filter, the selection 
lists, and the selection.  Although the FileSelectionBox provides an intuitive 
navigation interface, it may present some difficulties due to its strict 
interpretation of the use of these three fields. In general, you navigate 
through the file system by double clicking on directory names in the lefthand
ScrolledList. The '..' entry takes you to the parent directory. Any other entry
drills down into that directory.

The filter lets you specify a UNIX-style pattern matching string (i.e. regular
expression) for filenames. For example, a filter of /users/bill/* displays all
files and directories in that directory, while a filter of /users/bill/*.cob 
displays only the Cobol source files in that directory. There are two ways to
activate a filter: 1) edit the filter then hit <CR> when the edit cursor is in
the filter's Text widget, or 2) edit the filter then press the Filter button at
the bottom of the Dialog.

The files and directories that match the filter appear in two respective 
ScrolledLists. The directories appear in the ScrolledList on the left, and the 
files appear in the other one. No matter what the filter, the left ScrolledList 
always contains the full list of directories that exist in the directory 
specified in the filter up to the last '/'. This rule is the key to using the 
FileSelectionBox properly.

An example will clear up any possible confusion. If you create a filter of 
/users/applications/finance/utables when that pathname is a directory and hit
the Filter button, the directory ScrolledList will contain all of the 
directories in /users/applications/finance and the file ScrolledList will 
contain nothing since utables is not a file. However, if you replace "utables"
with a '*' on that filter, the file ScrolledList will contain all of the files
in the "finance" directory, and the directory ScrolledList will remain the same.
However, the file ScrolledList now shows the files in that directory as well.
Note that if you leave the last character of the filter a '/' and activate the
filter, the FileSelectionBox automatically assumes you really want a '*' at the
end and puts it there for you.

When a file or directory in one of the ScrolledLists is highlighted and you hit
the Ok button, the FileSelectionBox tells Sun MTPScan of your choice. Note that 
while you can choose both files and directories, Sun MTPScan only accepts files and
lets you know when you choose a directory. The pathname that gets selected 
appears in the Selection TextField. If you like, you can edit this field by 
hand and not even use the ScrolledLists to make your choice.

There are a few ways to make a selection. As just mentioned, you can hand edit
the Selection TextField and hit <CR> to make a choice. You can also highlight 
an item in either of the ScrolledLists and click the Ok button. The other way 
to make a selection is to double click on the file's name in the file 
ScrolledList. 

When you double click on a directory's name in the directory ScrolledList, you 
'move' into that directory by implicitly changing the filter. Then the filter 
is reapplied to the new directory. If you double click on the '..' entry, you 
go back into the parent directory. 

To dismiss the FileSelectionBox without making any choice, just press the Cancel
button. Note that the FileSelectionDialog is modeless, so you can leave it 
popped up and still interact with the rest of Sun MTPScan. 

See also: Dialog, PushButton, ScrollBar, ScrollBarArrow, ScrollBarColumn, 
           ScrollBarTrough, ScrolledList, TextField
