dirbrowser3 - Motif-style select file from directory


dirbrowser3 pathName ?options?



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.
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 *
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.
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.


-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)).


  • Tcl7.4+, Tk4.0+
  • parseargs, with_grab_focus (ie. dkflib.tcl)


  • 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).


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).
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.


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:

Accepts the value specified in the lower entry (activated by pressing Return in that entry, or by Double-Clicking in the righthand listbox).
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).
Cancels the file selection action, returning an empty string (optionally generating an exception, see the -cancelexception option).
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.


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:
  1. 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.
  2. 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.
  3. The key Escape is equivalent to pressing the Cancel button.
  4. The keys Help and F1 are equivalent to pressing the Help button.
  5. A Button 1 Release in the righthand (file) listbox causes the file selected there to become the file currently in the lower entry.
  6. 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 ..
  7. 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.
  8. 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.
  9. 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.
Accepts all changes made to the directory hotlist.
Rejects all changes made to the directory hotlist.
Brings up a dialog box with help on the directory hotlist editor.


The following bindings extend the editor beyond the Tk defaults:
  1. The key u invokes the Move Item Up button.
  2. The key d invokes the Move Item Down button.
  3. The keys i and Insert invoke the Insert Directory button.
  4. The key m invokes the Modify Entry button.
  5. The keys Backspace and Delete invoke the Delete Entry button.
  6. The key Return invokes the O.K. button.
  7. The key Escape invokes the Cancel button.
  8. The keys Help and F1 invoke the Help button.

Global Variables

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:

Window path of the buttons area within the browser.
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).
Window path of the directory list within the browser.
Internal to the directory list editor.
Internal to the directory list editor.
Number of extra buttons added to the browser.
Actual current filename (contents of filename entry).
Window path of file list within the browser.
Window path of file entry within the browser.
Expression to evaluate at a global level to determine whether a file is to be inserted in the file list.
Counter to help determine which side of the browser the mouse pointer is in.
Window path of filter entry within the browser.
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.
Flag to say whether hidden directories (starting with . on UNIX systems) should be included in the directory list.
Flag to say whether hidden files (starting with . on UNIX systems) should be included in the file list.
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.
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...
Window path of the toplevel of the browser.
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.
Flag that states whether to use send to communicate with the separate process whose invokation is controlled by the usecd flag.
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


Used to clean up. DO NOT CALL. EXIT THE APP USING `exit', NOT `destroy .'
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

Like cd, but doesn't change the current process's idea of the CWD.
Performs globs (possibly in a separate process). Will be extended to handle better globbing on non-Unix systems at some point.
Initialises the directory subsystem (with initial dir).
Companion pwd for dirbrowser_chdir.

Hot Directory List Management

Handle menu for hot directories.
Allows the user to edit their directory list.
Auxiliary functions for above.

Highlighting (Pseudo- `Focus Follows Mouse')

Action on entering the filter part of the dialog box.
Handles all changes in highlighting.
Action on leaving the filter part of the dialog box.

User Action Handlers

Double-click on directory / Return in filter box.
Bring up a help dialog.
Performs filename completion.
Handles drops of FILENAME items into the main browser.

Extended Globbing Facilities

Gets a (sorted) list of subdirectories of the specified directory (taking account of the -showhidden option).
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

Clears the selection from the two listboxes (whenever the pointer changes focus zone).
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.
Recalculates the appropriate contents of the filename entry whenever a key is pressed in it and the selection is active in the directory listbox.


To Do


browse, dialog, directory, file, select

See Also

entry(n), file(n), glob(n), listbox(n), toplevel(n).


Donal K. Fellows, University of Manchester, U.K.