FileSelectionBox is a subclass of SelectionBox designed for finding and selecting files. By default, a FileSelectionBox contains the same children as a standard SelectionBox, with the addition of a second ScrolledList and a second text edit area. Unlike a SelectionBox, the default Apply button in a FileSelectionBox is labeled "Filter" in a C locale.
One of the text areas, the directory mask area, holds a directory mask specifying a base directory to be searched and a search pattern. However, if the XmNpathMode resource is set to XmPATH_MODE_RELATIVE, FileSelectionBox splits this text area into two separate TextFields. One of these TextFields holds the base directory to be searched and the other holds the search pattern.
Another text area, the selection area, holds the name of the selected file.
One of the Lists, the directory list, displays the subdirectories of the current base directory. The other List, the file list, displays all the files, subdirectories, or both in the base directory that match the search pattern. The XmNfileListItems resource holds the selected items in this list.
The XmNfileFilterStyle resource determines whether or not hidden files (those starting with a period, usually) will be displayed in the directory and file lists.
The user can select a new base directory to examine by scrolling through the list of directories and selecting the desired directory or by editing the directory mask. Selecting a new directory from the directory list does not change the search pattern. A user can select a new search pattern by editing the directory mask. Double clicking or pressing osfActivate on a directory in the directory list initiates a search for files and subdirectories in the new directory, using the current search pattern.
Activating the Filter button, the directory list, or the directory mask text area causes the FileSelectionBox to initiate a file search. The FileSelectionBox uses three procedures, each the value of a resource, in conducting the search: XmNqualifySearchDataProc, XmNdirSearchProc and XmNfileSearchProc. The XmNqualifySearchDataProc procedure extracts the base directory and the search pattern from the directory mask. The XmNdirSearchProc procedure uses the data returned by XmNqualifySearchDataProc to update the directory list. The XmNfileSearchProc procedure uses the data returned by XmNqualifySearchDataProc to update the file list.
The user can select a file by scrolling through the list of filenames and selecting the desired file or by entering the filename directly into the text edit area. Selecting a file from the list causes that filename to appear in the file selection text edit area. The user confirms the selection by activating the OK button, the file list, or the selection text area.
FileSelectionBox uses the SelectionBox callback lists to notify the application when the user activates one of the buttons. The application can also provide one or more of the three procedures that FileSelectionBox uses to conduct a search. For a specification of the input to and output from these routines, see the XmFileSelectionBox(3) reference page in the Motif Programmer's Reference.
The application can remove the directory list, the file list, or both. The application must unmanage the ScrolledWindow parent of the List and the corresponding label. An application can also add additional children to a FileSelectionBox, which manages any additional children in the same way as SelectionBox.
XmCreateFileSelectionDialog creates a FileSelectionBox and a parent DialogShell.