XmFileSelectionBox(3Xm) XmFileSelectionBox(3Xm)
NAME
XmFileSelectionBox - the FileSelectionBox widget class.
AES SUPPORT LEVEL
full-use
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.
- 1 -
XmFileSelectionBox(3Xm) XmFileSelectionBox(3Xm)
⊕ 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
- 2 -
XmFileSelectionBox(3Xm) XmFileSelectionBox(3Xm)
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
- 3 -
XmFileSelectionBox(3Xm) XmFileSelectionBox(3Xm)
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
XmNtextFontList XmCTextFontList XmFontList NULL CSG
XmNtextTranslations XmCTranslations XtTranslations NULL C
XmNunmapCallback XmCCallback XtCallbackList NULL C
XmManager Resource Set
- 4 -
XmFileSelectionBox(3Xm) XmFileSelectionBox(3Xm)
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
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;
- 5 -
XmFileSelectionBox(3Xm) XmFileSelectionBox(3Xm)
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(3X).
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:
- 6 -
XmFileSelectionBox(3Xm) XmFileSelectionBox(3Xm)
#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(3X) and its sections on behavior and
default translations.
RELATED INFORMATION
Composite(3X), Constraint(3X), Core(3X),
XmBulletinBoard(3X), XmCreateFileSelectionBox(3X),
XmCreateFileSelectionDialog(3X),
XmFileSelectionBoxGetChild(3X),
XmFileSelectionDoSearch(3X), XmManager(3X), and
XmSelectionBox(3X),
- 7 -