XmFileSelectionBox(3Xm)

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

XmFileSelectionBox Resource Set
Name | Class | Type | Default | Access
XmNdirMask | XmCDirMask | XmString | "*" | CSG
XmNdirSpec | XmCDirSpec | XmString | NULL | CSG
XmNfileSearchProc | XmCFileSearchProc | XtProc | see below | CSG
XmNfilterLabelString | XmCFilterLabelString | XmString | "File Filter" | CSG
XmNlistUpdated | XmCListUpdated | Boolean | True | CSG

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.

XmSelectionBox Resource Set
Name | Class | Type | Default | Access
XmNapplyCallback | XmCCallback | XtCallbackList | NULL | C
XmNapplyLabelString | XmCApplyLabelString | XmString | "Filter" | CSG
XmNcancelCallback | XmCCallback | XtCallbackList | NULL | C
XmNcancelLabelString | XmCXmString | XmString | "Cancel" | CSG
XmNdialogType | XmCDialogType | unsigned char | XmDIALOG_FILE_SELECTION | CG
XmNhelpLabelString | XmCXmString | XmString | "Help" | CSG
XmNlistItemCount | XmCItemCount | int | 0 | CSG
XmNlistItems | XmCItems | XmStringList | NULL | CSG
XmNlistLabelString | XmCXmString | XmString | "Files" | CSG
XmNlistVisibleItemCount | XmCVisibleItemCount | int | 8 | CSG
XmNminimizeButtons | XmCMinimizeButtons | Boolean | False | CSG
XmNmustMatch | XmCMustMatch | Boolean | False | CSG
XmNnoMatchCallback | XmCCallback | XtCallbackList | NULL | C
XmNokCallback | XmCCallback | XtCallbackList | NULL | C
XmNokLabelString | XmCXmString | XmString | "OK" | CSG
XmNselectionLabelString | XmCXmString | XmString | "Selection" | CSG
XmNtextAccelerators | XmCTextAccelerators | XtTranslations | see description | C
XmNtextColumns | XmCTextColumns | int | 31 | CSG
XmNtextString | XmCTextString | XmString | NULL | CSG

XmBulletinBoard Resource Set
Name | Class | Type | Default | Access
XmNallowOverlap | XmCAllowOverlap | Boolean | True | CSG
XmNautoUnmanage | XmCAutoUnmanage | Boolean | False | CSG
XmNbuttonFontList | XmCButtonFontList | XmFontList | NULL | 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 | XmCXmString | XmString | NULL | CSG
XmNfocusCallback | XmCCallback | XtCallbackList | NULL | C
XmNlabelFontList | XmCLabelFontList | XmFontList | NULL | CSG
XmNmapCallback | XmCCallback | XtCallbackList | NULL | C
XmNmarginHeight | XmCMarginHeight | short | 10 | CSG
XmNmarginWidth | XmCMarginWidth | short | 10 | CSG
XmNnoResize | XmCNoResize | Boolean | False | CSG
XmNresizePolicy | XmCResizePolicy | unsigned char | XmRESIZE_ANY | CSG
XmNshadowType | XmCShadowType | unsigned char | XmSHADOW_OUT | CSG
XmNstringDirection | XmCStringDirection | XmStringDirection | XmSTRING_DIRECTION_L_TO_R | CSG
XmNtextFontList | XmCTextFontList | XmFontList | NULL | CSG
XmNtextTranslations | XmCTranslations | XtTranslations | NULL | C
XmNunmapCallback | XmCCallback | XtCallbackList | NULL | C

XmManager Resource Set
Name | Class | Type | Default | Access
XmNbottomShadowColor | XmCForeground | Pixel | dynamic | CSG
XmNbottomShadowPixmap | XmCBottomShadowPixmap | Pixmap | XmUNSPECIFIED_PIXMAP | CSG
XmNforeground | XmCForeground | Pixel | dynamic | CSG
XmNhelpCallback | XmCCallback | XtCallbackList | NULL | C
XmNhighlightColor | XmCForeground | Pixel | Black | CSG
XmNhighlightPixmap | XmCHighlightPixmap | Pixmap | dynamic | CSG
XmNshadowThickness | XmCShadowThickness | short | dynamic | CSG
XmNtopShadowColor | XmCBackground | Pixel | dynamic | CSG
XmNtopShadowPixmap | XmCTopShadowPixmap | Pixmap | XmUNSPECIFIED_PIXMAP | CSG
XmNunitType | XmCUnitType | unsigned char | XmPIXELS | CSG
XmNuserData | XmCUserData | caddr_t | NULL | CSG

Composite Resource Set
Name | Class | Type | Default | Access
XmNinsertPosition | XmCInsertPosition | XmRFunction | NULL | CSG

Core Resource Set
Name | Class | Type | Default | Access
XmNaccelerators | XmCAccelerators | XtTranslations | NULL | CSG
XmNancestorSensitive | XmCSensitive | Boolean | True | G
XmNbackground | XmCBackground | Pixel | dynamic | CSG
XmNbackgroundPixmap | XmCPixmap | Pixmap | XmUNSPECIFIED_PIXMAP | CSG
XmNborderColor | XmCBorderColor | Pixel | Black | CSG
XmNborderPixmap | XmCPixmap | Pixmap | XmUNSPECIFIED_PIXMAP | CSG
XmNborderWidth | XmCBorderWidth | Dimension | 0 | CSG
XmNcolormap | XmCColormap | Colormap | XtCopyFromParent | CG
XmNdepth | XmCDepth | int | XtCopyFromParent | CG
XmNdestroyCallback | XmCCallback | XtCallbackList | NULL | C
XmNheight | XmCHeight | Dimension | 0 | CSG
XmNmappedWhenManaged | XmCMappedWhenManaged | Boolean | True | CSG
XmNscreen | XmCScreen | Pointer | XtCopyScreen | CG
XmNsensitive | XmCSensitive | Boolean | True | CSG
XmNtranslations | XmCTranslations | XtTranslations | NULL | CSG
XmNwidth | XmCWidth | Dimension | 0 | CSG
XmNx | XmCPosition | Position | 0 | CSG
XmNy | XmCPosition | Position | 0 | CSG

  Callback Information
The following structure is returned with each callback:

typedef struct
{
	int	reason;
	XEvent	* event;
	XmString	value;
	int	length;
	XmString	mask;
	int	mask_length;
} XmFileSelectionBoxCallbackStruct;

reason
    Indicates why the callback was invoked.

event
    Points to the XEvent that triggered the callback.

value
    Specifies the value of the current XmNdirSpec.

length
    Specifies the number of bytes of the structure pointed to by value.

mask
    Specifies the current value of XmNdirMask.

mask_length
    Specifies 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),