Provided by: libmotif-dev_2.3.4-5ubuntu0.1_amd64 
NAME
XmFileSelectionBox — The FileSelectionBox widget class "XmFileSelectionBox" "widget class"
"FileSelectionBox"
SYNOPSIS
#include <Xm/FileSB.h>
DESCRIPTION
FileSelectionBox traverses through directories, views the files and subdirectories in
them, and then selects files.
A FileSelectionBox has five main areas:
• A text input field for displaying and editing a directory mask used to select the
files to be displayed
• An optional text input field for displaying and editing a filter mask used to select
the files to be displayed.
• A scrollable list of filenames
• A scrollable list of subdirectories
• A text input field for displaying and editing a filename
• A group of PushButtons, labeled OK, Filter, Cancel, and Help. The layout direction
of the buttons depends on the XmNlayoutDirection resource.
####Additional children may be added to the FileSelectionBox after creation.
FileSelectionBox inherits the layout functionality provided by SelectionBox for any
additional children. To remove the list of filenames, the list of subdirectories, or both
from the FileSelectionBox after creation, unmanage the appropriate widgets and their
labels. The list and label widgets are obtained through a call to the
XmFileSelectionBoxGetChild function. To remove either the directory list or the file
list, unmanage the parent of the appropriate list widget and unmanage the corresponding
label.
The user can specify resources in a resource file for the automatically created widgets
and gadgets of FileSelectionBox. The following list identifies the names of these widgets
(or gadgets) and the associated FileSelectionBox areas:
FilterLabel
FilterText
Filter Text
TextField
Directory List
DirList
Directory List Label
Dir
DirL Label
DirText TextField
The directory mask is a string specifying the base directory to be examined and a search
pattern. Ordinarily, the directory list displays the subdirectories of the base
directory, as well as the base directory itself and its parent directory. The file list
ordinarily displays all files and/or subdirectories in the base directory that match the
search pattern.
Optionally, the search pattern mask and the base directory can be displayed in two
separate text fields. This option is controlled by the XmNpathMode resource. Using this
alternate display does not change the meaning of resources that control the content of
these fields: XmNdirectory, XmNdirMask, XmNpattern.
A procedure specified by the XmNqualifySearchDataProc resource extracts the base directory
and search pattern from the directory mask. If the directory specification is empty, the
current working directory is used. If the search pattern is empty, a pattern that matches
all files is used.
An application can supply its own XmNqualifySearchDataProc as well as its own procedures
to search for subdirectories and files. The default XmNqualifySearchDataProc works as
follows: The directory mask is a pathname that can contain zero or more wildcard
characters in its directory portion, its file portion, or both. The directory components
of the directory mask — up to, but not including, the first component with a wildcard
character — specify the directory to be searched, relative to the current working
directory. The remaining components specify the search pattern. If the directory mask is
empty or if its first component contains a wildcard character, the current working
directory is searched. If no component of the directory mask contains a wildcard
character, the entire directory mask is the directory specification, and all files in that
directory are matched.
The user can select a new 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 or, when the
FileSelectionBox has the optional XmNpathMode XmPATH_MODE_RELATIVE display, the filter
text field. Double clicking or pressing KActivate on a directory in the directory list
initiates a search for files and subdirectories in the new directory, using the current
search pattern.
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 may select a new file as many times as desired. The application is not notified
until the user takes one of the following actions:
• Selects the OK PushButton
• Presses KActivate while the selection text edit area has the keyboard focus
• Double clicks or presses KActivate on an item in the file list
FileSelectionBox initiates a directory and file search when any of the following occurs:
• The FileSelectionBox is initialized
• The function XtSetValues is used to change XmNdirMask, XmNdirectory, XmNpattern, or
XmNfileTypeMask
• The user activates the Filter PushButton
• The user double clicks or presses KActivate on an item in the directory list
• The application calls XmFileSelectionDoSearch
• The user presses KActivate while the directory mask text edit area has the keyboard
focus
When a file search is initiated, the FileSelectionBox takes the following actions:
• Constructs an XmFileSelectionBoxCallbackStruct structure with values appropriate for
the action that initiated the search
• Calls the XmNqualifySearchDataProc with the callback structure as the data input
argument
• Sets XmNdirectoryValid and XmNlistUpdated to False
• Calls the XmNdirSearchProc with the qualified data returned by the
XmNqualifySearchDataProc
If XmNdirectoryValid is True, the FileSelectionBox takes the following additional actions:
• Sets XmNlistUpdated to False
• Calls the XmNfileSearchProc with the qualified data returned by the
XmNqualifySearchDataProc (and possibly modified by the XmNdirSearchProc)
• If XmNlistUpdated is True and the file list is empty, displays the XmNnoMatchString
in the file list and clears the selection text and XmNdirSpec
• If XmNlistUpdated is True and the file list is not empty, sets the selection text
and XmNdirSpec to the qualified dir returned by the XmNqualifySearchDataProc (and
possibly modified by the XmNdirSearchProc)
• Sets the directory mask text and XmNdirMask to the qualified mask returned by the
XmNqualifySearchDataProc (and possibly modified by the XmNdirSearchProc)
• Sets XmNdirectory to the qualified dir returned by the XmNqualifySearchDataProc (and
possibly modified by the XmNdirSearchProc)
• Sets XmNpattern to the qualified pattern returned by the XmNqualifySearchDataProc
(and possibly modified by the XmNdirSearchProc)
FileSelectionBox uses the XmQTactivatable trait.
Data Transfer Behavior
Child widgets of a FileSelectionBox support the data transfer operations and targets
associated with their widget classes.
In addition, if the source of a data transfer is the directory list and if
XmNdirSearchProc has its default value, the directory list supports the FILE and FILE_NAME
targets.
If the source of a data transfer is the file list and if XmNfileSearchProc has its default
value, the file list supports the FILE and FILE_NAME targets.
In either case, FileSelectionBox adds an XmNconvertCallback procedure to the appropriate
list. This procedure adds FILE and FILE_NAME to the TARGETS returned by the list. It
treats requests for conversion of a selection to FILE and FILE_NAME exactly like requests
for conversion to TEXT.
If an application changes XmNdirSearchProc or XmNfileSearchProc and wants to support the
FILE and FILE_NAME targets on the corresponding list, it must provide support itself by
adding a procedure to the list's XmNconvertCallback list.
Descendants
FileSelectionBox automatically creates the descendants shown in the following table. An
application can use XtNameToWidget to gain access to the named descendant. In addition, a
user or an application can use the named descendant when specifying resource values.
┌─────────────────┬───────────────────────┬────────────────────────────────────┐
│Named Descendant │ Class │ Identity │
├─────────────────┼───────────────────────┼────────────────────────────────────┤
├─────────────────┼───────────────────────┼────────────────────────────────────┤
├─────────────────┼───────────────────────┼────────────────────────────────────┤
│Apply │ XmPushButtonGadget │ Apply button │
├─────────────────┼───────────────────────┼────────────────────────────────────┤
│Cancel │ XmPushButtonGadget │ Cancel button │
├─────────────────┼───────────────────────┼────────────────────────────────────┤
│Dir │ XmLabelGadget │ title above list of directories │
├─────────────────┼───────────────────────┼────────────────────────────────────┤
│DirList │ XmList │ list of directories │
├─────────────────┼───────────────────────┼────────────────────────────────────┤
│DirListSW │ XmScrolledWindow │ ScrolledWindow parent of DirList │
├─────────────────┼───────────────────────┼────────────────────────────────────┤
│FilterLabel │ XmLabelGadget │ title above filter box │
├─────────────────┼───────────────────────┼────────────────────────────────────┤
│FilterText │ XmText or XmTextField │ text within filter box │
├─────────────────┼───────────────────────┼────────────────────────────────────┤
│Help │ XmPushButtonGadget │ Help button │
├─────────────────┼───────────────────────┼────────────────────────────────────┤
│Items │ XmLabelGadget │ title above list of filenames │
├─────────────────┼───────────────────────┼────────────────────────────────────┤
│ItemsList │ XmList │ list of filenames │
├─────────────────┼───────────────────────┼────────────────────────────────────┤
│ItemsListSW │ XmScrolledWindow │ ScrolledWindow parent of ItemsList │
├─────────────────┼───────────────────────┼────────────────────────────────────┤
│OK │ XmPushButtonGadget │ OK button │
├─────────────────┼───────────────────────┼────────────────────────────────────┤
│Selection │ XmLabelGadget │ title above selection box │
├─────────────────┼───────────────────────┼────────────────────────────────────┤
│Separator │ XmSeparatorGadget │ optional dividing line │
├─────────────────┼───────────────────────┼────────────────────────────────────┤
│Text │ XmText or XmTextField │ text within selection box │
├─────────────────┼───────────────────────┼────────────────────────────────────┤
└─────────────────┴───────────────────────┴────────────────────────────────────┘
Classes
FileSelectionBox inherits behavior, resources, and traits from Core, Composite,
Constraint, XmManager, XmBulletinBoard, and XmSelectionBox.
The class pointer is xmFileSelectionBoxWidgetClass.
The class name is XmFileSelectionBox.
New Resources
The following table defines a set of widget resources used by the programmer to specify
data. The programmer can also set the resource values for the inherited classes to set
attributes for this widget. To reference a resource by name or by class in a .Xdefaults
file, remove the XmN or XmC prefix and use the remaining letters. To specify one of the
defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the
remaining letters (in either lowercase or uppercase, but include any underscores between
words). The codes in the access column indicate if the given resource can be set at
creation time (C), set by using XtSetValues (S), retrieved by using XtGetValues (G), or is
not applicable (N/A).
┌─────────────────────────────────────────────────────────────────────────────────────────────────┐
--
RELATED
Composite(3), Constraint(3), Core(3), XmBulletinBoard(3), XmCreateFileSelectionBox(3),
XmCreateFileSelectionDialog(3), XmFileSelectionBoxGetChild(3), XmFileSelectionDoSearch(3),
XmManager(3), XmSelectionBox(3) XmVaCreateFileSelectionBox(3), and
XmVaCreateManagedFileSelectionBox(3),.
XmFileSelectionBox(3)