org.zkoss.zul
Class Tree

java.lang.Object
  org.zkoss.zk.ui.AbstractComponent
      org.zkoss.zk.ui.HtmlBasedComponent
          org.zkoss.zul.impl.XulElement
              org.zkoss.zul.impl.MeshElement
                  org.zkoss.zul.Tree

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, Component, Scope, ComponentCtrl, Paginated

public class Tree
extends MeshElement

A container which can be used to hold a tabular or hierarchical set of rows of elements.

Event:

1. SelectEvent is sent when user changes the selection.
2. onAfterRender is sent when the model's data has been rendered.(since 5.0.4)

Default getZclass(): z-tree. (since 3.5.0)

Custom Attributes:

org.zkoss.zul.tree.rightSelect

Specifies whether the selection shall be toggled when user right clicks on item, if the checkmark (isCheckmark()) is enabled.
Notice that you could specify this attribute in any of its ancestor's attributes. It will be inherited.

org.zkoss.zul.tree.autoSort

.(since 5.0.7)

Specifies whether to sort the model when the following cases:

1. setModel(org.zkoss.zul.TreeModel) is called and Treecol.setSortDirection(java.lang.String) is set.
2. Treecol.setSortDirection(java.lang.String) is called.
3. Model receives TreeDataEvent and Treecol.setSortDirection(java.lang.String) is set.

If you want to ignore sort when receiving TreeDataEvent, you can specifies the value as "ignore.change".
Notice that you could specify this attribute in any of its ancestor's attributes. It will be inherited.

[Since 6.0.0]

To retrieve what are selected in Tree with a TreeSelectableModel, you shall use TreeSelectableModel.isPathSelected(int[]) to check whether the current path is selected in TreeSelectableModel rather than using getSelectedItems(). That is, you shall operate on the item of the TreeSelectableModel rather than on the Treeitem of the Tree if you use the TreeSelectableModel and TreeModel.

 TreeSelectableModel selModel = ((TreeSelectableModel)getModel());
 int[][] paths = selModel.getSelectionPaths();
 List selected = new ArrayList();
 AbstractTreeModel model = (AbstractTreeModel) selModel;
 for (int i = 0; i < paths.length; i++) {
                selected.add(model.getChild(paths[i]));
 }
 

[Since 6.0.0]

If the TreeModel in Tree implements a TreeSelectableModel, the multiple selections status is applied from the method of TreeSelectableModel.isMultiple()

 DefaultTreeModel selModel = new DefaultTreeModel(treeNode);
 selModel.setMultiple(true);
 tree.setModel(selModel);
 

[Since 6.0.0]

To retrieve what are opened nodes in Tree with a TreeOpenableModel, you shall use TreeOpenableModel.isPathOpened(int[]) to check whether the current path is opened in TreeOpenableModel rather than using Treeitem.isOpen(). That is, you shall operate on the item of the TreeOpenableModel rather than on the Treeitem of the Tree if you use the TreeOpenableModel and TreeModel.

 TreeOpenableModel openModel = ((TreeOpenableModel)getModel());
 int[][] paths = openModel.getOpenPaths();
 List opened = new ArrayList();
 AbstractTreeModel model = (AbstractTreeModel) openModel;
 for (int i = 0; i < paths.length; i++) {
                opened.add(model.getChild(paths[i]));
 }
 

org.zkoss.zul.tree.selectOnHighlight.disabled

.(since 7.0.4)

Sets whether to disable select functionality when highlighting text content with mouse dragging or not.

[Since 7.0.0] (EE version only)

org.zkoss.zul.tree.initRodSize

.

Specifies the number of items rendered when the Tree first render.

org.zkoss.zul.tree.maxRodPageSize

.

Specifies how many pages (of treeitems) to keep rendered in memory (on the server side) when navigating the tree using pagination. (Paging mold only)

org.zkoss.zul.tree.preloadSize

.

Specifies the number of items to preload when receiving the rendering request from the client.

It is used only if live data (setModel(TreeModel) and not paging (getPagingChild()).

Author:

tomyeh

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class org.zkoss.zul.impl.MeshElement

MeshElement.InternalPaging

Nested classes/interfaces inherited from class org.zkoss.zk.ui.HtmlBasedComponent

HtmlBasedComponent.ExtraCtrl

Nested classes/interfaces inherited from class org.zkoss.zk.ui.AbstractComponent

AbstractComponent.Children

Field Summary

Fields inherited from class org.zkoss.zk.ui.HtmlBasedComponent

_zclass

Fields inherited from interface org.zkoss.zk.ui.Component

APPLICATION_SCOPE, COMPONENT_SCOPE, DESKTOP_SCOPE, PAGE_SCOPE, REQUEST_SCOPE, SESSION_SCOPE, SPACE_SCOPE

Fields inherited from interface org.zkoss.zk.ui.sys.ComponentCtrl

CE_BUSY_IGNORE, CE_DUPLICATE_IGNORE, CE_IMPORTANT, CE_NON_DEFERRABLE, CE_REPEAT_IGNORE

Constructor Summary

Tree()

Method Summary

void	addItemToSelection(Treeitem item) Selects the given item, without deselecting any other items that are already selected..
void	beforeChildAdded(Component newChild, Component refChild) Default: does nothing.
void	clear() Clears all child tree items (Treeitem.
void	clearSelection() Clears the selection.
java.lang.Object	clone() Clones the component.
protected java.lang.Object	getAssociatedNode(Treeitem ti, Tree t) Return a node which is an associated Treeitem ti in a Tree tree
protected Component	getChildByNode(java.lang.Object node) Return the Tree or Treeitem component by a given associated node in model, or null if the treeitem is not instantiated (i.e., rendered) yet.
protected Component	getChildByPath(int[] path) Return the Tree or Treeitem component by a path, or null if corresponding Treeitem is not instantiated (i.e., rendered) yet.
Frozen	getFrozen() Returns the frozen child.
java.util.Collection<Component>	getHeads() Returns a collection of heads, including getTreecols() and auxiliary heads (Auxhead) (never null).
java.lang.String	getInnerWidth() Returns the inner width of this component.
int	getItemCount() Returns the number of child Treeitem.
<T> TreeitemRenderer<T>	getItemRenderer() Returns the renderer to render each item, or null if the default renderer is used.
java.util.Collection<Treeitem>	getItems() Returns a readonly list of all descending Treeitem (children's children and so on).
<T> TreeModel<T>	getModel() Returns the list model associated with this tree, or null if this tree is not associated with any tree data model.
java.lang.String	getName() Returns the name of this component.
java.lang.String	getNonselectableTags() Returns a list of HTML tag names that shall not cause the tree item being selected if they are clicked.
int	getPageSize() Returns the page size, a.k.a., the number items per page.
Paginal	getPaginal() Returns the paging controller, or null if not available.
Paging	getPagingChild() Returns the child paging controller that is created automatically, or null if mold is not "paging", or the controller is specified externally by setPaginal(org.zkoss.zul.ext.Paginal).
int	getRows() Returns the rows.
int	getSelectedCount() Returns the number of items being selected.
Treeitem	getSelectedItem() Returns the selected item.
java.util.Set<Treeitem>	getSelectedItems() Returns all selected items.
java.lang.String	getSeltype() Returns the seltype.
int	getTabindex() Returns the tab order of this component.
Treechildren	getTreechildren() Returns the treechildren that this tree owns (might null).
Treecols	getTreecols() Returns the treecols that this tree owns (might null).
Treefoot	getTreefoot() Returns the treefoot that this tree owns (might null).
<T> TreeitemRenderer<T>	getTreeitemRenderer() Deprecated. As of release 5.0.6, replaced with getItemRenderer(). /** Returns the renderer to render each item, or null if the default renderer is used.
java.lang.String	getZclass() Returns the ZK Cascading Style class(es) for this component.
boolean	insertBefore(Component newChild, Component refChild) Inserts a child before the reference child.
protected boolean	isAutohidePaging()
boolean	isCheckmark() Returns whether the check mark shall be displayed in front of each item.
boolean	isFixedLayout() Deprecated. since 5.0.0, use !MeshElement.isSizedByContent() instead
boolean	isMultiple() Returns whether multiple selections are allowed.
protected boolean	isSelectOnHighlightDisabled()
boolean	isVflex() Returns whether to grow and shrink vertical to fit their given space, so called vertical flexibility.
void	onChildAdded(Component child) Default: does nothing.
void	onChildRemoved(Component child) Default: does nothing.
void	onInitRender() Handles a private event, onInitRender.
void	onPageAttached(Page newpage, Page oldpage) Default: handles special event listeners.
void	onPageDetached(Page page) Default: handles special event listeners.
protected Paginal	pgi() Returns the instance of the @{link Paginal}
protected void	redrawChildren(java.io.Writer out) Redraws children (and then recursively descendants).
void	removeItemFromSelection(Treeitem item) Deselects the given item without deselecting other items.
void	renderItem(Treeitem item) Renders the specified Treeitem, if not loaded yet, with getItemRenderer().
void	renderItem(Treeitem item, java.lang.Object node) Renders the specified Treeitem, if not loaded yet, with getItemRenderer().
Treeitem	renderItemByNode(java.lang.Object node) Load the treeitems by the given node.
Treeitem	renderItemByPath(int[] path) Load the treeitems by giving a path of the treeitems top open.
void	renderItems(java.util.Set<? extends Treeitem> items) Renders the specified Treeitem if not loaded yet, with getItemRenderer().
protected void	renderProperties(ContentRenderer renderer) Renders the content of this component, excluding the enclosing tags and children.
void	selectAll() Selects all items.
void	selectItem(Treeitem item) Deselects all of the currently selected items and selects the given item.
void	service(AuRequest request, boolean everError) Processes an AU request.
void	sessionDidActivate(Page page) Notification that the session, which owns this component, has just been activated (a.k.a., deserialized).
void	sessionWillPassivate(Page page) Notification that the session, which owns this component, is about to be passivated (a.k.a., serialized).
void	setActivePage(Treeitem item) Sets the active page in which the specified item is.
void	setCheckmark(boolean checkmark) Sets whether the check mark shall be displayed in front of each item.
void	setFixedLayout(boolean fixedLayout) Deprecated. since 5.0.0, use MeshElement.setSizedByContent(boolean)(!fixedLayout) instead
void	setInnerWidth(java.lang.String innerWidth) Sets the inner width of this component.
void	setItemRenderer(java.lang.String clsnm) Sets the renderer by use of a class name.
void	setItemRenderer(TreeitemRenderer<?> renderer) Sets the renderer which is used to render each item if getModel() is not null.
void	setModel(TreeModel<?> model) Sets the tree model associated with this tree.
void	setMold(java.lang.String mold) Sets the mold to render this component.
void	setMultiple(boolean multiple) Sets whether multiple selections are allowed.
void	setName(java.lang.String name) Sets the name of this component.
void	setNonselectableTags(java.lang.String tags) Sets a list of HTML tag names that shall not cause the tree item being selected if they are clicked.
void	setPageSize(int pgsz) Sets the page size, a.k.a., the number items per page.
void	setPaginal(Paginal pgi)
void	setRows(int rows) Sets the rows.
void	setSelectedItem(Treeitem item) Deselects all of the currently selected items and selects the given item.
void	setSeltype(java.lang.String seltype) Sets the seltype.
void	setTabindex(int tabindex) Sets the tab order of this component.
void	setTreeitemRenderer(TreeitemRenderer<?> renderer) Deprecated. As of release 5.0.6, replaced with setItemRenderer(org.zkoss.zul.TreeitemRenderer). Sets the renderer which is used to render each item if getModel() is not null. Note: changing a render will not cause the tree to re-render. If you want it to re-render, you could assign the same model again (i.e., setModel(getModel())), or fire an TreeDataEvent event.
void	setVflex(boolean vflex) Sets whether to grow and shrink vertical to fit their given space, so called vertical flexibility.
void	smartUpdate(java.lang.String attr, java.lang.Object value) Smart-updates a property of the peer widget associated with the component, running at the client, with the given value.
void	toggleItemSelection(Treeitem item) If the specified item is selected, it is deselected.

Methods inherited from class org.zkoss.zul.impl.MeshElement

getActivePage, getPageCount, getPagingPosition, getSpan, isAutopaging, isSizedByContent, isSpan, setActivePage, setAutopaging, setPagingPosition, setSizedByContent, setSpan, setSpan

Methods inherited from class org.zkoss.zul.impl.XulElement

getContext, getCtrlKeys, getPopup, getTooltip, setContext, setContext, setCtrlKeys, setPopup, setPopup, setTooltip, setTooltip

Methods inherited from class org.zkoss.zk.ui.HtmlBasedComponent

focus, getAction, getDraggable, getDroppable, getExtraCtrl, getHeight, getHflex, getLeft, getRenderdefer, getSclass, getStyle, getTooltiptext, getTop, getVflex, getWidth, getZindex, getZIndex, setAction, setClass, setDraggable, setDroppable, setFocus, setHeight, setHeightDirectly, setHflex, setHflexDirectly, setLeft, setLeftDirectly, setRenderdefer, setSclass, setStyle, setTooltiptext, setTop, setTopDirectly, setVflex, setWidth, setWidthDirectly, setZclass, setZindex, setZIndex, setZIndexDirectly

Methods inherited from class org.zkoss.zk.ui.AbstractComponent

addAnnotation, addAnnotation, addClientEvent, addEventHandler, addEventListener, addEventListener, addForward, addForward, addForward, addForward, addMoved, addRedrawCallback, addScopeListener, addShadowRoot, addShadowRootBefore, addSharedEventHandlerMap, appendChild, applyProperties, beforeChildRemoved, beforeParentChanged, detach, didActivate, didActivate, didDeserialize, didDeserialize, disableBindingAnnotation, disableClientUpdate, enableBindingAnnotation, equals, getAnnotatedProperties, getAnnotatedPropertiesBy, getAnnotation, getAnnotation, getAnnotations, getAnnotations, getAnnotations, getAttribute, getAttribute, getAttribute, getAttributeOrFellow, getAttributes, getAttributes, getAuService, getAutag, getChildren, getClientAttribute, getClientEvents, getDefaultMold, getDefinition, getDesktop, getEventHandler, getEventHandlerNames, getEventListenerMap, getEventListeners, getFellow, getFellow, getFellowIfAny, getFellowIfAny, getFellows, getFirstChild, getId, getLastChild, getListenerIterator, getMold, getNextSibling, getPage, getParent, getPreviousSibling, getRedrawCallback, getRoot, getShadowRoots, getShadowVariable, getShadowVariable0, getSpaceOwner, getSpecialRendererOutput, getStubonly, getSubBindingAnnotationCount, getTemplate, getTemplateNames, getUuid, getWidgetAttribute, getWidgetAttributeNames, getWidgetClass, getWidgetListener, getWidgetListenerNames, getWidgetOverride, getWidgetOverrideNames, hasAttribute, hasAttribute, hasAttribute, hasAttributeOrFellow, hasBindingAnnotation, hasFellow, hasFellow, hasSubBindingAnnotation, invalidate, isChildable, isInvalidated, isListenerAvailable, isVisible, onWrongValue, query, queryAll, redraw, removeAttribute, removeAttribute, removeAttribute, removeChild, removeEventListener, removeForward, removeForward, removeRedrawCallback, removeScopeListener, removeShadowRoot, render, render, render, replace, response, response, response, service, setAttribute, setAttribute, setAttribute, setAuService, setAutag, setClientAttribute, setDefinition, setDefinition, setId, setPage, setPageBefore, setParent, setStubonly, setStubonly, setSubBindingAnnotationCount, setTemplate, setVisible, setVisibleDirectly, setWidgetAttribute, setWidgetClass, setWidgetListener, setWidgetOverride, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdateWidgetListener, smartUpdateWidgetOverride, toString, updateByClient, updateSubBindingAnnotationCount, willPassivate, willPassivate, willSerialize, willSerialize

Methods inherited from class java.lang.Object

finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Tree

public Tree()

Method Detail

onPageAttached

public void onPageAttached(Page newpage,
                           Page oldpage)

Description copied from class: AbstractComponent

Default: handles special event listeners.

Specified by:

onPageAttached in interface ComponentCtrl

Overrides:

onPageAttached in class AbstractComponent

Parameters:

newpage - the new page (never null).

oldpage - the previous page, if any, or null if it didn't belong to any page.

See Also:

ComponentCtrl.onPageAttached(org.zkoss.zk.ui.Page, org.zkoss.zk.ui.Page)

onPageDetached

public void onPageDetached(Page page)

Description copied from class: AbstractComponent

Default: handles special event listeners.

Specified by:

onPageDetached in interface ComponentCtrl

Overrides:

onPageDetached in class AbstractComponent

Parameters:

page - the previous page (never null)

See Also:

ComponentCtrl.onPageDetached(org.zkoss.zk.ui.Page)

setMold

public void setMold(java.lang.String mold)

Sets the mold to render this component.

Specified by:

setMold in interface Component

Overrides:

setMold in class AbstractComponent

Parameters:

mold - the mold. If null or empty, "default" is assumed. Allowed values: default, paging

See Also:

ComponentDefinition

getPaginal

public Paginal getPaginal()

Returns the paging controller, or null if not available. Note: the paging controller is used only if AbstractComponent.getMold() is "paging".

If mold is "paging", this method never returns null, because a child paging controller is created automatically (if not specified by developers with setPaginal(org.zkoss.zul.ext.Paginal)).

If a paging controller is specified (either by setPaginal(org.zkoss.zul.ext.Paginal), or by setMold(java.lang.String) with "paging"), the tree will rely on the paging controller to handle long-content instead of scrolling.

Since:

3.0.7

setPaginal

public void setPaginal(Paginal pgi)

getPagingChild

public Paging getPagingChild()

Returns the child paging controller that is created automatically, or null if mold is not "paging", or the controller is specified externally by setPaginal(org.zkoss.zul.ext.Paginal).

Since:

3.0.7

getPageSize

public int getPageSize()

Returns the page size, a.k.a., the number items per page.

Overrides:

getPageSize in class MeshElement

Throws:

java.lang.IllegalStateException - if getPaginal() returns null, i.e., mold is not "paging" and no external controller is specified.

Since:

2.4.1

setPageSize

public void setPageSize(int pgsz)
                 throws WrongValueException

Sets the page size, a.k.a., the number items per page.

Note: mold is "paging" and no external controller is specified.

Overrides:

setPageSize in class MeshElement

Throws:

WrongValueException

Since:

2.4.1

pgi

protected Paginal pgi()

Description copied from class: MeshElement

Returns the instance of the @{link Paginal}

Specified by:

pgi in class MeshElement

setFixedLayout

public void setFixedLayout(boolean fixedLayout)

Deprecated. since 5.0.0, use MeshElement.setSizedByContent(boolean)(!fixedLayout) instead

Parameters:

fixedLayout - true to outline this grid by browser

isFixedLayout

public boolean isFixedLayout()

Deprecated. since 5.0.0, use !MeshElement.isSizedByContent() instead

getTreecols

public Treecols getTreecols()

Returns the treecols that this tree owns (might null).

getTreefoot

public Treefoot getTreefoot()

Returns the treefoot that this tree owns (might null).

getFrozen

public Frozen getFrozen()

Returns the frozen child.

Since:

7.0.0

getTreechildren

public Treechildren getTreechildren()

Returns the treechildren that this tree owns (might null).

getHeads

public java.util.Collection<Component> getHeads()

Returns a collection of heads, including getTreecols() and auxiliary heads (Auxhead) (never null).

Since:

3.0.0

getRows

public int getRows()

Returns the rows. Zero means no limitation.

Default: 0.

setRows

public void setRows(int rows)
             throws WrongValueException

Sets the rows.

Note: if both HtmlBasedComponent.setHeight(java.lang.String) is specified with non-empty, setRows(int) is ignored

Throws:

WrongValueException

getName

public java.lang.String getName()

Returns the name of this component.

Default: null.

The name is used only to work with "legacy" Web application that handles user's request by servlets. It works only with HTTP/HTML-based browsers. It doesn't work with other kind of clients.

Don't use this method if your application is purely based on ZK's event-driven model.

setName

public void setName(java.lang.String name)

Sets the name of this component.

The name is used only to work with "legacy" Web application that handles user's request by servlets. It works only with HTTP/HTML-based browsers. It doesn't work with other kind of clients.

Don't use this method if your application is purely based on ZK's event-driven model.

Parameters:

name - the name of this component.

setNonselectableTags

public void setNonselectableTags(java.lang.String tags)

Sets a list of HTML tag names that shall not cause the tree item being selected if they are clicked.

Default: null (it means button, input, textarea and a). If you want to select no matter which tag is clicked, please specify an empty string.

Parameters:

tags - a list of HTML tag names that will not cause the tree item being selected if clicked. Specify null to use the default and "" to indicate none.

Since:

5.0.5

getNonselectableTags

public java.lang.String getNonselectableTags()

Returns a list of HTML tag names that shall not cause the tree item being selected if they are clicked.

Refer to setNonselectableTags(java.lang.String) for details.

Since:

5.0.5

isCheckmark

public boolean isCheckmark()

Returns whether the check mark shall be displayed in front of each item.

Default: false.

setCheckmark

public void setCheckmark(boolean checkmark)

Sets whether the check mark shall be displayed in front of each item.

The check mark is a checkbox if isMultiple() returns true. It is a radio button if isMultiple() returns false.

isVflex

public boolean isVflex()

Returns whether to grow and shrink vertical to fit their given space, so called vertical flexibility.

Note: this attribute is ignored if setRows(int) is specified

Default: false.

setVflex

public void setVflex(boolean vflex)

Sets whether to grow and shrink vertical to fit their given space, so called vertical flexibility.

Note: this attribute is ignored if setRows(int) is specified

setInnerWidth

public void setInnerWidth(java.lang.String innerWidth)

Sets the inner width of this component. The inner width is the width of the inner table. By default, it is 100%. That is, it is the same as the width of this component. However, it is changed when the user is sizing the column's width.

Application developers rarely call this method, unless they want to preserve the widths of sizable columns changed by the user. To preserve the widths, the developer have to store the widths of all columns and the inner width (getInnerWidth()), and then restore them when re-creating this component.

Parameters:

innerWidth - the inner width. If null, "100%" is assumed.

Since:

3.0.0

getInnerWidth

public java.lang.String getInnerWidth()

Returns the inner width of this component. The inner width is the width of the inner table.

Default: "100%"

Since:

3.0.0

See Also:

setInnerWidth(java.lang.String)

getSeltype

public java.lang.String getSeltype()

Returns the seltype.

Default: "single".

setSeltype

public void setSeltype(java.lang.String seltype)
                throws WrongValueException

Sets the seltype. "single","multiple" is supported.

Throws:

WrongValueException

getTabindex

public int getTabindex()

Returns the tab order of this component.

Since:

7.0.4

Default: 0 (means the same as browser's default).

setTabindex

public void setTabindex(int tabindex)
                 throws WrongValueException

Sets the tab order of this component.

Throws:

WrongValueException

Since:

7.0.4

isMultiple

public boolean isMultiple()

Returns whether multiple selections are allowed.

Default: false.

setMultiple

public void setMultiple(boolean multiple)

Sets whether multiple selections are allowed.

Notice that, if a model is assigned, it will change the model's state (by TreeSelectableModel.setMultiple(boolean)).

setActivePage

public void setActivePage(Treeitem item)

Sets the active page in which the specified item is. The active page will become the page that contains the specified item.

Parameters:

item - the item to show. If the item is null, invisible, or doesn't belong to the same tree, nothing happens.

Since:

3.0.4

smartUpdate

public void smartUpdate(java.lang.String attr,
                        java.lang.Object value)

Description copied from class: AbstractComponent

Smart-updates a property of the peer widget associated with the component, running at the client, with the given value.

The second invocation with the same property will replace the previous call. In other words, the same property will be set only once in each execution. If you prefer to send both updates to the client, use AbstractComponent.smartUpdate(String, Object, boolean) instead.

This method has no effect if AbstractComponent.invalidate() is ever invoked (in the same execution), since AbstractComponent.invalidate() assumes the whole content shall be redrawn and all smart updates to this components can be ignored,

Once AbstractComponent.invalidate() is called, all invocations to AbstractComponent.smartUpdate(String, Object) will then be ignored, and AbstractComponent.redraw(java.io.Writer) will be invoked later.

It can be called only in the request-processing and event-processing phases; excluding the redrawing phase.

There are two ways to draw a component, one is to invoke Component.invalidate(), and the other is AbstractComponent.smartUpdate(String, Object). While Component.invalidate() causes the whole content to redraw, AbstractComponent.smartUpdate(String, Object) let component developer control which part to redraw.

Overrides:

smartUpdate in class AbstractComponent

value - the new value. If it is DeferredValue, the value will be retrieved (by calling DeferredValue.getValue()) in the rendering phase. It is useful if the value can not be determined now.

For some old application servers (example, Websphere 5.1), Execution.encodeURL(java.lang.String) cannot be called in the event processing thread. So, the developers have to use DeferredValue or disable the use of the event processing thread (by use of disable-event-thread in zk.xml).

If you want to generate the JavaScript code directly (i.e., the value is a valid JavaScript snippet), you can use JavaScriptValue. Notice that the JavaScript code will be evaluated before assigning it to the widget.

If the value is a Date object, a special pattern will be generated (a.k.a., marshaling) to ensure it can be unmarshalled back correctly at the client. Notice that it is marshalled to a string based on TimeZones.getCurrent(), and then unmarshalled back at the client. In other words, if the client is in different time-zone, the value returned by getTime() might be different. However, the value will remain the same if the client marshalled the Date object back. In other words, it assumes the browser's time zone from enduser's perspective (not really browser's setting) shall be the same as TimeZones.getCurrent().

If the value is a component, a special pattern will be generated to ensure it can be unmarshalled back correctly at the client.

In addition, the value can be any kind of objects that the client accepts (marshaled by JSON) (see also JSONAware).

See Also:

AbstractComponent.updateByClient(java.lang.String, java.lang.Object), AbstractComponent.smartUpdate(String, Object, boolean)

getItems

public java.util.Collection<Treeitem> getItems()

Returns a readonly list of all descending Treeitem (children's children and so on).

Note: the performance of the size method of returned collection is no good.

getItemCount

public int getItemCount()

Returns the number of child Treeitem. The same as getItems().size().

Note: the performance of this method is no good.

selectItem

public void selectItem(Treeitem item)

Deselects all of the currently selected items and selects the given item.

It is the same as setSelectedItem(org.zkoss.zul.Treeitem).

Parameters:

item - the item to select. If null, all items are deselected.

addItemToSelection

public void addItemToSelection(Treeitem item)

Selects the given item, without deselecting any other items that are already selected..

removeItemFromSelection

public void removeItemFromSelection(Treeitem item)

Deselects the given item without deselecting other items.

toggleItemSelection

public void toggleItemSelection(Treeitem item)

If the specified item is selected, it is deselected. If it is not selected, it is selected. Other items in the tree that are selected are not affected, and retain their selected state.

clearSelection

public void clearSelection()

Clears the selection.

selectAll

public void selectAll()

Selects all items.

getSelectedItem

public Treeitem getSelectedItem()

Returns the selected item.

setSelectedItem

public void setSelectedItem(Treeitem item)

Deselects all of the currently selected items and selects the given item.

It is the same as selectItem(org.zkoss.zul.Treeitem).

getSelectedItems

public java.util.Set<Treeitem> getSelectedItems()

Returns all selected items.

getSelectedCount

public int getSelectedCount()

Returns the number of items being selected.

clear

public void clear()

Clears all child tree items (Treeitem.

Note: after clear, getTreechildren() won't be null, but it has no child

getZclass

public java.lang.String getZclass()

Description copied from class: HtmlBasedComponent

Returns the ZK Cascading Style class(es) for this component. It usually depends on the implementation of the mold (AbstractComponent.getMold()).

Default: null (the default value depends on element).

HtmlBasedComponent.setZclass(java.lang.String)) will completely replace the default style of a component. In other words, the default style of a component is associated with the default value of HtmlBasedComponent.getZclass(). Once it is changed, the default style won't be applied at all. If you want to perform small adjustments, use HtmlBasedComponent.setSclass(java.lang.String) instead.

Overrides:

getZclass in class HtmlBasedComponent

See Also:

HtmlBasedComponent.getSclass()

beforeChildAdded

public void beforeChildAdded(Component newChild,
                             Component refChild)

Description copied from class: AbstractComponent

Default: does nothing.

Specified by:

beforeChildAdded in interface ComponentCtrl

Overrides:

beforeChildAdded in class AbstractComponent

Parameters:

newChild - the child to be added (never null).

refChild - another child component that the new child will be inserted before it. If null, the new child will be the last child.

See Also:

ComponentCtrl.beforeChildAdded(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component)

insertBefore

public boolean insertBefore(Component newChild,
                            Component refChild)

Description copied from interface: Component

Inserts a child before the reference child.

You could use Component.setParent(org.zkoss.zk.ui.Component) or Component.appendChild(org.zkoss.zk.ui.Component) instead of this method, unless you want to control where to put the child.

Note: Component.setParent(org.zkoss.zk.ui.Component) always calls back Component.insertBefore(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component) and/or Component.removeChild(org.zkoss.zk.ui.Component), while Component.insertBefore(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component) and Component.removeChild(org.zkoss.zk.ui.Component) always calls back Component.setParent(org.zkoss.zk.ui.Component), if the parent is changed. Thus, you don't need to override both Component.insertBefore(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component) and Component.setParent(org.zkoss.zk.ui.Component), if you want to customize the behavior.

If you would like to monitor if a component is attached or detached from a page, you could register a desktop listener implementing UiLifeCycle.

Specified by:

insertBefore in interface Component

Overrides:

insertBefore in class AbstractComponent

Parameters:

newChild - the new child to be inserted.

refChild - the child before which you want the new child being inserted. If null, the new child is append to the end.

Returns:

true if newChild is added successfully or moved; false if it already has the specified child and the order doesn't change.

onChildAdded

public void onChildAdded(Component child)

Description copied from class: AbstractComponent

Default: does nothing.

Specified by:

onChildAdded in interface ComponentCtrl

Overrides:

onChildAdded in class AbstractComponent

See Also:

ComponentCtrl.onChildAdded(org.zkoss.zk.ui.Component)

onChildRemoved

public void onChildRemoved(Component child)

Description copied from class: AbstractComponent

Default: does nothing.

Specified by:

onChildRemoved in interface ComponentCtrl

Overrides:

onChildRemoved in class AbstractComponent

See Also:

ComponentCtrl.onChildRemoved(org.zkoss.zk.ui.Component)

clone

public java.lang.Object clone()

Description copied from interface: Component

Clones the component. All of its children and descendants are cloned. Also, ID are preserved.

Specified by:

clone in interface Component

Overrides:

clone in class XulElement

Returns:

the new component. Notice that it doesn't belong to any page, nor desktop. It doesn't have a parent, either.

sessionWillPassivate

public void sessionWillPassivate(Page page)

Description copied from interface: ComponentCtrl

Notification that the session, which owns this component, is about to be passivated (a.k.a., serialized).

Note: only root components are notified by this method.

Specified by:

sessionWillPassivate in interface ComponentCtrl

Overrides:

sessionWillPassivate in class AbstractComponent

sessionDidActivate

public void sessionDidActivate(Page page)

Description copied from interface: ComponentCtrl

Notification that the session, which owns this component, has just been activated (a.k.a., deserialized).

Note: only root components are notified by this method.

Specified by:

sessionDidActivate in interface ComponentCtrl

Overrides:

sessionDidActivate in class AbstractComponent

getChildByNode

protected Component getChildByNode(java.lang.Object node)

Return the Tree or Treeitem component by a given associated node in model, or null if the treeitem is not instantiated (i.e., rendered) yet. It returns this tree if the given node is the root node (i.e., TreeModel.getRoot()).

Throws:

java.lang.IllegalStateException - if no model is assigned (setModel(org.zkoss.zul.TreeModel)).

Since:

3.0.0

See Also:

renderItemByNode(java.lang.Object)

getChildByPath

protected Component getChildByPath(int[] path)

Return the Tree or Treeitem component by a path, or null if corresponding Treeitem is not instantiated (i.e., rendered) yet. It returns this tree if the given node is the root node. (i.e., TreeModel.getRoot()).

Since:

6.0.0

setModel

public void setModel(TreeModel<?> model)

Sets the tree model associated with this tree.

Note: changing a render will not cause the tree to re-render. If you want it to re-render, you could assign the same model again (i.e., setModel(getModel())), or fire an TreeDataEvent event.

Parameters:

model - the tree model to associate, or null to dissociate any previous model.

Throws:

UiException - if failed to initialize with the model

Since:

3.0.0

onInitRender

public void onInitRender()

Handles a private event, onInitRender. It is used only for implementation, and you rarely need to invoke it explicitly.

Since:

6.0.0

getModel

public <T> TreeModel<T> getModel()

Returns the list model associated with this tree, or null if this tree is not associated with any tree data model.

Returns:

the list model associated with this tree

Since:

3.0.0

setItemRenderer

public void setItemRenderer(TreeitemRenderer<?> renderer)

Sets the renderer which is used to render each item if getModel() is not null.

Note: changing a render will not cause the tree to re-render. If you want it to re-render, you could assign the same model again (i.e., setModel(getModel())), or fire an TreeDataEvent event.

Parameters:

renderer - the renderer, or null to use the default.

Throws:

UiException - if failed to initialize with the model

Since:

5.0.6

setItemRenderer

public void setItemRenderer(java.lang.String clsnm)
                     throws java.lang.ClassNotFoundException,
                            java.lang.NoSuchMethodException,
                            java.lang.IllegalAccessException,
                            java.lang.InstantiationException,
                            java.lang.reflect.InvocationTargetException

Sets the renderer by use of a class name. It creates an instance automatically.

Throws:

java.lang.ClassNotFoundException

java.lang.NoSuchMethodException

java.lang.IllegalAccessException

java.lang.InstantiationException

java.lang.reflect.InvocationTargetException

Since:

6.5.2

getItemRenderer

public <T> TreeitemRenderer<T> getItemRenderer()

Returns the renderer to render each item, or null if the default renderer is used.

Returns:

the renderer to render each item, or null if the default

Since:

5.0.6

setTreeitemRenderer

public void setTreeitemRenderer(TreeitemRenderer<?> renderer)

Deprecated. As of release 5.0.6, replaced with setItemRenderer(org.zkoss.zul.TreeitemRenderer). Sets the renderer which is used to render each item if getModel() is not null.

Note: changing a render will not cause the tree to re-render. If you want it to re-render, you could assign the same model again (i.e., setModel(getModel())), or fire an TreeDataEvent event.

Parameters:

renderer - the renderer, or null to use the default.

Throws:

UiException - if failed to initialize with the model

Since:

3.0.0

getTreeitemRenderer

public <T> TreeitemRenderer<T> getTreeitemRenderer()

Deprecated. As of release 5.0.6, replaced with getItemRenderer(). /** Returns the renderer to render each item, or null if the default renderer is used.

Returns:

the renderer to render each item, or null if the default

Since:

3.0.0

renderItem

public void renderItem(Treeitem item)

Renders the specified Treeitem, if not loaded yet, with getItemRenderer().

It does nothing if getModel() returns null.

To unload treeitem, use Treeitem.unload().

Since:

3.0.0

See Also:

renderItems(java.util.Set)

renderItem

public void renderItem(Treeitem item,
                       java.lang.Object node)

Renders the specified Treeitem, if not loaded yet, with getItemRenderer().

It does nothing if getModel() returns null.

Note: Since the corresponding node is given, This method has better performance than renderItem(Treeitem item) due to not searching for its corresponding node.

To unload treeitem, use Treeitem.unload().

Since:

3.0.0

See Also:

renderItems(java.util.Set)

renderItems

public void renderItems(java.util.Set<? extends Treeitem> items)

Renders the specified Treeitem if not loaded yet, with getItemRenderer().

It does nothing if getModel() returns null.

To unload treeitem, with Treeitem.unload().

Since:

3.0.0

See Also:

renderItem(org.zkoss.zul.Treeitem)

getAssociatedNode

protected java.lang.Object getAssociatedNode(Treeitem ti,
                                             Tree t)

Return a node which is an associated Treeitem ti in a Tree tree

Since:

3.0.0

renderItemByNode

public Treeitem renderItemByNode(java.lang.Object node)

Load the treeitems by the given node. This method must be used with a tree model, and the node is one of the value returned by TreeModel.getChild(E, int).

Notice that this method has to search the model one-by-one. The performance might not be good, so use renderItemByPath(int[]) if possible.

Returns:

the treeitem that is associated with the give node, or null no treeitem is associated (including the give node is the root).

Throws:

java.lang.IllegalStateException - if no model is assigned (setModel(org.zkoss.zul.TreeModel)).

Since:

5.0.6, #getChildByNode

renderItemByPath

public Treeitem renderItemByPath(int[] path)

Load the treeitems by giving a path of the treeitems top open.
Note: By using this method, all treeitems in path will be rendered and opened (Treeitem.setOpen(boolean)). If you want to visit the rendered item in paging mold, please invoke setActivePage(Treeitem).

Parameters:

path - - an index path. The first element is the index at the first level of the tree structure.

Returns:

the treeitem from tree by given path

Since:

3.0.0

redrawChildren

protected void redrawChildren(java.io.Writer out)
                       throws java.io.IOException

Description copied from class: AbstractComponent

Redraws children (and then recursively descendants).

Default: it invokes AbstractComponent.redraw(java.io.Writer) for all its children.

If a derived class renders only a subset of its children (such as paging/cropping), it could override AbstractComponent.redrawChildren(java.io.Writer).

Overrides:

redrawChildren in class AbstractComponent

Throws:

java.io.IOException

See Also:

AbstractComponent.redraw(java.io.Writer)

renderProperties

protected void renderProperties(ContentRenderer renderer)
                         throws java.io.IOException

Description copied from class: HtmlBasedComponent

Renders the content of this component, excluding the enclosing tags and children.

See also ZK Client-side Reference: Property Rendering

Overrides:

renderProperties in class MeshElement

Throws:

java.io.IOException

isAutohidePaging

protected boolean isAutohidePaging()

Specified by:

isAutohidePaging in class MeshElement

isSelectOnHighlightDisabled

protected boolean isSelectOnHighlightDisabled()

service

public void service(AuRequest request,
                    boolean everError)

Processes an AU request.

Default: in addition to what are handled by HtmlBasedComponent.service(org.zkoss.zk.au.AuRequest, boolean), it also handles onSelect.

Specified by:

service in interface ComponentCtrl

Overrides:

service in class HtmlBasedComponent

everError - whether any error ever occurred before processing this request.

Since:

5.0.0

See Also:

AbstractComponent.setAuService(org.zkoss.zk.au.AuService)