[Table of Contents] [Previous: Titled Buttons] [Next: Tab Widget]

Feature Owner: David Hyatt

The tree widget provides the ability to display multiple items in a tabular format. Each item is represented as a row in the table. Each row may consist of multiple cells. A tree widget has all the same components as an HTML table, and any users of this widget should be thoroughly familiar with the capabilites of HTML tables. Trees can also respond to all of the same CSS properties as HTML tables, as documented in the CSS2 spec on tables.

The following tags are roughly analogous to their HTML table counterparts.

Table	Tree
table	tree
caption	treecaption
colgroup	treecolgroup
col	treecol
thead	treehead
tbody	treebody
tfoot	treefoot
tr	treeitem
td	treecell

To insert a tree widget into a document, use the tree tag. This tag is analogous to the table tag in HTML.

The tree widget can contain a caption, which can be specified using the treecaption tag.

The tree's column information can be specified using the treecolgroup and treecol tags; these tags respond to all the same properties that the HTML col tags do. These column tags can be used to specify column widths and to apply styles to individual columns in the tree view. Tree column tags can respond to an additional CSS property, column-layout, which indicates whether or not this column's size is alterable using the tree's column resizing capabilities. It has values of fixed and flexible, with the default being flexible. [This is not yet implemented.]

A tree can contain headers, bodies, and footers, just as a table does. [Not yet implemented, but coming online soon, so pay attention.] A tree widget's body (unlike a table's body) tries to be as small as possible, and this means that a tree widget's height (in order for the widget to be usable) must always be specified or implied (and never intrinsically determined). Typically a tree widget will be placed inside a box (See The Box System for details.) so that it can be made to expand to a constrained size (even when the size is a percentage height). This allows tree designers to force an overflow on the tree's body in circumstances where a table would not normally overflow.

The treeitem tag is used to declare a single row in the tree. The tree item contains one or more cells, which are specified using the treecell tag.

<tree> <treehead> <treeitem> <treecell>Name</treecell> <treecell>URL</treecell> </treeitem> </treehead> <treebody> <treeitem> <treecell>Netscape Home Page</treecell> <treecell>http://www.netscape.com</treecell> </treeitem> </treebody> </tree>

Tree items are either open or closed, and their state is specified using the open attribute. This attribute, when set to true, indicates that the tree item's children should be displayed in the tree. If it is set to false, or if it isn't set at all, then the tree item's children are not displayed.

A tree item's children are specified using the treechildren tag, which is placed within the parent treeitem tag. The treechildren tag contains tree items that represent the children of the parent node.

<tree> <treehead> <treeitem> <treecell>Name</treecell> <treecell>URL</treecell> </treeitem> </treehead> <treebody> <treeitem> <treecell>Netscape Bookmarks Folder</treecell> <treecell/> <treechildren> <treeitem> <treecell>Netscape Home Page</treecell> <treecell>http://www.netscape.com</treecell> </treeitem> </treechildren> </treeitem> </treebody> </tree>

The tree automatically handles selection, and it is capable of supporting single and multiple selection (through the use of modifier keys). The tree's selection is reflected into the content model. Tree items that are selected have an attribute called selected set to true. Tree cells that are selected have an attribute called selectedcell that is set to true. CSS can be applied using attribute selector rules, thus enabling the tree designer to control the look of the tree's selection. [This should probably change to use :active instead.]

The tree widget also supports hover feedback on items and cells. This hover feedback is also reflected into the content model. Tree items that are currently moused over have an attribute called hover set to true. Tree cells that are being moused over have an attribute called hovercell set to true. CSS can be applied using attribute selector rules, which enable control of the hover feedback effects for the tree. [This will probably change to use the :hover mechanism at some point.]

Because the tree handles selection, events that would normally go to the content inside the cell are intercepted by the cell. This behavior can be turned off on a cell by cell basis by setting the allowevents attribute on the cell. This attribute, when set to true, indicates that the cell is unselectable, and that the content inside should receive events (like mouse clicks and keystrokes).

Content in a tree cell can be automatically indented based on the node's level in the tree by using the treeindentation tag. The indentation tag can have a width property applied to it using CSS, and this property is multiplied by the node's level of indentation to determine how much padding to insert. The default if no property is specified is 16 pixels per level. [Style support for treeindentation is not yet implemented.]

Answers to Common Questions

How do I give column headers a visually distinct look?
You can make a CSS rule like the following to apply a look only to cells inside the head of the table.

treehead treeitem treecell { ... }

Can I set the widths of my columns using percentages?

Yes. Click here for details.

I don't want the text in my tree cells to wrap. What do I do?

Set the whitespace property on your tree cells in CSS to a value of nowrap. Then constrain the width of your tree (e.g., give your tree a width of 100%). Once you have done this, the contents of the cells will be clipped.

I would like the text in my tree cells to be cropped in addition to being clipped. What do I do?

[Not yet implemented.] You will be able to specify this through CSS. If the nowrap property is set and an additional cropstyle property is set (whose value can be left, middle, or right), then the text in the cell can be made to crop.

A temporary workaround to get this feature working would be to use titled buttons to hold the text. (See Titled Buttons for details.) Titled buttons already know how to crop right by default when their widths are constrained.

I want to use the same event handler for all items in my tree, but I don't want to define these handlers over and over on each node. What do I do?

Take advantage of the DOM's event handling capabilities. You can allow events to bubble up to your tree node, and handle the events there. The target of an event that bubbles up can be retrieved using evt.target.

When using bubbling on a tree view, it is important to remember that the events will bubble from child node to parent node. Don't think of it like a table, where the events will always go from cell to row to body. If a node is 11 levels deep, then the event will bubble out through the node's parents before getting to the tree body. Be aware of this distinction when writing event-handling code.

How do I make the tree's body scroll independently of the header/footer?
Constrain the height of the tree and this overflow will happen automatically when there are too many items to fit in the displayable area. Boxes can be used to make the tree springy (and to make the tree be sized to the width and height of a window). [There are currently issues with this, so don't beat your head against a wall trying to make this work yet.]

How do I make clickable graphical cell contents like in Messenger (flags, checks, etc.)?

Use Titled Buttons. In the click handler for the button, set an attribute on the button to cycle through the various states. Use attribute selector rules for each possible attribute value to set up different images for each state of the button. If desired, the button's border can even be hidden using CSS.

How do I hide columns?

You can read about this capability here.

I want to do insert my feature here with the tree, but I don't know where to start!
It is important to remember that a tree is an extended table, and therefore many of its capabilities are inherited from tables. Make sure you read the CSS2 and HTML specs on tables (links are at the top of this page) to see if your question is answered there.