  TkDesk User's Guide
  Christian Bolik, zzhibol@rrzn-user.uni-hannover.de
  Version 1.0a1, 31 March 1996

  TkDesk is a graphical, highly configurable and powerful file manager
  for Unix and the X Window System.  This document is meant to be a com-
  prehensive guide to the vast number of functions and features of
  TkDesk, but so far I've only found time to describe the most essential
  functions and key respectively mouse bindings. This guide will hope-
  fully grow with each upcoming release of TkDesk.

  If you would like to print this manual, there is a Postscript version
  available in the doc subdirectory when unpacking the TkDesk package.
  It's called guide.ps.

  Sorry, this guide has not yet been updated to version 1.0a2. Please
  have a look at the ``@file CHANGES'' for recent modifications and new
  features (by simply clicking on the green letters).
  
  ______________________________________________________________________
  

  1.  Introduction

  TkDesk is a graphical file manager for Unix (esp. Linux) and the X
  Window System. Compared with other file managers available, it offers
  the most complete set of file operations and services, plus gives the
  user the ability to configure most every aspect of TkDesk in a
  powerful way. The reason for this is the use of Tcl/Tk as the
  configuration and (for the greatest part of TkDesk) implementation
  language. TkDesk has been influenced by various other systems and file
  managers, such as NeXT, for laying out the file browser windows, Apple
  Finder, for the idea of file annotations and, shock horror, Windows 95,
  for some other (of course minor and unimportant) inspirations.

  This is a brief overview of the most prominent features of TkDesk:

  o  Arbitrary number of file browsers and file list windows,

  o  Configurable file-specific popup-menus,

  o  History of visited directories, opened files, executed commands,
     and others, which is automatically saved to disk,

  o  Find files through their annotation, name, contents, size or age,

  o  A trash can for safe deletion of files and directories,

  o  Drag and drop,

  o  Calculation of disk usage for directory hierarchies,

  o  All file operations (find, copy, disk usage, etc.) are carried out
     in the background,

  o  Traversal of directory hierarchies through recursive cascaded
     menus,

  o  Bookmarks, create menu entries for often used files/directories,

  o  Online help (not much yet, but this will be extended in future
     releases),

  o  A configurable application bar, with cascaded popup menus for each
     button,

  o  A built-in multi-buffer editor,

  o  Sound support,

  o  Powerful configuration of nearly all aspect of TkDesk through
     Tcl/Tk,

  o  Free of charge! But see the file COPYING, or menu entry
     Help/License for information on usage and redistribution of TkDesk.

  The installation procedure for TkDesk is outlined in the file INSTALL.

  2.  The File Browser Window

  The file browser window contains a menu bar, a button bar for fast
  access to the most often used file operations and other functions, an
  entry field displaying the current directory, a horizontal scrollbar,
  a certain number of file listboxes (three by default), and a status
  and information bar.

  2.1.  The Menu Bar

  The individual menus will be described in more detail in future
  releases of TkDesk.

  2.1.1.  TkDesk

  The TkDesk menu contains entries for

  o  opening new file browsers and closing the current one,

  o  editing and rereading of all or individual configuration files (see
     section ``Configuration of TkDesk'' for more),

  o  exiting from TkDesk.

  2.1.2.  File

  This menu contains all the usual file operations, such as

  o  information on selected files, which also allows you to annotate
     files,

  o  creation of new files and directories,

  o  copying, moving, linking (both hard and symbolically) and renaming
     files and directories (you can even move directories from one file
     system to another, because TkDesk automatically translates this
     function into a sequence of copy and delete operations),

  o  deletion of files and directories, either safe, by moving them to
     the trash can, or for good.

  Other functions accessible from this menu are:

  o  Finding files through their annotation, name, size, date or
     contents,

  o  copying the full pathnames of all selected file to the X clipboard
     (for example, these can then be copied into an xterm by clicking
     inside the xterm with the middle mouse button),

  o  opening all selected files. This performs the default action for
     each selected file.

  2.1.3.  Directories

  Contains menu entries for

  o  Opening a new file list window with a given directory,

  o  creating a new directory,

  o  changing the current path of the file browser to your home
     directory,

  o  opening the trash can.

  The next menu entry, labeled Filesystems, contains to submenus: Home
  and Root. You can select a directory which is located anywhere below
  these directories, by traversing the recursively created submenus.
  This is a bit hard to describe, I suggest you just try it out.

  The remaining entries can be configured by the configuration file
  Directories. See section ``Configuration of TkDesk'' for details on
  how to do this. If one of these menu entries is invoked, the path of
  the file browser will change to that directory. If such an entry is
  invoked while at the same time pressing the Control key, a new file
  list window will be created displaying the contents of this file. This
  feature applies to all menus that contain directory names.

  2.1.4.  Commands

  The entries in this submenu allow you to:

  o  Execute a command,

  o  have a command executed periodically and viewing its output,

  o  have a rudimentary form of job control. Processes started from
     within TkDesk can be stopped, continued etc. with simple mouse
     clicks.

  The remaining entries can be configured by the configuration file
  Commands. See section ``Configuration of TkDesk'' for details on how
  to do this. If one of these menu entries is invoked, the corresponding
  command will be executed.

  2.1.5.  Bookmarks

  This menu lets you create bookmarks for often used files and
  directories. To do this, select at least one file/directory and invoke
  the Add Bookmark menu entry. The name(s) of the selected files resp.
  directories will now appear in the Bookmarks menu. You can remove any
  bookmark from the menu by selecting its corresponding entry from the
  Remove Bookmark submenu.

  The bookmarks you add will be automatically saved.

  2.1.6.  Options

  The Options menu lets you configure some aspects of TkDesk "on the
  fly". The entries are:

  o  Add Icons: If selected nice little images will appear left of the
     file names in the file listboxes. This looks nice, but has
     currently a major drawback: It is very slow. For this reason this
     option is by default deselected.

  o  Show All Files: Whether to show files in the file lists whose name
     start with ".".

  o  Folders On Top: If selected (default) folders will always appear on
     top of the file lists.

  o  Append Type Char: Whether to append a file-type specific character
     to the file names. This is mainly intended for monochrome displays.

  o  Strip <your home directory>: If this is selected, and the current
     path of the browser is somewhere under your home directory, the
     leftmost file listbox will contain your home directory rather than
     the root directory. This speeds up the display of directory
     hierarchies under your home directory.

  o  Overwrite Always: If this option is selected, TkDesk won't ask if
     the destination file already exists when copying or moving files.

  o  Really Delete: Relates to the deletion of files. If this option is
     selected, the "Delete Files" dialog box will always have the REALLY
     delete checkbutton selected by default.

  o  Quick Drag'n'Drop: Normally when you drop files onto a file list,
     the copy dialog appears. If this option is selected, dropped files
     will be moved to the destination directory without further
     questions. If the control key is pressed during dropping, the files
     will be copied.

  o  Sort History: This option determines whether the history menus are
     be sorted alphabetically or not.

  o  Number Of Listboxes: This relates to the number of listboxes in the
     file browser window. Between 2 and 6 can be displayed.

  The default setting for these options can be configured via the
  configuration file Preferences. See section ``Configuration of TkDesk''
  for details on how to do this.

  2.1.7.  Help

  This menu tries to give you some help with using TkDesk. It also
  contains an entry for displaying the license for using and
  distributing TkDesk, as well as an option for activating or
  deactivating the balloon help.

  And then there is the most important menu entry of TkDesk: About
  TkDesk... Make sure you invoke it at least once!

  2.2.  The Button Bar

  The button bar allows you fast access to more often used functions of
  TkDesk, or other commands. When you place the mouse button over any of
  these buttons, a small help window will appear telling you what this
  button does (provided the Balloon Help option is activated).

  The contents of this button bar can be configured via the
  configuration file ButtonBar. See section ``Configuration of TkDesk''
  for details on how to do this.

  2.3.  The Path Entry

  This entry field displays the current path of the directory. You can
  also type directly into this field to change the display to another
  directory. There is some sort of "auto-completion" available; if you
  type only the first part of a directory's name and press Control-Tab,
  its name will be automagically completed. That is, provided there is
  no other directory starting with the same letters.

  If you click the right mouse button over this field a popup menu
  appears which lets you select any of the current directory's parent
  directories.

  The button to the right of the entry field contains a menu of the last
  20 (default) directories you have visited. If you select one of these,
  the current path of the browser will change to it. The "Control-trick"
  described in section ``Directories'' works here as well!

  2.4.  The File Listboxes

  The main part of the file browser are the file listboxes. Directories
  are by default display in blue and with a bold font, executable files
  in red and also bold, and regular files in black and with a medium
  font. These settings can be configured via the System configuration
  file. The color and font of individual file types can be configured
  via the FileTags configuration file. See section ``Configuration of TkDesk''
  for details on how to do this.

  Every listbox contains a full listing of its directory. You can make
  the hidden parts visible by scrolling the listbox with the horizontal
  scrollbar at its bottom border. Every listbox also contains a menu,
  which can be accessed by clicking on the listbox's title. It contains
  entries for:

  o  Refreshing the listbox. Although TkDesk refreshes all its file
     lists every 5 seconds (default), sometimes you may want to have a
     file listbox instantly updated.

  o  Calculating the directory's disk usage, i.e. the number of bytes
     occupied by that directory and all its subdirectories. A window
     will appear when this has been done, containing a sorted list of
     all subdirectories and their individual disk usages. If you double-
     click on any of these, a new file list window will appear
     displaying the directory's contents.

  o  Setting a mask for the listbox's display. For example, you can
     configure the listbox to only display files matching the pattern
     *.gif.

  o  Sorting the listbox's contents, either by Name, Size, Date,
     Extension, or not at all.

  o  Displaying all files, that also those starting with a ".".

  o  Inverting the listing.

  o  Open a new file list window displaying the directory's contents.

  2.4.1.  Handling of the Listboxes (Bindings)

  The handling of the file lists is very similar to that of the NeXT
  file manager: when you double clock on a directory, the listbox right
  to the current one will display this directory's contents. Than you
  can open a directory in this listbox, and the listbox right to this
  one will display its contents. This way you can browse through
  complete directory hierarchies, while having instant access to the
  contents of the complete directory tree. When the number of opened
  directories exceeds the number of visible listboxes, you can scroll
  the listboxes with the horizontal scrollbar which is located right
  above the file lists.

  Files are selected with the left mouse button. A single click selects
  a single file, deselecting all other files. If the Shift key is
  pressed simultaneously, the old selection will be retained. By
  dragging the mouse pointer over a file list, while at the same time
  pressing the left mouse button, a set of files can be selected.
  Shift-doubleclick selects all files in that file list.

  A double click performs the default action for the selected file. For
  directories that is to open the directory, for executables to execute
  it, and for files to invoke the first entry of the corresponding popup
  menu (see below). If the Control key is pressed while double-clicking
  a directory, a new file list window is created displaying the contents
  of that directory. For files, a dialog box will appear asking for a
  command to execute on that file.

  Files can be dragged by pressing the middle mouse button on any
  selected file. If no file is selected, the clicked-on file will be
  selected. Files can be dropped by releasing the mouse button over any
  other file listbox, over windows of the build in editor, over the
  application bar (if the corresponding button has been configured to
  handle dropped files), over iconified file browsers and file lists
  (only if fvwm is used as the window manager) and in general over any
  other application supporting the file protocol of the BLT package.
  Valid drop targets can be identified by looking at the window that is
  displayed when files are dragged: the window's relief appears raised
  if over a valid target, flat if not.

  The right mouse button is used in the file listboxes to access the
  file-specific popup menu. Every popup menu contain a submenu, labeled
  with the file's name, which contains entries for the most common file
  operations. The remaining entries of the menu can be configured via
  the configuration file Popups. See section ``Configuration of TkDesk''
  for details on how to do this.

  2.5.  The Status Bar

  Displays either

  o  the current state of TkDesk,

  o  details of the currently selected file,

  o  number and summed size of currently selected files,

  o  the available space left on the current file system. This
     information may not be available for your system.

  3.  The File List Window

  The file list window is basically a more compact variant of the file
  browser window. It contains no button bar, displays only one listbox,
  which results in the fact that the contents of opened directories is
  always displayed in the same listbox, and doesn't have a status bar.
  Its advantage is that it is faster created than a file browser and
  occupies less space on your screen. My usual setup is that I have one
  file browser and lots of file lists opened.

  The menu bar of the file list windows is also more compact, but allows
  access to all menus of the file browser through sub menus of the
  Others menu. This menu contains one additional entry to open a file
  browser window displaying this file list's directory.

  4.  File Operations

  4.1.  Copying, Moving and Deleting Files

  These functions can be accessed from the File menu. There is one
  dialog for copying, moving and linking files, one dialog for renaming
  files (which does of course nothing else than moving the file to its
  new name), and one dialog for deleting files.

  The Rename dialog is very straight-forward and probably does not need
  further explanation. The Copy etc. dialog contains the obvious source
  and destination entry fields, plus a checkbutton labeled "all selected
  files". If more than one file is selected and this checkbutton is
  checked (default) the operation will be applied on all selected files.
  If it is not checked, each file will be handled individually. The Skip
  button can then be used for skipping individual files.

  The Delete dialog also contains this checkbutton, plus a checkbutton
  labeled REALLY delete. If this checkbutton is checked, the files will
  not be moved to the trash can but will be really and finally deleted!!
  The default setting of this checkbutton can be set from the Options
  menu.

  4.2.  Finding Files

  The File menu contains two entries for finding files: Find Files...
  and Find Annotation.... Files can be annotated through their "Info"
  dialog (accessible from the File menu or from their popup menu).

  Find Annotation enables you to look for a annotated files whose
  annotation matches a certain regular expression (which can be as
  simple as an ordinary string).

  Find Files lets you look for files (or rather: let's you instruct
  TkDesk to look for files) whose name match a certain pattern, which
  are of a certain type (such as directory), which contain a certain
  string, which are smaller or bigger than a certain number of kilobytes
  or which are older/younger than a certain number of dates.  All fields
  which are not left blank in this dialog will be combined with a
  logical AND. This dialog is currently the only one utilizing the
  balloon help capability of TkDesk, so for now I would like to refer
  you to this. For instance, if you want to know how to enter the file
  size you're looking for, place the mouse pointer over the Size entry
  field without moving it for a few seconds.

  Both find dialogs display their results by now well-known file
  listboxes. The same bindings described in section
  ``Handling of the Listboxes (Bindings)'' apply here as well!

  5.  The Application Bar

  TkDesk provides you with an application bar for fast access to your
  favorite applications, commands, directories etc.  It consists of an
  arbitrary number of buttons.  Each button (apart from the date
  display) contains a popup menu which can be accessed by pressing the
  right mouse button over any them.  If you single-click the left mouse
  button over such a button, the first (active) entry from the
  corresponding popup menu will be invoked.

  The first button (displaying a comet) could be called TkDesk's "Start
  Button", although I would prefer "Take-off Button" ;-).  Its popup
  menu contains entries for accessing TkDesk's most often used
  functions, such as executing a command or opening a file list window,
  plus submenus for your bookmarks, the files you most recently opened,
  the directories you've last visited and the command you've most
  recently executed (although this last history doesn't work perfectly
  yet).  The remaining two entries allow you to configure the
  application bar and TkDesk to your heart's content. See section
  ``Configuration of TkDesk'' for details on how to do this.

  The second button is not a real button but rather a display for the
  current time and date.

  All the other buttons can be configured by you! See the following
  section for more on this.

  6.  The Built-in Editor

  To be written... Its usage is very straight-forward though, so that
  you should get along without a detailed description for the time
  being.

  7.  Configuration of TkDesk

  Currently, TkDesk can be configured only by editing ASCII files. This
  is not necessarily a drawback, because this way you can add complex
  Tcl/Tk procedures to the configuration files, but if you don't know
  Tcl/Tk you would probably prefer a dialog-based configuration. This
  should be implemented in one of the future releases of TkDesk.

  If you don't know Tcl/Tk: don't despair! For the biggest part of
  TkDesk's configuration files it is absolutely not necessary for you to
  know how to program in Tcl/Tk, since you just have to modify values or
  extend the examples I have provided.

  The configuration files can be accessed from the TkDesk menu via the
  entry Edit Config Files. The built-in editor (default) will then
  appear with the selected configuration file(s) already loaded. Each
  configuration file contains rather detailed comments on what the
  indivual setting are for, and how they can be modified. Well, at least
  they contain examples, which can guide your modification attempts.
  Once you have modified the configuration file, save it (e.g. by
  pressing Alt-s resp. Meta-s) an reload it by invoking its
  corresponding entry from the submenu labeled Reread Config Files of
  the TkDesk menu. (Or via the "comet" button of the application bar.)

  Or, which is much faster, select one of the entries from the "TkDesk"
  menu of the editor that appears when editing configuration files.

  TkDesk comes with lots of Pixmaps (XPM files which only use the same
  32 colours) and Bitmaps. You find these in the "images" subdirectory
  of TkDesk's library directory (typically /usr/local/lib/TkDesk).

  TkDesk uses the following configuration files:

     AppBar
        For configuring the application bar.

     ButtonBar
        For configuring the button bar of the file browser windows.

     Commands
        Contains commands that are to be appended to the Commands menu.

     Directories
        Contains directories that are to be appended to the Directories
        menu.

     FileTags
        For configuring the color and font of regular files in the file
        listboxes.

     Popups
        For configuring the file-specific popup menus.

     Preferences
        For default settings of the Options menu's entries.

     Sounds
        For defining which command to use for playing sounds, and which
        sound file should be played at which event. By default sound is
        disabled (since the respective line is commented out).

     System
        Contains global definitions for TkDesk, such as which default
        fonts and colors to use, which shell commands to use for
        copying, deleting etc., how often to refresh the file lists etc.

  As already mentioned, each configuration file contains directions on
  how to modify its definitions. And the general advice is: just look at
  the example definitions, because these make things clearer than lots
  of explanations can (I guess).

