Name dirbrowser3 -
Motif-style select file from directory
Synopsis
dirbrowser3 pathName ?options?
Options
Basic
- -cancelexception
-
Generates an exception when the cancel button is pressed, instead of
returning an empty string.
-
-defaultfile fileName
-
Sets the default file selected. If a path to the file is given, this
overrides the value in the
-directory
option.
-
-directory directoryName
-
Sets the initial directory that the browser starts in. Defaults to
.
and is overridden by the path specified as part of the
-defaultfile
if a path is given there.
-
-showhidden
-
Tells the file name matching engine to include files starting with a
"." in it's search. Normally these are excluded.
-
-filemask pattern
-
Gives a pattern of files to match. Defaults to
*
-
-globalgrab
-
Tells the browser to use a global grab as opposed to a local grab.
-
-message text
-
Gives a string to be displayed to the user at the top of the window.
-
-usecd
-
Tells the directory processor to use cd (in a sub-process) to perform
filename resolution for all directory names, and not just that of the
starting directory.
Advanced-
-aftersetuphook command
-
Gives a command to be run after all the widgets and their bindings
within the browser have been created. This command will have the
pathname of the toplevel of the browser appended. This is the only way
to change the default bindings of the browser.
-
-extendwidget command
-
Gives a commmand to be run immediately after the creation of the
toplevel widget, but before any operations have been performed on
it. The command will have the pathname of the toplevel of the browser
appended. This is the best way to add a new sub-panel to the top of
the browser, and if used, it is recommended that the
-message
option is not used.
-
-extrabuttons list
-
Specifies a list of buttons to be added between the Cancel and the
Help buttons. Each element specifies one button and consists of a
sublist; the first element of which is the textual label on the
button, and the second element of which is the button command.
-
-filetest expression
-
The expression is evaluated at the toplevel by the directory search
engine for every file found in order to determine if that file is
suitable for adding to the list of files to select. Directory names
are not verified using this mechanism. The name of the file being
considered is available in the (global) variable
dirbrowser_filename.
The expression defaults to
1
(true).
-
-hotpaths varName
-
If this option ispresent, by holding down Mouse Button 3, a menu of
`hot' directories should be popped up. Choosing one of the directories
from the menu will result in the browser moving into that directory.
Also available on the menu is an option to allow the user to add the
current directory to the end of the menu, and another option to allow
the user to edit the contents of the menu. The first directory on the
menu is always the user's home directory (as specified in
env(HOME)).
|
Requires
- Tcl7.4+, Tk4.0+
- parseargs, with_grab_focus (ie. dkflib.tcl)
Supports
- Tcl7.5+ and Tk4.1+ (I think, but I haven't tested it yet)
- Drag-n-Drop (accepts data of type
FILENAME and the directory hotlist editor can generate
data of types FILENAME and STRING though
this code is probably experimental still. Only supported if you have
dragdrop.tcl and dragdrop_ifc.tcl on your
auto_path (strictly, only if the commands they contain
can be autoloaded and run).
Files
The division of procedures between files is fairly arbitrary, but it
does separate out at least one significant portion of code which is
not required immediately (the hotlist code).
File | Description
| dirbrowser3.tcl | The
browser itself and commands it uses immediately.
| dirbrowser_directory.tcl | Directory management and globbing routines.
| dirbrowser_hotlist.tcl | Directory hotlist management code.
| |
|
Description
The dirbrowser2 command creates a new toplevel window (given by
the pathName argument) and makes it into a directory
browser. The additional options, described above, may only be
specified on the command line, and they configure aspects of the
directory browser such as its starting directory and search
pattern. When the user selects a file, the full pathname of that file
is returned by this command. Should the user cancel the operation,
then an empty string will be returned instead, unless the
-cancelexception option is given to the command, in which case
an exception condition will be generated (currently the exception code
used is 64).
The directory browser offers the user two listboxes and two entries,
the top/left entry/listbox allowing the user to change directory and
the file search pattern, and the bottom/right entry/listbox allowing
the user to specify which file they want to select. It makes no
(lasting) changes to the current process's current work
directory. Pressing the Tab key while in the bottom entry
(filename entry) will invoke filename completion if what is already
present uniquely determines at least the next character, otherwise
performing the standard Tab-traversal behaviour.
At the bottom of the window created are several buttons:
- O.K.
Accepts the value specified in the lower entry (activated by
pressing Return in that entry, or by Double-Clicking in the
righthand listbox).
| - Filter
Rescans using the filename and directory specified in the upper
entry (activated by pressing Return in that entry or by
Double-Clicking in the lefthand listbox).
| - Cancel
Cancels the file selection action, returning an empty string
(optionally generating an exception, see the -cancelexception
option).
| - Help
Brings up a window giving help on directory browser.
| | | | |
Optionally (see the
-hotpaths
option) the user may hold down Mouse Button 3 to get a menu of
user-specified `hot' paths, selecting one of which causes the browser
to change directory to the one specified and scan for files matching
the current mask. Also on this menu are:
- Add Current Directory
- Adds the current directory to the end of the menu. Disabled if the
current directory is already present on the menu.
- Edit Directory Hotlist
- Brings up a dialog box which allows the user to edit their
hotlist. This is described below.
- Home Directory
- This entry is always present, and allows the user to change into
their home directory (as determined by the variable
env(HOME)).
The labels of all the other entries on the hotlist are the last
pathname component of the directory they represent.
Bindings
The browser is broadly focus-follows-mouse, with the main default
focus targets being the two entries and the Cancel and Help
buttons. The selection highlight in the listboxes may be
manipulated by using the Up and Down keys, and the
entries will be updated accordingly. The default Tk bindings for the
constituent widgets are augmented by the following bindings:
- The key Return, when pressed in the upper (filter) entry,
causes the browser to read the new directory and filter from the
entry and use them to rebuild the data in the listboxes and the
lower (file) entry, as if the Filter button was pressed.
- The key Return, when pressed in the lower (file) entry,
causes the browser to return the value specified in that entry, as
if the O.K. button was pressed. This destroys the directory
browser.
- The key Escape is equivalent to pressing the Cancel
button.
- The keys Help and F1 are equivalent to pressing the
Help button.
- A Button 1 Release in the righthand (file) listbox causes the
file selected there to become the file currently in the lower entry.
- A Double Button 1 in the lefthand (directory) listbox
causes that directory to become the current directory. The
``<< Parent >>'' entry is equivalent in this
respect to ..
- A Double Button 1 in the righthand (file) listbox causes the file
selected there to be returned as the result of the directory browser
operation, similar to if the O.K. button had been pressed.
- A Button 3 Press causes the `hot' directory menu to pop up, if
this has been enabled using the -hotpaths option. By default,
this is not enabled.
- The key Tab, when pressed in the filename (bottommost)
entry, invokes filename completion, and traverses the window only if
no (further) completion is currently possible.
Directory Hotlist Editor
The directory list editor consists of a listbox containing the current
directory hotlist, and a collection of buttons on the right of it
which allow operations to be carried out on the hotlist. There are no
programmer configurable portions to the hotlist editor.
Button Actions
- Move Item Up
Moves the currently selected item up one place in the hotlist
(provided it is not the topmost entry).
| - Move Item Down
Moves the currently selected item down one place in the hotlist
(provided it is not the bottommost entry).
| - Insert Directory
Inserts a new entry (bringing up a dialog box to allow the user to
enter it's value) in the hotlist after the current entry.
| - Modify Entry
Brings up a dialog box which allows the user to modify the value of
the currently selected entry.
| - Delete Entry
Deletes the current entry from the hotlist.
| - O.K.
Accepts all changes made to the directory hotlist.
| - Cancel
Rejects all changes made to the directory hotlist.
| - Help
Brings up a dialog box with help on the directory hotlist editor.
| | | | | | | | |
Bindings
The following bindings extend the editor beyond the Tk defaults:
- The key u invokes the Move Item Up button.
- The key d invokes the Move Item Down button.
- The keys i and Insert invoke the Insert
Directory button.
- The key m invokes the Modify Entry button.
- The keys Backspace and Delete invoke the Delete
Entry button.
- The key Return invokes the O.K. button.
- The key Escape invokes the Cancel button.
- The keys Help and F1 invoke the Help
button.
Global Variables
- dirbrowser
- Array containing all private state to the directory browser. Only
the filterbody and filebody elements (the contents of
the upper and lower entries respectively) are likely to be of much
use to anyone tampering with this code. After setting these either
of these variables, it is advised that the programmer call
dirbrowser_filterCommand with no arguments to force a rescan
using the updated values.
For reference, the variables within this array that are currently in
use are:
- buttons
- Window path of the buttons area within the browser.
- cwd
- Current work directory (or at least very closely related to it)
used when not using a separate process to manage the CWD (as
controlled by the usecd flag below).
- dirlist
- Window path of the directory list within the browser.
- dirlist*
- Internal to the directory list editor.
- edit*
- Internal to the directory list editor.
- extrabut
- Number of extra buttons added to the browser.
- filebody
- Actual current filename (contents of filename entry).
- filelist
- Window path of file list within the browser.
- fileref
- Window path of file entry within the browser.
- filetest
- Expression to evaluate at a global level to determine whether a
file is to be inserted in the file list.
- filtcnt
- Counter to help determine which side of the browser the mouse
pointer is in.
- filter
- Window path of filter entry within the browser.
- filterbody
- Contents of filter entry (current filter). Changes to this
variable must be followed by a call to dirbrowser_filterCommand
to force a rescan of the filesystem for matching files and
directories.
- hiddendirs
- Flag to say whether hidden directories (starting with . on UNIX
systems) should be included in the directory list.
- hiddenfiles
- Flag to say whether hidden files (starting with . on UNIX
systems) should be included in the file list.
- proc
- Name of stream for communication with subsidiary process (only
used when the -usecd option has been given to the browser
at some time during the history of the program.
- sendid
- Name of application at other end of proc so that the more
efficient communication offerend by the send command (from
this programmer's point of view at least) can be utilised. This
variable is not set if this commmunication has been disabled due
to a lack of security or the use of the
rename send {} command. Changing from allowing
sends to forbidding them after a use of the -usecd option
to the browser is a bad idea, and should not be done...
- toplevel
- Window path of the toplevel of the browser.
- usecd
- Flag that states whether to use a separate process to maintain
an idea of the current directory (this makes behaviour of the
browser closely model that of most other directory browsers.
- usesend
- Flag that states whether to use send to communicate with the
separate process whose invokation is controlled by the usecd
flag.
- dirbrowser_filename
- Variable containing the name of the file currently being
considered in the file test (see -filetest option). Never
read by the filename globbing mechanism, so modifying is pointless
(and the precise effects are undefined).
Private Procedures
Internal
- __dirbrowser_exit
- Used to clean up. DO NOT CALL. EXIT THE APP USING `exit', NOT
`destroy .'
- dirbrowser_init
- Used to perform initialisations without cluttering up the variable
space. Run automatically when loading the main source file, and
deletes itself (and doesn't occur in the tclIndex file), so
it is not user-runnable.
-
Directory Management
dirbrowser_chdir
- Like cd, but doesn't change the current process's idea of the
CWD.
- dirbrowser_glob
- Performs globs (possibly in a separate process). Will be extended
to handle better globbing on non-Unix systems at some point.
- dirbrowser_initdir
- Initialises the directory subsystem (with initial dir).
- dirbrowser_pwd
- Companion pwd for dirbrowser_chdir.
-
Hot Directory List Management
dirbrowser_do_menu
- Handle menu for hot directories.
- dirbrowser_edit_dirlist
- Allows the user to edit their directory list.
- dirbrowser_edit_*
- Auxiliary functions for above.
-
Highlighting (Pseudo- `Focus Follows
Mouse')
dirbrowser_enterFilter
- Action on entering the filter part of the dialog box.
- dirbrowser_hl
- Handles all changes in highlighting.
- dirbrowser_leaveFilter
- Action on leaving the filter part of the dialog box.
-
User Action Handlers
dirbrowser_filterCommand
- Double-click on directory / Return in filter box.
- dirbrowser_helpCommand
- Bring up a help dialog.
- dirbrowser_complete
- Performs filename completion.
- dirbrowser_dropFn
- Handles drops of
FILENAME
items into the main
browser.
-
Extended Globbing Facilities
dirbrowser_getdirlist
- Gets a (sorted) list of subdirectories of the specified directory
(taking account of the -showhidden option).
- dirbrowser_getfilelist
- Gets a (sorted) list of files in the specified directory matching
the specified mask and satisfying the conditional expression
supplied with the -filetest option. Takes account of the
-showhidden option.
-
Keyboard Navigation Utilities
dirbrowser_clearsel
- Clears the selection from the two listboxes (whenever the pointer
changes focus zone).
- dirbrowser_dirkey
- Recalculates the appropriate contents of the directory/filter
entry whenver a key is pressed in it and the selection is active in
the directory listbox.
- dirbrowser_filekey
- Recalculates the appropriate contents of the filename entry
whenever a key is pressed in it and the selection is active in the
directory listbox.
Bugs
- I'm not happy with the grabbing and focussing mechanisms.
- Doesn't currently support the options database as a way to
specify options. I suppose this should go on the todo list...
- The filename completion conflicts with the keyboard traversal,
and doesn't work all well anyway.
- It messes up badly with Tcl7.5/Tk4.1 under Windows due to the
existance of several roots to the directory tree, though this might
be fixed now (I can't test it there myself). It doesn't handle a
``//'' specified root either, so don't use that form...
- If this works on the Mac, I'll be both surprised and pleased...
- The browser doesn't position itself properly on the screen with
respect to its parent sometimes. I've no idea what causes this,
since I can't get the bug to replicate itself reliably, but my
window manager is probably at fault here.
- The browser can't be embedded in another window.
- There is at least one bug in this page.
To Do
- Fix (some of) the bugs.
- Making the online help into hypertext would be nice.
- Add drag-n-drop support.
Keywords
browse, dialog, directory, file, select
See Also
entry(n),
file(n),
glob(n),
listbox(n),
toplevel(n).
Author
Donal K. Fellows, University of Manchester,
U.K.
donal.k.fellows@man.ac.uk