'\" t

...\" FileSelA.sgm /main/12 1996/09/26 14:54:48 cdedoc $

.de P!

.fl

\!!1 setgray

.fl

\\&.\"

.fl

\!!0 setgray

.fl			\" force out current output buffer

\!!save /psv exch def currentpoint translate 0 0 moveto

\!!/showpage{}def

.fl			\" prolog

.sy sed -e 's/^/!/' \\$1\" bring in postscript file

\!!psv restore

.

.de pF

.ie     ?\\*(f1?? .ds f1 \\n(.f

.el .ie ?\\*(f2?? .ds f2 \\n(.f

.el .ie ?\\*(f3?? .ds f3 \\n(.f

.el .ie ?\\*(f4?? .ds f4 \\n(.f

.el .tm ? font overflow

.ft \\$1

..

.de fP

.ie     !?\\*(f4?? \{\

.	ft \\*(f4

.	ds f4\"

'	br \}

.el .ie !?\\*(f3?? \{\

.	ft \\*(f3

.	ds f3\"

'	br \}

.el .ie !?\\*(f2?? \{\

.	ft \\*(f2

.	ds f2\"

'	br \}

.el .ie !?\\*(f1?? \{\

.	ft \\*(f1

.	ds f1\"

'	br \}

.el .tm ? font underflow

..

.ds f1\"

.ds f2\"

.ds f3\"

.ds f4\"

.ta 8n 16n 24n 32n 40n 48n 56n 64n 72n 

.TH "XmFileSelectionBox" "library call"

.SH "NAME"

\fBXmFileSelectionBox\fP \(em The FileSelectionBox widget class

.iX "XmFileSelectionBox"

.iX "widget class" "FileSelectionBox"

.SH "SYNOPSIS"

.PP

.nf

#include <Xm/FileSB\&.h>

.fi

.SH "DESCRIPTION"

.PP

FileSelectionBox traverses

through directories, views the files and subdirectories in them,

and then selects files\&.

.PP

A FileSelectionBox has five main areas:

.IP "   \(bu" 6

A text input field for displaying and editing a directory mask used to

select the files to be displayed

.IP "   \(bu" 6

An optional text input field for displaying and editing a filter mask

used to select the files to be displayed\&.

.IP "   \(bu" 6

A scrollable list of filenames

.IP "   \(bu" 6

A scrollable list of subdirectories

.IP "   \(bu" 6

A text input field for displaying and editing a filename

.IP "   \(bu" 6

A group of PushButtons,

labeled \fBOK\fP, \fBFilter\fP, \fBCancel\fP, and \fBHelp\fP\&.

The layout direction of the buttons depends on the

\fBXmNlayoutDirection\fP resource\&.

.PP

####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

\fBXmFileSelectionBoxGetChild\fP function\&.

To remove either the directory list or the file list, unmanage the

parent of the appropriate list widget and unmanage the corresponding

label\&.

.PP

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:

.IP "FilterLabel" 10

\fBFilterText\fP

.IP "Filter Text" 10

\fBTextField\fP

.IP "Directory List" 10

\fBDirList\fP

.IP "Directory List Label" 10

\fBDir\fP

.IP "DirL" 10

\fBLabel\fP

.IP "DirText" 10

\fBTextField\fP

.PP

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\&.

.PP

Optionally, the search pattern mask and the base directory can be

displayed in two separate text fields\&. This option is controlled by

the \fBXmNpathMode\fP resource\&. Using this alternate

display does not change the meaning of resources that control the

content of these fields: \fBXmNdirectory\fP, \fBXmNdirMask\fP,

\fBXmNpattern\fP\&.

.PP

A procedure specified by the \fBXmNqualifySearchDataProc\fP 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\&.

.PP

An application can supply its own \fBXmNqualifySearchDataProc\fP as well

as its own procedures to search for subdirectories and files\&.

The default \fBXmNqualifySearchDataProc\fP works as follows:

The directory mask is a pathname that can contain zero or more

\fIwildcard\fP characters in its directory portion, its file portion, or

both\&.

The directory components of the directory mask \(em up to, but not

including, the first component with a wildcard character \(em 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\&.

.PP

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 \fBXmNpathMode

XmPATH_MODE_RELATIVE\fP display, the filter text field\&.

Double clicking or pressing \fBKActivate\fP on a directory in the

directory list initiates a search for files and subdirectories in the

new directory, using the current search pattern\&.

.PP

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\&.

.PP

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:

.IP "   \(bu" 6

Selects the \fBOK\fP PushButton

.IP "   \(bu" 6

Presses \fBKActivate\fP while the selection text edit area has the

keyboard focus

.IP "   \(bu" 6

Double clicks or presses \fBKActivate\fP on an item in the file list

.PP

FileSelectionBox initiates a directory and file search when any of the

following occurs:

.IP "   \(bu" 6

The FileSelectionBox is initialized

.IP "   \(bu" 6

The function \fBXtSetValues\fP is used to change \fBXmNdirMask\fP,

\fBXmNdirectory\fP, \fBXmNpattern\fP, or \fBXmNfileTypeMask\fP

.IP "   \(bu" 6

The user activates the \fBFilter\fP PushButton

.IP "   \(bu" 6

The user double clicks or presses \fBKActivate\fP on an item in the

directory list

.IP "   \(bu" 6

The application calls \fBXmFileSelectionDoSearch\fP

.IP "   \(bu" 6

The user presses \fBKActivate\fP while the directory mask text edit area

has the keyboard focus

.PP

When a file search is initiated, the FileSelectionBox takes the

following actions:

.IP "   \(bu" 6

Constructs an \fBXmFileSelectionBoxCallbackStruct\fR structure with

values appropriate for the action that initiated the search

.IP "   \(bu" 6

Calls the \fBXmNqualifySearchDataProc\fP with the callback structure as

the data input argument

.IP "   \(bu" 6

Sets \fBXmNdirectoryValid\fP and \fBXmNlistUpdated\fP to False

.IP "   \(bu" 6

Calls the \fBXmNdirSearchProc\fP with the qualified data returned by the

\fBXmNqualifySearchDataProc\fP

.PP

If \fBXmNdirectoryValid\fP is True, the FileSelectionBox takes the

following additional actions:

.IP "   \(bu" 6

Sets \fBXmNlistUpdated\fP to False

.IP "   \(bu" 6

Calls the \fBXmNfileSearchProc\fP with the qualified data returned by

the \fBXmNqualifySearchDataProc\fP (and possibly modified by the

\fBXmNdirSearchProc\fP)

.IP "   \(bu" 6

If \fBXmNlistUpdated\fP is True and the file list is empty, displays the

\fBXmNnoMatchString\fP in the file list and clears the selection text

and \fBXmNdirSpec\fP

.IP "   \(bu" 6

If \fBXmNlistUpdated\fP is True and the file list is not empty, sets the

selection text and \fBXmNdirSpec\fP to the qualified \fIdir\fP returned

by the \fBXmNqualifySearchDataProc\fP (and possibly modified by the

\fBXmNdirSearchProc\fP)

.IP "   \(bu" 6

Sets the directory mask text and \fBXmNdirMask\fP to the qualified

\fImask\fP returned by the \fBXmNqualifySearchDataProc\fP (and possibly

modified by the \fBXmNdirSearchProc\fP)

.IP "   \(bu" 6

Sets \fBXmNdirectory\fP to the qualified \fIdir\fP returned by the

\fBXmNqualifySearchDataProc\fP (and possibly modified by the

\fBXmNdirSearchProc\fP)

.IP "   \(bu" 6

Sets \fBXmNpattern\fP to the qualified \fIpattern\fP returned by the

\fBXmNqualifySearchDataProc\fP (and possibly modified by the

\fBXmNdirSearchProc\fP)

.PP

FileSelectionBox uses the \fBXmQTactivatable\fP trait\&.

.SS "Data Transfer Behavior"

.PP

Child widgets of a FileSelectionBox support the data transfer operations

and targets associated with their widget classes\&.

.PP

In addition, if the source of a data transfer is the directory list and

if \fBXmNdirSearchProc\fP has its default value, the directory list

supports the \fBFILE\fP and \fBFILE_NAME\fP targets\&.

.PP

If the source of a data transfer is the file list and if

\fBXmNfileSearchProc\fP has its default value, the file list supports

the \fBFILE\fP and \fBFILE_NAME\fP targets\&.

.PP

In either case, FileSelectionBox adds an \fBXmNconvertCallback\fP

procedure to the appropriate list\&.

This procedure adds \fBFILE\fP and \fBFILE_NAME\fP to the \fBTARGETS\fP

returned by the list\&.

It treats requests for conversion of a selection to \fBFILE\fP and

\fBFILE_NAME\fP exactly like requests for conversion to \fBTEXT\fP\&.

.PP

If an application changes \fBXmNdirSearchProc\fP or

\fBXmNfileSearchProc\fP and wants to support the \fBFILE\fP and

\fBFILE_NAME\fP targets on the corresponding list, it must provide

support itself by adding a procedure to the list\&'s

\fBXmNconvertCallback\fP list\&.

.SS "Descendants"

.PP

FileSelectionBox automatically creates the descendants shown in the

following table\&.

An application can use \fBXtNameToWidget\fP to gain access

to the named descendant\&. In addition, a user or an application

can use the named descendant when specifying resource values\&.

.TS

tab(?) box;

l| l| l.

\fBNamed Descendant\fP?\fBClass\fP?\fBIdentity\fP

_?_?_?

=

_?_?_?

\fBApply\fP?\fBXmPushButtonGadget\fP?Apply button

_?_?_?

\fBCancel\fP?\fBXmPushButtonGadget\fP?Cancel button

_?_?_?

\fBDir\fP?\fBXmLabelGadget\fP?title above list of directories

_?_?_?

\fBDirList\fP?\fBXmList\fP?list of directories

_?_?_?

\fBDirListSW\fP?\fBXmScrolledWindow\fP?ScrolledWindow parent of \fBDirList\fP

_?_?_?

\fBFilterLabel\fP?\fBXmLabelGadget\fP?title above filter box

_?_?_?

\fBFilterText\fP?\fBXmText\fP or \fBXmTextField\fP?text within filter box

_?_?_?

\fBHelp\fP?\fBXmPushButtonGadget\fP?Help button

_?_?_?

\fBItems\fP?\fBXmLabelGadget\fP?title above list of filenames

_?_?_?

\fBItemsList\fP?\fBXmList\fP?list of filenames

_?_?_?

\fBItemsListSW\fP?\fBXmScrolledWindow\fP?ScrolledWindow parent of \fBItemsList\fP

_?_?_?

\fBOK\fP?\fBXmPushButtonGadget\fP?OK button

_?_?_?

\fBSelection\fP?\fBXmLabelGadget\fP?title above selection box

_?_?_?

\fBSeparator\fP?\fBXmSeparatorGadget\fP?optional dividing line

_?_?_?

\fBText\fP?\fBXmText\fP or \fBXmTextField\fP?text within selection box

_?_?_?

.TE

.SS "Classes"

.PP

FileSelectionBox inherits behavior,

resources, and traits from \fBCore\fP, \fBComposite\fP,

\fBConstraint\fP, \fBXmManager\fP,

\fBXmBulletinBoard\fP, and \fBXmSelectionBox\fP\&.

.PP

The class pointer is \fBxmFileSelectionBoxWidgetClass\fP\&.

.PP

The class name is \fBXmFileSelectionBox\fP\&.

.SS "New Resources"

.PP

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 \fB\&.Xdefaults\fP file, remove the \fBXmN\fP or

\fBXmC\fP prefix and use the remaining letters\&. To specify one of the defined

values for a resource in a \fB\&.Xdefaults\fP file,

remove the \fBXm\fP 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 \fBXtSetValues\fP (S),

retrieved by using \fBXtGetValues\fP (G), or is not applicable (N/A)\&.

.PP

.TS

tab(?) box;

c s s s s

l| l| l| l| l.

\fBXmFileSelectionBox Resource Set\fP

\fBName\fP?\fBClass\fP?\fBType\fP?\fBDefault\fP?\fBAccess\fP

_?_?_?_?_?

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?T{

"\0[\0\0\0\0]\0"

T}?CSG

_?_?_?_?_?

XmNpathMode?XmCPathMode?XtEnum?XmPATH_MODE_FULL?C

_?_?_?_?_?

XmNpattern?XmCPattern?XmString?dynamic?CSG

_?_?_?_?_?

XmNqualifySearchDataProc?XmCQualifySearchDataProc?XmQualifyProc?default procedure?CSG

_?_?_?_?_?

.TE

.IP "\fBXmNdirectory\fP" 10

Specifies the base directory used in combination with \fBXmNpattern\fP

in determining the files and directories to be displayed\&.

The default value is determined by the \fBXmNqualifySearchDataProc\fP

and depends on the initial values of \fBXmNdirMask\fP,

\fBXmNdirectory\fP, and \fBXmNpattern\fP\&.

If the default is NULL or empty, the current working directory is used\&.

.IP "\fBXmNdirectoryValid\fP" 10

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

\fBXmNdirMask\fP, \fBXmNdirectory\fP, and \fBXmNpattern\fP are not

changed\&.

.IP "\fBXmNdirListItems\fP" 10

Specifies the items in the directory list\&.

\fBXtGetValues\fP for this resource returns the list items themselves,

not a copy of the list items\&.

The application must not free the returned items\&.

.IP "\fBXmNdirListItemCount\fP" 10

Specifies the number of items in the directory list\&.

The value must not be negative\&.

.IP "\fBXmNdirListLabelString\fP" 10

Specifies the label string of the directory list\&.

The default for this resource depends on the locale\&.

In the C locale the default is \fBDirectories\fP\&.

.IP "" 10

Now that some default localized label strings are provided through

message catalogs for the children of composite widgets, the

\fBlabelString\fP resources

cannot be set on the child through default resource files\&.

Instead, the resource provided at the parent level must be used\&.

.IP "\fBXmNdirMask\fP" 10

Specifies the directory mask used

in determining the files and directories to be displayed\&.

The default value is determined by the

\fBXmNqualifySearchDataProc\fP

and depends on the initial values of \fBXmNdirMask\fP,

\fBXmNdirectory\fP, and \fBXmNpattern\fP\&.

.IP "\fBXmNdirSearchProc\fP" 10

Specifies a directory search procedure to replace the default

directory search procedure\&.

FileSelectionBox\&'s default directory search procedure fulfills the needs

of most applications\&.

Because it is impossible to cover the requirements of all applications,

you can replace the default search procedure\&.

.IP "" 10

The directory search procedure is called with two arguments:

the FileSelectionBox widget and a pointer to an

\fBXmFileSelectionBoxCallbackStruct\fR structure\&.

The callback structure is generated by the

\fBXmNqualifySearchDataProc\fP 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 generate a new list of

directories and update the FileSelectionBox widget by using

\fBXtSetValues\fP\&.

.IP "" 10

The search procedure must set \fBXmNdirectoryValid\fP and

\fBXmNlistUpdated\fP\&.

If it generates a new list of directories, it must also set

\fBXmNdirListItems\fP and \fBXmNdirListItemCount\fP\&.

.IP "" 10

If the search procedure cannot search the specified directory, it must

warn the user and set \fBXmNdirectoryValid\fP and \fBXmNlistUpdated\fP

to False, unless it prompts and subsequently obtains a valid directory\&.

If the directory is valid but is the same as the current

\fBXmNdirectory\fP, the search procedure must set

\fBXmNdirectoryValid\fP to True, but it may elect not to generate a new

list of directories\&.

In this case, it must set \fBXmNlistUpdated\fP to False\&.

.IP "" 10

If the search procedure generates a new list of directories, it must set

\fBXmNdirListItems\fP to the new list of directories and

\fBXmNdirListItemCount\fP to the number of items in the list\&.

If there are no directories, it sets \fBXmNdirListItems\fP to NULL and

\fBXmNdirListItemCount\fP to 0 (zero)\&.

In either case, it must set \fBXmNdirectoryValid\fP and

\fBXmNlistUpdated\fP to True\&.

.IP "" 10

The search procedure ordinarily should not change the callback 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 \fIdir\fP member of the callback structure

to the new directory,

call the \fBXmNqualifySearchDataProc\fP with the

callback struct as the input argument, and copy the qualified data

returned by the \fBXmNqualifySearchDataProc\fP into the callback struct\&.

.IP "\fBXmNdirSpec\fP" 10

Specifies the full file path specification\&.

This is the \fBXmNtextString\fP resource in SelectionBox, renamed for

FileSelectionBox\&.

The default value is determined by the FileSelectionBox after conducting

the initial directory and file search\&.

.IP "\fBXmNdirTextLabelString\fP" 10

Uses the specified \fBXmString\fR as the label above the TextField

directory\&. The resource takes effect when the \fBXmNpathMode\fP

resource has a value of \fBXmPATH_MODE_RELATIVE\fP\&. It is ignored

when the \fBXmNpathMode\fP resource has a value of \fBXmPATH_MODE_FULL\fP\&.

.IP "" 10

Now that some default localized label strings are provided through

message catalogs for the children of composite widgets, the

\fBlabelString\fP resources

cannot be set on the child through default resource files\&.

Instead, the resource provided at the parent level must be used\&.

.IP "\fBXmNfileFilterStyle\fP" 10

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:

.RS

.IP "\fBXmFILTER_NONE\fP" 10

Does not filter hidden files\&.

.IP "\fBXmFILTER_HIDDEN_FILES\fP" 10

Restricts the list of possible file names, such as those beginning

with . (period)\&.

.RE

.IP "\fBXmNfileListItems\fP" 10

Specifies the items in the file list\&.

This is the \fBXmNlistItems\fP resource in SelectionBox, renamed for

FileSelectionBox\&.

\fBXtGetValues\fP for this resource returns the list items themselves,

not a copy of the list items\&.

The application must not free the returned items\&.

.IP "\fBXmNfileListItemCount\fP" 10

Specifies the number of items in the file list\&.

This is the \fBXmNlistItemCount\fP resource in SelectionBox, renamed for

FileSelectionBox\&.

The value must not be negative\&.

.IP "\fBXmNfileListLabelString\fP" 10

Specifies the label string of the file list\&.

This is the \fBXmNlistLabelString\fP resource in SelectionBox, renamed

for FileSelectionBox\&.

The default for this resource depends on the locale\&.

In the C locale the default is \fBFiles\fP\&.

.IP "" 10

Now that some default localized label strings are provided through

message catalogs for the children of composite widgets, the

\fBlabelString\fP resources

cannot be set on the child through default resource files\&.

Instead, the resource provided at the parent level must be used\&.

.IP "\fBXmNfileSearchProc\fP" 10

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 applications,

you can replace the default search procedure\&.

.IP "" 10

The file search procedure is called with two arguments:

the FileSelectionBox widget and a pointer to an

\fBXmFileSelectionBoxCallbackStruct\fR structure\&.

The callback structure is generated by the

\fBXmNqualifySearchDataProc\fP (and possibly modified by the

\fBXmNdirSearchProc\fP)\&.

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 \fBXtSetValues\fP\&.

.IP "" 10

The search procedure must set \fBXmNlistUpdated\fP\&.

If it generates a new list of files, it must also set

\fBXmNfileListItems\fP and \fBXmNfileListItemCount\fP\&.

.IP "" 10

It is recommended that the search procedure always generate a new list of

files\&.

If the \fImask\fP member of the callback structure is the same as the

\fImask\fP 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 \fBXmNlistUpdated\fP to False\&.

.IP "" 10

If the search procedure generates a new list of files, it must set

\fBXmNfileListItems\fP to the new list of files and

\fBXmNfileListItemCount\fP to the number of items in the list\&.

If there are no files, it sets \fBXmNfileListItems\fP to NULL and

\fBXmNfileListItemCount\fP to 0 (zero)\&.

In either case it must set \fBXmNlistUpdated\fP to True\&.

.IP "" 10

In constructing the list of files, the search procedure should include

only files of the types specified by the widget\&'s \fBXmNfileTypeMask\fP\&.

.IP "" 10

Setting \fBXmNdirSpec\fP 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\&.

.IP "\fBXmNfileTypeMask\fP" 10

Specifies the type of files listed in the file list\&.

The possible values are

.RS

.IP "\fBXmFILE_REGULAR\fP" 10

Restricts the file list to contain only regular

files\&.

.IP "\fBXmFILE_DIRECTORY\fP" 10

Restricts the file list to contain only

directories\&.

.IP "\fBXmFILE_ANY_TYPE\fP" 10

Allows the list to contain all file types

including directories\&.

.RE

.IP "\fBXmNfilterLabelString\fP" 10

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 \fBFilter\fP\&.

.IP "" 10

Now that some default localized label strings are provided through

message catalogs for the children of composite widgets, the

\fBlabelString\fP resources

cannot be set on the child through default resource files\&.

Instead, the resource provided at the parent level must be used\&.

.IP "\fBXmNlistUpdated\fP" 10

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\&.

.IP "\fBXmNnoMatchString\fP" 10

Specifies a string to be displayed in the file list if the list of files

is empty\&.

.IP "\fBXmNpattern\fP" 10

Specifies the search pattern used in combination with \fBXmNdirectory\fP

in determining the files and directories to be displayed\&.

The default value is determined by \fBXmNqualifySearchDataProc\fP

and depends on the initial values of \fBXmNdirMask\fP,

\fBXmNdirectory\fP, and \fBXmNpattern\fP\&.

If the default is NULL or empty, a pattern that matches all files is

used\&.

.IP "\fBXmNpathMode\fP" 10

Specifies whether or not an additional text field will be used to

display and edit the filter\&. The possible values are

.RS

.IP "\fBXmPATH_MODE_FULL\fP" 10

Specifies that no additional text field will be used to display

the filter\&. There will just be a single text field to display

\fBXmNdirMask\fP\&.

.IP "\fBXmPATH_MODE_RELATIVE\fP" 10

Specifies that there will be two text field displays, one to display

the \fBXmNdirectory\fP and one to display the \fBXmNpattern\fP\&. In

this instance, the \fBXmNfilterLabelString\fP resource applies to the

text field for

\fBXmNpattern\fP and \fBXmNdirTextLabelString\fP applies to the text

field for \fBXmNdirectory\fP\&.

.RE

.IP "\fBXmNqualifySearchDataProc\fP" 10

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\&.

.IP "" 10

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

\fBXmFileSelectionBoxCallbackStruct\fR 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\&.

.IP "" 10

If the input \fIdir\fP and \fIpattern\fP members are not NULL, the

procedure must copy them to the corresponding members of the output

callback structure\&.

.IP "" 10

If the input \fIdir\fP is NULL, the procedure constructs the

output \fIdir\fP as follows:

If the input \fImask\fP member is NULL, the procedure uses the

widget\&'s \fBXmNdirectory\fP as the output \fIdir\fP; otherwise, it

extracts the output \fIdir\fP from the input \fImask\fP\&.

If the resulting output \fIdir\fP is empty, the procedure uses

the current working directory instead\&.

.IP "" 10

If the input \fIpattern\fP is NULL, the procedure constructs

the output \fIpattern\fP as follows:

If the input \fImask\fP member is NULL, the procedure uses the

widget\&'s \fBXmNpattern\fP as the output \fIpattern\fP; otherwise, it

extracts the output \fIpattern\fP from the input \fImask\fP\&.

If the resulting output \fIpattern\fP is empty, the procedure

uses a pattern that matches all files instead\&.

.IP "" 10

The data qualification procedure constructs the output \fImask\fP from

the output \fIdir\fP and \fIpattern\fP\&.

The procedure must ensure that the output \fIdir\fP, \fIpattern\fP, and

\fImask\fP are fully qualified\&.

.IP "" 10

If the input \fIvalue\fP member is not NULL, the procedure must copy it

to the output \fIvalue\fP member; otherwise, the procedure must copy the

widget\&'s \fBXmNdirSpec\fP to the output \fIvalue\fP\&.

.IP "" 10

The data qualification procedure must calculate the lengths of the

output \fIvalue\fP, \fImask\fP, \fIdir\fP, and \fIpattern\fP members and

must fill in the corresponding length members of the output callback

struct\&.

.IP "" 10

The data qualification procedure must copy the input \fIreason\fP and

\fIevent\fP members to the corresponding output members\&.

.PP

The values of the \fBXmNdirSearchProc\fP and \fBXmNfileSearchProc\fP

are procedure pointers of type \fBXmSearchProc\fR, defined as

follows:

.PP

.nf

void (* XmSearchProc) (\fIw, search_data\fP)

        Widget \fIw\fP;

        XtPointer \fIsearch_data\fP;

.fi

.IP "\fIw\fP" 10

The FileSelectionBox widget

.IP "\fIsearch_data\fP" 10

Pointer to an \fBXmFileSelectionBoxCallbackStruct\fR containing

information for conducting a search

.PP

The value of the \fBXmNqualifySearchDataProc\fP resource

is a procedure pointer of type \fBXmQualifyProc\fR, defined

as follows:

.PP

.nf

void (* XmQualifyProc) (\fIw, input_data, output_data\fP)

        Widget \fIw\fP;

        XtPointer \fIinput_data\fP;

        XtPointer \fIoutput_data\fP;

.fi

.IP "\fIw\fP" 10

The FileSelectionBox widget

.IP "\fIinput_data\fP" 10

Pointer to an \fBXmFileSelectionBoxCallbackStruct\fR containing

input data to be qualified

.IP "\fIoutput_data\fP" 10

Pointer to an \fBXmFileSelectionBoxCallbackStruct\fR containing

output data to be filled in by the qualification procedure

.SS "Inherited Resources"

.PP

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\&.

.PP

.TS

tab(?) box;

c s s s s

l| l| l| l| l.

\fBXmSelectionBox Resource Set\fP

\fBName\fP?\fBClass\fP?\fBType\fP?\fBDefault\fP?\fBAccess\fP

_?_?_?_?_?

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

_?_?_?_?_?

.TE

.PP

.TS

tab(?) box;

c s s s s

l| l| l| l| l.

\fBXmBulletinBoard Resource Set\fP

\fBName\fP?\fBClass\fP?\fBType\fP?\fBDefault\fP?\fBAccess\fP

_?_?_?_?_?

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

_?_?_?_?_?

.TE

.PP

.TS

tab(?) box;

c s s s s

l| l| l| l| l.

\fBXmManager Resource Set\fP

\fBName\fP?\fBClass\fP?\fBType\fP?\fBDefault\fP?\fBAccess\fP

_?_?_?_?_?

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

_?_?_?_?_?

.TE

.PP

.TS