
_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%
   
  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-item new-item mixin) - creates and returns
     a new (empty) hierarchical-list-item<%>, but first, applies
     `mixin' to a class implemeting hierarchical-list-item<%> and uses
     the result as the class for the new hierarchical-list-item<%>
     object.

>  new-list :: (send a-list 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 implemeting
     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-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) - sorts items in the list
     by calling `less-than-proc' on pairs of items.

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

> 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

>  select :: (send an-item select on?) - selects or deselects the
     item; hierarchical-list%'s select is called

>  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

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

> 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 implemeting hierarchical-list-item<%> and uses
     the result as the class for the new hierarchical-list-item<%>
     object.

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


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

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