FileNominator(3n) FileNominator(3n)
NAME
FileNominator - A file selector widget
DESCRIPTION
Application header file <FileNominator.h>
Class header file <FileNominatorP.h>
Class fileNominatorWidgetClass
Class Name FileNominator
Superclass Core The FileNominator widget is a directory
browser and file selector. It consists of a scrollable list (List
widget [instance name = list] inside a Viewlist [R5] or Viewport [R4]
widget [viewport]) of directory entries, a button (Command widget)
[Filter:], two one-line input areas (ScrollingText widget [filter],
and ScrollingText widget [filename]), and three buttons: a Command
button [select] for selecting the nominated file or directory, a
MenuButton button [path] whose defualt menu contains the elements of
the path of the directory whose contents are displayed in the List
widget and a Command button [cancel] for cancelling use of the widget.
The user may nominate a file by choosing from the list using mouse
button 1 (causing the name to be entered into the filename input
area), or by typing into the input area, or by doing both. All
keyboard input is directed to the filename widget when the
FileNominator has the input focus, unless the pointer is in the filter
widget, in which case it receives the input. The content of the input
area is assumed to be relative to the directory currently displayed if
not an absolute pathname. The selection is always taken from the
nomination in the input area, and happens when the select button is
clicked (button 1) or the Return key is pressed. If no modification is
to be made then a choice from the List widget can be selected by
double clicking mouse button 1 or by single clicking mouse button 2.
Further, an immediate selection of some other directory in the path of
the displayed directory can be made by selecting from the "path"
button menu. A '~' as the first character in the input area is
understood to mean the user's home directory. If a nomination begins
with a '$' then the first component will be treated as a possible
reference to an environment variable, with the expansion being made if
a variable of that name exists. In addition the user may define (see
pathList under RESOURCES below) a list of potential nominations -
either files or directories - to be added to the "path" button menu.
Since selecting an entry from the menu is equivalent to entering the
entry in the input area and selecting it in the normal way, i.e it is
subject to the checks that would be applied if the user had typed the
value as a nomination, then '~' and '$' may feature in the user-added
entries. When the selection is a directory the contents of the
directory are filtered according to the pattern in the filter input
area, so that a reduced subset of interest may be displayed. A new
filter can be run on the current directory by hitting Return in the
Filter input area or by clicking the Filter: button.
RESOURCES
When creating a FileNominator widget instance, the following
- 1 - Formatted: June 9, 2026
FileNominator(3n) FileNominator(3n)
additional resources (to those of Core) are retrieved from the
argument list or from the resource database: tab(/) ; lB lB lB lB.
NAME/CLASS/TYPE/DEFAULT VALUE lB l l l. bellLevel/bellLevel/int/100
cancelCallback/Callback/XtCallbackList/NULL
initialDirectory/InitialDirectory/String/NULL filter/Filter/String/*
margin/Margin/Dimension/10 numberRows/NumberStrings/int/12
selectCallback/Callback/XtCallbackList/NULL
showDotFiles/ShowDotFiles/Boolean/True pathList/PathList/String/NULL
userData/UserData/XtPointer/NULL
bellLevel How loud the keyboard bell should be rung. The value is
passed unchanged to XBell.
cancelCallback All functions on this list are called whenever the
cancel buttons's notify action is invoked.
initialDirectory
The initial directory whose contents are to be
displayed. The default, or if the supplied value is
invalid, is the current working directory.
filter An initial filter pattern to be applied to the contents
of initialDirectory. The default is "*", i.e. all
filenames are displayed.
margin The default distance between component widgets and
between the edges of the widget and components.
numberRows The number of rows of the List widget to display.
selectCallback All functions on this list are called whenever the
select buttons's notify action is invoked.
showDotFiles This value of this boolean resource determines whether
the names of "." files are shown. The default is True.
"." and ".." are always shown.
pathList The value of this resource is a colon separated list of
pathnames that are converted into menu entries and
added to the path button menu.
userData This resource is provided for the programmar to use as
they see fit.
ACTIONS
The FileNominator widget supports the following actions:
o Processing file or directory nominations in the List widget with
Nominate.
- 2 - Formatted: June 9, 2026
FileNominator(3n) FileNominator(3n)
o Constructing a menu of path elements for the MenuButton widget.
o Toggling the display of "." files. The following default
translation tables are defined by the FileNominator Widget on its
component widgets: List widget default translation table
lB.
<Btn1Up>(2): Set() Nominate() Unset()
<Btn1Down>,<Btn1Up>: Set() Notify()
<Btn2Up>: Set() Notify() Nominate() Unset() Filter widget
default translation table
<Key>Return: Filter() Filename widget default translation
table
<Key>Return: Nominate() Select button default translation
table
lB.
<Btn1Up>: Nominate() unset() MenuButton default translation
table
lB.
<BtnDown>: reset() MakeMenu() XawPositionSimpleMenu(menu)
MenuPopup(menu)
The full list of actions supported by FileNominator widget is:
Nominate() nominates the text in the text widget as the user's
choice. If the nomination is a directory then the
contents of the List widget will change. If the
nomination is a file - which need not exist - then
callbacks on the selectCallback list will be called.
MakeMenu() makes a SimpleMenu consisting of the path elements of
the pathname of the current directory.
ToggleDotFiles()
toggles the value of the showDotFiles resource and
causes the currently displayed directory to be
rescanned with the new value effective. This action is
bound to the Escape key by default.
CALLBACKS
All procedures on the FileNominator widget's selectCallback list will
have a FileNominatorStruct passed to them as call_data. The structure
is defined in the FileNominator widget's application header file.
typedef struct {
String directoryPart;
int directoryStatus;
String filenamePart;
- 3 - Formatted: June 9, 2026
FileNominator(3n) FileNominator(3n)
int filenameStatus;
} FileNominatorStruct; The concatenation of directoryPart and
filenamePart yield the pathname of the nominated file. directoryStatus
and filenameStatus provide information about the access that the user
has to the separate parts. Their values are the symbolic constant
FileNominatorNonexistent or logical OR combinations of
FileNominatorReadable, FileNominatorWritable and
FileNominatorExecutable. Note that the data pointed to by the String
fields are owned by the FileNominator and should NOT be freed by the
callback routines.
CONVENIENCE ROUTINES
To change the directory that is displayed, use void
FileNominatorSetDirectory(w, dir)
Widget w;
String * dir;
w Specifies the FileNominator widget.
dir Specifies the new directory for the FileNominator widget to
display. To get the name of the directory that is
displayed, use String FileNominatorGetDirectory()
FileNominatorGetDirectory returns the current directory of
the FileNominator widget.
- 4 - Formatted: June 9, 2026
