XmFileSelectionBox(Xm) UNIX System V
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 DIRMASK 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(Xm).
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>KPEnter: 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>KPEnter: Return()
Keyboard Traversal
For information on keyboard traversal, see the man page for
XmManager(Xm) and its sections on behavior and default
translations.
RELATED INFORMATION
Composite(Xm), Constraint(Xm), Core(Xm),
XmBulletinBoard(Xm), XmCreateFileSelectionBox(Xm),
XmCreateFileSelectionDialog(Xm),
XmFileSelectionBoxGetChild(Xm), XmFileSelectionDoSearch(Xm),
XmManager(Xm), and XmSelectionBox(Xm),
(printed 2/14/90) XmFileSelectionBox(Xm)