SgFileSelectionBox(3X)SgFileSelectionBox(3X)NAMESgFileSelectionBox — The enhanced FileSelectionBox widget
SYNOPSIS
#include <Xm/FileSB.h>
VERSION
This page documents the version of Sgm that accompanies Motif 1.2.
DESCRIPTION
The enhanced XmFileSelectionBox traverses directories, shows files and
subdirectories, and selects files.
An enhanced XmFileSelectionBox has three main areas: A Finder widget,
consisting of a text field, zoom bar, drop pocket, and history button.
A scrollable list of filenames and subdirectories A group of Buttons,
labeled OK, Filter, Cancel, and Help
The user can select a new directory to examine by scrolling through the
list of files and directories and selecting the desired directory.
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 Finder widget consists of a text field, drop pocket, and history
button. The text area allows a user to type a file name. The text
field will always display the current directory whose files are listed
in the XmFileSelectionBox's list widget. It may also display a file
name concatenated on the tail of the current directory.
The zoom bar is a line of buttons that mimic the structure of the
directory in the text field. Pressing on a zoom bar button with the
left mouse button sets the current directory to the directory under‐
neath the button in the text field. The last button will not change
anything since it will always be either the current directory or a file
in the current directory. Pressing on a zoom bar button with the right
mouse button will pop-up a menu of subdirectories that are at the same
level as the directory underneath the button in the text field. Choos‐
ing an entry from one of these menus will set the current directory to
the directory corresponding with the menu entry.
The history button shows directories. It pops up a menu of visited
directories. The history button will have at least 1 entry: the direc‐
tory in which the XmFileSelectionBox started in. If a user presses OK,
the current directory will be added to the history button menu.
Selecting an item on the history button menu sets the current directory
to that item.
The drop pocket allows icons to be dropped into the XmFileSelectionBox.
When an icon is dropped, the current directory is set to the location
of that icon. If the icon is a file, the filename is also concatenated
onto the tail of the current directory. Acceptable icons for drops
will change the background color of the drop pocket. If the type of a
file is not known, or the file doesn't exist (as in a new file you are
specifying), the drop pocket displays the unkown icon (which looks like
a round balloon).
Unix .. and . directories may be specified in the text edit area. The
tilde: ~ can also be used for home directories in the text edit area.
The text edit area supports csh-style file completion. While typing,
the longest matching substring from the items currently shown in the
list is inserted in the text edit area. The current selection is set
to the inserted text. You can just keep typing to ignore it, or use
shift-space to accept the text. Typing shift-space at any time will
extend the the current text to next entry in the list that matches the
current text. If there are multiple matches, the current selection
will be set to the ambiguous portion. You can then use the up and down
arrows to cycle through all of the matching list item. Completion also
works on ~ for home directories.
The Filter button pops up a dialog asking for a shell style file match‐
ing expression. The files in the XmFileSelectionBox's list will be
filtered by the expression when the Filter dialog's OK or Apply button
is pressed. If the patten does not contain any file matching meta-
characters, '*', '?', '[', the patten is assumed to be the name of an
FTR file type. After the Filter dialog is cancelled, the file list is
updated without any filtering.
The XmNpattern resource is set to mirror the filter specified in the
filter dialog. If the XmFileSelectionBox came up with a preset XmNpat‐
tern, and the user presses Cancel in the Filter dialog, the XmNpattern
is set to "*".
The user may select a new file as many times as desired. The applica‐
tion is not notified until the user takes one of these actions: Selects
the OK PushButton Presses KActivate while the File Selection Box has
the keyboard focus and a file is selected. Double clicks or presses
KActivate on a file in the file list. Activate is typically the Enter
key.
FileSelectionBox initiates a directory and file search when any of the
following occurs: The FileSelectionBox is initialized The user double
clicks or presses KActivate on an item in the directory 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.
Summary
New Resources
The following table defines a set of widget resources used by the pro‐
grammer to specify data. The programmer can also set the resource val‐
ues 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).
Enhanced XmFileSelectionBox Resource Set
Name Class Type Default Access
───────────────────────────────────────────────────────────────────────────────────────────
SgNbrowserFileMask SgCBrowserFileMask unsigned char XmFILE_DIRECTORY CSG
SgNcompletionDelay SgCCompletionDelay int 250 CSG
SgNuseEnhancedFSB SgCUseEnhancedFSB Boolean True CG
SgNviewerMode SgCViewerMode SgRFSBViewerMode SgVIEWER_NEVER CSG
SgNviewerFileName SgCViewerFileName XmString NULL CSG
SgNviewerFilter SgCViewerFilter XmString "*" CSG
SgNviewerUpdateDelay SgCViewerUpdateDelay int 250 CSG
Specifies the type of files listed in the zoom bar browser menus. Fol‐
lowing are the possible values: XmFILE_REGULAR restricts the browser
menu to contain only regular files. XmFILE_DIRECTORY restricts the
browser menu to contain only directories. SgFILE_NOT_HIDDEN restricts
the browser menu to contain only non-hidden files. XmFILE_ANY_TYPE
allows the browser menu to contain all file types including directo‐
ries. Specifies the amount of time in miliseconds to wait after the
last character is entered in the text field before attempting to auto‐
matically invoke the completion function. If this resource is set to
zero, auto-completion is disabled. If true, and the application is
linked with -lSgm before -lXm, the enhanced file selection box
described by this manual page will be used. If false, the standard
Motif file selection box described in XmFileSelectionBox(3X) will be
used. This resource can only be set at creation time. Specifies the
policy for showing and updating the multi-media file viewer. Following
are the possible values: SgVIEWER_NEVER entirely disables the use of
the viewer. SgVIEWER_NONE enables the use of viewer but initially
leaves it unmanaged. To manage it later, this resource must be set to
either SgVIEWER_AUTOMATIC or SgVIEWER_EXPLICIT. SgVIEWER_AUTOMATIC
enables and manages the viewer. The viewer will automatically be
updated as the filename in the finder changes. SgVIEWER_EXPLICIT
enables and manages the viewer. The viewer will always display file
indicated by the SgNviewerFileName resource. Specifies the name of the
file to be display in the viewer when SgNviewerMode is set to
SgVIEWER_EXPLICIT. Specifies the list of file types to be displayed in
the viewer when SgNviewerMode is set to SgVIEWER_AUTOMATIC. Specifies
the amount of time in miliseconds to wait after the an item in the list
becomes selected before attempting to update the previewer.
XmFileSelectionBox Resource Set
Name Class Type Default Access
──────────────────────────────────────────────────────────────────────────────────────
XmNdirectory XmCDirectory XmString dynamic CSG
XmNdirSpec XmCDirSpec XmString dynamic SG
XmNfileListItems XmCItems XmStringTable dynamic SG
XmNfileListItemCount XmCItemCount int dynamic SG
XmNfileListLabelString XmCFileListLabelString XmString dynamic CSG
XmNfilterLabelString XmCFilterLabelString XmString dynamic CSG
XmNnoMatchString XmCNoMatchString XmString " [ ] " CSG
XmNpattern XmCPattern XmString "*" CSG
Specifies the base directory used in determining the files and directo‐
ries to be displayed. If the default is NULL or empty, the current
working directory is used. This resource should not be changed by the
application after initialization. The application should not free the
returned resource. Specifies the full file path specification. The
default value is determined by the FileSelectionBox after conducting
the initial directory and file search. The application should not free
this returned resource. Specifies the items in the file list. This is
the XmNlistItems resource in SelectionBox, renamed for FileSelection‐
Box. XtGetValues for this resource returns the list items themselves,
not a copy of the list items. The application must not free the
returned items. Specifies the number of items in the file list. This
is the XmNlistItemCount resource in SelectionBox, renamed for FileSe‐
lectionBox. The value must not be negative. 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". 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". Specifies a string to be dis‐
played in the file list if the list of files is empty. Specifies a
string used as a regular expression in determining the files to be dis‐
played. The default value is "*" which matches everything. The pattern
does not affect display of directories. The format of the pattern is a
regular expression of the type described in the ed(1) manual page. If
the pattern does not contain any regular expression meta characters, it
will be interpreted as a space separated list of FTR file types.
Compatibility Resources
The following table shows resources for the enhanced XmFileSelectionBox
widget which are provided for compatibility with the XmFileSelection‐
Box. These resources are not used by the enhanced XmFileSelectionBox
widget. Their default values may be different from the default in
XmFileSelectionBox(3X). For more information on the purpose of these
resources in the XmFileSelectionBox(3X), see the man page for XmFileSe‐
lectionBox(3X).
XmFileSelectionBox Compatibility Resources
Name Class Type Default Access
──────────────────────────────────────────────────────────────────────────────────────────────
XmNdirectoryValid XmCDirectoryValid Boolean TRUE SG
XmNdirListItems XmCDirListItems XmStringTable NULL SG
XmNdirListItemCount XmCDirListItemCount int XmUNSPECIFIED SG
XmNdirListLabelString XmCDirListLabelString XmString "" CSG
XmNdirMask XmCDirMask XmString "*" CSG
XmNdirSearchProc XmCDirSearchProc XmSearchProc NULL CSG
XmNfileSearchProc XmCFileSearchProc XmSearchProc NULL CSG
XmNfileTypeMask XmCFileTypeMask unsigned char XmFILE_REGULAR CSG
XmNlistUpdated XmCListUpdated Boolean TRUE SG
XmNqualifySearchDataProc XmCQualifySearchDataProc XmQualifyProc NULL CSG
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. Note that the XmFileSelectionBox
widget resets XmNautoUnmanage to FALSE and XmNdialogType to XmDIA‐
LOG_FILE_SELECTION.
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
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
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
XmNscreen XmCScreen Screen * dynamic CG
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
The Callback structure is XmFileSelectionCallbackStruct. Some fields
are not used by the enhanced XmFileSelectionBox. A pointer to the fol‐
lowing 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; Indi‐
cates why the callback was invoked Points to the XEvent that triggered
the callback Specifies the full pathname of the selected file Specifies
the number of bytes in value Not used, always NULL Not used, always 0.
Specifies the current base directory, i.e. the parent of the file in
value Specifies the number of bytes in dir Not used, always NULL Not
used, always 0
Translations
XmFileSelectionBox inherits translations from XmSelectionBox.
Accelerators
The XmNtextAccelerators from XmSelectionBox are added to the selection
Text descendant of XmFileSelectionBox.
Additional Behavior
The FileSelectionBox widget has the additional behavior described
below: Calls the activate callbacks for the cancel button if it is sen‐
sitive. If no cancel button exists and the parent of the FileSelec‐
tionBox is a manager, passes the event to the parent. Calls the selec‐
tion 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. Oth‐
erwise, calls the XmNokCallback callbacks with reason XmCR_OK. Calls
the file list widget's XmNdefaultActionCallback callbacks. Calls the
XmNokCallback callbacks with reason XmCR_OK. Replaces the selection
text with the selected list item. 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. 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. Oth‐
erwise, calls the XmNokCallback callbacks with reason XmCR_OK.
Calls the XmNcancelCallback callbacks with reason XmCR_CANCEL. Calls
the XmNhelpCallback callbacks with reason XmCR_HELP. 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. Oth‐
erwise, 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 INFORMATIONComposite(3X), Constraint(3X), Core(3X), XmBulletinBoard(3X), SgCreate‐
FileSelectionBox(3X), SgCreateFileSelectionDialog(3X), SgFileSelection‐
BoxGetChild(3X), XmManager(3X), and XmSelectionBox(3X).
SgFileSelectionBox(3X)
