com.extjs.gxt.ui.client.widget.treepanel
Class TreePanel<M extends ModelData>

java.lang.Object
  com.google.gwt.user.client.ui.UIObject
      com.google.gwt.user.client.ui.Widget
          com.extjs.gxt.ui.client.widget.Component
              com.extjs.gxt.ui.client.widget.BoxComponent
                  com.extjs.gxt.ui.client.widget.treepanel.TreePanel<M>

Type Parameters:

M - the model type

All Implemented Interfaces:

CheckProvider<M>, Observable, com.google.gwt.event.shared.HasHandlers, com.google.gwt.user.client.EventListener

public class TreePanel<M extends ModelData>
extends BoxComponent
implements CheckProvider<M>

A hierarchical tree widget bound directly to a @link TreeStore. TreePanel contains no child widgets, rather, the tree is rendered based on the models contained in the tree store. Once bound, the tree will remain in sync with the bound tree store.

The text of each node can be specified in a couple of different ways. First, a display property can be set using setDisplayProperty(String). The is useful when the item's text is contained within the model's data. Second, a model string provider can be specified using setLabelProvider(ModelStringProvider).

With state enabled, TreePanel will save and restore the expand state of the nodes in the tree. A ModelKeyProvider must specified with the TreeStore this tree is bound to. Save and restore works with both local, and asynchronous loading of children.

Events:

BeforeExpand : TreePanelEvent(treePanel, item)

Fires before a node is expanded. Listeners can cancel the action by calling BaseEvent.setCancelled(boolean).

• treePanel : the source tree
• item : this

BeforeCollapse : TreePanelEvent(treePanel, item)

Fires before a node is collapsed. Listeners can cancel the action by calling BaseEvent.setCancelled(boolean).

• treePanel : the source tree
• item : this

Expand : TreePanelEvent(treePanel, item)

Fires after a node has been expanded.

• treePanel : the source tree
• item : this

Collapse : TreePanelEvent(treePanel, item)

Fires after a node is collapsed.

• treePanel : the source tree
• item : this

BeforeCheckChange : TreePanelEvent(treePanel, item)

Fires before a node's check state is changed. Listeners can cancel the action by calling BaseEvent.setCancelled(boolean).

• treePanel : the source tree
• item : this
• checked : the checked state.

CheckChange : TreePanelEvent(treePanel, item)

Fires after a item's check state changes.

• treePanel : the source tree
• item : this
• checked : the checked state.

CheckChanged : CheckChangeEvent(provider, checkedeSelection)

Fires after the tree's overall checked state changes.

• provider : the source tree
• checkedSelection : the tree checked item

Nested Class Summary

static class	TreePanel.CheckCascade Check cascade enum.
static class	TreePanel.CheckNodes Check nodes enum.
static class	TreePanel.Joint Joint enum.
class	TreePanel.TreeNode Maintains the internal state of nodes contained in the tree.

Nested classes/interfaces inherited from class com.google.gwt.user.client.ui.UIObject

com.google.gwt.user.client.ui.UIObject.DebugIdImpl, com.google.gwt.user.client.ui.UIObject.DebugIdImplEnabled

Field Summary

Fields inherited from class com.google.gwt.user.client.ui.UIObject

DEBUG_ID_PREFIX

Constructor Summary

TreePanel(TreeStore<M> store)
Creates a new tree panel.

Method Summary

void	addCheckListener(CheckChangedListener<M> listener) Adds the check change listener.
void	collapseAll() Collapses all nodes.
void	expandAll() Expands all nodes.
TreePanel.TreeNode	findNode(com.google.gwt.user.client.Element target) Returns the tree node for the given target.
java.util.List<M>	getCheckedSelection() Returns the current checked selection.
TreePanel.CheckNodes	getCheckNodes() Returns the child nodes value which determines what node types have a check box.
TreePanel.CheckCascade	getCheckStyle() The check cascade style value which determines if check box changes cascade to parent and children.
java.lang.String	getDisplayProperty() Returns the display property.
ModelIconProvider<M>	getIconProvider() Returns the model icon provider.
TreePanelSelectionModel<M>	getSelectionModel() Returns the tree's selection model.
TreeStore<M>	getStore() Returns the tree's store.
TreeStyle	getStyle() Returns the tree style.
TreePanelView<M>	getView() Returns the tree's view.
boolean	isAutoLoad() Returns true if auto load is enabled.
boolean	isAutoSelect() Returns true if select on load is enabled.
boolean	isCaching() Returns true when a loader is queried for it's children each time a node is expanded.
boolean	isCheckable() Returns true if check boxes are enabled.
boolean	isChecked(M model) Returns true if the model is checked.
boolean	isExpanded(M model) Returns true if the model is expanded.
boolean	isExpandOnFilter() Returns the if expand all and collapse all is enabled on filter changes.
boolean	isLeaf(M model) Returns true if the model is a leaf node.
boolean	isTrackMouseOver() Returns true if nodes are highlighted on mouse over.
void	onComponentEvent(ComponentEvent ce) Any events a component receives will be forwarded to this method.
void	recalculate() Called when the component is in a LayoutContainer and the container's layout executes.
void	removeCheckListener(CheckChangedListener<M> listener) Removes the check change listener.
void	scrollIntoView(M model) Scrolls the tree to ensure the given model is visible.
void	setAutoLoad(boolean autoLoad) Sets whether all children should automatically be loaded recursively (defaults to false).
void	setAutoSelect(boolean autoSelect) True to select the first model after the store's data changes (defaults to false).
void	setCaching(boolean caching) Sets whether the children should be cached after first being retrieved from the store (defaults to true).
void	setCheckable(boolean checkable) Sets whether check boxes are used in the tree.
void	setChecked(M item, boolean checked) Sets the check state of the item.
void	setCheckedSelection(java.util.List<M> selection) Sets the current checked selection.
void	setCheckNodes(TreePanel.CheckNodes checkNodes) Sets which tree items will display a check box (defaults to BOTH).
void	setCheckStyle(TreePanel.CheckCascade checkStyle) Sets the cascading behavior for check tree (defaults to PARENTS).
void	setDisplayProperty(java.lang.String displayProperty) Sets the display property name used to the item's text.
void	setExpanded(M model, boolean expand) Sets the item's expand state.
void	setExpanded(M model, boolean expand, boolean deep) Sets the item's expand state.
void	setExpandOnFilter(boolean expandOnFilter) Sets whether the tree should expand all and collapse all when filters are applied (defaults to true).
void	setIconProvider(ModelIconProvider<M> iconProvider) Sets the tree's model icon provider which provides the icon style for each model.
void	setLabelProvider(ModelStringProvider<M> labelProvider) Sets the tree's model string provider for the text description of each node.
void	setLeaf(M model, boolean leaf) Sets the item's leaf state.
void	setSelectionModel(TreePanelSelectionModel<M> sm) Sets the tree's selection model.
void	setStyle(TreeStyle style) Sets the tree style.
void	setTrackMouseOver(boolean trackMouseOver) True to highlight nodes when the mouse is over (defaults to true).
void	setView(TreePanelView<M> view) Sets the tree's view.
void	toggle(M model) Toggles the model's expand state.

Methods inherited from class com.extjs.gxt.ui.client.widget.BoxComponent

getBounds, getHeight, getHeight, getPosition, getShadow, getShadowOffset, getShadowPosition, getSize, getWidth, getWidth, isAutoHeight, isAutoWidth, isDeferHeight, isShim, setAutoHeight, setAutoWidth, setBounds, setBounds, setDeferHeight, setHeight, setHeight, setPagePosition, setPagePosition, setPixelSize, setPosition, setShadow, setShadowOffset, setShadowPosition, setShim, setSize, setSize, setWidth, setWidth, sync, syncSize

Methods inherited from class com.extjs.gxt.ui.client.widget.Component

addListener, addPlugin, addStyleName, addWidgetListener, clearState, disable, disableEvents, disableTextSelection, el, enable, enableEvents, fireEvent, fireEvent, fireEvent, fly, focus, getBaseStyle, getBorders, getContextMenu, getData, getElement, getHideMode, getId, getItemId, getListeners, getModel, getState, getStateId, getToolTip, hasListeners, hasListeners, hide, hideToolTip, isDisabledEvents, isEnabled, isRendered, isStateful, isVisible, mask, mask, mask, onBrowserEvent, removeAllListeners, removeFromParent, removeListener, removeStyleName, removeSwallow, removeToolTip, removeWidgetListener, render, render, repaint, saveState, setBorders, setContextMenu, setData, setElement, setEnabled, setHideMode, setId, setIntStyleAttribute, setItemId, setStateful, setStateId, setStyleAttribute, setStyleName, setTitle, setToolTip, setToolTip, setVisible, setZIndex, show, sinkEvents, swallowEvent, swallowEvent, toString, unmask

Methods inherited from class com.google.gwt.user.client.ui.Widget

fireEvent, getParent, isAttached

Methods inherited from class com.google.gwt.user.client.ui.UIObject

addStyleDependentName, ensureDebugId, ensureDebugId, getAbsoluteLeft, getAbsoluteTop, getOffsetHeight, getOffsetWidth, getStyleName, getStylePrimaryName, getTitle, isVisible, removeStyleDependentName, setStylePrimaryName, setVisible, unsinkEvents

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

TreePanel

public TreePanel(TreeStore<M> store)

Creates a new tree panel.

Parameters:

store - the tree store

Method Detail

addCheckListener

public void addCheckListener(CheckChangedListener<M> listener)

Description copied from interface: CheckProvider

Adds the check change listener.

Specified by:

addCheckListener in interface CheckProvider<M extends ModelData>

Parameters:

listener - the listener to be added

collapseAll

public void collapseAll()

Collapses all nodes.

expandAll

public void expandAll()

Expands all nodes.

findNode

public TreePanel.TreeNode findNode(com.google.gwt.user.client.Element target)

Returns the tree node for the given target.

Parameters:

target - the target element

Returns:

the tree node or null if no match

getCheckedSelection

public java.util.List<M> getCheckedSelection()

Description copied from interface: CheckProvider

Returns the current checked selection.

Specified by:

getCheckedSelection in interface CheckProvider<M extends ModelData>

Returns:

the checked selection

getCheckNodes

public TreePanel.CheckNodes getCheckNodes()

Returns the child nodes value which determines what node types have a check box. Only applies when check boxes have been enabled ( setCheckable(boolean).

Returns:

the child nodes value

getCheckStyle

public TreePanel.CheckCascade getCheckStyle()

The check cascade style value which determines if check box changes cascade to parent and children.

Returns:

the check cascade style

getDisplayProperty

public java.lang.String getDisplayProperty()

Returns the display property.

Returns:

the display property

getIconProvider

public ModelIconProvider<M> getIconProvider()

Returns the model icon provider.

Returns:

the icon provider

getSelectionModel

public TreePanelSelectionModel<M> getSelectionModel()

Returns the tree's selection model.

Returns:

the selection model

getStore

public TreeStore<M> getStore()

Returns the tree's store.

Returns:

the store

getStyle

public TreeStyle getStyle()

Returns the tree style.

Returns:

the tree style

getView

public TreePanelView<M> getView()

Returns the tree's view.

Returns:

the view

isAutoLoad

public boolean isAutoLoad()

Returns true if auto load is enabled.

Returns:

the auto load state

isAutoSelect

public boolean isAutoSelect()

Returns true if select on load is enabled.

Returns:

the auto select state

isCaching

public boolean isCaching()

Returns true when a loader is queried for it's children each time a node is expanded. Only applies when using a loader with the tree store.

Returns:

true if caching

isCheckable

public boolean isCheckable()

Returns true if check boxes are enabled.

Returns:

the check box state

isChecked

public boolean isChecked(M model)

Description copied from interface: CheckProvider

Returns true if the model is checked.

Specified by:

isChecked in interface CheckProvider<M extends ModelData>

Parameters:

model - the model

Returns:

the check state

isExpanded

public boolean isExpanded(M model)

Returns true if the model is expanded.

Parameters:

model - the model

Returns:

true if expanded

isExpandOnFilter

public boolean isExpandOnFilter()

Returns the if expand all and collapse all is enabled on filter changes.

Returns:

the expand all collapse all state

isLeaf

public boolean isLeaf(M model)

Returns true if the model is a leaf node. The leaf state allows a tree item to specify if it has children before the children have been realized.

Parameters:

model - the model

Returns:

the leaf state

isTrackMouseOver

public boolean isTrackMouseOver()

Returns true if nodes are highlighted on mouse over.

Returns:

true if enabled

onComponentEvent

public void onComponentEvent(ComponentEvent ce)

Description copied from class: Component

Any events a component receives will be forwarded to this method. Subclasses should override as needed. The Component.onBrowserEvent(com.google.gwt.user.client.Event) method should not be overridden or modified.

Overrides:

onComponentEvent in class Component

Parameters:

ce - the base event

recalculate

public void recalculate()

Description copied from class: Component

Called when the component is in a LayoutContainer and the container's layout executes. This method will not be called on container instances. Default implementation does nothing.

Overrides:

recalculate in class Component

removeCheckListener

public void removeCheckListener(CheckChangedListener<M> listener)

Description copied from interface: CheckProvider

Removes the check change listener.

Specified by:

removeCheckListener in interface CheckProvider<M extends ModelData>

Parameters:

listener - the listener to be removed

scrollIntoView

public void scrollIntoView(M model)

Scrolls the tree to ensure the given model is visible.

Parameters:

model - the model to scroll into view

setAutoLoad

public void setAutoLoad(boolean autoLoad)

Sets whether all children should automatically be loaded recursively (defaults to false). Useful when the tree must be fully populated when initially rendered.

Parameters:

autoLoad - true to auto load

setAutoSelect

public void setAutoSelect(boolean autoSelect)

True to select the first model after the store's data changes (defaults to false).

Parameters:

autoSelect - true to auto select

setCaching

public void setCaching(boolean caching)

Sets whether the children should be cached after first being retrieved from the store (defaults to true). When false, a load request will be made each time a node is expanded.

Parameters:

caching - the caching state

setCheckable

public void setCheckable(boolean checkable)

Sets whether check boxes are used in the tree.

Parameters:

checkable - true for check boxes

setChecked

public void setChecked(M item,
                       boolean checked)

Sets the check state of the item. The checked state will only be set for nodes that have been rendered, setAutoLoad(boolean) can be used to render all children.

Parameters:

item - the item

checked - true for checked

setCheckedSelection

public void setCheckedSelection(java.util.List<M> selection)

Description copied from interface: CheckProvider

Sets the current checked selection.

Specified by:

setCheckedSelection in interface CheckProvider<M extends ModelData>

Parameters:

selection - the checked selection

setCheckNodes

public void setCheckNodes(TreePanel.CheckNodes checkNodes)

Sets which tree items will display a check box (defaults to BOTH).

Valid values are:

• BOTH - both nodes and leafs
• PARENT - only nodes with children
• LEAF - only leafs

Parameters:

checkNodes - the child nodes value

setCheckStyle

public void setCheckStyle(TreePanel.CheckCascade checkStyle)

Sets the cascading behavior for check tree (defaults to PARENTS). When using CHILDREN, it is important to note that the cascade will only be applied to rendered nodes. setAutoLoad(boolean) can be used to fully render the tree on render.

Valid values are:

• NONE - no cascading
• PARENTS - cascade to parents
• CHILDREN - cascade to children

Parameters:

checkStyle - the child style

setDisplayProperty

public void setDisplayProperty(java.lang.String displayProperty)

Sets the display property name used to the item's text. As an alternative, a ModelStringProvider can be specified using setLabelProvider(ModelStringProvider).

Parameters:

displayProperty - the property name

setExpanded

public void setExpanded(M model,
                        boolean expand)

Sets the item's expand state.

Parameters:

model - the model

expand - true to expand

setExpanded

public void setExpanded(M model,
                        boolean expand,
                        boolean deep)

Sets the item's expand state.

Parameters:

model - the model

expand - true to expand

deep - true to expand all children recursively

setExpandOnFilter

public void setExpandOnFilter(boolean expandOnFilter)

Sets whether the tree should expand all and collapse all when filters are applied (defaults to true).

Parameters:

expandOnFilter - true to expand and collapse on filter changes

setIconProvider

public void setIconProvider(ModelIconProvider<M> iconProvider)

Sets the tree's model icon provider which provides the icon style for each model.

Parameters:

iconProvider - the icon provider

setLabelProvider

public void setLabelProvider(ModelStringProvider<M> labelProvider)

Sets the tree's model string provider for the text description of each node. If a a display property has been specified, it will be pased to the string provider. If a property has not been specified, null will be passed.

Parameters:

labelProvider - the label provider

setLeaf

public void setLeaf(M model,
                    boolean leaf)

Sets the item's leaf state. The leaf state allows control of the expand icon before the children have been realized.

Parameters:

model - the model

leaf - the leaf state

setSelectionModel

public void setSelectionModel(TreePanelSelectionModel<M> sm)

Sets the tree's selection model.

Parameters:

sm - the selection model

setStyle

public void setStyle(TreeStyle style)

Sets the tree style.

Parameters:

style - the tree style

setTrackMouseOver

public void setTrackMouseOver(boolean trackMouseOver)

True to highlight nodes when the mouse is over (defaults to true).

Parameters:

trackMouseOver - true to highlight nodes on mouse over

setView

public void setView(TreePanelView<M> view)

Sets the tree's view. Only needs to be called when customizing the tree's presentation.

Parameters:

view - the view

toggle

public void toggle(M model)

Toggles the model's expand state.

Parameters:

model - the model