Tree
A container which can be used to hold a tabular or hierarchical set of rows of elements. The tree may contain any number of rows and any number of columns. Each row of the tree may contain child rows which are displayed indented from the parent. Unlike other elements, the data to display inside the tree is not specified using tags, but is determined from a view object. The view object implements the nsITreeView interface. The view is queried for the data to appear in the tree. There are several ways in which trees are used, as listed below. The second column lists the interfaces available via the tree's view property. The third column indicates whether treeitem element are used.
| Tree Type | View Interfaces | Has DOM Nodes | Description |
|---|---|---|---|
| Content Tree | nsITreeView, nsITreeContentView | Yes | This tree has treeitem elements placed within the treechildren element. In this situation, a content view (which implements the interface nsITreeContentView) which is a more specialized type of view, uses the treeitem elements and their descendants to determine the data to display in the tree. However, the treeitems are not displayed directly; they are used only as data to the content view. However, the content view will automatically update the tree if treeitems are changed. |
| RDF Tree | nsITreeView, nsIXULTreeBuilder | No | This tree is generated from an RDF datasource. It is used when a tree has a datasources attribute, and has 'dont-build-content' in its flags attribute. For this tree, the data comes directly from the RDF datasource. DOM treeitems are not created. Even though the template uses treeitem elements to define the content, DOM nodes for these elements are not created. This is the type that should be used for RDF generated trees with lots of rows. |
| RDF Content Tree | nsITreeView, nsIXULTreeBuilder nsITreeContentView | Yes | This tree is generated from an RDF datasource. It is similar to the previous type but is used when the tree does not have 'dont-build-content' in its flags attribute. DOM treeitems are created, so you can access the data using RDF functions or DOM functions. This type is suitable for RDF generated trees with a fairly small number of rows. |
| Custom View Tree | nsITreeView | No | For this tree you implement the nsITreeView interface yourself. The tree's data is retrieved from this custom view. The custom view should be attached to the tree by setting its view property. |
nsIAccessibleProvider nsIDOMXULTreeElement nsIDOMXULMultiSelectControlElement
Attributes:
| disableKeyNavigation | disabled | enableColumnDrag | flags | hidecolumnpicker |
| onselect | rows | seltype | statedatasource | tabindex |
Properties and Methods:
| accessible | builderView | columns | contentView | currentIndex |
| disableKeyNavigation | disabled | enableColumnDrag | firstOrdinalColumn | selType |
| selstyle | tabIndex | treeBoxObject | view |
Attributes:
Inherited from XUL Element:
align
allowevents
allownegativeassertions
class
coalesceduplicatearcs
collapsed
container
containment
context
contextmenu
datasources
dir
empty
equalsize
flags
flex
height
hidden
id
insertafter
insertbefore
left
maxheight
maxwidth
menu
minheight
minwidth
mousethrough
observes
ordinal
orient
pack
persist
popup
position
preference-editable
ref
removeelement
sortDirection
sortResource
sortResource2
statustext
style
template
tooltip
tooltiptext
top
uri
wait-cursor
width
disableKeyNavigation
Type: boolean
If this attribute is not used, the user can navigate to specific items in the tree by pressing the first the first letter of the item's label. This is done incrementally, so pressing additional keys will select more specific items. This feature may be disabled for a tree by setting this attribute to true.
disabled
Type: boolean
Indicates whether the tree is disabled or not. If this attribute is set to true, the tree is disabled. This is usually drawn with the text in grey. If the tree is disabled, it does not respond to user actions. The element cannot be focused and the command event will not fire. The element will still respond to mouse events. To enable the tree, leave the attribute out entirely as opposed to setting the value to false.
enableColumnDrag
Type: boolean
When set to 'true', the user may drag the column headers around to change the order that they are displayed in.
flags
Type: string
Set this attribute to 'dont-build-content' for a template generated tree. For trees that have their content placed directly inside the tree or have a custom view object, this flag should not be used.
hidecolumnpicker
Type: boolean
When set to false, a drop-down will appear in the upper right corner of the tree, which the user may use to show and hide columns. When set to true, the column picker will be hidden. The default value is false.
onselect
Type: script code
This event is sent to an tree when a row is selected, or whenever the selection changes. The user can select multiple rows by holding down Shift or Control and click on a row. The onselect event will be sent for each item added or removed to the selection.
rows
Type: integer
The number of rows to display in the tree.
seltype
Type: one of the values below
Used to indicate whether multiple selection is allowed.
- single: Only one row may be selected at a time.
- multiple: Multiple rows may be selected at once.
statedatasource
Type: datasource URI
Chrome XUL may specify an RDF datasource to use to store tree state information. This is used to hold which tree items are open and which items are collapsed. This information will be remembered for the next time the XUL file is opened. If you do not specify this attribute, state information will be stored in the local store (rdf:local-store).
tabindex
Type: integer
The tab order of the element. The tab order is the order in which the focus is moved when the user presses the Tab key. Elements with a higher tabindex are later in the tab order sequence.
Properties and Methods:
Inherited from XUL Element:
align
allowEvents
blur
boxObject
boxObject.element
boxObject.getLookAndFeelMetric
boxObject.height
boxObject.screenX
boxObject.screenY
boxObject.width
boxObject.x
boxObject.y
builder
className
click
collapsed
contextMenu
controllers
database
datasources
dir
doCommand
flex
focus
getElementsByAttribute
height
hidden
id
left
maxHeight
maxWidth
menu
minHeight
minWidth
observes
ordinal
orient
pack
persist
ref
resource
statusText
style
tooltip
tooltipText
top
width
Inherited from Element:
addEventListener
appendChild
attributes
childNodes
cloneNode
dispatchEvent
firstChild
getAttribute
getAttributeNS
getAttributeNode
getAttributeNodeNS
getElementsByTagName
getElementsByTagNameNS
hasAttribute
hasAttributeNS
hasAttributes
hasChildNodes
insertBefore
isSupported
lastChild
localName
namespaceURI
nextSibling
nodeName
nodeType
nodeValue
normalize
ownerDocument
parentNode
prefix
previousSibling
removeAttribute
removeAttributeNS
removeAttributeNode
removeChild
removeEventListener
replaceChild
setAttribute
setAttributeNS
setAttributeNode
setAttributeNodeNS
tagName
accessible
Type: nsIAccessible
Returns the accessibility object for the tree.
builderView
Type: nsIXULTreeBuilder
A reference to the tree builder which constructed the tree data. The builder provides access to the RDF resources for each row in the tree, and allows sorting the data by column. In newer versions of Mozilla, the builderView property is actually a synonym for the view property, since the two interfaces are flattened together into a single interface in JavaScript. This property is read only.
columns Mozilla 1.8
Returns the columns for the tree as an nsITreeColumns object.
contentView
Type: nsITreeContentView
For trees built with a content builder - that is, those that do not have flags="dont-build-content" set -- the contentView will be a reference to the nsITreeContentView for the tree. This interface lets you retrieve the DOM element corresponding to a given a row index and vice versa. For trees that are not built with a content builder, the functions of nsITreeContentView will not be available, since there are no DOM nodes to retrieve. In newer versions of Mozilla, the contentView property is actually a synonym for the view property, since the two interfaces are flattened together into a single interface in JavaScript. This property is read only.
currentIndex
Type: integer
Set to the index of the currently focused row in the tree. If no row is focused, the value will be -1. For multiple selection trees, the current index is the last row selected. Do not use this property to change the selection. Instead, use the methods of the TreeSelection object available via tree.view.selection.
disableKeyNavigation
Type: boolean
If this attribute is not used, the user can navigate to specific items in the tree by pressing the first the first letter of the item's label. This is done incrementally, so pressing additional keys will select more specific items. This feature may be disabled for a tree by setting this attribute to true.
disabled
Type: boolean
Gets and sets the value of the disabled attribute.
enableColumnDrag
Type: boolean
When set to 'true', the user may drag the column headers around to change the order that they are displayed in.
firstOrdinalColumn
Type: treecol element
A reference to the first treecol element, which or may not be the first column displayed in the tree.
selType Mozilla 1.8
Gets and sets the value of the seltype attribute.
selstyle
Type: string
If set to the value 'primary', only the label of the primary column will be highlighted when an item in the tree is selected. Otherwise, the entire row will be highlighted. To see the difference, compare the selection style in the folder list and the message list in Mozilla mail.
tabIndex Mozilla 1.8
Type: integer
Get and sets the value of the tabindex attribute.
treeBoxObject
Type: nsITreeBoxObject
The box object is responsible for rendering the tree on the window. This object implements the nsITreeBoxObject interface and contains functions for retrieving the cells at certain coordinates, redrawing cells and scrolling the tree. This property is equivalent to the boxObject property.
view
Type: nsITreeView
The view for the tree, which is the object which generates the data to be displayed. You can assign an object which implements nsITreeView to this property. Trees built from RDF or those which use treeitems directly will already have a view. Functions available in the view allow one to retrieve the data within the cells, and determine which rows are nested within others. For a complete list of view functions, see the nsITreeView interface.