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:

FileSelectionBox initiates a directory and file search when any of the following occurs:

When a file search is initiated, the FileSelectionBox takes the following actions:

If XmNdirectoryValid is True, the FileSelectionBox takes the following additional actions:

FileSelectionBox uses the XmQTactivatable trait.

Now that some default localized label strings are provided through message catalogs for the children of composite widgets, the labelString resources cannot be set on the child through default resource files. Instead, the resource provided at the parent level must be used.

The directory search procedure is called with two arguments: the FileSelectionBox widget and a pointer to an XmFileSelectionBoxCallbackStruct 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 generate a new list of directories and update the FileSelectionBox widget by using XtSetValues.

The search procedure must set XmNdirectoryValid and XmNlistUpdated. If it generates a new list of directories, it must also set XmNdirListItems and XmNdirListItemCount.

If the search procedure cannot search the specified directory, 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 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 dir member of the callback structure to the new directory, call the XmNqualifySearchDataProc with the callback struct as the input argument, and copy the qualified data returned by the XmNqualifySearchDataProc into the callback struct.

Now that some default localized label strings are provided through message catalogs for the children of composite widgets, the labelString resources cannot be set on the child through default resource files. Instead, the resource provided at the parent level must be used.

Now that some default localized label strings are provided through message catalogs for the children of composite widgets, the labelString resources cannot be set on the child through default resource files. Instead, the resource provided at the parent level must be used.

The file search procedure is called with two arguments: the FileSelectionBox widget and a pointer to an XmFileSelectionBoxCallbackStruct structure. The callback structure is generated 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 generates 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 structure 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 XmNfileListItemCount to the number of items in the list. If there are no files, it sets XmNfileListItems to NULL and XmNfileListItemCount 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 widget'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.

Now that some default localized label strings are provided through message catalogs for the children of composite widgets, the labelString resources cannot be set on the child through default resource files. Instead, the resource provided at the parent level must be used.

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 procedure must copy them to the corresponding members of the output callback structure.

If the input dir is NULL, the procedure constructs the output dir as follows: If the input mask member is NULL, the procedure uses the widget's XmNdirectory as the output dir; otherwise, 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 pattern; 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 callback 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;

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;

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 compatibility, 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.

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.

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.

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.