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.

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

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

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

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.

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

See Also

Author