<!doctype linuxdoc system>

<article>

<!-- Title information -->

<title>TkDesk User's Guide
<author>Christian Bolik, <tt>Christian.Bolik@Mainz.netsurf.de</tt>
<date>Version 1.0b3, 25 September 1996
<abstract>
TkDesk is a graphical, highly configurable and powerful desktop manager
for UNIX and the X Window System. This document is meant to be a
comprehensive
guide to the functions, services and possibilities offered by
TkDesk. (It may not be fully up to date with the current version, but
should be useful anyway. Take a look at the CHANGES file for latest
news.)
A list of answers to frequently asked questions is also
included. Please note that there is a TkDesk-page on the World Wide Web at
<url url="http://sun1.rrzn-user.uni-hannover.de/&tilde;zzhibol/tkdesk/">,
as well as a mailing list at
<tt><htmlurl url="mailto:majordomo@mrj.com" name="majordomo@mrj.com"></tt>
(send a mail with the body &dquot;subscribe tkdesk&dquot; to join).
</abstract>

<!-- Table of contents -->
<toc>

<!-- Begin the document -->

<sect> Introduction <p>

TkDesk is a graphical desktop manager for UNIX (especially 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 aspects 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: 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:

<itemize>
<item> Arbitrary number of automatically refreshed file browsers and
file list windows,
<item> Configurable file-specific popup-menus,
<item> Drag and drop,
<item> Files and directories may also be dropped onto the root window,
	a.k.a. desktop,
<item> Configurable application bar, with several displays and
cascaded popup menus for
each button, files can also be dropped here,
<item> History of visited directories, opened files, executed commands,
and others, which is automatically saved to disk,
<item> Find files through their annotation, name, contents, size or age,
<item> Trash can for safe deletion of files and directories,
<item> Calculation of disk usage for directory hierarchies,
<item> All file operations (find, copy, disk usage, etc.) are carried out in
the background,
<item> Traversal of directory hierarchies through recursive cascaded menus,
<item> Bookmarks, create menu entries for often used files/directories,
<item> Comprehensive hypertextish online help,
<item> Built-in multi-buffer and undo-capable editor,
<item> Close coupling with Netscape for displaying HTML files or
selected URLs,
<item> Sound support,
<item> Powerful configuration of nearly all aspect of TkDesk through
Tcl/Tk, this also allows the Tcl-literate to extend TkDesk in
arbitrary ways,
<item> Free of charge! But see the file <tt>COPYING</tt>, or menu
entry <tt>Help/License</tt> for
information on usage and redistribution of TkDesk.
</itemize>

<sect1> Acknowledgments <p>

TkDesk uses a number of other freely available packages without which
TkDesk would not have been possible. I'd like to say many thanks to
the following people:

<itemize>
<item> Chris Sterritt for setting up and managing the TkDesk mailing list
(at
<tt><htmlurl url="mailto:majordomo@mrj.com" name="majordomo@mrj.com"></tt>,
send a mail with the body &dquot;subscribe tkdesk&dquot; to join),
<item> Ken Hornstein for his wonderful netscape-remote package,
<item> Ioi Kim Lan for making an XPM image reader for Tk available,
<item> George Howlett for his great BLT, of which parts are used by TkDesk,
<item> Michael McLennan for his massively useful <tt>[incr tcl]</tt>,
<item> John Ousterhout for Tcl/Tk, which is definitely the best thing
since sliced bread,
<item> Greg Hankins and Matt Welsh for putting together the most
wonderful linuxdoc-sgml package,
<item> and of course, Linus Torvalds whose Linux kind of changed my
life, really!
</itemize>

And a very big thank you to the growing TkDesk user community,
which provides me with a constant flow of bug reports (getting less
now <tt>:-)</tt>), suggestions for enhancements of TkDesk, and lots of
motivation and encouragement.

Special thanks to Chuck Robey for revising a previous version of
this guide.


<sect1> Using TkDesk's Help System <p>

If you have Netscape running, TkDesk will use that for displaying
this User's Guide on-line. Otherwise, to reduce overhead, TkDesk
uses its own, rather sophisticated help system. It features
hypertext links, context sensitivity (which is not yet utilised by
TkDesk) and full text search. 

The help window consists of three areas:

<enum>
<item> A listbox listing all the section headings. A section can be
selected by pressing the left mouse button,
<item> the text display, which contains the actual help text, and
<item> a button &dquot;Back&dquot;, which jumps back after a hypertext
link has been followed (see next paragraph), a button
&dquot;Close&dquot; which closes the help window, and a text entry. In
this entry a regular expression can be entered (such as
<tt>[Ff]eatures</tt>). After hitting <tt>Return</tt>, the whole help
text is searched for this expression. Pressing <tt>Return</tt> again
continues the search.
</enum>

Text that is displayed blue in the help window is a hypertext
link. When the left mouse button is clicked over such a link the
display will automatically change to the referenced section. One can
jump back by pressing the &dquot;Back&dquot; button described above.

The following keys are bound when the mouse pointer is inside the help
window:

<descrip>
<tag><tt>Tab</tt></tag> Moves to the next section.
<tag><tt>Shift-Tab</tt></tag> Moves to the previous section.
<tag><tt>Control-Tab</tt></tag> Moves to the first section.
<tag><tt>Control-Shift-Tab</tt></tag> Moves to the last section.
<tag><tt>Up, Down</tt></tag> Scrolls one line up/down.
<tag><tt>Page up, Page down</tt></tag> Scrolls one page up/down.
<tag><tt>Control-Home</tt></tag> Jumps to start of help text.
<tag><tt>Control-End</tt></tag> Jumps to end of help text.
<tag><tt>Meta/Alt-b</tt></tag> Equivalent to pressing the
&dquot;Back&dquot; button.
<tag><tt>Meta/Alt-c, Escape</tt></tag> Equivalent to pressing the
&dquot;Close&dquot; button.
</descrip>

<sect1> Command Line Options <label id="cmdopts"><p>

Usually TkDesk is started simply by executing the command
&dquot;<tt>tkdesk</tt>&dquot; from the shell prompt or your X
initialisation file. The command line options understood by TkDesk are
the following:

<descrip>
<tag>-configdir <it>dir</it></tag> Reads the configuration from
directory <it>dir</it> instead of <tt>~/.tkdesk</tt>.
<tag>-default</tag> Reads the default configuration of TkDesk 
instead of the user's one in <tt>~/.tkdesk</tt>.
<tag>-fvwm</tag> TkDesk uses the icon window facility only if fvwm is
the current window manager. Since other window managers may also
support icon windows, or TkDesk maybe unable to detect you're running
fvwm, this command line option forces TkDesk to use icon windows. The
advantage of these is that they look nicer and files can be dropped on
them.
<tag>-iconic</tag> Iconifies all file browser and file list windows
created by TkDesk during start-up.
<tag>-startdir <it>dir</it></tag> If this option is given,
the first file browser will open with directory <it>dir</it>.
</descrip>

For example, the command &dquot;<tt>tkdesk -fvwm -iconic</tt>&dquot;
forces Tkdesk to use icon windows and starts with all windows iconified.


<sect> The File Browser Window <p>

The file browser window is the largest window when TkDesk is started
for the first time.
It 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.


<sect1> The Menu Bar <p>

The following sections describe the entries of the individual menus of
the file browser windows.

<sect2> TkDesk <p>

The &dquot;TkDesk&dquot; menu contains the following entries:

<descrip>
<tag>New Browser...</tag>
Asks for a directory for which to open a new file browser window. If
the directory is the empty string, the operation is cancelled.
<tag>Clone Window</tag>
Creates a new file browser window with the same directory as the
current one (that is, the directory of the file browser from which
this menu entry was invoked).
<tag>Application Bar</tag>
Opens the application bar if it had been closed before, or raises the
application bar above all other windows.
<tag>Edit Config Files</tag>
This is a submenu from which individual or all configuration files of
TkDesk can be opened to modify them.
<tag>Reread Config Files</tag>
Another submenu whose entries reread individual or all configuration
files. 
<tag>Auto Save</tag>
Here you can select which parts of TkDesk are automatically saved
periodically and when TkDesk exits.
<tag>Save All Now</tag>
Saves all parts of TkDesk's configuration no matter what the settings
in the previous submenu.
<tag>Close Window</tag>
Closes the file browser window.
<tag>Quit</tag>
Quits TkDesk if this is what the user really wishes.
</descrip>

<sect2> File <p>

This menu provides all the usual file operations plus entries for
finding files. The contained menu entries are:

<descrip>
<tag>Information</tag> Opens a file information window for each
currently selected file. This window, which can also be used to add
annotations to files, is described in section
<ref id="fileinfo" name="File Information">.
<tag>New File...</tag> Asks for the name of a file which will be
created in the current directory of the file browser or list.
<tag>New Directory...</tag> Asks for the name of a directory which will be
created in the current directory of the file browser or list.
<tag>Copy, Move, Link...</tag> Opens a dialog box for copying, moving,
linking, and symbolic linking of files. If the currently selected file
is a tar archive the dialog contains an extra button labeled
&dquot;Untar&dquot;. This dialog window is described in more detail in
section <ref id="copydel" name="Copying, Moving and Deleting Files">.
<tag>Rename...</tag> For each selected file, TkDesk asks for a new
name. Before actually renaming TkDesk checks for an existing file with
the same name.
<tag>Delete...</tag> Opens a dialog to delete files. The
section <ref id="copydel" name="Copying, Moving and Deleting Files">
gives more details.
<tag>Print...</tag> Asks for a command to print the currently selected
files. The names of the selected files will be appended to the
command. The default command can be defined in the configuration file
&dquot;System&dquot;.
<tag>Find Files...</tag> Opens a dialog window which can be used to
search for files, using a variety of characteristics. This dialog is
described in more detail in section
<ref id="findfiles" name="Finding Files">.
<tag>Find Annotation...</tag> Lets you search for files with a certain
annotation. More details in section <ref id="findfiles" name="Finding Files">.
<tag>Copy To X Selection</tag>
Copies the complete names of all currently selected files
(i.e. including their paths) to the X clipboard. They can then be
pasted into any other X application using the middle mouse button.
<tag>Open Selected Files</tag>
For each currently selected file, the default action is performed.
</descrip>

<sect2> Directories <label id="dir"><p>

The main purpose of this menu is to select directories which are to be
opened. It also manages TkDesk's trash can. The menu contains the
following entries:

<descrip>
<tag>Open...</tag>
Asks for a directory. A new file list or file browser window will be
created, baesed on the setting of the &dquot;In Browser&dquot; checkbutton.
<tag>New...</tag>  Asks for the name of a directory which will be
created in the current directory of the file browser or list.
<tag>Home Directory</tag> Changes the directory of the window from
which this entry is invoked to the user's home directory.
<tag>Trees</tag> Contains two cascaded submenus: &dquot;Home&dquot;
and &dquot;Root&dquot;. The contents of these submenus is dynamically
generated and corresponds to the directory hierarchy rooted either at
the user's home directory or at &dquot;/&dquot;. Selecting an entry
from these submenus changes the directory of the window to the
selected directory. Pressing <tt>Control</tt> at the same time opens a
new window with this directory.
<tag>Trash</tag> Opens a file list window displaying the contents of
the trash can. When this window is iconified and TkDesk uses icon
windows the icon can be used as a Mac-like trash can.
<tag>Empty Trash</tag> Empties the trash can after confirmation from
the user.
</descrip>

The remaining entries can be configured by the configuration file
<tt>Directories</tt>. See section <ref id="config" name="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 (if
the option &dquot;Always In Browser&dquot; is selected a file browser
window will be created), displaying the contents of the selected
directory. This feature applies to <bf>all</bf> menus that contain
directory names!


<sect2> Commands <p>

This menu provides entries to execute commands either once or
periodically, and provides some &dquot;job control&dquot;. Its entries
are:  

<descrip>
<tag>Execute...</tag>
Asks for a command to execute. The button to the right of the command
entry contains a history of previously executed commands. Selecting
one of these copies its name to the entry widget.
<tag>Periodic Execution...</tag> Opens a window which can be used to
execute a command and watch its output periodically. If the
&dquot;Don't execute&dquot; checkbutton is selected, the execution is
paused. 
<tag>Job Control</tag> Opens a window which allows to stop, terminate,
kill etc. processes which have been started by TkDesk.
</descrip>

The remaining entries can be defined in the configuration file
<tt>Commands</tt>. See section
<ref id="config" name="Configuration of TkDesk"> for details on how to
do this. If one of these menu entries is invoked, the corresponding
command will be executed.


<sect2> Bookmarks <p>

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

The bookmarks you add will be automatically saved, if the
&dquot;Bookmarks&dquot; entry of the &dquot;Auto Save&dquot; submenu
contained in the &dquot;TkDesk&dquot; menu is selected
(which is the default).

<sect2> Options <p>

The <tt>Options</tt> menu lets you configure many aspects of TkDesk
&dquot;on the fly&dquot;. The entries are:

<descrip>
<tag>Add Icons</tag> If selected, pretty 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.
<tag>Show All Files</tag> Whether to show files in the file
lists whose name start with &dquot;.&dquot;.
<tag>Folders On Top</tag> If selected (default) folders will
always appear on top of the file lists.
<tag>Append Type Char</tag> Whether to append a file-type
specific character to the file names. This is mainly intended for
monochrome displays and is then automagically selected.
<tag>Single Click (Dirs)</tag> Lets you open directories with a single
click of the left mouse button. Individual directories can still be
selected by pressing <tt>Shift</tt> at the same time.
<tag>Always In Browser</tag> If this option is selected, the &dquot;In
Browser&dquot; checkbutton of the &dquot;Open Directory&dquot; dialog
will always be selected. <tt>Control-Doubleclick</tt> on a directory
will open a file browser instead of a file list window.
<tag>Strip &lt;your home directory&gt;</tag> 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.
<tag>Overwrite Always</tag> If this option is selected, TkDesk
won't ask if the destination file already exists when copying or
moving files.
<tag>Really Delete</tag> Relates to the deletion of files. If
this option is selected, the &dquot;Delete Files&dquot; dialog box
will always have the &dquot;REALLY delete&dquot; checkbutton
selected by default.
<tag>Quick Drag'n'Drop</tag> 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 <tt>Control</tt> is pressed during dropping, the
files will be copied. If the drop target is the trash can, TkDesk will
ask if the files are to be deleted &dquot;really&dquot;.
<tag>Sort History</tag> This option determines whether the
history menus are to be sorted alphabetically or not.
<tag>Use Sound</tag> If you have sound working with TkDesk on your
machine, you can temporarily disable sound by selecting this
option. Handy when playing Audio CDROMs, for instance.
<tag>Dialogs at Pointer</tag> If selected, TkDesk will always try to
place new windows right under the mouse pointer.
<tag>Number Of Listboxes</tag> This relates to the number of
listboxes in the file browser window. Between 1 and 6 can be
displayed, though 18 would theoratically not be a problem.
</descrip>

The settings of these options are by default automatically saved.
This can be disabled by deselecting the &dquot;Options&dquot; entry of
the &dquot;TkDesk/Auto Save&dquot; submenu.

<sect2> Help <p>

This menu tries to give you some help with using TkDesk.  It also
contains entries for displaying the list of FAQs, recently made
changes to TkDesk, and the license for using and
distributing TkDesk, as well as an option for activating or
deactivating the balloon help. The setting of the ballon help entry
will be saved together with the ones of the &dquot;Options&dquot;
menu. 

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


<sect1> The Button Bar <p>

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 &dquot;Balloon Help&dquot; option is activated).

The contents of this button bar can be defined via the
configuration file <tt>ButtonBar</tt>. See section
<ref id="config" name="Configuration of TkDesk"> and the configuration
file itself for details on how to do this.

<sect1> The Path Entry <p>

This entry field displays the current path of the file browser or
file list. You can
also type directly into this field to change the display to another
directory.  There is a sort of &dquot;auto-completion&dquot;
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
&dquot;Control-trick&dquot; described in section
<ref id="dir" name="Directories"> works here as well!


<sect1> The File Listboxes <p>

The main part of the file browser are the file listboxes.  Directories
are by default displayed in blue with a bold font, executable files
in red and bold, and regular files in black and a medium
font.  These settings can be configured via the <tt>System</tt>
configuration file.  The color and font of individual file types can be
configured via the <tt>FileTags</tt> configuration file.  See section
<ref id="config" name="Configuration of TkDesk"> for details on how to
do this.

Every listbox contains a &dquot;long&dquot; 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:

<itemize>
<item> 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.
<item> 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 its entries, a new file list window will appear displaying the
directory's contents.
<item> Executing a command in the listbox's directory. All the usual
&percnt;-shortcuts my be used (see section
<ref id="config" name="Configuration of TkDesk">).
<item> Setting a mask for the listbox's display.  For example, you can
configure the listbox to only display files matching the pattern
<tt>*.gif</tt>.
<item> Sorting the listbox's contents, either by Name, Size, Date,
Extension, or not at all.
<item> Displaying all files, that is also those
starting with a &dquot;.&dquot;.
<item> Inverting the listing.
<item> Open a new file list window displaying the directory's contents.
</itemize>

This menubutton can also be used to drop files, as well as to drag the
directory displayed in the associated listbox to another target, e.g.
the root window.

<sect2> Handling of the Listboxes (Bindings) <label id="bind"><p>

The handling of the file lists is very similar to that of the NeXT
file manager: when you double click on a directory, the listbox right
to the current one will display this directory's contents.  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.

Note that if the option &dquot;Single Click (Dirs)&dquot; is set a
single click on a directory will open it. Then you need to use
Shift-Click to select a single directory.

A double click performs the default action for the selected file.  For
directories that opens the directory, for executables it executes
it, and for files it invokes 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 or file browser window (depending on the
setting of the &dquot;Always In Browser&dquot; option)
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 and the menubutton above them,
over windows of the built-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 TkDesk is in &dquot;fvwm-mode&dquot;, see section
<ref id="cmdopts" name="Command Line Options">) and in general over any
other application supporting the <tt>file</tt> protocol of the BLT
package's drag and drop implementation.
Valid drop targets can be identified by looking at the window
that is displayed while 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 contains 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 <tt>Popups</tt>. See section
<ref id="config" name="Configuration of TkDesk"> for details on how to
do this.


<sect1> The Status Bar <p>

The status bar is located at the bottom edge of file browser windows.
It displays either

<itemize>
<item> the current state of TkDesk,
<item> details of the currently selected file, or
<item> number and summed size of currently selected files.
</itemize>


<sect> The File List Window <p>

The file list window is basically a more compact version of the file
browser window.  It displays only one listbox, which results in the
fact that the contents of opened directories are always displayed in
the same listbox, and it doesn't have a status bar.  Its advantage is
that it is more quickly created than a file browser window 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 submenus of the
&dquot;Others&dquot; menu.  This menu contains one additional entry to open
a file browser window displaying this file list's directory.


<sect> File Operations <p>

<sect1> File Information <label id="fileinfo"><p>

The &dquot;File Information&dquot; window displays detailed
information about a file. It can also be used to change the owner or
access-permissions of a file. In addition, an annotation to a file can
be added here.

The following information is displayed:

<descrip>
<tag>Path</tag> The path of the file.
<tag>Size</tag> The size of the file in bytes.
<tag>Modified</tag> When the file was last modified. By clicking on
the button displaying the date file can be &dquot;touched&dquot;,
ie. their modification timestamp will be set to the current time.
<tag>Owner</tag> Displays the owner of the file. By clicking the
button displaying the owner, the owner can be changed to another user.
<tag>Group</tag> Displays the group ownership of the file. By clicking the
button displaying the group's name, the group can be changed.
<tag>Mode</tag> Here the access permissions are displayed in &dquot;ls
-l&dquot; style. The first three button correspond to the rights of
the owner (r: may read, w: may write, x: may execute or open the
directory), the second three buttons to the rights of the group, and
the last three buttons to every one else's rights. The &dquot;x&dquot;
button are special in that they cycle through four settings:
<tt>x</tt> for executable, <tt>s</tt> for set user/group id
<it>and</it> executable, <tt>S</tt> for set id only, and <tt>-</tt>
for not executable. If the settings any of these buttons is changed,
the &dquot;Change Mode&dquot; button at the bottom edge of the window
must be clicked to actually change the file's permissions.
<tag>Links</tag> Number of (hard) links to this file.
<tag>Type</tag> Tries to give some information about the file's
contents. TkDesk uses the shell command <tt>file</tt> for this.
</descrip>

In the &dquot;Annotation&dquot; text field you can enter any remarks
about the file. This annotation will be saved when the
&dquot;Close&dquot; button is pressed. If the window displays
information about a file an additional button labeled &dquot;Disk
Usage&dquot; is provided, which calculates the disk usage of the
hierarchy rooted at that directory. The entries of the &dquot;Disk
Usage&dquot; window can be double-clicked to open new file list
windows. 

<sect1> Copying, Moving and Deleting Files <label id="copydel"><p>

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

The &dquot;Rename&dquot; dialog is very straight-forward and probably does
not need further explanation.  The &dquot;Copy etc.&dquot; dialog contains
the obvious source and destination entry fields, plus a checkbutton
labeled &dquot;all selected files&dquot;.  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 &dquot;Skip&dquot; button can then be used for
skipping individual files.

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


<sect1> Finding Files <label id="findfiles"><p>

The &dquot;File&dquot; menu contains two entries for finding files:
&dquot;Find Files...&dquot; and &dquot;Find Annotation...&dquot;. Files can be
annotated through their &dquot;Info&dquot; dialog (accessible from the
&dquot;File&dquot; menu or from their popup menu), see section
<ref id="fileinfo" name="File Information">.

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

&dquot;Find Files&dquot; 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 younger/older than a certain date.
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
&dquot;Size&dquot; entry field without moving it for a few seconds.

Both &dquot;Find&dquot; dialogs display their results in the same file
listboxes that are used by the file list and browser windows,
so the same bindings described in section
<ref id="bind" name="Handling of the Listboxes (Bindings)">
apply here as well!


<sect> The Application Bar <p>

TkDesk provides you with an application bar for fast access to your
favorite applications, commands, directories etc., plus displays for
the current date and time, system load, and the status of your mailbox.
It consists of an arbitrary number of buttons.
Each button (also the aforementioned displays) contains a popup menu which
can be accessed by pressing the right mouse button over any of 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
&dquot;Start Button&dquot;,
although I would prefer &dquot;Take-off Button&dquot;
<tt>;-)</tt>.
Its popup menu
contains entries for accessing TkDesk's most often used functions,
such as executing a command or opening a file list or browser window, plus
submenus for your bookmarks, the files you most recently opened, and the
directories you've last visited. The next entry is a submenu labeled
&dquot;Application Bar&dquot;. Here you can configure all aspects of
the application bar, especially its <bf>position and orientation</bf>.
See my answer to the MFAQ <ref id="apppos" name="How can I change
the position of the application bar?"> for more.
The last entry labeled &dquot;Configuration&dquot; contains another
submenu which gives you fast access to TkDesk's configuration files.

The remaining two entries allow you to configure the application bar
and TkDesk to your heart's content. See section
<ref id="config" name="Configuration of TkDesk"> for details on how to
do this.

The second button with the question mark gives you access to this guide
to TkDesk, and lets you view manual pages, also making use of a running
TkMan (which is a hypertextified manual pager which is to be highly
recommended). This button also allows you to drop executables on it to
automatically display their manual page, if they have got one.

All the other buttons can be configured by you! See section
<ref id="config" name="Configuration of TkDesk"> for details on how to
do this.

<sect> The Built-in Editor <label id="editor"><p>

The built-in editor of TkDesk is meant to be a simple ASCII editor for
editing files smaller than, say, 500kB. A single editor window can
handle an arbitrary number of buffers each of which contains another
file. Files can either be loaded through the &dquot;File&dquot; menu
of the editor or by simply dropping one or more files on the text
field of the editor window from one of the file listboxes.

An editor window contains the following menus in its menu bar:

<descrip>
<tag>File</tag> Contains entries to load, save, and print files, and
to close the current buffer, current window, or all windows.
<tag>Edit</tag> The first entry provides access to the editor's
&dquot;Undo&dquot; functionality. Note that the undo buffer may
contain a maximum of 500 events. This menu also
contains entries for managing TkDesk's own text
clipboard. Also provides entries to search for text (regular
expressions), replace text, or find the next occurence of the
currently selected text. The entry &dquot;HyperSearch&dquot; is a
special form of search: all matching lines are displayed in a file
listbox. If one of its entries is clicked on, the editor automatically
displays that line at the top of the text field. This can be useful
for jumping to headings, function definitions etc. Oh yes, and the
regular expressions entered here are also saved with the other
histories. 
<tag>Options</tag>
The &dquot;Auto Indent&dquot; option determines whether the cursor is
automatically indented after hitting <tt>Return</tt>. If the
&dquot;Send to Netscape&dquot; option is set, the current file will be loaded
by (maybe a running) Netscape each time it is saved. Useful when
editing HTML files. The
&dquot;Font...&dquot; option lets you select a font by making use of
the xfontsel program, which is pretty standard on X systems, I think.
TkDesk might provide its own font selector at one time though.
<tag>Buffers</tag> Lists the buffers of the editor window. Buffers can
be selected from this menu.
<tag>TkDesk</tag> This menu is only available when editing one of
TkDesk's configuration files. It lets you save the file and reload it
into TkDesk by selecting the corresponding menu entry or pressing
<tt>F5</tt>, or exactly the same plus closing the buffer by invoking
the next entry or pressing <tt>F6</tt>. This way configuration files
can very quickly be edited and reloaded into TkDesk.
</descrip>

The text area provides all the more common Motif- and Emacs-like
key-bindings (including <tt>Control-Space</tt> for selecting an area
of the text). Maybe it should be mentioned that <tt>Control-C/X/V</tt>
do not work on the X selection but on TkDesk's own clipboard. Use the
middle mouse button to paste from the X selection into TkDesk or from
TkDesk into another application.

Marks can be set with <tt>Control-[1-9]</tt>, and be jumped to with
<tt>Alt/Meta-[1-9]</tt>. You can always jump back with <tt>Control-0</tt>.


<sect> Configuration of TkDesk <label id="config"><p>

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 a future release 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. And to those who want to exploit
all of the power available by using Tcl/Tk as TkDesk's configuration
language, have a look at the answer to FAQ
<ref id="tcltk" name="Where can I find out more about Tcl/Tk?">.

The configuration files can be accessed from the <tt>TkDesk</tt> menu
via the entry <tt>Edit Config Files</tt>, or from the
&dquot;Configuration&dquot; submenu of the popup menu of the
application bar's first button (I should really call this the
&dquot;comet-button&dquot; or something similar).  The built-in editor
will then appear with the selected configuration file(s)
already loaded.  Each configuration file contains rather detailed
comments on what the individual settings 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,
you can save it and reload it into TkDesk making use of the entries of
the editor's &dquot;TkDesk&dquot; menu described in section
<ref id="editor" name="The Built-in Editor">. Use F5 to save the file
and reload it into TkDesk, and F6 to do the same but additionally
close the configuration file.

The following sections briefly describe what the individual
configuration files are used for by TkDesk, and what settings can be
defined by them.

As already mentioned, each configuration file contains directions on
how to modify its definitions.  The general advice is: just look at
the example definitions, because these make things clearer than lots
of explanations can. And don't be shy, but experiment! It's easier
than you might think, really!

<sect1> AppBar <label id="appbar"><p>

This configuration file lets you define all aspects of the application
bar (apart from its geometry, use the entries of the submenu
&dquot;Application Bar&dquot; of the comet-button's popup menu for
this). This is what you can define here:

<itemize>
<item> If the application bar should be managed by the window manager
just as an ordinary window. I don't like this, so this is disabled by
default <tt>:-)</tt>.
<item> The maximum number of buttons in a column (vertical layout) or
row (horizontal layout). Yes, the application bar can contain several
columns or rows!
<item> The fonts to use for the time and date display.
<item> The actual button definitions, ie. which image to display, and
the entries of the (possibly cascaded) popup menu. See the
&dquot;AppBar&dquot; file itself for the syntax used. TkDesk comes
with a rich set of b/w XBM and colour XPM images, these are located in
the <tt>images</tt> subdirectory of TKDesk's library directory. You
can find out where this is by looking at the fifth line of the
<tt>tkdesk</tt> script.
</itemize>


<sect1> ButtonBar <p>

This file defines the contents and appearance of the Button Bar,
which is displayed underneath the menu bar of TkDesk's file browser
or file list windows. Both button bars are configured independently
from one another.

<sect1> Commands <p>

In this file you can define entries which will be added to TkDesk's
&dquot;Command&dquot; menu, for example to uncompress all selected
files or do whatever you can possibly imagine.

<sect1> Directories <p>

Here you can define entries and cascaded submenus of directories which
will be added to TkDesk's &dquot;Directories&dquot; menu. More details
are contained in the &dquot;Directories&dquot file itself.

You can also define a list of directories whose parent directories are
not to be displayed in file browser windows, as is usually the case
with your home directory. This can speed up display of directories
underneath an AFS directory, for instance.

Another list lets you define action that are to be performed when a
specific directory is opened. This can be used for example to
auto-mount floppy and CDROM drives.

<sect1> FileTags <p>

Contains definitions for color and font of specific file types, that
will be used in TkDesk's file lists. Also the icons displayed when the
&dquot;Add Icons&dquot; option is selected are configured here, as
well
as the icons used for the desk items, i.e. files and directories which
have been dropped on the root window. 

<sect1> Popups <p>

The popup menus that appear when the right mouse button is clicked
over a file or directory are defined here. There are individual
definitions for the popup menus of directories, executables, and of
other files.

<sect1> Sounds <p>

Here the command to be used for playing sounds can be defined, as well
as the sound files which are to be played at certain events.
 TkDesk comes
with a few VOC sound files which are located in
the <tt>sounds</tt> subdirectory of TkDesk's library directory. You
can find out where this is by looking at the fifth line of the
<tt>tkdesk</tt> script.

<sect1> System <p>

All the more &dquot;basic&dquot; features of TkDesk can be configured
here. These are:

<itemize>
<item> Colours to be used by TkDesk,
<item> Fonts to be used by TkDesk,
<item> Default geometry of file listboxes,
<item> Definitions of shell command which are used by TkDesk to copy,
move, delete etc. files. These should be fine as they are in most cases.
<item> The default command for printing,
<item> Which editor to use, plus settings for the built-in editor,
<item> Periods for automatic refreshing of the file lists and saving
of TkDesk's configuration,
<item> Maximum number of entries in history menus,
<item> If TkDesk should ask for confirmation when the user wants to
quit TkDesk,
<item> If TkDesk should allow the menus to be &dquot;tearoff-able&dquot;,
<item> The paths in which TkDesk will look for images and sounds used
in the configuration files,
<item> Icons to use for file list and browser windows, and for the
help window,
<item> And if TkDesk should try to emulate Motif as closely as possible.
</itemize>

And that's it! Well, for the moment at least...


<appendix>

<sect> Frequently Asked Questions <p>

This section is intended to give answers to the most frequently asked
questions about TkDesk.  This file is derived from the emails I'm
receiving, so if you think something is missing just tell me about it
(<tt><htmlurl url="mailto:zzhibol@rrzn-user.uni-hannover.de"
name="zzhibol@rrzn-user.uni-hannover.de"></tt>).

<sect1>
How can I change the position of the application bar?
<label id="apppos">
<p>

You can drag the application bar around simply by holding down the
Alt- or Meta-key and simultaneously pressing the left mouse button
over the application bar. You can also invoke the
&dquot;Move...&dquot; entry from the comet button's popup menu to do
the same without having to press Alt/Meta.

Since version 1.0b1 the configuration file "AppBar" sets also a
variable named tkdesk(appbar,wm_managed) which can be used to have the
apllication bar managed by the window manager, although this is
usually not necessary.

<sect1>
Can I have transparent icons?
<p>

No, but have a look at the answer to the next question.

<sect1>
How can I change the background colour of the icons and desk items?
<p>

The background colour of icons used when the window manager iconifies
a window can be set in the configuration file "System". The variable
you are looking for is tkdesk(color,icon_background). By setting this
variable to the same colour as your root window you can achieve the
effect of transparent icons. You can define the colour either as a
normal name (such as "grey", "blue") or in the form &num;rrggbb.

<sect1>
How can I have a different set of desk items on each virtual screen? 
<p>

(This answer applies to fvwm, but should be transferable to other
virtual window managers.)

First, you have to set the variable
<tt>tkdesk(desk_items,wm_managed)</tt> in the System config file to 1.
Then you have to configure fvwm to not decorate windows of class
<tt>dsk_DeskItem</tt>. For instance:
<tscreen><verb>
Style "dsk_DeskItem"    NoTitle, NoHandles, WindowListSkip, BorderWidth 0
</verb></tscreen>

<sect1>
Binding to execute (export foo=bar; program;) doesn't work.
<p>

Yes, this is a bit tricky. What you need to do is the following:

<tscreen><verb>
dsk_exec sh -c {export foo=bar; program}
</verb></tscreen>

<sect1>
I'd like TkDesk to do this and that. How can I achieve this?
<p>

The first place to start are the various configuration files of TkDesk.
These can be accessed either by the "TkDesk/Edit Config Files" menu
of the file browser windows, or by the "Configuration" submenu of the
popup menu of the very first button of the application bar of TkDesk.
<tt>:-)</tt>

Since TkDesk uses Tcl as the language for its configuration, and these
configuration files are simply "source"ed, you could add any sort of
Tcl proc for instance to the configuration file "System". This proc
would then be available in every other configuration file as well.
With the set of commands provided by TkDesk, which are listed e.g.
in the configuration file "Popups", TkDesk provides a very powerful
platform for the user who knows Tcl.

<sect1> Is there a TkDesk mailing list? <p>

Yes! Thanks to Chris Sterritt, there is a mailing list dedicated to
TkDesk at mrj.com.  Just send a mail to
<tt><htmlurl url="mailto:majordomo@mrj.com" name="majordomo@mrj.com"></tt>
with an empty subject line and &dquot;subscribe tkdesk&dquot; as the
message body. Please join!

<sect1>
Where can I find out more about Tcl/Tk?
<label id="tcltk">
<p>

The official Tcl/Tk homepage is at
<tt><url url="http://www.sunlabs.com/research/tcl"></tt>.
The Tcl/Tk FAQs and lots of user-contributed software can be obtained
from <tt><url url="ftp://ftp.neosoft.com/pub/tcl"></tt>.
There is also a newsgroup dedicated
to Tcl/Tk: <tt><htmlurl url="news:comp.lang.tcl" name="comp.lang.tcl"></tt>.

<sect> Tips and Tricks <p>

This section currently contains just one tip on how to combine TkDesk
and XEmacs. If <bf>you</bf> have any procs or other stuff in your
configuration file which you consider could be useful for others as
well, or just think it's generally cool, please send me an email, so
that I can add it to this section! Thanks!

<sect1> TkDesk and XEmacs <p>

If you are using XEmacs 19.12 or later you can couple TkDesk and
XEmacs quite closely together by adding the following proc 
into any of your configuration files (I have it in
&dquot;Popups&dquot;):

<tscreen><code>
proc xemacs_load {what {where same}} {
    switch $where {
    	"same" {
  	    exec gnudoit -q (find-file \"$what\")
    	}
    	"other" {
  	    exec gnudoit -q (find-file-other-window \"$what\")
    	}
    	"frame" {
  	    exec gnudoit -q (find-file-other-frame \"$what\")
    	}
    	"scratch" {
  	    exec gnudoit -q (switch-to-buffer-other-frame \"*scratch*\")
    	}
    }
}
</code></tscreen>

And now my generic popup menu for files matching <tt>*</tt> reads:

<tscreen><code>
    {{*} {
	{{Edit} {dsk_edit %s}}
	{{XEmacs} {xemacs_load %s}}
	{{Other Window} {xemacs_load %s other}}
	{{Other Frame} {xemacs_load %s frame}}
	-
	{{Print} {dsk_print %s}}
    }}
</code></tscreen>

This way you can load files from TkDesk into a running XEmacs! This
assumes that you have the command <tt>gnudoit</tt> somewhere in your
path, and have started the XEmacs server. This can be done by adding
the following line to your <tt>~/.emacs</tt>:

<tscreen><verb>
(gnuserv-start)
</verb></tscreen>

Like that? Stay tuned for more...

</article>

