Re: [Tile-dev] Strawman Tree widget API

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

Joe English wrote: 

As a starting point for discussion, I've posted 
a strawmanpage here: 

    <URL: http://tktable.sourceforge.net/tile/doc/treeview.html <http://tktable.sourceforge.net/tile/doc/treeview.html>  > 

The documented interface is still incomplete, but I think 
it's a pretty good start.  I *hope* that it's simple enough 
to figure out how to use the widget from the manpage alone -- 
I've omitted the EXAMPLES section on purpose to test if that's 
actually the case :-) 

Stuff that's missing: 

+ Need to keep track of an "active" or "focussed" item; 
+ Support for selections; 
+ Drag and drop support, or (more likely) a foundation upon which 
  drag and drop support could be built. 
+ A way to specify column headings, column widgths, and other stuff

Headings need to be buttons with -commands, and support label/image combinations

+ Might want to be able to turn different components on and off: 
  column headings, open/close indicators, tree "connecting lines", 
  maybe even the tree labels to support "pure" multicolumn listboxes. 

Some things I like about this design: 

Separate -columns and -displaycolumns options make it easy 
to hide or reorder columns without having to change all the 
item -values.

Yes!

It works as a plain tree (leave -columns empty and don't 
supply -values for any items), and -- almost -- as a plain 
multicolumn listbox (create all items as children of the root 
and leave out -text and -image.) 

Some things I'm not too keen on: 

    $tree insert $index $parent $itemid ? ... options ... ?

I different approach may be to have two methods, one that adds an item after the index as a sibling, and another that adds an item as a child of the index.  Which raises a question: are indexes relative to the parent node, or absolute?  If a parent node is collapsed, what happens to the subsequent indexes?  Maybe what's needed is a path like index scheme (e.g. "1.2.2.1.7")

I copied this straight from the BWidget Tree, just to have a 
starting point.  I'm not sure how useful user-supplied node 
IDs are; it may be better to just use widget-generated integers 
like the canvas does.  This would reduce the number of required 
arguments from 3 to 2; and since then it's incompatible with 
BWidget anyway we can swap the order of the first two arguments 
and make it: 

        $tree insert $parent $index ?... options ... ? 

which seems more natural to me.

Without a UID, how do you find something in the tree?  The UID is not necessarily a hierarchical list of labels.  For example, a Windows explorer like display, where the file extensions are hidden.  The label for two files can be identical, but the file names themselves are different.

I don't like the overloaded nature of the "-columns" argument -- 
either an integer representing the number of columns or a list 
of symbolic column names.  But I *really* like the ability to 
have named columns, and if we had separate -numbercolumns 
and -columnnames options it'd be more work for users and for 
the widget to ensure they were always consistent.

Following the "everything-is-a-string" paradigm, I would just say that all columns are named; period.  This also gives you a default header label.

Specifying "-displaycolumns {}" (the default) means that all 
columns are shown, in order.  There is no way to say "do not 
display any columns". 

The -height option should really specify the desired number of 
visible items, not the height in pixels.  I'm not sure what 
units '-width' ought to take.

I've never liked "item" based sizing.  It leads to funky window resizing behavior.

The return value of [$tree identify $x $y] is a hairball. 

I'm not too sure about the names 'open' and 'close'. 

How about "expand" and "collapse".

I'm also not too sure about the number of widget commands; 
maybe some of these should be merged into a subensemble. 

Other stuff to think about: 

Item states: there are a few item states that the tree indicator 
element should be aware of, so it can select an appropriate display 
based on whether the node is open or closed, and whether or not 
it's a leaf element.  None of the currently-defined TTK_STATE_* 
flags really match those concepts well.  "selected" might serve 
for open/closed, except that we also want to support listbox-style 
selections.  I'm using the USER1 and USER2 state flags internally 
right now for open and nonleaf, respectively; but there really 
ought to be a mechanism for assigning meaningful names. 

Comments?

I would also like to see an incremental or dynamic interface that allows for support of larger datasets.  We have an interface on our tree that is comprised of three configure options:  -querycommand, -querysizecmd, -queryblocksize.  The -querycommand is called whenever a node is expanded (opened), and is passed the node id ("" for root).  The command will return a list of items which are the children for that node.  Each element of the list is a list of triples, one triple for each column.  The triple is comprised of {<label> <tags> <image>}.  The label and image should be obvious.  The tags element is a list of flags, the primary ones being "branch", or "leaf".

In the simple case, all the children for a node are returned when requested.  To handle large datasets, the -querysizecmd and -queryblocksize are used.  Before calling -querycommand, the -querysizecmd is called to calculate the number of children for the node.  Then the -querycommand is called with two additional parameters, a start index and a count (count comes from -queryblocksize).  The callback will only return "count" items starting at the start index.  The widget determines what range is needed based on the scroll offset and only makes enough calls to get the data needed to satisfy the display.  Also, the command callbacks support % substitution for node (%n), start (%s), and count (%c).

I find this interface easier to use then the traditional "$w insert ..." interface, especially when the data is dynamic.  A simple trigger can be used to cause the widget to re-acquire the data from the callbacks.

-Brian

--Joe English 

  jen...@fl... <mailto:jen...@fl...>  

------------------------------------------------------- 
This SF.Net email is sponsored by: YOU BE THE JUDGE. Be one of 170 
Project Admins to receive an Apple iPod Mini FREE for your judgement on 
who ports your project to Linux PPC the best. Sponsored by IBM. 
Deadline: Sept. 24. Go here: http://sf.net/ppc_contest.php <http://sf.net/ppc_contest.php>  
_______________________________________________ 
Tktable-tile-dev mailing list 
Tkt...@li... <mailto:Tkt...@li...>  
https://lists.sourceforge.net/lists/listinfo/tktable-tile-dev <https://lists.sourceforge.net/lists/listinfo/tktable-tile-dev>  

-- 

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

--                 Model Technology Inc.                   --

-- 8005 SW Boeckman Road                  503.685.7000 tel --

-- Wilsonville, OR 97070 USA              503.685.0921 fax --

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

-- Technical support ............ mailto:su...@mo... <mailto:su...@mo...>  --

-- Sales and marketing info ....... mailto:sa...@mo... <mailto:sa...@mo...>  --

-- Licensing .................... mailto:li...@mo... <mailto:li...@mo...>  --

-- Home Page ........................ http://www.model.com <http://www.model.com>  --

-- AIM ........................................ bgriffin42 --

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