
_Hierarchical List Control_

hierlists.ss defines hierlist^
hierlistr.ss returns a unit/sig, imports mred^ and 
mzlib:function^ and exports hierlist^
hierlist.ss invoke-opens hierlistr.ss

_hierlist_ defines three classes:

--------------------------------------------------

> hierarchical-list%, derived from editor-canvas%
   
It accepts two initialization arguments. The first
specifies the GUI parent for the control and is
required. The second is the `style' parameter
passed to the super class (editor-canvas%)
and defaults to: '(no-hscroll).


New methods:

>  get-selected :: (send a-list get-selected) - returns #f or an
     instance of hierarchical-list-item<%>

>  new-item :: (send a-list new-item) - creates and returns a new
     (empty) hierarchical-list-item<%>

>  new-item :: (send a-list new-item mixin) - creates and returns
     a new (empty) hierarchical-list-item<%>, but first, applies
     `mixin' to a class implementing hierarchical-list-item<%> and uses
     the result as the class for the new hierarchical-list-item<%>
     object.

> set-no-sublists :: (send a-list set-no-sublists no-sublists?) - 
     avoids space to the left of the list that would normally align
     non-list items with list items; this method can be called only
     when the list is empty

>  new-list :: (send a-list new-list) - creates and returns a new
     (empty) hierarchical-list-compound-item<%>

>  new-list :: (send a-list new-list mixin) - creates and returns
     a new (empty) hierarchical-list-compound-item<%>, but first,
     applies `mixin' to a class implementing
     hierarchical-list-compound-item<%> and uses the result as the
     class for the new hierarchical-list-compound-item<%> object.

>  delete-item :: (send a-list delete-item i) - delete
     hierarchical-list-item<%> i from the list

>  get-items :: (send a-list get-items) - returns a list of the items
     in the list

>  selectable :: (send a-list selectable) - returns #t if items are
     selectable, #f otherwise; default is #t
>  selectable :: (send a-list selectable on?) - sets whether items
     are selectable

>  on-select :: (send a-list on-select i) - called for new select of
     `i', hierarchical-list-item<%> or #f, where #f means that no item
     is selected

>  on-click :: (send a-list on-click i) - called when an item is
     clicked on, but selection for that item is not allowed.
     `i' is a hierarchical-list-item<%>.

     selection can be disallowed by the `set-allow-selection' method
     or by the `selectable' method.
     
>  on-double-select :: (send a-list on-double-select i) - called for
     double-click on hierarchical-list-item<%> `i'

>  on-item-opened :: (send a-list on-item-opened i) - called when the
     arrow for `i' is turned down

>  on-item-closed :: (send a-list on-item-closed i) - called when the
     arrow for `i' is turned up

>  sort :: (send a-list sort less-than-proc [recur?]) - sorts items in
     the list by calling `less-than-proc' on pairs of items; if
     `recur?' is #t (the default), sub-items are sorted recursively

>  can-do-edit-operation? :: (send a-list can-do-edit-operation? sym bool)
     - like the method on editor<%>s; returns #f always

>  do-edit-operation :: (send a-list do-edit-operation sym bool)
     - like the method on editor<%>s; does nothing

>  select-prev :: (send a-list select-prev)
>  select-next :: (send a-list select-next)
>  select-first :: (send a-list select-first)
>  select-last :: (send a-list select-last)
>  select-in :: (send a-list select-in)
>  select-out :: (send a-list select-out)
>  click-select :: (send a-list select i)
>  page-up :: (send a-list page-up)
>  page-down :: (send a-list page-down)
     - Move the selection, scroll, and call on-select

>  select :: (send a-list select i)
     - Like `click-select', but does not call `on-select'
       unless `on-select' is always called (see `on-select-always')

>  on-select-always :: (send on-select-always)
>  on-select-always :: (send on-select-always on?)
     - Gets/sets whether the `on-select' method is called in
       response to `select' (as opposed to `click-select');
       the default is #t

>  allow-deselect :: (send allow-deselect)
>  allow-deselect :: (send allow-deselect on?)
     - Gets/sets whether the `select' can be used with a #f
       argument to deselect the current item (leaving none
       selected); the default is #f

--------------------------------------------------

> hierarchical-list-item<%>, instantiate via new-item

  Methods:

>  get-editor :: (send an-item get-editor) - returns text% editor
     containing the display representation of the item

>  is-selected? :: (send an-item is-selected?) - returns #t or #f

>  click-select :: (send an-item select on?) - selects or deselects
     the item; hierarchical-list%'s `on-select' is called; see also
     `allow-deselect'
>  select :: (send an-item select on?) - like `click-select', 
     but `on-select' might not be called; see `on-select-always'

>  user-data :: (send an-item user-data) - returns user data;
     initialized to #f
>  user-data :: (send an-item user-data v) - sets user data to v

>  get-clickable-snip :: (send an-item get-clickable-snip) -
   returns the snip that (when clicked) selects this element in
   the list. This is intended for use with the automatic test
   suite.

>  get-allow-selection? :: (send an-item get-allow-selection?) -

   returns #t or #f -- dictating if this item is allowed
   to be selected.

>  set-allow-selection :: (send an-item set-allow-selection boolean) -
   determines if this item is allowed to be selected
   
--------------------------------------------------

> hierarchical-list-compound-item<%>, instantiate via new-list
  extends hierarchical-list-item<%>

  New methods:

>  new-item :: (send a-list-item new-item) - creates and returns a new
     (empty) hierarchical-list-item<%>

>  new-item :: (send a-list-item new-item mixin) - creates and returns
     a new (empty) hierarchical-list-item<%>, but first, applies
     `mixin' to a class implementing hierarchical-list-item<%> and uses
     the result as the class for the new hierarchical-list-item<%>
     object.

> set-no-sublists :: (send a-list set-no-sublists no-sublists?) - 
     avoids space to the left of the list that would normally align
     non-list items with list items; this method can be called only
     when the list is empty

>  new-list :: (send a-list-item new-list) - creates and returns a new
     (empty) hierarchical-list-compound-item<%>

>  new-list :: (send a-list-item new-list mixin) - creates and returns
     a new (empty) hierarchical-list-compound-item<%>, but first,
     applies `mixin' to a class implementing
     hierarchical-list-compound-item<%> and uses the result as the
     class for the new hierarchical-list-compound-item<%> object.

>  delete-item :: (send a-list delete-item i) - delete
     hierarchical-list-item<%> `i' from the compound item

>  get-items :: (send a-list-item get-items) - returns a list of the
     items in the compound item

> open :: (send a-list-item open) - displays the children of this list.

> close :: (send a-list-item close) - hides the children of this list.

> toggle-open/closed :: (send a-list-item toggle-open/closed) - 
     toggles the visible status of the children of this list

> is-open? :: (send a-list-item is-open?) - 
     returns a boolean indicating if the children of this list are visible.

> get-arrow-snip :: (send a-list-item get-arrow-snip) -
     returns the arrow snip. intended for test suites to facilitate simulated clicks


--------------------------------------------------

If you use the `find-position' and `find-snip' methods of a
hierarchical-list%, you will get back
hierarchical-item-snip% and hierarchical-list-snip%
objects. They support these methods:

> hierarchical-item-snip% derived from editor-snip%

> get-item :: (send a-hl-item-snip get-item) - returns the 
     hierarchical-list-item<%> corresponding to this snip

> hierarchical-list-snip% derived from editor-snip%

> get-item :: (send a-hl-list-snip get-item) - returns the 
     hierarchical-list-item<%> corresponding to this snip

> get-content-buffer :: (send a-hl-list-snip get-content-buffer) -
     returns the text% that contains the sub-items.

--------------------------------------------------

_Hierlist keystrokes_

Hierlists support these keystrokes:

 - down:    move to the next entry at the current level (skipping lower levels)
 - up:      move to the previous entry at the current level (skipping lower levels)
 - left:    move to the enclosing level (only valid at embedded levels)
 - right:   move down in one level (only valid for lists)
 - return:  open / close the current selected level (only valid for lists)
