jfs.tcl
The
jfs.tcl library is distributed as part of the
jstools package. It creates a generalpurpose modal fileselection
panel that allows the user to select a file (or directory) and
returns its full pathname.
This document describes
jfs.tcl version 1998.09.30.
Accessing the Library
In order to use the
jfs.tcl library, it (and any other libraries it depends on) must be
in your Tcl
auto_path, described in
tclvars(n). Information about how to arrange that, and other conventions
common to
the
jstools libraries, is in
the
Usage section of
The jstools Libraries.
Author
Jay Sekora
js@aq.org
http://www.aq.org/~js/
Copyright
The library is copyright © 1992-1998 by Jay Sekora, but may be
freely redistributed under the conditions at the top of the file.
Procedures
j:fs - file selection panel
j:fs:fill_list - fill
j:fs listbox with files from current directory
Usage
j:fs
[options]
Options
-buttons
buttonlist
(default
{ok cancel mkdir home})
-prompt
prompt
(localisable, default
Choose a file)
-directory
dir
(default
.)
-cancelvalue
cancelvalue
(default
{})
-fileprompt
fileprompt
(localisable, default
File:)
-title
title
(localisable, default
File Selector)
-types
typelist
(default
{})
-typevariable
typevar
(default
{})
-typeprompt
typeprompt
(localisable, default
File type:)
-filehistory
filehistory
(default
fs_files)
Examples
set filename [j:fs -prompt "Save as:"]
set dirname [j:fs -buttons {here cancel home root} \
-prompt "Change directory to..."]
set outfile [j:fs -prompt "Save as:" \
-types {sc oleo "Tab-separated values" "LaTeX table"} \
-typevariable format -typeprompt "Spreadsheet format:"]
set settings [j:fs -prompt "Save settings to:" \
-dir $env(HOME)/settings \
-filehistory settings
Description
This procedure creates a fileselection box with a configurable
set of buttons, a label containing
prompt at the top, a listbox showing the files in the current directory,
and an entry labelled
fileprompt at the bottom that lets the user type in a file name. The
user can select an existing file either with the mouse or from
the keyboard, and the entry supports filename completion with
the
Tab key. (A new file name, of course, has to be typed in.)
The windowmanager name of the panel will be
title.
The file selection panel has a number of predefined buttons,
and you can choose which ones appear using the
-buttons option. The first button in
buttonlist will be the default button, and pressing
Return in the entry widget or doubleclicking in the listbox will
do the same thing as clicking on this button (unless the current
file name is a directory, in which case it will switch to that
directory). If the
-buttons option is not specified, the
ok,
cancel,
mkdir, and
home buttons will be displayed (and
ok will be the default button).
The available buttons and their functions are:
-
ok - Return the current filename if it is a file;
cd to it if it's a directory. This is the typical way to select
a filename
-
gointo -
cd to the current filename, if it's a directory. This is useful
when here is the default button.
-
home -
cd to the user's home directory.
-
root -
cd to the root directory.
-
here - Return the name of the current working directory. This
can be used, for instance, to choose where to move a file to.
-
mkdir - Ask for the name of a directory to create, create it, and
cd into it. Useful when the user is saving a file and wants
to create a new subdirectory to save it in.
-
cancel - Return
cancelvalue.
Unless
filehistory is the null string,
filehistory will be used as the name of a history list (see
jhistory.tcl) associated with the filename entry widget at the bottom of the
panel. Two buttons with arrows will be displayed next to the
entry field. Clicking the uparrow button or pressing the up
arrow on the keyboard will go up (back) in the history list.
Clicking the downarrow button or pressing the down arrow on the
keyboard will go down (forwards) in the history list. The currentlydisplayed
value will be added to the history list whenever a noncancelvalue value is returned (e.g. when the user clicks the OK button).
This makes it easy for the user to access frequentlyused files.
If
-types and
-typevariable are specified, an option button, labelled
typeprompt, will be displayed that lets the user choose among the file types
in
typelist. The
j:fs procedure will set the variable
typevar in the caller's scope to the element of
typelist that the user selected. This is intended to let the user
select a file format for saving, although it could conceivably
be put to other uses.
Unless the global variable
J_PREFS(j_fs_fast) is true, directory names in the listbox will have a trailing
slash (/). The user can set this with a small checkbox at the upperright
of the fileselection panel (as well as from
the Global Preferences panel created by
j:global_pref_panel, in
jprefpanel.tcl).
Keyboard shortcuts for the Cancel button are set up using
j:cancel_button in
jtkutils.tcl, even if it doesn't appear in
buttonlist. This means that the user can always cancel (returning
cancelvalue) by typing (e.g.)
Control-c, even if you didn't include
cancel in
buttonlist.
Note that while
j:fs may change the working directory while it's active (i.e., when
the user goes into a directory,
j:fs
cds into that directory to display its contents), it restores the
original working directory before it returns. Since
j:fs is modal, this means that you don't have to worry about your
application changing directory unless you explicitly do a
cd yourself. (This behaviour is different from that of previous
versions.)
Usage
j:fs:fill_list
listbox
Argument
listbox is the listbox widget to fill
Description
This procedure fills a listbox with a list of the files in the
current directory. The parent directory (`..') is first, followed by all filenames which don't start with
a period, followed by those files that do start with a period.
The current directory `.' does not appear. Other than that,
files are listed in ASCII collating order.
Any directory names will be followed by slashes (`/'), unless the global variable
J_PREFS(j_fs_fast) is true.
This procedure is for use by
j:fs. You may find it useful for other applications, but don't
rely on it too much.
Bugs and Limitations
- The value given by
[pwd] isn't always the most appropriate way to refer to a directory,
for instance if the automounter is being used.
- It's nonorthogonal that
j:fs returns the filename as the procedure's return value, but returns
the file type in a variable as a sideeffect. I can't think
of a better way to do it, though, since I want the common case
(not specifying a list of file types) to be as terse and intuitive
as possible.
Future Directions
- More buttons should be available for
j:fs - one that springs to mind is a `preview' button. Also,
there should be a way for the calling procedure to add arbitrary
buttons to the
j:fs panel.