dirbrowser2 - Motif-style select file from directory

Synopsis

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

Description

The dirbrowser2 command creates a new top-level window (given by the pathName argument, or a child of that if it exists) 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.

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 default Tk bindings for the constituent widgets are augmented by the following bindings:
  1. The browser is broadly focus-follows-mouse, with the main default focus targets being the two entries and the Cancel and Help buttons.
  2. 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.
  3. 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.
  4. The key Escape is equivalent to pressing the Cancel button.
  5. The keys Help and F1 are equivalent to pressing the Help button.
  6. A Button 1 Release in the righthand (file) listbox causes the file selected there to become the file currently in the lower entry.
  7. 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 ..
  8. 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.
  9. 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.
  10. 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:
  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

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

Directory Management

dirbrowser_chdir
Like cd, but doesn't change the current process's idea of the CWD.
dirbrowser_enddir
Shuts down directory subsystem (null-op currently).
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.
dirbrowser_resetFilter
In case things get confused (as can happen).

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.

Extended Globbing Facilities

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

Requires

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

Bugs

To Do


Keywords

browse, dialog, directory, file, select

See Also

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


Author

Donal K. Fellows:fellowsd@cs.man.ac.uk