XmFileSelectionBox

NAME

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

Additional children may be added to the FileSelectionBox after creation. FileSelectionBox inherits the layout functionality provided by SelectionBox for any additional children. The list of filenames, the list of subdirectories, or both can be removed from the FileSelectionBox after creation by unmanaging the appropriate widgets and their labels. The list and label widgets are obtained by calling the function XmFileSelectionBoxGetChild. 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.

Filter Label-"FilterLabel"
Filter Text-"Text"
Directory List-"DirList"
Directory List Label-"Dir"

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.

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. 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 these actions:

Selects the OK PushButton
Presses KActivate while the selection text edit area has the keyboard focus.
Double clicks or presses KActivate on an item in the file list

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

The FileSelectionBox is initialized
The function XtSetValues is used to change XmNdirMask, XmNdirectory, XmNpattern, or XmNfileTypeMask
The user activates the Filter PushButton
The user double clicks or presses KActivate on an item in the directory list
The application calls XmFileSelectionDoSearch
The user presses KActivate while the directory mask text edit area has the keyboard focus

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

Constructs an XmFileSelectionBoxCallbackStruct structure with values appropriate for the action that initiated the search
Calls the XmNqualifySearchDataProc with the callback structure as the data input argument
Sets XmNdirectoryValid and XmNlistUpdated to False
Calls the XmNdirSearchProc with the qualified data returned by the XmNqualifySearchDataProc

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

Sets XmNlistUpdated to False
Calls the XmNfileSearchProc with the qualified data returned by the XmNqualifySearchDataProc (and possibly modified by the XmNdirSearchProc)
If XmNlistUpdated is True and the file list is empty, displays the XmNnoMatchString in the file list and clears the selection text and XmNdirSpec
If XmNlistUpdated is True and the file list is not empty, sets the selection text and XmNdirSpec to the qualified dir returned by the XmNqualifySearchDataProc (and possibly modified by the XmNdirSearchProc)
Sets the directory mask text and XmNdirMask to the qualified mask returned by the XmNqualifySearchDataProc (and possibly modified by the XmNdirSearchProc)
Sets XmNdirectory to the qualified dir returned by the XmNqualifySearchDataProc (and possibly modified by the XmNdirSearchProc)
Sets XmNpattern to the qualified pattern returned by the XmNqualifySearchDataProc (and possibly modified by the XmNdirSearchProc)

Classes

FileSelectionBox inherits behavior and resources from Core, Composite, Constraint, XmManager, XmBulletinBoard, and XmSelectionBox.

The class pointer is xmFileSelectionBoxWidgetClass.

The class name is XmFileSelectionBox.

New Resources

The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the XmN or XmC prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the Xm prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A).


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
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
XmNpattern                XmCPattern                XmString       dynamic            CSG
XmNqualifySearchDataProc  XmCQualifySearchDataProc  XmQualifyProc  default procedure  CSG

**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
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
XmNpattern	XmCPattern	XmString	dynamic	CSG
XmNqualifySearchDataProc	XmCQualifySearchDataProc	XmQualifyProc	default procedure	CSG

XmNdirectory

Specifies the base directory used in combination with XmNpattern in determining the files and directories to be displayed. The default value is determined by the XmNqualifySearchDataProc 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".

XmNdirMask

Specifies the directory mask used in determining the files and directories to be displayed. The default value is determined by the XmNqualifySearchDataProc and depends on the initial 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 applications. Because it is impossible to cover the requirements of all applications, you can replace the default search procedure.

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 is 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. In either case it must set XmNdirectoryValid and XmNlistUpdated to True.

The search procedure ordinarily should not change the callback struct. 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 struct 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.

XmNdirSpec

Specifies the full file path specification. This is the XmNtextString resource in SelectionBox, renamed for FileSelectionBox. The default value is determined by the FileSelectionBox after conducting the initial directory and file search.

XmNfileListItems

Specifies the items in the file list. This is the XmNlistItems resource in SelectionBox, renamed for FileSelectionBox. 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 FileSelectionBox. 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".

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 applications, you can replace the default search procedure.

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

The search procedure is recommended always to generate a new list of files. If the mask member of the callback struct 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. 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.

XmNfileTypeMask

Specifies the type of files listed in the file list. Following are the possible values:

XmFILE_REGULAR restricts the file list to contain only regular files.
XmFILE_DIRECTORY restricts the file list to contain only directories.
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".

XmNlistUpdated

Specifies an attribute that is set only by the directory and file search procedures. 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 XmNdirectory in determining the files and directories to be displayed. The default value is determined by the XmNqualifySearchDataProc 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.

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 struct contains the input data. The second callback struct 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 struct.

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;

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 following superclasses. For a complete description of each resource, refer to the man 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

**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
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
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
XmNtextTranslations  XmCTranslations     XtTranslations  NULL           C
XmNunmapCallback     XmCCallback         XtCallbackList  NULL           C

**XmBulletinBoard Resource Set**
Name	Class	Type	Default	Access
XmNallowOverlap	XmCAllowOverlap	Boolean	True	CSG
XmNautoUnmanage	XmCAutoUnmanage	Boolean	False	CG
XmNbuttonFontList	XmCButtonFontList	XmFontList	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
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
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
XmNnavigationType      XmCNavigationType      XmNavigationType   XmTAB_GROUP           CSG
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

**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
XmNnavigationType	XmCNavigationType	XmNavigationType	XmTAB_GROUP	CSG
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

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

**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
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
mask: Specifies the current value of XmNdirMask
mask_length: Specifies the number of bytes in mask
dir: Specifies the current base directory
dir_length: Specifies the number of bytes in dir
pattern: Specifies the current search pattern
pattern_length: Specifies the number of bytes in pattern

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 described below:

SelectionBoxUpOrDown(0|1|2|3):

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 a 0 argument, selects the previous item in the list and replaces the text with that item.

When called with a 1 argument, selects the next item in the list and replaces the text with that item.

When called with a 2 argument, selects the first item in the list and replaces the text with that item.

When called with a 3 argument, 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, replaces the selection text with the selected item in the file list. If no item in the file list is selected, clears the selection text.

If the directory mask text has the focus, replaces the directory mask text with a new directory mask constructed from the XmNdirectory and XmNpattern resources.

Additional Behavior

The FileSelectionBox widget has the additional behavior described below:

MAny KCancel:: 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, passes the event to the parent.
<KActivate> in Selection Text:: Calls the selection text widget's XmNactivateCallback callbacks. If XmNmustMatch is True and the selection text does not match an item in the file list, calls the XmNnoMatchCallback callbacks with reason XmCR_NO_MATCH. Otherwise, calls the XmNokCallback callbacks with reason XmCR_OK.
<KActivate> in Directory Mask Text:: Calls the directory mask text widget's XmNactivateCallback callbacks. Initiates a directory and file search. Calls the XmNapplyCallback callbacks with reason XmCR_APPLY.
<DoubleClick> or <KActivate> in Directory List:: Calls the directory list widget's XmNdefaultActionCallback callbacks. Initiates a directory and file search. Calls the XmNapplyCallback callbacks with reason XmCR_APPLY.
<DoubleClick> or <KActivate> in File List:: Calls the file list widget's XmNdefaultActionCallback callbacks. Calls the XmNokCallback callbacks with reason XmCR_OK.
<Single Select> or <Browse Select> 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, uses a pattern that matches all files in the directory. Replaces the directory mask text with the new directory mask.
<Single Select> or <Browse Select> in File List:: Replaces the selection text with the selected list item.
<BDrag> in File List:: Drags the content of one or more selected list items using the drag and drop facility. If BDrag is pressed on an unselected item, drags only that item, excluding any other selected items.
The XmNexportTargets resource of the associated DragContext is set to target types of COMPOUND_TEXT and FILE_NAME. The XmNclientData resource is set to the index of the item in the list.
<BDrag> in Directory List:: Drags the content of one or more selected list items using the drag and drop facility. If BDrag is pressed on an unselected item, drags only that item, excluding any other selected items.
The XmNexportTargets resource of the associated DragContext is set to target types of COMPOUND_TEXT and FILE_NAME. The XmNclientData resource is set to the index of the item in the list.
<Apply Button Activated>:: Initiates a directory and file search. Calls the XmNapplyCallback 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 callbacks with reason XmCR_NO_MATCH. Otherwise, calls the XmNokCallback callbacks with reason XmCR_OK.
<Cancel Button Activated>:: Calls the XmNcancelCallback callbacks with reason XmCR_CANCEL.
<Help Button Activated>:: Calls the XmNhelpCallback callbacks with reason XmCR_HELP.
<KActivate>:: 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, calls the XmNnoMatchCallback callbacks with reason XmCR_NO_MATCH. Otherwise, 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(3X).

RELATED INFORMATION

Composite(3X), Constraint(3X), Core(3X), XmBulletinBoard(3X), XmCreateFileSelectionBox(3X), XmCreateFileSelectionDialog(3X), XmFileSelectionBoxGetChild(3X), XmFileSelectionDoSearch(3X), XmManager(3X), and XmSelectionBox(3X).