SgFileSelectionBox(3X) UNIX System V SgFileSelectionBox(3X)
NAME
SgFileSelectionBox - 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 underneath 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
Page 1 (printed 4/30/98)
SgFileSelectionBox(3X) UNIX System V SgFileSelectionBox(3X)
are at the same level as the directory underneath the button
in the text field. Choosing 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 directory 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 matching 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 XmNpattern, and the user presses
Cancel in the Filter dialog, the XmNpattern is set to "*".
Page 2 (printed 4/30/98)
SgFileSelectionBox(3X) UNIX System V SgFileSelectionBox(3X)
The user may select a new file as many times as desired.
The application 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 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
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
Page 3 (printed 4/30/98)
SgFileSelectionBox(3X) UNIX System V SgFileSelectionBox(3X)
__________________________________________________________________________________________
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
SgNbrowserFileMask
Specifies the type of files listed in the zoom bar
browser menus. Following are the possible values:
⊕ XmFILEREGULAR restricts the browser menu to
contain only regular files.
⊕ XmFILEDIRECTORY restricts the browser menu
to contain only directories.
⊕ SgFILENOTHIDDEN restricts the browser menu
to contain only non-hidden files.
⊕ XmFILEANYTYPE allows the browser menu to
contain all file types including directories.
SgNcompletionDelay
Specifies the amount of time in miliseconds to
wait after the last character is entered in the
text field before attempting to automatically
invoke the completion function. If this resource
is set to zero, auto-completion is disabled.
SgNuseEnhancedFSB
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.
SgNviewerMode
Specifies the policy for showing and updating the
multi-media file viewer. Following are the
possible values:
⊕ SgVIEWERNEVER entirely disables the use of
the viewer.
Page 4 (printed 4/30/98)
SgFileSelectionBox(3X) UNIX System V SgFileSelectionBox(3X)
⊕ SgVIEWERNONE 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.
⊕ SgVIEWERAUTOMATIC enables and manages the
viewer. The viewer will automatically be
updated as the filename in the finder
changes.
⊕ SgVIEWEREXPLICIT enables and manages the
viewer. The viewer will always display file
indicated by the SgNviewerFileName resource.
SgNviewerFileName
Specifies the name of the file to be display in
the viewer when SgNviewerMode is set to
SgVIEWER_EXPLICIT.
SgNviewerFilter
Specifies the list of file types to be displayed
in the viewer when SgNviewerMode is set to
SgVIEWER_AUTOMATIC.
SgNviewerUpdateDelay
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
XmNdirectory
Specifies the base directory used in determining
the files and directories 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
Page 5 (printed 4/30/98)
SgFileSelectionBox(3X) UNIX System V SgFileSelectionBox(3X)
resource.
XmNdirSpec
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.
XmNfileListItems
Specifies the items in the file list. This is the
XmNlistItems resource in SelectionBox, renamed for
FileSelectionBox. XtGetValues for this resource
returns the list items themselves, not a copy of
the list items. The application must not free the
returned items.
XmNfileListItemCount
Specifies the number of items in the file list.
This is the XmNlistItemCount resource in
SelectionBox, renamed for FileSelectionBox. The
value must not be negative.
XmNfileListLabelString
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".
XmNfilterLabelString
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".
XmNnoMatchString
Specifies a string to be displayed in the file
list if the list of files is empty.
XmNpattern
Specifies a string used as a regular expression in
determining the files to be displayed. 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.
Page 6 (printed 4/30/98)
SgFileSelectionBox(3X) UNIX System V SgFileSelectionBox(3X)
Compatibility Resources
The following table shows resources for the enhanced
XmFileSelectionBox widget which are provided for
compatibility with the XmFileSelectionBox. 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 XmFileSelectionBox(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 XmDIALOGFILESELECTION.
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
Page 7 (printed 4/30/98)
SgFileSelectionBox(3X) UNIX System V SgFileSelectionBox(3X)
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
Page 8 (printed 4/30/98)
SgFileSelectionBox(3X) UNIX System V SgFileSelectionBox(3X)
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 following 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;
reason Indicates why the callback was invoked
Page 9 (printed 4/30/98)
SgFileSelectionBox(3X) UNIX System V SgFileSelectionBox(3X)
event Points to the XEvent that triggered the callback
value Specifies the full pathname of the selected file
length Specifies the number of bytes in value
mask Not used, always NULL
mask_length
Not used, always 0.
dir Specifies the current base directory, i.e. the
parent of the file in value
dir_length
Specifies the number of bytes in dir
pattern Not used, always NULL
pattern_length
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:
MAny KCancel:
Calls the activate callbacks for the cancel button
if it is sensitive. If no cancel button exists
and the parent of the FileSelectionBox is a
manager, passes the event to the parent.
<KActivate> in Selection Text:
Calls the selection 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 XmCRNOMATCH. Otherwise,
calls the XmNokCallback callbacks with reason
XmCROK.
Page 10 (printed 4/30/98)
SgFileSelectionBox(3X) UNIX System V SgFileSelectionBox(3X)
<DoubleClick> or <KActivate> in File List:
Calls the file list widget's
XmNdefaultActionCallback callbacks. Calls the
XmNokCallback callbacks with reason XmCROK.
<Single Select> or <Browse Select> in File List:
Replaces the selection text with the selected list
item.
<BDrag> in File List:
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.
<OK Button Activated>:
If XmNmustMatch is True and the selection text
does not match an item in the file list, calls the
XmNnoMatchCallback callbacks with reason
XmCRNOMATCH. Otherwise, calls the XmNokCallback
callbacks with reason XmCROK.
<Cancel Button Activated>:
Calls the XmNcancelCallback callbacks with reason
XmCRCANCEL.
<Help Button Activated>:
Calls the XmNhelpCallback callbacks with reason
XmCRHELP.
<KActivate>:
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 XmCRNOMATCH. Otherwise, calls the
XmNokCallback callbacks with reason XmCROK.
Virtual Bindings
The bindings for virtual keys are vendor specific. For
information about bindings for virtual buttons and keys, see
VirtualBindings(3X).
RELATED INFORMATION
Page 11 (printed 4/30/98)
SgFileSelectionBox(3X) UNIX System V SgFileSelectionBox(3X)
Composite(3X), Constraint(3X), Core(3X),
XmBulletinBoard(3X), SgCreateFileSelectionBox(3X),
SgCreateFileSelectionDialog(3X),
SgFileSelectionBoxGetChild(3X), XmManager(3X), and
XmSelectionBox(3X).
Page 12 (printed 4/30/98)