//@Man: Introduction
/**
The Be application kit is a good start, but some of the more advanced control types are missing. 
This package attempts to plug one of the gaps.
Sometimes it is nice to view data in a tree structured way.  Several mechanisms can be used, but if
the stucture is important then the most natural way is to simply show the tree as a preorder indented list.

The features supported by this control are:

\begin{itemize}
\item Display of a heirarchically organized list
\item User control over expansion or contraction of branches of the tree
\item Programmer defined single or multiple selection within the list
\item Notification of actions such as double-clicking
\item Graphical representation of tree structure and item types
\end{itemize}
*/

//@Man: User Interface
/**
The appearance and behaviour of the list can be modified significantly by the programmer but if
used without any modification the list has an inherent look and feel.  The default appearance uses lines, boxes,
icons and text to provide a visually stimulating view of the list.  There is an alternative look that borrows from
what I presume is a Maclike look (aka, boring).  What is described in detail here is the more adorned look.

The tree list has vertical and horizontal scrollbars with the obvious uses, these scroll the list itself which
contains the items.  Each item is either a root item (a list may have multiple roots), or a child item.  Any item
may itself be a parent to other child items.  Any item that has children is displayed with a little exploder box
that can be used to control whether its children are shown or hidden.

Individual items are shown as an icon as well as an optional text string.  The icon is intended to indicate the
type of the item in the same way as the browser does, unlike the browser the icon may be any size the programmer
wishes, and sizes may be mixed within a list.  The text string is intended to display the name
of the icon.  Selection affects the way the list items are shown.  If it is selected then the icon is shown with subdued
colors and the text is shown in inverted colors.  In addition to selection (which may be multiple), the "current"
item is indicated by drawing a samll marker to the left og the item.  Only one item may be "current", and this is
usually the last item clicked on.  The notion of of the current item is that it is the focus of the list and any
keyboard operations apply relative to that item.

The keyboard interface allows the list to be used by the mouse-impaired.  This is a list of
keys.

\begin{description}
\item[up-arrow, down-arrow] Move up and down the list (well, what did you expect?)
\item[left-arrow, right-arrow] Explode and collapse children
\item[enter] Invoke, the keyboard equivalent of double-clicking
\item[space] Select, the keyboard equivalent of single-click
\item[shift] Extend selection
\end{description}
 
*/

//@Man: Programmer Interface
/**
There are two key classes, \Ref{TreeList} and \Ref{TreeItem}.
A TreeList is
derived from BControl and is the thing you need to create as a
child view of one of your views.  The TreeList organizes a horizontal
and vertical scroll bar, as well as a target view containing the
graphics of the list.  One or more TreeItems should be added to the
TreeList.  These are displayed as the roots of the tree.  TreeItems
can also be added as children of other TreeItems, this is how the
tree structure is created.

There is a supporting class
\Ref{TreeView}, which is a child view of TreeList and is used to render the
graphics.
*/

//@Man: Xyzzy
/**
For jeers, cheers and unsolicited gifts try mailing
me, Andy Philpotts, at \URL[xyzzy@pobox.com]{mailto:xyzzy@pobox.com}.  You can also browse my
\URL[web page]{http:\\www.pobox.com\~xyzzy}.

When reporting bugs please be sure to send me full details including your inside leg measurement,
hat size, favorite color, political affiliation and most importantly,
your birthsign, otherwise there is little I can do to reproduce your problem, thanks.
*/

