XmFileSelectionBox(library call) XmFileSelectionBox(library call)
NAMEXmFileSelectionBox — The FileSelectionBox widget class
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 XmNlayoutDi‐
rection resource.
####Additional children may be added to the FileSelectionBox after cre‐
ation. FileSelectionBox inherits the layout functionality provided by
SelectionBox for any additional children. To remove the list of file‐
names, 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 XmFileSelec‐
tionBoxGetChild 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 dis‐
played 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: XmNdi‐
rectory, 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, rela‐
tive to the current working directory. The remaining components spec‐
ify 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 applica‐
tion 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 key‐
board 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, XmNdirec‐
tory, 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 follow‐
ing 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 XmNquali‐
fySearchDataProc (and possibly modified by the XmNdirSearchProc)
· Sets XmNpattern to the qualified pattern returned by the XmNqual‐
ifySearchDataProc (and possibly modified by the XmNdirSearchProc)
FileSelectionBox uses the XmQTactivatable trait.
Data Transfer Behavior
Child widgets of a FileSelectionBox support the data transfer opera‐
tions 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 XmNfileSearch‐
Proc 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 pro‐
grammer to specify data. The programmer can also set the resource val‐
ues 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).
┌─────────────────────────────────────────────────────────────────────────────────────────────────┐
│ │ XmFileSelectionBox Resource Set │ │ │
│Name │ Class │ Type │ Default │ Access │
├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
│XmNdirectory │ XmCDirectory │ XmString │ dynamic │ CSG │
├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
│XmNdirectoryValid │ XmCDirectoryValid │ Boolean │ dynamic │ SG │
├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
│XmNdirListItems │ XmCDirListItems │ XmStringTable │ dynamic │ SG │
├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
│XmNdirListItemCount │ XmCDirListItemCount │ int │ dynamic │ SG │
├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
│XmNdirListLabelString │ XmCDirListLabelString │ XmString │ dynamic │ CSG │
├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
│XmNdirMask │ XmCDirMask │ XmString │ dynamic │ CSG │
├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
│XmNdirSearchProc │ XmCDirSearchProc │ XmSearchProc │ default procedure │ CSG │
├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
│XmNdirSpec │ XmCDirSpec │ XmString │ dynamic │ CSG │
├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
│XmNdirTextLabelString │ XmCDirTextLabelString │ XmString │ NULL │ C │
├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
│XmNfileFilterStyle │ XmCFileFilterStyle │ XtEnum │ XmFILTER_NONE │ C │
├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
│XmNfileListItems │ XmCItems │ XmStringTable │ dynamic │ SG │
├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
│XmNfileListItemCount │ XmCItemCount │ int │ dynamic │ SG │
├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
│XmNfileListLabelString │ XmCFileListLabelString │ XmString │ dynamic │ CSG │
├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
│XmNfileSearchProc │ XmCFileSearchProc │ XmSearchProc │ default procedure │ CSG │
├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
│XmNfileTypeMask │ XmCFileTypeMask │ unsigned char │ XmFILE_REGULAR │ CSG │
├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
│XmNfilterLabelString │ XmCFilterLabelString │ XmString │ dynamic │ CSG │
├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
│XmNlistUpdated │ XmCListUpdated │ Boolean │ dynamic │ SG │
├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
│XmNnoMatchString │ XmCNoMatchString │ XmString │ " [ ] " │ CSG │
├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
│XmNpathMode │ XmCPathMode │ XtEnum │ XmPATH_MODE_FULL │ C │
├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
│XmNpattern │ XmCPattern │ XmString │ dynamic │ CSG │
├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
│XmNqualifySearchDataProc │ XmCQualifySearchDataProc │ XmQualifyProc │ default procedure │ CSG │
├─────────────────────────┼──────────────────────────┼───────────────┼───────────────────┼────────┤
└─────────────────────────┴──────────────────────────┴───────────────┴───────────────────┴────────┘
XmNdirectory
Specifies the base directory used in combination with XmNpat‐
tern in determining the files and directories to be dis‐
played. The default value is determined by the XmNqualify‐
SearchDataProc and depends on the initial values of
XmNdirMask, XmNdirectory, and XmNpattern. If the default is
NULL or empty, the current working directory is used.
XmNdirectoryValid
Specifies an attribute that is set only by the directory
search procedure. The value is set to True if the directory
passed to the directory search procedure can actually be
searched. If this value is False the file search procedure
is not called, and XmNdirMask, XmNdirectory, and XmNpattern
are not changed.
XmNdirListItems
Specifies the items in the directory list. XtGetValues for
this resource returns the list items themselves, not a copy
of the list items. The application must not free the
returned items.
XmNdirListItemCount
Specifies the number of items in the directory list. The
value must not be negative.
XmNdirListLabelString
Specifies the label string of the directory list. The
default for this resource depends on the locale. In the C
locale the default is Directories.
Now that some default localized label strings are provided
through message catalogs for the children of composite wid‐
gets, the labelString resources cannot be set on the child
through default resource files. Instead, the resource pro‐
vided at the parent level must be used.
XmNdirMask
Specifies the directory mask used in determining the files
and directories to be displayed. The default value is deter‐
mined by the XmNqualifySearchDataProc and depends on the ini‐
tial values of XmNdirMask, XmNdirectory, and XmNpattern.
XmNdirSearchProc
Specifies a directory search procedure to replace the default
directory search procedure. FileSelectionBox's default
directory search procedure fulfills the needs of most appli‐
cations. Because it is impossible to cover the requirements
of all applications, you can replace the default search pro‐
cedure.
The directory search procedure is called with two arguments:
the FileSelectionBox widget and a pointer to an XmFileSelec‐
tionBoxCallbackStruct structure. The callback structure is
generated by the XmNqualifySearchDataProc and contains all
information required to conduct a directory search, including
the directory mask and a qualified base directory and search
pattern. Once called, it is up to the search routine to gen‐
erate a new list of directories and update the FileSelection‐
Box widget by using XtSetValues.
The search procedure must set XmNdirectoryValid and XmNlis‐
tUpdated. If it generates a new list of directories, it must
also set XmNdirListItems and XmNdirListItemCount.
If the search procedure cannot search the specified direc‐
tory, it must warn the user and set XmNdirectoryValid and
XmNlistUpdated to False, unless it prompts and subsequently
obtains a valid directory. If the directory is valid but is
the same as the current XmNdirectory, the search procedure
must set XmNdirectoryValid to True, but it may elect not to
generate a new list of directories. In this case, it must
set XmNlistUpdated to False.
If the search procedure generates a new list of directories,
it must set XmNdirListItems to the new list of directories
and XmNdirListItemCount to the number of items in the list.
If there are no directories, it sets XmNdirListItems to NULL
and XmNdirListItemCount to 0 (zero). In either case, it must
set XmNdirectoryValid and XmNlistUpdated to True.
The search procedure ordinarily should not change the call‐
back structure. But if the original directory is not valid,
the search procedure may obtain a new directory from the
user. In this case, it should set the dir member of the
callback structure to the new directory, call the XmNqualify‐
SearchDataProc with the callback struct as the input argu‐
ment, and copy the qualified data returned by the XmNqualify‐
SearchDataProc into the callback struct.
XmNdirSpec
Specifies the full file path specification. This is the XmN‐
textString resource in SelectionBox, renamed for FileSelec‐
tionBox. The default value is determined by the FileSelec‐
tionBox after conducting the initial directory and file
search.
XmNdirTextLabelString
Uses the specified XmString as the label above the TextField
directory. The resource takes effect when the XmNpathMode
resource has a value of XmPATH_MODE_RELATIVE. It is ignored
when the XmNpathMode resource has a value of
XmPATH_MODE_FULL.
Now that some default localized label strings are provided
through message catalogs for the children of composite wid‐
gets, the labelString resources cannot be set on the child
through default resource files. Instead, the resource pro‐
vided at the parent level must be used.
XmNfileFilterStyle
Specifies whether or not the "hidden" files (those whose
names begin with . (period) in POSIX systems) will be listed
in the file and directory scrolling lists (where the default
directory search procedure is used). The possible values
are:
XmFILTER_NONE
Does not filter hidden files.
XmFILTER_HIDDEN_FILES
Restricts the list of possible file names, such as
those beginning with . (period).
XmNfileListItems
Specifies the items in the file list. This is the XmNlis‐
tItems resource in SelectionBox, renamed for FileSelection‐
Box. XtGetValues for this resource returns the list items
themselves, not a copy of the list items. The application
must not free the returned items.
XmNfileListItemCount
Specifies the number of items in the file list. This is the
XmNlistItemCount resource in SelectionBox, renamed for FileS‐
electionBox. The value must not be negative.
XmNfileListLabelString
Specifies the label string of the file list. This is the
XmNlistLabelString resource in SelectionBox, renamed for
FileSelectionBox. The default for this resource depends on
the locale. In the C locale the default is Files.
Now that some default localized label strings are provided
through message catalogs for the children of composite wid‐
gets, the labelString resources cannot be set on the child
through default resource files. Instead, the resource pro‐
vided at the parent level must be used.
XmNfileSearchProc
Specifies a file search procedure to replace the default file
search procedure. FileSelectionBox's default file search
procedure fulfills the needs of most applications. Because
it is impossible to cover the requirements of all applica‐
tions, you can replace the default search procedure.
The file search procedure is called with two arguments: the
FileSelectionBox widget and a pointer to an XmFileSelection‐
BoxCallbackStruct structure. The callback structure is gen‐
erated by the XmNqualifySearchDataProc (and possibly modified
by the XmNdirSearchProc). It contains all information
required to conduct a file search, including the directory
mask and a qualified base directory and search pattern. Once
this procedure is called, it is up to the search routine to
generate a new list of files and update the FileSelectionBox
widget by using XtSetValues.
The search procedure must set XmNlistUpdated. If it gener‐
ates a new list of files, it must also set XmNfileListItems
and XmNfileListItemCount.
It is recommended that the search procedure always generate a
new list of files. If the mask member of the callback struc‐
ture is the same as the mask member of the callback struct in
the preceding call to the search procedure, the procedure may
elect not to generate a new list of files. In this case it
must set XmNlistUpdated to False.
If the search procedure generates a new list of files, it
must set XmNfileListItems to the new list of files and XmN‐
fileListItemCount to the number of items in the list. If
there are no files, it sets XmNfileListItems to NULL and XmN‐
fileListItemCount to 0 (zero). In either case it must set
XmNlistUpdated to True.
In constructing the list of files, the search procedure
should include only files of the types specified by the wid‐
get's XmNfileTypeMask.
Setting XmNdirSpec is optional, but recommended. Set this
attribute to the full file specification of the directory
searched. The directory specification is displayed below the
directory and file lists.
XmNfileTypeMask
Specifies the type of files listed in the file list. The
possible values are
XmFILE_REGULAR
Restricts the file list to contain only regular
files.
XmFILE_DIRECTORY
Restricts the file list to contain only directo‐
ries.
XmFILE_ANY_TYPE
Allows the list to contain all file types including
directories.
XmNfilterLabelString
Specifies the label string for the text entry field for the
directory mask. The default for this resource depends on the
locale. In the C locale the default is Filter.
Now that some default localized label strings are provided
through message catalogs for the children of composite wid‐
gets, the labelString resources cannot be set on the child
through default resource files. Instead, the resource pro‐
vided at the parent level must be used.
XmNlistUpdated
Specifies an attribute that is set only by the directory and
file search procedures. This resource is set to True if the
search procedure updated the directory or file list.
XmNnoMatchString
Specifies a string to be displayed in the file list if the
list of files is empty.
XmNpattern
Specifies the search pattern used in combination with XmNdi‐
rectory in determining the files and directories to be dis‐
played. The default value is determined by XmNqualifySearch‐
DataProc and depends on the initial values of XmNdirMask,
XmNdirectory, and XmNpattern. If the default is NULL or
empty, a pattern that matches all files is used.
XmNpathMode
Specifies whether or not an additional text field will be
used to display and edit the filter. The possible values are
XmPATH_MODE_FULL
Specifies that no additional text field will be
used to display the filter. There will just be a
single text field to display XmNdirMask.
XmPATH_MODE_RELATIVE
Specifies that there will be two text field dis‐
plays, one to display the XmNdirectory and one to
display the XmNpattern. In this instance, the XmN‐
filterLabelString resource applies to the text
field for XmNpattern and XmNdirTextLabelString
applies to the text field for XmNdirectory.
XmNqualifySearchDataProc
Specifies a search data qualification procedure to replace
the default data qualification procedure. FileSelectionBox's
default data qualification procedure fulfills the needs of
most applications. Because it is impossible to cover the
requirements of all applications, you can replace the default
procedure.
The data qualification procedure is called to generate a
qualified directory mask, base directory, and search pattern
for use by the directory and file search procedures. It is
called with three arguments: the FileSelectionBox widget and
pointers to two XmFileSelectionBoxCallbackStruct structures.
The first callback structure contains the input data. The
second callback structure contains the output data, to be
filled in by the data qualification procedure.
If the input dir and pattern members are not NULL, the proce‐
dure must copy them to the corresponding members of the out‐
put callback structure.
If the input dir is NULL, the procedure constructs the output
dir as follows: If the input mask member is NULL, the proce‐
dure uses the widget's XmNdirectory as the output dir; other‐
wise, it extracts the output dir from the input mask. If the
resulting output dir is empty, the procedure uses the current
working directory instead.
If the input pattern is NULL, the procedure constructs the
output pattern as follows: If the input mask member is NULL,
the procedure uses the widget's XmNpattern as the output pat‐
tern; otherwise, it extracts the output pattern from the
input mask. If the resulting output pattern is empty, the
procedure uses a pattern that matches all files instead.
The data qualification procedure constructs the output mask
from the output dir and pattern. The procedure must ensure
that the output dir, pattern, and mask are fully qualified.
If the input value member is not NULL, the procedure must
copy it to the output value member; otherwise, the procedure
must copy the widget's XmNdirSpec to the output value.
The data qualification procedure must calculate the lengths
of the output value, mask, dir, and pattern members and must
fill in the corresponding length members of the output call‐
back struct.
The data qualification procedure must copy the input reason
and event members to the corresponding output members.
The values of the XmNdirSearchProc and XmNfileSearchProc are procedure
pointers of type XmSearchProc, defined as follows:
void (* XmSearchProc) (w, search_data)
Widget w;
XtPointer search_data;
w The FileSelectionBox widget
search_data
Pointer to an XmFileSelectionBoxCallbackStruct containing
information for conducting a search
The value of the XmNqualifySearchDataProc resource is a procedure
pointer of type XmQualifyProc, defined as follows:
void (* XmQualifyProc) (w, input_data, output_data)
Widget w;
XtPointer input_data;
XtPointer output_data;
w The FileSelectionBox widget
input_data
Pointer to an XmFileSelectionBoxCallbackStruct containing
input data to be qualified
output_data
Pointer to an XmFileSelectionBoxCallbackStruct containing
output data to be filled in by the qualification procedure
Inherited Resources
FileSelectionBox inherits behavior and resources from the superclasses
described in the following tables. For a complete description of each
resource, refer to the reference page for that superclass.
┌──────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ │ XmSelectionBox Resource Set │ │ │
│Name │ Class │ Type │ Default │ Access │
├────────────────────────┼─────────────────────────┼────────────────┼─────────────────────────┼────────┤
│XmNapplyCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
├────────────────────────┼─────────────────────────┼────────────────┼─────────────────────────┼────────┤
│XmNapplyLabelString │ XmCApplyLabelString │ XmString │ dynamic │ CSG │
├────────────────────────┼─────────────────────────┼────────────────┼─────────────────────────┼────────┤
│XmNcancelCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
├────────────────────────┼─────────────────────────┼────────────────┼─────────────────────────┼────────┤
│XmNcancelLabelString │ XmCCancelLabelString │ XmString │ dynamic │ CSG │
├────────────────────────┼─────────────────────────┼────────────────┼─────────────────────────┼────────┤
│XmNchildPlacement │ XmCChildPlacement │ unsigned char │ XmPLACE_ABOVE_SELECTION │ CSG │
├────────────────────────┼─────────────────────────┼────────────────┼─────────────────────────┼────────┤
│XmNdialogType │ XmCDialogType │ unsigned char │ XmDIALOG_FILE_SELECTION │ G │
├────────────────────────┼─────────────────────────┼────────────────┼─────────────────────────┼────────┤
│XmNhelpLabelString │ XmCHelpLabelString │ XmString │ dynamic │ CSG │
├────────────────────────┼─────────────────────────┼────────────────┼─────────────────────────┼────────┤
│XmNlistItemCount │ XmCItemCount │ int │ dynamic │ CSG │
├────────────────────────┼─────────────────────────┼────────────────┼─────────────────────────┼────────┤
│XmNlistItems │ XmCItems │ XmStringTable │ dynamic │ CSG │
├────────────────────────┼─────────────────────────┼────────────────┼─────────────────────────┼────────┤
│XmNlistLabelString │ XmCListLabelString │ XmString │ dynamic │ CSG │
├────────────────────────┼─────────────────────────┼────────────────┼─────────────────────────┼────────┤
│XmNlistVisibleItemCount │ XmCVisibleItemCount │ int │ dynamic │ CSG │
├────────────────────────┼─────────────────────────┼────────────────┼─────────────────────────┼────────┤
│XmNminimizeButtons │ XmCMinimizeButtons │ Boolean │ False │ CSG │
├────────────────────────┼─────────────────────────┼────────────────┼─────────────────────────┼────────┤
│XmNmustMatch │ XmCMustMatch │ Boolean │ False │ CSG │
├────────────────────────┼─────────────────────────┼────────────────┼─────────────────────────┼────────┤
│XmNnoMatchCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
├────────────────────────┼─────────────────────────┼────────────────┼─────────────────────────┼────────┤
│XmNokCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
├────────────────────────┼─────────────────────────┼────────────────┼─────────────────────────┼────────┤
│XmNokLabelString │ XmCOkLabelString │ XmString │ dynamic │ CSG │
├────────────────────────┼─────────────────────────┼────────────────┼─────────────────────────┼────────┤
│XmNselectionLabelString │ XmCSelectionLabelString │ XmString │ dynamic │ CSG │
├────────────────────────┼─────────────────────────┼────────────────┼─────────────────────────┼────────┤
│XmNtextAccelerators │ XmCTextAccelerators │ XtAccelerators │ default │ C │
├────────────────────────┼─────────────────────────┼────────────────┼─────────────────────────┼────────┤
│XmNtextColumns │ XmCColumns │ short │ dynamic │ CSG │
├────────────────────────┼─────────────────────────┼────────────────┼─────────────────────────┼────────┤
│XmNtextString │ XmCTextString │ XmString │ dynamic │ CSG │
├────────────────────────┼─────────────────────────┼────────────────┼─────────────────────────┼────────┤
└────────────────────────┴─────────────────────────┴────────────────┴─────────────────────────┴────────┘
┌──────────────────────────────────────────────────────────────────────────────────────┐
│ │ XmBulletinBoard Resource Set │ │ │
│Name │ Class │ Type │ Default │ Access │
├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
│XmNallowOverlap │ XmCAllowOverlap │ Boolean │ True │ CSG │
├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
│XmNautoUnmanage │ XmCAutoUnmanage │ Boolean │ False │ CG │
├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
│XmNbuttonFontList │ XmCButtonFontList │ XmFontList │ dynamic │ CSG │
├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
│XmNbuttonRenderTable │ XmCButtonRenderTable │ XmRenderTable │ dynamic │ CSG │
├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
│XmNcancelButton │ XmCWidget │ Widget │ Cancel button │ SG │
├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
│XmNdefaultButton │ XmCWidget │ Widget │ OK button │ SG │
├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
│XmNdefaultPosition │ XmCDefaultPosition │ Boolean │ True │ CSG │
├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
│XmNdialogStyle │ XmCDialogStyle │ unsigned char │ dynamic │ CSG │
├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
│XmNdialogTitle │ XmCDialogTitle │ XmString │ NULL │ CSG │
├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
│XmNfocusCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
│XmNlabelFontList │ XmCLabelFontList │ XmFontList │ dynamic │ CSG │
├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
│XmNlabelRenderTable │ XmCLabelRenderTable │ XmRenderTable │ dynamic │ CSG │
├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
│XmNmapCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
│XmNmarginHeight │ XmCMarginHeight │ Dimension │ 10 │ CSG │
├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
│XmNmarginWidth │ XmCMarginWidth │ Dimension │ 10 │ CSG │
├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
│XmNnoResize │ XmCNoResize │ Boolean │ False │ CSG │
├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
│XmNresizePolicy │ XmCResizePolicy │ unsigned char │ XmRESIZE_ANY │ CSG │
├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
│XmNshadowType │ XmCShadowType │ unsigned char │ XmSHADOW_OUT │ CSG │
├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
│XmNtextFontList │ XmCTextFontList │ XmFontList │ dynamic │ CSG │
├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
│XmNtextRenderTable │ XmCTextRenderTable │ XmRenderTable │ dynamic │ CSG │
├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
│XmNtextTranslations │ XmCTranslations │ XtTranslations │ NULL │ C │
├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
│XmNunmapCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
├─────────────────────┼──────────────────────┼────────────────┼───────────────┼────────┤
└─────────────────────┴──────────────────────┴────────────────┴───────────────┴────────┘
┌────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ │ XmManager Resource Set │ │ │
│Name │ Class │ Type │ Default │ Access │
├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
│XmNbottomShadowColor │ XmCBottomShadowColor │ Pixel │ dynamic │ CSG │
├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
│XmNbottomShadowPixmap │ XmCBottomShadowPixmap │ Pixmap │ XmUNSPECIFIED_PIXMAP │ CSG │
├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
│XmNforeground │ XmCForeground │ Pixel │ dynamic │ CSG │
├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
│XmNhelpCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
│XmNhighlightColor │ XmCHighlightColor │ Pixel │ dynamic │ CSG │
├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
│XmNhighlightPixmap │ XmCHighlightPixmap │ Pixmap │ dynamic │ CSG │
├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
│XmNinitialFocus │ XmCInitialFocus │ Widget │ dynamic │ CSG │
├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
│XmNlayoutDirection │ XmCLayoutDirection │ XmDirection │ dynamic │ CG │
├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
│XmNnavigationType │ XmCNavigationType │ XmNavigationType │ XmTAB_GROUP │ CSG │
├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
│XmNpopupHandlerCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
│XmNshadowThickness │ XmCShadowThickness │ Dimension │ dynamic │ CSG │
├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
│XmNstringDirection │ XmCStringDirection │ XmStringDirection │ dynamic │ CG │
├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
│XmNtopShadowColor │ XmCTopShadowColor │ Pixel │ dynamic │ CSG │
├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
│XmNtopShadowPixmap │ XmCTopShadowPixmap │ Pixmap │ dynamic │ CSG │
├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
│XmNtraversalOn │ XmCTraversalOn │ Boolean │ True │ CSG │
├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
│XmNunitType │ XmCUnitType │ unsigned char │ dynamic │ CSG │
├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
│XmNuserData │ XmCUserData │ XtPointer │ NULL │ CSG │
├────────────────────────┼───────────────────────┼───────────────────┼──────────────────────┼────────┤
└────────────────────────┴───────────────────────┴───────────────────┴──────────────────────┴────────┘
┌───────────────────────────────────────────────────────────────────────┐
│ │ Composite Resource Set │ │ │
│Name │ Class │ Type │ Default │ Access │
├──────────────────┼───────────────────┼─────────────┼─────────┼────────┤
│XmNchildren │ XmCReadOnly │ WidgetList │ NULL │ G │
├──────────────────┼───────────────────┼─────────────┼─────────┼────────┤
│XmNinsertPosition │ XmCInsertPosition │ XtOrderProc │ NULL │ CSG │
├──────────────────┼───────────────────┼─────────────┼─────────┼────────┤
│XmNnumChildren │ XmCReadOnly │ Cardinal │ 0 │ G │
├──────────────────┼───────────────────┼─────────────┼─────────┼────────┤
└──────────────────┴───────────────────┴─────────────┴─────────┴────────┘
┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ │ Core Resource Set │ │ │
│Name │ Class │ Type │ Default │ Access │
├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
│XmNaccelerators │ XmCAccelerators │ XtAccelerators │ dynamic │ N/A │
├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
│XmNancestorSensitive │ XmCSensitive │ Boolean │ dynamic │ G │
├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
│XmNbackground │ XmCBackground │ Pixel │ dynamic │ CSG │
├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
│XmNbackgroundPixmap │ XmCPixmap │ Pixmap │ XmUNSPECIFIED_PIXMAP │ CSG │
├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
│XmNborderColor │ XmCBorderColor │ Pixel │ XtDefaultForeground │ CSG │
├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
│XmNborderPixmap │ XmCPixmap │ Pixmap │ XmUNSPECIFIED_PIXMAP │ CSG │
├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
│XmNborderWidth │ XmCBorderWidth │ Dimension │ 0 │ CSG │
├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
│XmNcolormap │ XmCColormap │ Colormap │ dynamic │ CG │
├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
│XmNdepth │ XmCDepth │ int │ dynamic │ CG │
├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
│XmNdestroyCallback │ XmCCallback │ XtCallbackList │ NULL │ C │
├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
│XmNheight │ XmCHeight │ Dimension │ dynamic │ CSG │
├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
│XmNinitialResourcesPersistent │ XmCInitialResourcesPersistent │ Boolean │ True │ C │
├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
│XmNmappedWhenManaged │ XmCMappedWhenManaged │ Boolean │ True │ CSG │
├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
│XmNscreen │ XmCScreen │ Screen * │ dynamic │ CG │
├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
│XmNsensitive │ XmCSensitive │ Boolean │ True │ CSG │
├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
│XmNtranslations │ XmCTranslations │ XtTranslations │ dynamic │ CSG │
├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
│XmNwidth │ XmCWidth │ Dimension │ dynamic │ CSG │
├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
│XmNx │ XmCPosition │ Position │ 0 │ CSG │
├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
│XmNy │ XmCPosition │ Position │ 0 │ CSG │
├──────────────────────────────┼───────────────────────────────┼────────────────┼──────────────────────┼────────┤
└──────────────────────────────┴───────────────────────────────┴────────────────┴──────────────────────┴────────┘
Callback Information
A pointer to the following structure is passed to each callback:
typedef struct
{
int reason;
XEvent * event;
XmString value;
int length;
XmString mask;
int mask_length;
XmString dir;
int dir_length;
XmString pattern;
int pattern_length;
} XmFileSelectionBoxCallbackStruct;
reason Indicates why the callback was invoked
event Points to the XEvent that triggered the callback
value Specifies the current value of XmNdirSpec
length Specifies the number of bytes in value This member is obso‐
lete and exists for compatibility with earlier releases.
mask Specifies the current value of XmNdirMask
mask_length
Specifies the number of bytes in mask This member is obsolete
and exists for compatibility with earlier releases.
dir Specifies the current base directory
dir_length
Specifies the number of bytes in dir This member is obsolete
and exists for compatibility with earlier releases.
pattern Specifies the current search pattern
pattern_length
Specifies the number of bytes in pattern This member is obso‐
lete and exists for compatibility with earlier releases.
Translations
XmFileSelectionBox inherits translations from XmSelectionBox.
Accelerators
The XmNtextAccelerators from XmSelectionBox are added to the selection
and directory mask (filter) Text descendants of XmFileSelectionBox.
Action Routines
The XmFileSelectionBox action routines are
SelectionBoxUpOrDown(Previous|Next|First|Last):
If neither the selection text nor the directory mask (filter)
text has the focus, this action does nothing.
If the selection text has the focus, the term list in the
following description refers to the file list, and the term
text refers to the selection text. If the directory mask
text has the focus, list refers to the directory list, and
text refers to the directory mask text.
When called with an argument of Previous, or 0 (zero) for
compatibility, this action selects the previous item in the
list and replaces the text with that item.
When called with an argument of Next, or 1 for compatibility,
this action selects the next item in the list and replaces
the text with that item.
When called with an argument of First, or 2 for compatibil‐
ity, this action selects the first item in the list and
replaces the text with that item.
When called with an argument of Last, or 3 for compatibility,
this action selects the last item in the list and replaces
the text with that item.
SelectionBoxRestore():
If neither the selection text nor the directory mask (filter)
text has the focus, this action does nothing.
If the selection text has the focus, this action replaces the
selection text with the selected item in the file list. If
no item in the file list is selected, it clears the selection
text.
If the directory mask text has the focus, this action
replaces the directory mask text with a new directory mask
constructed from the XmNdirectory and XmNpattern resources.
Additional Behavior
The FileSelectionBox widget has the following additional behavior:
<Key><osfCancel>:
Calls the activate callbacks for the cancel button if it is
sensitive. If no cancel button exists and the parent of the
FileSelectionBox is a manager, it passes the event to the
parent.
<Key><osfActivate> in Selection Text:
Calls the selection text widget's XmNactivateCallback call‐
backs. If XmNmustMatch is True and the selection text does
not match an item in the file list, it calls the XmNnoMatch‐
Callback callbacks with reason XmCR_NO_MATCH. Otherwise, it
calls the XmNokCallback callbacks with reason XmCR_OK.
<Key><osfActivate> in Directory Mask Text:
Calls the directory mask text widget's XmNactivateCallback
callbacks, initiates a directory and file search, and calls
the XmNapplyCallback callbacks with reason XmCR_APPLY.
<Btn1Down>(2+) or <Key><osfActivate> in Directory List:
Calls the directory list widget's XmNdefaultActionCallback
callbacks, initiates a directory and file search, and calls
the XmNapplyCallback callbacks with reason XmCR_APPLY.
<Btn1Down>(2+) or <Key><osfActivate> in File List:
Calls the file list widget's XmNdefaultActionCallback call‐
backs and calls the XmNokCallback callbacks with reason
XmCR_OK.
<Key><osfSelect> in Directory List:
Generates a new directory mask, using the selected list item
as the directory and the pattern extracted from the current
directory mask text as the search pattern. If the search
pattern is empty, it uses a pattern that matches all files in
the directory. Replaces the directory mask text with the new
directory mask.
<Key><osfSelect> in File List:
Replaces the selection text with the selected list item.
<Btn2Down> in File List:
Drags the content of one or more selected list items using
the drag and drop facility. If <Btn2Down is pressed on an
unselected item, drags only that item, excluding any other
selected items.
This action sets the XmNconvertProc of the DragContext to a
function that calls the XmNconvertCallback procedures of the
file list, possibly multiple times, for the _MOTIF_DROP
selection.
<Btn2Down> in Directory List:
Drags the content of one or more selected list items using
the drag and drop facility. If <Btn2Down is pressed on an
unselected item, it drags only that item, excluding any other
selected items.
This action sets the XmNconvertProc of the DragContext to a
function that calls the XmNconvertCallback procedures of the
directory list, possibly multiple times, for the _MOTIF_DROP
selection.
<Apply Button Activated>:
Initiates a directory and file search. Calls the XmNapply‐
Callback callbacks with reason XmCR_APPLY.
<OK Button Activated>:
If XmNmustMatch is True and the selection text does not match
an item in the file list, calls the XmNnoMatchCallback call‐
backs with reason XmCR_NO_MATCH. Otherwise, calls the XmNok‐
Callback callbacks with reason XmCR_OK.
<Cancel Button Activated>:
Calls the XmNcancelCallback callbacks with reason XmCR_CAN‐
CEL.
<Help Button Activated>:
Calls the XmNhelpCallback callbacks with reason XmCR_HELP.
<Key><osfActivate>:
If no button, list widget, or text widget has the keyboard
focus, if XmNmustMatch is True and the selection text does
not match an item in the file list, it calls the XmNnoMatch‐
Callback callbacks with reason XmCR_NO_MATCH. Otherwise, it
calls the XmNokCallback callbacks with reason XmCR_OK.
Virtual Bindings
The bindings for virtual keys are vendor specific. For information
about bindings for virtual buttons and keys, see VirtualBindings(3).
RELATEDComposite(3), Constraint(3), Core(3), XmBulletinBoard(3), XmCreateFile‐
SelectionBox(3), XmCreateFileSelectionDialog(3), XmFileSelection‐
BoxGetChild(3), XmFileSelectionDoSearch(3), XmManager(3), and XmSelec‐
tionBox(3).
XmFileSelectionBox(library call)
