NAME

XmFileSelectionBox — the FileSelectionBox widget class. 

SYNOPSIS

#include <Xm/FileSB.h>

DESCRIPTION

FileSelectionBox traverses through directories, views the files in them, and then selects a file. 

A FileSelectionBox has four main areas:

•A directory mask that includes a filter label and a directory mask input field used to specify the directory that is to be examined. 

•A scrollable list of file names. 

•A text input field for directly typing in a file name. 

•A group of PushButtons, labeled OK, Filter, Cancel, and Help. 

One additional WorkArea child may be added to the FileSelectionBox after creation. 

The user can select a file by scrolling through the list of file names and selecting the desired file or by entering the file name directly into the text edit area.  Selecting a file from the list will cause that file name 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 selects the OK PushButton or presses the return key while the selection text edit area has the keyboard focus. 

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

•The function XtSetValues is used to change the directory mask. 

•The user activates the Filter PushButton. 

•The application calls XmFileSelectionDoSearch. 

•The user presses the return key while the directory mask input field has the keyboard focus. 

This may be useful when an application creates a new file and wants to incorporate it into the file list. 

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 lower case or upper case, 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). 

XmNdirMask
Specifies the directory mask used in determining the files to be displayed in the list box.

XmNdirSpec
Specifies the full file specification.  This resource overrides the XmNtextString resource in SelectionBox. 

XmNfileSearchProc
Specifies a directory search procedure to replace the default file selection 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 the XmFileSelectionCallbackStruct structure.  The callback structure contains all required information to conduct a directory search, including the current file search mask.  Once called, it is up to the search routine to generate a new list of files and update the file selection widget by using XtSetValues. 

The following attributes must be set:  XmNitems, XmNitemsCount, XmNlistUpdated, and XmNdirSpec.  Set XmNitems to the new list of files.  If there are no files, set this attribute to NULL.  This sets the XmNitems attribute associated with SelectionBox. 

If there are no files, set XmNitemsCount to zero.  This sets the XmNitemsCount associated with SelectionBox.  Always set XmNlistUpdated to True when updating the file list using a search procedure, even if there are no files.  Setting XmNdirSpec is optional, but recommended.  Set this attribute to the full file specification of the directory searched.  The directory specification is displayed above the list box. 

XmNfilterLabelString
Specifies the string value for the label located above the DIR_MASK text entry field. 

XmNlistUpdated
Specifies an attribute that is set only by the file search procedure.  Set to True, if the file list has been updated.

Inherited Resources

FileSelectionBox inherits behavior and resources from the following superclasses.  For a complete description of these resources, refer to the man page for that superclass. 

Callback Information

The following structure is returned with each callback:

typedef struct
{
intreason;
XEvent∗ event;
XmStringvalue;
intlength;
XmStringmask;
intmask_length;
} XmFileSelectionBoxCallbackStruct;

reasonIndicates why the callback was invoked. 

eventPoints to the XEvent that triggered the callback. 

valueSpecifies the value of the current XmNdirSpec. 

lengthSpecifies the number of bytes of the structure pointed to by value. 

maskSpecifies the current value of XmNdirMask. 

mask_lengthSpecifies the number of bytes of the structure pointed to by mask. 

Behavior

FileSelectionBox inherits behavior from SelectionBox and BulletinBoard; below is an addition to that behavior. 

<Apply Button Activated>:
A new file search begins when the apply button is activated.

Default Translations

FileSelectionBox inherits SelectionBox’s default translations.  See the man page for XmSelectionBox(3Xm). 

Default Accelerators

The following are the default accelerator translations added to descendants of a BulletinBoard if the parent of the BulletinBoard is a DialogShell:

#override
<Key>F1:Help()
<Key>Return:Return()
<Key>KP_Enter: Return()

Default Text Accelerators

The following are the default text accelerators inherited from SelectionBox:

#override
<Key>Up:UpOrDown(0)
<Key>Down:UpOrDown(1)
<Key>F1:Help()
<Key>Return:Return()
<Key>KP_Enter: Return()

Keyboard Traversal

For information on keyboard traversal, see the man page for XmManager(3Xm) and its sections on behavior and default translations. 

RELATED INFORMATION

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

7th Edition