<!doctype linuxdoc system>

<article>

<!-- Title information -->

<title>TkDesk User's Guide
<author>Originally written by Christian Bolik,
now maintained by J. Chris Coppick, <tt>jchris@users.sourceforge.net</tt>
<date>Version 2.0, 15 April 2004
<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 configuration
possibilities offered by TkDesk.  Please also take a look at the
CHANGES file for latest news.  A list of answers to frequently asked
questions is also included.  The TkDesk homepage is at
<tt><url url="http://tkdesk.sourceforge.net">.</tt>
</abstract>

<!-- Table of contents -->

<toc>

<!-- Begin the document -->

<!-- ********************************************************************** -->
<!-- ********************************************************************** -->

<sect> Introduction <p>

TkDesk is a graphical desktop manager for UNIX (with a slight emphasis
on Linux, but it also runs just as well on AIX, Solaris, HP-UX, SGI
Irix and other UNIX flavors) and the X
Window System.   It offers a very
complete set of file operations and services, plus gives the user
the ability to configure most aspects of TkDesk in a very powerful
way.  The reason for this is the use of the Tcl scripting language
as the configuration and (for the greatest part of TkDesk) implementation
language.  This makes TkDesk not just configurable but truly
<it>programmable</it>.
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, age,
or other criteria,
<item> A 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> Remote control of XEmacs,
<item> Close coupling with Netscape Navigator for displaying HTML files or
selected URLs,
<item> Sound support,
<item> Powerful on-the-fly configuration of nearly all aspect of TkDesk using
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>

Christian Bolik writes:

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 the old location 
<tt><htmlurl url="mailto:majordomo@mrj.com" name="majordomo@mrj.com"></tt>
<item> Alan V. Shackelford for seamlessly taking over the list to his
machine and responsibility (the list is now at
<tt><htmlurl url="mailto:majordomo@shaknet.clark.net"
name="majordomo@shaknet.clark.net"></tt>),
<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 check menu entry <tt>Options/Use Netscape for Help</tt>,
TkDesk will use that for displaying
this User's Guide on-line.  Otherwise, to reduce overhead, TkDesk
uses its own help system.  It features
hypertext links, context sensitivity (which is not yet fully utilised by
TkDesk) and full text search. 

The help window consists of four areas:

<enum>
<item> A <bf>listbox</bf> listing all the section headings.  A section can be
selected by pressing the left mouse button,
<item> the <bf>text display</bf>, which contains the actual help text,
<item> a <bf>text entry field</bf> in which
a regular expression may 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, 
<item> three <bf>buttons</bf>: &dquot;Print&dquot; prints the complete help
volume, &dquot;Back&dquot; jumps back after a hypertext
link has been followed (see next paragraph), and &dquot;Close&dquot;
to close the help window.
</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.  You 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.  However, you may specify the following options
to this command:

<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>-iconic</tag> Iconifies all file browser and file list windows
created by TkDesk during start-up.
<tag>-layout <it>file</it></tag> Reads the window layout information from
file <it>file</it> instead of the default <tt>~/.tkdesk/_layout</tt>.
<tag>-startdir <it>dir</it></tag> If this option is given,
the first file browser will open with directory <it>dir</it>.
<tag>-twm</tag> Don't use icon windows when file browser or list
windows are iconified.  Some window managers liek twm cannot handle
these properly.
</descrip>

For example, the command &dquot;<tt>tkdesk -twm -iconic</tt>&dquot;
tells Tkdesk to not use icon windows and start 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 configurable button bar (for fast
access to the most often used file operations and other functions),
an entry field (displaying the current path),
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 Menu <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.  By
default the checkbox &dquot;In Browser&dquot; is checked, but if you
uncheck it a file list window will be opened instead.  The button to
the right of the text entry field gives access to a menu containing
previously visited directories.

<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>Display AppBar/Hide AppBar</tag>
Opens the application bar if it had been closed before, or hides
(closes) it otherwise.  This menu entry's label changes based on
whether the AppBar is currently displayed or not.

<tag>Configuration</tag>
This is a submenu from which individual or all configuration files of
TkDesk can be opened to modify them.

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

</descrip>

<!-- ********************************************************************** -->

<sect2> File Menu <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.  If
&dquot;Open in Editor&dquot; is checked the new file will
automatically be opened in the configured editor.

<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.  If
&dquot;Open after Creation&dquot; is checked the current window will
switch to the new directory after it is created.

<tag>Open</tag> Opens the selected files using their default action,
which corresponds to the first action defined in their popup menus as
configured in the &dquot;Popups&dquot; configuration file.

<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>Copy, Move, Link...</tag> Opens a dialog box for copying, moving,
linking, symbolic linking etc. of files.  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>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>Copy Names Only</tag>
Same as previous one, but copies only the files' names (i.e. not their
paths.)

<tag>History</tag>
Displays a submenu containing recently opened files.

<tag>Close Window</tag>
Closes the window.

</descrip>

<!-- ********************************************************************** -->

<sect2> Directory Menu <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><it>A number of path entries</it></tag>
These can be configured in 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 &dquot;Control&dquot; 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.  <bf>This feature applies to all menus that contain
directory names!</bf>

<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>Open Trash Can</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 Can</tag> Empties the trash can after confirmation from
the user.  <bf>This erases the files contained in the trash can for
good!</bf>

<tag>History</tag>
Displays a submenu containing recently opened directories.

</descrip>


<!-- ********************************************************************** -->

<sect2> Commands Menu <p>

This menu provides entries to execute commands either once or
periodically, edit files, and provides some very basic form of
&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.  Checking the
&dquot;View Output&dquot; button will open an editor window after the
command completed displaying its output (stdout and stderr).

<tag>Execute as root...</tag>
The same as the previous entry but TkDesk will ask you for the root
password before executing the command.  The command will then run
under root permission.

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

<tag>Environment...</tag> Opens the &dquot;Edit Environment&dquot;
dialog which can be used to display and modify TkDesk's environment
variables.  Programs and commands started from TkDesk after any
modification in this dialog has been made
will pick up the modified environment.

<tag>Edit File...</tag>
Asks for the name of a file to edit, and opens it in the editor you
selected in the &dquot;System&dquot; configuration file (defaults to
the built-in editor).  The &dquot;Browse...&dquot; button opens a file
selector from which a file may be selected.

<tag>New File</tag>
Opens a new blank editor window.

<tag>Edit Selected</tag>
Opens all currently selected files in one new editor window.

<tag>Buffers</tag>
Displays a submenu of all current editor buffers (both files and
command output).

<tag><it>A number of custom command entries</it></tag> 
These 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.

<tag>History</tag> 
Displays a submenu containing commands recently executed.

</descrip>


<!-- ********************************************************************** -->

<sect2> Bookmarks Menu <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 Menu <p>

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

<descrip>

<tag>Long Listing</tag> Select this to let the details of all files
and directories be displayed in the file listboxes.  This slightly
decreases performance and for that reason is switched off by default.

<tag>Show All Files</tag> Whether to show files in the file
lists whose name start with &dquot;.&dquot;.

<tag>Add Icons</tag> If selected, small icons will be displayed to the
left of the file names in the file listboxes.  Turn this off for
faster scrolling.

<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 automatically 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>Control</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>Status in List Windows</tag> Whether the singly columned file
list windows should have a status bar as well.

<tag>Sort by ...</tag>
Sort all file listboxes by one of these criteria: Name, Name (fold,
meaning that upper and lower case characters will be
&dquot;folded&dquot;, i.e. disregard case when sorting), Size, Date,
Extension, or Don't Sort to display directory entries as they are read
from disk.

<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;Delete permanently&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>TkDesk Server</tag> Start or stop the built-in server to remote
execute TkDesk commands.  See also section
<ref id="server" name="Using the TkDesk Server">. 

<tag>Dialogs at Pointer</tag> If selected, TkDesk will always try to
place new windows right under the mouse pointer.

<tag>Autoraise AppBar</tag> Whether to raise the AppBar above any
obscuring window when it is entered by the mouse pointer.

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

<tag>Balloon Help</tag> Whether to display a small window at the mouse
pointer if it is placed over part of TkDesk, e.g. an AppBar button.

<tag>Use Netscape for Help</tag> Whether to use Netscape rather than
the built-in help viewer for displaying TkDesk online help.

</descrip>

The settings of these options are by default automatically saved to
<tt>~/.tkdesk/_options</tt>.
This can be disabled by deselecting the &dquot;Options&dquot; entry of
the &dquot;TkDesk/Auto Save&dquot; submenu.


<!-- ********************************************************************** -->

<sect2> Help Menu <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:

<descrip>
<tag>User's Guide</tag> Displays the TkDesk User's Guide either in the
built-in help viewer or using Netscape (see previous section).

<tag>Manual Page...</tag> Asks for a command for which to display the
system's manual page in an editor window.

<tag>Getting Started</tag> Displays the &dquot;Getting Started&dquot;
guide.

<tag>TkDesk FAQ</tag> Jumps directly to the FAQ section of the TkDesk
help volume.

<tag>Changes</tag> Displays recent changes to TkDesk.  Make sure you
invoke this entry after upgrading to a newer version of TkDesk.

<tag>License</tag> Restates that TkDesk is distributed under the GNU
Public License (GPL).

<tag>About TkDesk...</tag> Some info about TkDesk (version, author
etc.), plus a link to the TkDesk web page.
</descrip>


<!-- ********************************************************************** -->

<sect1> The Button Bar <p>

The button bar that's located right underneath the menu bar allows for
fast access to any of the commands of TkDesk.  It's also possible to
configure each button individually to run customized Tcl scripts, that
e.g. work on the currently selected files.  By default, the buttons in
the button bar provide access to the more often used functions of
TkDesk (copy, create, delete etc.).  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.  Note that by not defining
the variable <tt>tkdesk(button_bar)</tt> in that file or by not
defining <tt>tkdesk(small_button_bar)</tt> the button for file viewer
or list windows may be surpressed respectively.


<!-- ********************************************************************** -->

<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 <tt>Control-Tab</tt>, its name will be automatically completed
as far as there's no ambiguity.

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 and their subdirectories.  You can also open files
directly from this popup menu.

The button to the right of the entry field contains a menu of the last
30 (default value this may be changed in the &dquot;System&dquot;
configuration file) 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; to open the selected path in a new list
window that's been described in section
<ref id="dir" name="Directories"> works here as well!


<!-- ********************************************************************** -->

<sect1> The File Listboxes <p>

The main part of the file browser and list windows is
taken up by 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 as well as the color, font and icons used for
individual file types may 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.

Right above each listbox the name of the directory whose contents it
shows is displayed, together with the current file mask settings.
Clicking on this label reveals a menu with the following entries:

<descrip>
<tag>Refresh</tag> 
Refreshes the listbox contents.  Although TkDesk refreshes all its file
lists every 5 seconds (default), sometimes you may want to have a file
listbox instantaneously updated.

<tag>Set Mask...</tag> 
Sets a mask for this listbox's display.  For example, you can
configure the listbox to only display or select files matching the pattern
<tt>*.gif</tt>.  Multiple masks separated by spaces may be entered to
display files matching any of these.  A history menu button for
reusing masks previously entered is also provided, as well as a
checkbutton for inverting the mask's effect (i.e. only files <bf>not</bf>
matching the given mask will be displayed).

<tag>No Mask</tag>
Removes a previously activated file mask.

<tag>Disk Usage</tag> 
Calculates the directory's disk usage, i.e. the number of
kilobytes (default)
occupied by that directory and all its subdirectories.  A window
will appear when the calculation is complete, 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.  Clicking the right mouse button over any of the
directories displays its associated popup menu.

<tag>Free Space</tag>
Displays the space available in the file system of this listbox's
directory, using TkDesk's &dquot;Periodic Execution&dquot; window.

<tag>Execute here...</tag>
Asks for a command to execute in the directory displayed by this
listbox.  All the usual TkDesk &percnt;-sequences to work with the
names of selected files may be used, e.g. <tt>&percnt;A</tt> to pass
all currently selected files to the command.

<tag>Execute as root...</tag>
The same as the previous one, except the command will be run under
root permission after asking you for the root password (and you
entered the correct one...).


<tag>Long Listing</tag>
Instead of just the file names displays a &dquot;long listing&dquot;
i.e. a listing containing all the details such as size, permission
bits, date and time of last modification etc.

<tag>Show All Files</tag>
Whether to display files starting with a dot (&dquot;.&dquot;) or not.

<tag>Inverse Order</tag>
Whether to invert the current sorting order.

<tag>Sort by...</tag>
This is identical to the entry of the same name in the menu bar's
&dquot;Options&dquot; menu, but affects this single listbox only.

<tag>Open List Window</tag>
If this listbox is part of a file browser window, open a new list
window displaying this listbox's directory.

<tag>Open Browser</tag>
Else, open a browser with this directory.
</descrip>

This menubutton can also be used to drag and drop files,
as well as to drag the
directory displayed in the associated listbox to another target, e.g.
the root window by pressing the middle mouse button over the listbox
title menu button.


<!-- ********************************************************************** -->

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

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

Files are selected in the file listboxes using
the left mouse button.  A single click selects
a single file, deselecting all other files. If the Control 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.  Holding down
the shift button extends the current selection unto that file
(a.k.a. &dquot;range-selection&dquot;).

Note that if the option &dquot;Single Click (Dirs)&dquot; is set in
the &dquot;Options&dquot; menu a
single click on a directory will suffice open it. In this case
you need to use
Control-Click to select a single directory.

A double click on any listbox item performs its default action.  For
directories this is to open it, for executables this is to execute
it, and for files it invokes the first entry of the corresponding popup
menu as defined in the &dquot;Popups&dquot; configuration file
(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 over any
selected file. If no file is selected, the clicked-over 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
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.

The file listboxes may also be fully controlled using the keyboard:

<descrip>
<tag>Up-/Down Arrow</tag>
Move the selection one file up/down.
<tag>Page Up/Down</tag>
Move the selection one page up/down.
<tag>Home/End</tag>
Move the selection to first/last item in the listbox.
<tag>A-Z</tag>
Select the first file matching the character pressed, cycle through
subsequent matches on repeated pressing of the same key.
<tag>Return</tag>
Open selected file.
<tag>Menu (the key left to the right Control key on W95
keyboards)</tag>
Display the currently selected file's popup menu, the menu itself may
also be operated using Up/Down, Return, and Esc.
<tag>Backspace</tag>
Change directory to the parent directory.
<tag>F11</tag>
Open the current file listbox's menu.
</descrip>


<!-- ********************************************************************** -->

<sect1> The Status Bar <p>

The status bar is located at the bottom edge of file browser windows.
If &dquot;Status in List Windows&dquot; is selected in the
&dquot;Options&dquot; menu file list windows will contain a status bar
as well.

It displays either

<itemize>
<item> the current state of TkDesk,
<item> the amount of free space in the current file system,
<item> details about the currently selected file, or
<item> number and total 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 unless
&dquot;Status in List Windows&dquot; is set in the
&dquot;Options&dquot; menu.  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;
buttons 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.  Note that using the right mouse button toggles
between <tt>-</tt> and <tt>x</tt> only.  Clicking the middle mouse
button over any of these buttons copies its current setting to the
corresponding button in the other two groups.
If the settings of 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.  Files having annotations
attached to them will appear underlined in the file listboxes, and
their popup menu will contain the first few words of that annotation
as an &dquot;informative&dquot; menu entry.

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,
among others.  There is
one dialog for copying, moving and linking files (plus an arbitrary
number of user-defined actions such as diff and patch, as configured in the
&dquot;Popups&dquot; config file), 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 that one file was
selected when this dialog was opened.  If this
checkbutton is selected (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;Delete permanently&dquot;.  If this checkbutton is
selected, the files will <it>not</it> be moved to the trash can but
will be <bf>really and ultimately 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 names match one or multiple patterns,
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> Cascading Directory Popup Menus  <p>

Ugh, what a title...  However, one of the most powerful features of
TkDesk are its &dquot;cascading directory popup menus.&dquot;  These
are menus that start from a given directory, contain submenus for each
subdirectories (and possibly menu entries for files), and that
dynamically add submenus as you traverse the menu.  Hm, kinda hard to
explain, but pretty cool.
These menus
are the ones that are accessible through menu entries
&dquot;Directory/ Trees/ Home&dquot; and &dquot;Root&dquot;, by
clicking the right mouse button in the file browser and list window's
path entry field, and through the popup menus of directories (submenu
&dquot;Subdirectories&dquot; and &dquot;... and Files&dquot;).  They
may also appear in other places, depending on your configuration of
TkDesk.

There are two special bindings available in these menus:

<descrip>
<tag>Control-Mousebutton-Release</tag>
On a menu entry associated with a directory this opens a new file list
window displaying this directory's contents.  On a file it asks for a
command to run on this file by displaying the &dquot;Open or
Execute&dquot; dialog.
<tag>Left-and-Right-Mousebutton-Press</tag>
If the left and right mousebuttons are pressed simultaneously over a
menu entry, the menu disappear, the popup menu for the associated file
or directory is displayed.
</descrip>

Otherwise the directory or file that's selected from the menu is
opened using its default command.

<!-- ********************************************************************** -->
<!-- ********************************************************************** -->

<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
and dialup link.
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
entry from the corresponding popup menu defining a command to execute
will be invoked.

The first button (displaying a small desk by default) could be called TkDesk's
&dquot;Start Button&dquot;.  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 second button gives you access to this User's Guide,
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.  Note
that the default value of the &dquot;Manual Page&dquot; dialog is the
contents of the current X selection, so this can be used for some sort
of &dquot;context sensitive&dquot; help.

Keep in mind that all the 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.
<tag>Buffers</tag> Lists the buffers of the editor window. Buffers can
be selected from this menu.
<tag>Configuration</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 be edited and reloaded very quickly 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.


<!-- ********************************************************************** -->

<sect1> Marks <p>
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>.  They work across buffer and editor window
boundaries, and are currently only valid as long as the buffer in
which the mark was set is open.


<!-- ********************************************************************** -->
<!-- ********************************************************************** -->

<sect> Using the TkDesk Server <label id="server"><p>

In order to allow remote control of TkDesk, i.e. to allow programs
outside of TkDesk to have TkDesk perform certain tasks, TkDesk
implements a TCP/IP server that can be used to send Tcl scripts to
TkDesk.  Whether this server is &dquot;up&dquot; or not is
determined by the option &dquot;TkDesk Server&dquot; that is to be
found in the &dquot;Options&dquot; menu.  Currently, only programs
running on the same machine as TkDesk may connect to the server,
but multiple TkDesk servers started from different users may be
running at the same time.

The server is a much faster way to send command to TkDesk then to use
the Tcl/Tk <tt>send</tt> command, as that requires a second Tcl/Tk
shell (&dquot;wish&dquot;) to be started to do the send.  However,
using a TCP/IP server that's basically system-wide accessible to
perform arbitrary command under the accout of the user who started
TkDesk and thus the server brings with quite a big security risk that
TkDesk tries to reduce by keeping the port the TkDesk server uses
secret.  The port to be used is calculated randomly at server
start-up, and is saved into a file that can only be read by the user
who started TkDesk.  To prevent &dquot;guessing&dquot; of the port
number a generated key is also stored in this file that get
passed to the server.

The client performing the communication with the TkDesk server gets
installed with TkDesk; its name is <tt>tkdeskclient</tt>.  This
command expects exactly one argument which will be directly sent to
the server and evaluated there as a Tcl script.  E.g. you could do a
<tscreen><verb>
	tkdeskclient "dsk_view id"
</verb></tscreen>
to find out who you are <tt>:-)</tt>.

Along with TkDesk a number of front-end shell scripts for
<tt>tkdeskclient</tt> are
installed, which comprise of the following:

<descrip>
<tag>cd-tkdesk <it>?path?</it></tag>
Let's the currently active TkDesk file list or browser window
(i.e. the one the mouse pointer was over last) change its directory to
<it>path</it> if <it>path</it> is given, or returns the current
directory of the active window.

<tag>ed-tkdesk <it>?+linenum? ?file? ...</it></tag>
Without argument opens a new editor window, or loads all files given
as arguments into the editor (and into the same window if you're using
a multi-buffer capable editor, such as the built-in one).  If a file
is preceded by <it>+linenum</it>, i.e. something like <it>+20</it>,
the built-in editor will position the cursor on the line when
displaying the file that's given in the following argument.

<tag>od-tkdesk <it>?dir?</it></tag>
If no arguments are given opens a file list window for the current
directory of the shell/program where the command was issued, or opens
a window for the directory specied in <it>dir</it>.

<tag>op-tkdesk <it>?file ...?</it></tag>
For each <it>file</it> performs its default action (the one defined first in
its corresponding popup menu as defined in &dquot;Popups&dquot;), or
asks for a command to execute if no files are given.

<tag>pop-tkdesk <it>file</it></tag>
Displays the popup menu for <it>file</it>, as defined in the
&dquot;Popups&dquot; config file.  The popup menu may also be controlled by
the keyboard: Up, Down, Return, and Esc keys do what you would expect.
</descrip>

Note that all of these scripts are merely examples of possible usages of
<tt>tkdeskclient</tt>.  Use your imagination to find new and even more exciting
applications! <tt>:-)</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.  GUI based configuration
is planned for one of the next releases.

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 and others have provided.
And to those who want to exploit
all of the power available by using Tcl/Tk as TkDesk's configuration
language, please 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 <tt>Configuration</tt> submenu, or from the
&dquot;Configuration&dquot; submenu of the popup menu of the
application bar's first button.  The built-in editor
will then appear with the selected configuration file(s)
already loaded.  Each configuration file contains pretty 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 by making use of the entries of
the editor's &dquot;Configuration&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.

As already mentioned, each configuration file contains directions on
how to modify its definitions.  The general advice is: Simply look at
the example definitions, because these make things a great deal
clearer than any explanation can.

<bf>Tip:</bf>
In case your looking for the definition of a specific part of TkDesk,
e.g. for the popup menu of <tt>pdf</tt> files, use the
&dquot;Find...&dquot; entry in the &dquot;Configuration&dquot; menu.
Just enter <tt>pdf</tt> in the &dquot;String:&dquot; field, hit enter,
and double-click the found file.

<sect1> Configuration Files <p>

All of these are &dquot;sourced&dquot; (i.e. processed) by TkDesk
during start-up.  This happens in the following order:

<enum>
<item> System
<item> ButtonBar
<item> Preferences
<item> FileTags
<item> Commands
<item> Directories
<item> Popups
<item> AppBar
<item> Sounds
<item> Local (if existent) 
</enum>

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

This configuration file lets you define all aspects of the application
bar (apart from its layout, use the entries of the submenu
&dquot;Application Bar&dquot; of the desk-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.  This is disabled by default.
<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> Period in seconds after which to update the system load and
mailbox displays, where to check for new mail, plus several additional
mail related options.
<item> Icons and commands to use for the dial-up networking button.
<item> Icons and fonts to use for the trash button, and whether to
display its current disk usage in the appbar.
<item> The actual button definitions, ie. which image to display, and
the entries of the (possibly cascaded) popup menu. See below
for the syntax used.
</itemize>


<sect2> 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
(<tt>tkdesk(button_bar)</tt>)
or file list windows (tkdesk(small_button_bar).
Both button bars are configured independently
from one another.

The third list defined here (<tt>tkdesk(dir_button_bar)</tt>) is for
directory-specific button bars which will be dynamically displayed and
hidden when the respective directory is entered or left.  These will
be displayed in addition to the standard button bar.

<sect2> 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, manage RPM package files, or do whatever you can possibly imagine.

<sect2> 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 floppies and CDROM's.

<sect2> FileTags <p>

Contains definitions for color and font of specific file types
(as distinguished by their extension) as well as standard values for
regular files, executables, and directories, 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. 

<sect2> Local <p>

This file does not exist when TkDesk gets installed, but still appears
in the &dquot;Configuration&dquot; menu.  This is because if it exists
it will be sourced during start-up of TkDesk, so this is the ideal
place to put local extensions of TkDesk.

<sect2> 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.  To find the correct popup menu for a file TkDesk checks
the mask of each entry of a popup list one after the other from the
beginning of the list to its end, so the
masks should become more general towards the end of the list.

An additional popup list (<tt>tkdesk(fileops,popup)</tt>) may be
defined here for use in the &dquot;Copy, Move, etc.&dquot; dialog.

<sect2> 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 AU 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.

<sect2> System <p>

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

<itemize>
<item> Colours and fonts to be used by TkDesk,
<item> Default size of file listboxes,
<item> Definitions of shell commands which are used by TkDesk to copy,
move, delete, etc. files. These should be fine as they are in most
cases,
but you may want to tweak them for your system, so take a look at
these definitions.
<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> Whether to use &dquot;focus follows mouse&dquot; default or not,
<item> Settings for the desk items, e.g. whether to let them be
managed by the window manager,
<item> Commands to execute after start-up and before shutdown (of TkDesk).
</itemize>


<sect1> The TkDesk API <p>

Many of the values to be specified for TkDesk's configuration files
are Tcl scripts.  Also, you can define your own Tcl proc's to
use in these scripts.  To allow better control of TkDesk, TkDesk
externalizes a couple of proc's which could be called the &dquot;TkDesk
API&dquot; (although currently they aren't much more then a random set
of more or less useful proc's, but anyway).

The proc's I currently think are part of the API are the following:

<descrip>
<tag>dsk_msg_alert <it>msg</it></tag>
 Display <it>msg</it> in an alert dialog box.
<tag>dsk_msg_error <it>msg</it></tag>
 Display <it>msg</it> in an error dialog box.
<tag>dsk_msg_info <it>msg</it></tag>
 Display <it>msg</it> in an info dialog box.
<tag>dsk_confirm <it>msg</it> <it>script</it></tag>
 Display <it>msg</it> in a dialog box with &dquot;OK&dquot; and
&dquot;Cancel&dquot; buttons.  Evaluate <it>script</it> if user
pressed &dquot;OK&dquot;.
<tag>dsk_debug <it>msg</it></tag>
 If TkDesk runs in development mode (e.g. by setting the
<tt>-devel</tt> command line option) print <it>msg</it> to stderr.

<tag>dsk_ask_dir</tag>
 Ask for a directory to open.
<tag>dsk_ask_exec</tag>
 Ask for a command to execute or file to open.

<tag>dsk_exec <it>command</it></tag>
 Execute <it>command</it> in the background.  When the command
completes its exit code will be displayed in the status bar of all
file browser windows.

<tag>dsk_exec_as_root <it>command</it></tag>
 Asks for the root password, and executes <it>command</it> in the
backgroud under root permission if it was okay.
<tag>dsk_view <it>command</it></tag>
 Execute <it>command</it> in the background and displays its output
(stdout and stderr) in a built-in editor window.
<tag>dsk_view_as_root <it>command</it></tag>
 Same as dsk_view but asks for the root password first.
<tag>dsk_path_exec <it>path command</it></tag>
 Executes <it>command</it> in <it>path</it> and in the background.
<tag>dsk_path_view</tag>
 Executes <it>command</it> in <it>path</it> and in the background, and
displays its output in an editor window.
<tag>dsk_edit <it>?+linenum? ?file? ...</it></tag>
 Without arguments asks for a file to open, or opens all
<it>files</it> in the same editor window, positioning the cursor at
line <it>linenum</it> if given.  If <it>file</it> is &dquot;New
File&dquot; a black editor window will be opened.

<tag>dsk_busy</tag>
 Displays mouse as &dquot;busy&dquot; and locks all TkDesk window from
receiving mouse events.
<tag>dsk_lazy</tag>
 Displays mouse as &dquot;lazy&dquot;, and makes all TkDesk windows
responsive again.

<tag>dsk_active <it>what</it></tag>
 Returns information about the currently active file browser or list
window: If <it>what</it> is &dquot;dir&dquot; it returns its
directory; if it is &dquot;sel&dquot; it returns all selected items as
a Tcl list; if it is &dquot;win&dquot; it returns the Tk name of the
active window.
<tag>dsk_select X ?names?</tag>
If <it>names</it> is not given, copies the full path names of the
files selected in the currently active file browser or list window
to the X selection.  Otherwise just their names are copied.
<tag>dsk_read_string <it>msg</it> <it>?script?</it> ?dontpaste?</tag>
 Displays &dollar;msg in a dialog box where the user can enter an
arbitrary string.  If <it>script</it> is not given, the string will be
returned; if it is given the variable <tt>dsk_read_string</tt> will be
set to the user's input and <it>script</it> will be evaluated.
If &dquot;dontpaste&dquot; is passed as a third argument to this
command the current X selection will not be pasted into the entry
field.

<tag>dsk_filesel <it>message</it> <it>path</it></tag>
 Opens TkDesk file selection dialog using <it>message</it> as the
label, and presetting the entry field with <it>path</it>.
<it>Path</it> is also used as the filter for the full file selection
box.
<tag>dsk_refresh ?file ...?</tag>
 For each <it>file</it> all windows displaying the corresponding
directory is refreshed.  <it>File</it> may also be a directory.
<tag>dsk_sound <it>sound</it></tag>
 Plays <it>sound</it> if a sound command has been defined and sound is
switched on.  <it>Sound</it> is the second index in the
<tt>tkdesk(sound,xxx)</tt> array as defined in the
&dquot;Sounds&dquot; config file (&dquot;xxx&dquot; in this case).

<tag>dsk_copy ?source ...? ?dest?</tag>
 Opens the &dquot;Copy, Move, etc.&dquot; dialog box, filling in
&dquot;Source&dquot; and &dquot;Destination&dquot; fields if provided.
<tag>dsk_dialup <it>phonenumber</it></tag>
 Without arguments asks for a phone number, and passes this to the
command specified in <tt>tkdesk(appbar,dialup,cmd_up)</tt>, else it
does the same without asking.
<tag>dsk_find_files ?options?</tag>
 Opens the &dquot;Find Files&dquot; dialog, presetting its fields from
the <it>options.</it>  The following options are available: -path
<it>path</it>, -mask <it>mask</it>, -string <it>string</it>, -regexp
<it>regexp</it>, -extreg <it>extreg</it>, -type
<it>&dquot;all|file|dir|sym|socket|pipe&dquot;</it>, -owner
<it>owner</it>, -group <it>group</it>, -modified <it>mod</it>,
-accessed <it>acc</it>, -size <it>size</it>, -case, -samefs,
-followsym.  If the option <tt>-doit</tt> is given the search will
start as soon as the dialog is displayed, without having to press
&dquot;Search&dquot;. 
<tag>dsk_mail <it>file</it> <it>?string?</it></tag>
 Asks for an email address where to send <it>file</it>.  If
<it>file</it> is the empty string, <it>string</it> will be sent instead.
<tag>dsk_netscape <it>what</it> <it>?url?</it> <it>?args?</it></tag>
 This proc is used to communicate with a running netscape.  If
Netscape is not running yet it will be started first. <it>What</it>
may be &dquot;file&dquot;, &dquot;url&dquot;, or &dquot;rcmd&dquot;
(Communicator only);
<it>url</it> may be a regular URL, a file name, or, if <it>what</it>
is &dquot;rcmd&dquot;, it may be &dquot;mail&dquot;,
&dquot;news&dquot; or &dquot;edit&dquot;. <it>Args</it> may be
&dquot;window&dquot;, or &dquot;raise&dquot;, or both.
<tag>dsk_periodic <it>command</it> <it>seconds</it></tag>
 Opens the &dquot;Periodic Execution&dquot; window and executes
&dquot;command&dquot; every &dquot;seconds&dquot; seconds.

<tag>dsk_open <it>viewer</it> <it>file</it></tag>
 Opens <it>file</it> by performing its default action.
<it>Viewer</it> should be given as &dquot;&dquot;; I just didn't
manage to get rid of this obsolete argument yet.
<tag>dsk_open_browser <it>dir</it></tag>
 Opens <it>dir</it> in a new file browser window.
<tag>dsk_open_dir <it>dir</it></tag>
 Opens <it>dir</it> in a new file list window (unless the option
&dquot;Always in Browser&dquot; is set).
<tag>dsk_openall <it>?files?</it></tag>
 Opens all <it>files</it> if given, or all currently selected files by
performing their respective default action.
</descrip>


<sect1> Shortcuts <p>

When specifying Tcl scripts in the popup and appbar configuration
lists (<tt>tkdesk(popup,...)</tt> and <tt>tkdesk(appbar)</tt>), and in
some other places as well (precide, hus?), you can use a number of
shortcuts that will be expanded just before evaluation:

<descrip>
<tag>&percnt;s</tag>
 Will be replaced with the full pathname of the first selected file.
<tag>&percnt;f</tag>
 Will be replaced with its filename only.
<tag>&percnt;b</tag>
 Will be replaced with its filename without extension
(&dquot;basename&dquot;).
<!-- This seems to be the same as %b in reality...
<tag>&percnt;c</tag>
 Will be replaced with its full pathname without extension. 
-->
<tag>&percnt;d</tag>
 Will be replaced with its directory only.
<tag>&percnt;A</tag>
 Will be replaced with a Tcl list of the full pathnames of all
currently selected files, or of the files dropped on an appbar button.
<tag>&percnt;a</tag>
 Same as &percnt;a, but replaces with a list of filenames only.
<tag>&percnt;B</tag>
 Same as &percnt;A but doesn't complain if no files are selected.
Instead it will be replaced with the empty string.
<tag>&percnt;D</tag>
 Will be replaced with the directory of the currently active file list
or browser window.
<tag>&percnt;x</tag>
 Will be replaced with the contents of the X selection.
<tag>&percnt;X</tag>
 Same as &percnt;x but doesn't complain if the selection is empty.
<tag>&percnt;S</tag>
 For the &dquot;Copy, Move, etc.&dquot; popup menu; will be replaced
of what's been entered into the &dquot;Source&dquot; text entry field.
<tag>&percnt;D</tag>
 For the same popup menu; will be replaced
of what's been entered into the &dquot;Destination&dquot;
text entry field.

</descrip>


<sect1> Utilities <p>

To make life while configuring TkDesk a little easier as long as
there's no GUI configuration available yet, TkDesk provides four
little &dquot;helper&dquot; tools that help with selecting colors,
fonts, icons, and sounds, by using graphical mouse-based dialog boxes.
These are accessed through the &dquot;Configuration&dquot; menu, and
are basically all handled in the same way.

Each of these dialogs contains three buttons:

<descrip>
<tag>Insert</tag>
 Works only correctly if the dialog was invoked from the editor's
&dquot;Configuration&dquot; menu.  Inserts the current value at the
cursor position in that editor window.
<tag>Select</tag>
 Copies the selected value to the X selection, so it can be pasted at
arbitrary places using the middle mouse button.
<tag>Close</tag>
 Closes the dialog.
</descrip>


<!-- appendix -->

<sect> Frequently Asked Questions <p>

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

The appbar should have a &dquot;handle&dquot; at the
upper or left edge that can be used to drag the appbar around the
screen by just pressing the left mouse button over it.

You can also 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 desk-button's popup menu to do
the same without having to press Alt/Meta.

The application-bar configuration file, &dquot;AppBar&dquot;, allows you
to set 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.  As far as I
know to have transparent icons in X you need to make use of X11's
SHAPE extension.  Now as raw X programming is something only for the
very brave, I didn't look into this any deeper yet.  Any takers?

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

<sect2>
FVWM and similar or derived window managers
<p>

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>

<sect2>
CDE window manager
<p>

As for FVWM, you first have to set the variable
<tt>tkdesk(desk_items,wm_managed)</tt> in the System config file to 1.
To tell the CDE window manager (dtwm) to not decorate desk items you
have to add the following line to either the file Dtwm or .Xdefaults
in your home directory, and then restart dtwm:
<tscreen><verb>
Dtwm*dsk_DeskItem*clientDecoration:  none
</verb></tscreen>

<sect1>
How do I configure FVWM mini-icons for TkDesk?
<p>
For fvwm95's Style command (like fvwm2 from which it comes) you can
use a variety of things to identify a tkdesk window - you don't have
to use the name only; you can also use the window's class name or
resource string.  To find out what the window class and resource
string are for a certain type of tkdesk window, use the FvwmIdent
module (if you use Debian, this will be under the Window
Managers->Modules menu; if you're using the default fvwm95rc that
comes with the fvwm95 distribution, this will be under the
Programs->Modules menu; I don't know about others).
<p>
Anyway, FvwmIdent tells me that the window opened by tkDesk's "Open
Browser..." menu has a class name of dsk_FileViewer, so I open the
FvwmConsole (or FvwmTalk) module, and enter the commands:

<tscreen><verb>
Style dsk_FileViewer TitleIcon mini-filemgr.xpm
Recapture
</verb></tscreen>

Then the browser window appears with the appropriate icon.  To get the 
window opened by the "Open Directory..." menu, use:
Style dsk_FileList TitleIcon mini-filemgr.xpm
<p>
(The "recapture" command is only necessary to apply the command to
windows already open; it isn't necessary in your config. file)
(Contributed by Daniel Martin, <tt>dtm12@jhunix.hcf.jhu.edu</tt>)

<sect1>Configuring the appbar or popup menus 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>
Composing characters doesn't work in TkDesk's editor.
<p>

Currently you have to edit the file cb_tools/bindings.tcl in TkDesk's
library directory to make this work.  Locate the two lines containing
the word &dquot;XKB&dquot;; all you need to do is to comment out the
following lines by prepending a '&num;'.

<sect1> TkDesk's layout seems to be screwed.  I can't get the appbar displayed anymore. <p>

TkDesk saves all layout information in the file ~/.tkdesk/_layout, so
this is the place to look for bad lines.  If in doubt you can safely
delete this file and all should be back to normal.

In case of the appbar not showing up you can try the following (sent by
Jochem Huhmann, joh@unidui.uni-duisburg.de):

<enum>
<item> Quit tkdesk
<item> Open the file ".tkdesk/_layout" within your home directory with your
favorite editor
<item> Delete the line looking like "Toplevel dsk_appbar 1 66x740+956+0"
<item> Write the file back to disk
<item> Restart tkdesk. It will place the AppBar according to its defaults 
now.
<item> Place the AppBar as you like (it doesn't like horizontal layout too
much)
<item> Do a "TkDesk/Save All Now"
</enum>

<sect1> On my RedHat 5.x system the appbar clock shows the wrong time. <p>

This is from Bryan Venable, spif@vousi.com:

This may have to do with the location of the zoneinfo directory.  For libc5
I believe it's /usr/lib/zoneinfo, whereas for glibc it'd be
/usr/share/zoneinfo.  Try making a symbolic link from whichever you have to
whichever you don't.  There is a fix to Red Hat 5.0 which has to do with
this, but in that situation the problem is with libc5 programs running on a
system "optimized" for glibc.

And Raul Quiroga, quiroga@cartan.math.cinvestav.mx, also has got some
advice for this:

Concerning the problem described below I received several suggestions.
Some allowed to get the date in the tkdesk right but an incorrect one with
the date command. Finally what I did is set the time with timeconfig to
Universal with "Hardware clock set to GMT" checked; after a reboot both
the appbar and date reported the correct time. Thanks all for your
help.

<sect1> TkDesk complains about &dquot;invalid command name wm&dquot; and won't start up<p>

There seem to be two solutions to this problem: One is if you're
running on a RedHad Linux 5.x system, the libc5 that's packaged and
installed in /lib may be too old a version.  If <tt>ls
/lib/libc.so.5.*</tt> on your system gives something like
<tt>/lib/libc.so.5.3.xx</tt> you should upgrade to at least 5.4.20.  I
think you can get a newer version of libc from sunsite.unc.edu in
/pub/Linux/GCC.

The other solution that should always work is to do the following
(thanks to Ike Hishikawa, ike@hishikawa.f.uunet.de, for this one):

<tscreen><verb>
Assuming that the tarball was unpacked under /usr/local,
open /usr/local/bin/tkdesk with your favorite editor.
At the very top of the file it should say:

  #!/bin/sh
  #-*- tcl -*- \
  PATH=/usr/local/bin:$PATH ;#\
  exec tkdesksh "$0" "$@"

After the 3rd line, insert two lines pointing to the location of
tcl/tk libs,  so that you get:

  #!/bin/sh
  #-*- tcl -*- \
  PATH=/usr/local/bin:$PATH ;#\
  export TCL_LIBRARY=/usr/local/lib/TkDesk/tcl_lib ;#\
  export TK_LIBRARY=/usr/local/lib/TkDesk/tk_lib ;#\
  exec tkdesksh "$0" "$@"

This did the trick for me :)
Hope this helps,
</verb></tscreen>

<sect1>
I cannot launch other Tcl/Tk applications from within TkDesk
<p>
Probably your version of TkDesk sets the environment variables
TK_LIBRARY and TCL_LIBRARY, which confuses other Tcl/Tk apps.
Unset these variables in the config files before the invocation of
the problematic commands, eg. replace xterm with

<tscreen><verb>
        sh -c {unset TK_LIBRARY TCL_LIBRARY; xterm}
</verb></tscreen>

(contributed by Christoph Dalitz, <tt>dalitz@infotech.de</tt>)

<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/Configuration" 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.

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>

There two mailing lists dedicated to TkDesk, one for discussing general
installation/usage topics (tkdesk-users) and one targeted more for
TkDesk-related development topics (tkdesk-code).  You can subscribe
to the tkdesk-users list here:
<tt><url url="https://lists.sourceforge.net/lists/listinfo/tkdesk-users">.</tt>
To post questions, etc., send email to <tt><htmlurl url="mailto:tkdesk-users@lists.sourceforge.net" name="tkdesk-users@lists.sourceforge.net">.</tt>

It you are interested in contributing to the development of TkDesk, you can
subscribe to the tkdesk-code list here:
<tt><url url="https://lists.sourceforge.net/lists/listinfo/tkdesk-code">.</tt>
Once you have subscribed, you can post using the address <tt><htmlurl url="mailto:tkdesk-code@lists.sourceforge.net" name="tkdesk-code@lists.sourceforge.net">.</tt>

<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.tcl.tk/"></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>

</article>