                                heirarchy 0.1

                    A Heirarchy drawing package for Tk/Tcl 


In the last few days I have been working on a widget to draw
heirarchies such as directory structures.  If you have used
Microsoft's File Manager you may seem some similarities.  The
1000 lines of Tk/Tcl code below are the result.

My use for this widget is not as a file manager, but it would
be good as a basis for one (even if a little slow... but hey, call
it a prototype...).  Also, it may be good for something showing
the heirarchy of mail folders in "exmh".

I have called this version "0.1".  If there is interest, I will
maintain and extend this package according to people's requirements
and my time availability.  If you use the package, please mail me
(Donald.Syme@cl.cam.ac.uk) and let me know so I can know at what
level I should maintain it.  

I have placed this package in the tcl-contrib site "incoming"
directory, so it should be available there soon.

If someone looking after one of the existing 
libraries of Tcl-coded "widgets" wants to consume this 
package into theirs and take it over, let me know and we can cut 
a deal!

Features:

	- Adds a Tcl-coded widget command called "heirarchy".  This
	is for displaying tree shaped information starting with a root
	node.  A bitmap and text label may be displayed at each root node.
	The bitmaps shown may be context dependent on the particular
	node.

	- The nodes of the tree may be collapsed and expanded.  An initial
	depth of expansion (or "all") may be given.
	This is done by double-clicking on the nodes

	- REALLY NIFTY: The same code can be used to orient the
	tree in EIGHT different ways, according to the eight different
	anchor points n, nw, w, sw, s, se, e and ne.  For instance,
	a typical family tree is oriented using the anchor "s" (south).
	In this case the tree extends upward with the root in the
	middle bottom of the screen.  With one word change you
	can anchor it in a fashion similar to MS File Manager using
	anchor "nw" (northwest, with the root in the top-right corner
	of the screen).

	- The widget can represent any of your tree-shaped information.
	The default is to display directory heirarchies, again like
	a file manager.  If you have
	your own type of heirarchy, for instance an ancestral tree,
	then you just supply these three configuration options:
		-rootnode	The name of the root node of the tree
		-nodechildren	A command which returns the children
				of a given node

		-nodelook	A command which returns the text and
				bitmap to display at the node, as well
				as fonts and colors to use to display
				it.


	- Nodes on the heirarchy can be selected.  Single
	or multiple selection is specified by the configuration option
		-multiselect
	
	A selection feature "-commonselect" is also available where
	nodes with identical names are all selected at once if any
	one of them is selected.  This is useful if elements in the
	tree really refer to the same logical structures.

	- Bindings can be added to nodes by calling
		heirarchy::bindnode
	The following substitution is available in addition to others:
		%n	the "path" to the node at which the action takes
			place.

	- The widget is quite clever at keeping the "area of activity"
	within the widget's window.  For instance, when a node is
	collapsed/expanded the node that is being acted on is kept
	at the same place on the screen regardless of what other
	changes occur in the layout of the heirarchy.

	- A global variable called "busy" is set to 1 whenever
	heirarchy code is executing, and set to 0 when it stops
	again.  This enables you to put a watch on this
	variable to do things like changing the cursor.

Performance:
	It can be slow, particularly as the tree gets bigger and bigger.
	It optimizes quite well in places but in many situations 
	can't help but chew through the cycles.  There are other 
	optimization which can be made which will reduce
	the redraw time considerabley, but they didn't make
	it to the first pass.


Documentation:
	See the header to the function in the code itself for the
	most complete documentation on the options available
	when creating a heirarchy widget.