org.zkoss.zul.api
Interface Tree

All Superinterfaces:
java.lang.Cloneable, Component, HtmlBasedComponent, Paginated, Scope, java.io.Serializable, XulElement
All Known Implementing Classes:
Tree

public interface Tree
extends XulElement, Paginated

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

Event:

  1. org.zkoss.zk.ui.event.SelectEvent is sent when user changes the selection.

Default HtmlBasedComponent.getZclass(): z-tree, and an other option is z-dottree. (since 3.5.0)

Since:
3.5.2
Author:
tomyeh

Field Summary
 
Fields inherited from interface org.zkoss.zk.ui.Component
APPLICATION_SCOPE, COMPONENT_SCOPE, DESKTOP_SCOPE, PAGE_SCOPE, REQUEST_SCOPE, SESSION_SCOPE, SPACE_SCOPE
 
Method Summary
 void addItemToSelectionApi(Treeitem item)
          Selects the given item, without deselecting any other items that are already selected..
 void clear()
          Clears all child tree items (Treeitem.
 void clearSelection()
          Clears the selection.
 int getActivePage()
          Returns the active page (starting from 0).
 java.util.Collection getHeads()
          Returns a collection of heads, including getTreecolsApi() 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.
 java.util.Collection getItems()
          Returns a readonly list of all descending Treeitem (children's children and so on).
 TreeModel 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.
 int getPageCount()
          Returns the number of pages.
 int getPageSize()
          Returns the page size, aka., the number items per page.
 Paginal getPaginal()
          Returns the paging controller, or null if not available.
 Paging getPagingChildApi()
          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 getSelectedItemApi()
          Returns the selected item.
 java.util.Set getSelectedItems()
          Returns all selected items.
 java.lang.String getSeltype()
          Returns the seltype.
 Treechildren getTreechildrenApi()
          Returns the treechildren that this tree owns (might null).
 Treecols getTreecolsApi()
          Returns the treecols that this tree owns (might null).
 Treefoot getTreefootApi()
          Returns the treefoot that this tree owns (might null).
 TreeitemRenderer getTreeitemRenderer()
          Returns the renderer to render each item, or null if the default renderer is used.
 boolean isFixedLayout()
          Deprecated. since 5.0.0, use !isSizedByContent() instead
 boolean isMultiple()
          Returns whether multiple selections are allowed.
 boolean isSizedByContent()
          Returns whether sizing tree grid column width by its content.
 void removeItemFromSelectionApi(Treeitem item)
          Deselects the given item without deselecting other items.
 void renderItemApi(Treeitem item)
          Renders the specified Treeitem, if not loaded yet, with getTreeitemRenderer().
 void renderItemApi(Treeitem item, java.lang.Object node)
          Renders the specified Treeitem, if not loaded yet, with getTreeitemRenderer().
 Treeitem renderItemByPathApi(int[] path)
          Load treeitems through path path
Note: By using this method, all treeitems in path will be rendered and opened (Treeitem.setOpen(boolean)).
 void renderItems(java.util.Set items)
          Renders the specified Treeitem if not loaded yet, with getTreeitemRenderer().
 void selectAll()
          Selects all items.
 void selectItemApi(Treeitem item)
          Deselects all of the currently selected items and selects the given item.
 void setActivePage(int pg)
          Sets the active page (starting from 0).
 void setActivePageApi(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 setSizedByContent(boolean)(!fixedLayout) instead
 void setInnerWidth(java.lang.String innerWidth)
          Sets the inner width of this component.
 void setModel(TreeModel model)
          Sets the tree model associated with this tree.
 void setMultiple(boolean multiple)
          Sets whether multiple selections are allowed.
 void setName(java.lang.String name)
          Sets the name of this component.
 void setPageSize(int pgsz)
          Sets the page size, aka., the number items per page.
 void setPaginal(Paginal pgi)
          Specifies the paging controller.
 void setPagingPosition(java.lang.String pagingPosition)
          Sets how to position the paging of tree at the client screen.
 void setRows(int rows)
          Sets the rows.
 void setSelectedItemApi(Treeitem item)
          Deselects all of the currently selected items and selects the given item.
 void setSeltype(java.lang.String seltype)
          Sets the seltype.
 void setSizedByContent(boolean byContent)
          Sets whether sizing tree grid column width by its content.
 void setTreeitemRenderer(TreeitemRenderer renderer)
          Sets the renderer which is used to render each item if getModel() is not null.
 void setVflex(boolean vflex)
          Sets whether to grow and shrink vertical to fit their given space, so called vertial flexibility.
 void toggleItemSelectionApi(Treeitem item)
          If the specified item is selected, it is deselected.
 
Methods inherited from interface org.zkoss.zul.impl.api.XulElement
getAction, getContext, getCtrlKeys, getPopup, getTooltip, setAction, setContext, setContext, setCtrlKeys, setPopup, setPopup, setTooltip, setTooltip
 
Methods inherited from interface org.zkoss.zk.ui.api.HtmlBasedComponent
focus, getHeight, getLeft, getSclass, getStyle, getTooltiptext, getTop, getWidth, getZclass, getZindex, getZIndex, setDraggable, setDroppable, setFocus, setHeight, setLeft, setSclass, setStyle, setTooltiptext, setTop, setWidth, setZclass, setZindex, setZIndex
 
Methods inherited from interface org.zkoss.zk.ui.Component
addEventListener, addForward, addForward, addForward, addForward, appendChild, applyProperties, clone, containsVariable, detach, getAttribute, getAttribute, getAttributeOrFellow, getAttributes, getAttributes, getAuService, getChildren, getDefinition, getDesktop, getFellow, getFellow, getFellowIfAny, getFellowIfAny, getFellows, getFirstChild, getId, getLastChild, getListenerIterator, getMold, getNamespace, getNextSibling, getPage, getParent, getPreviousSibling, getRoot, getSpaceOwner, getUuid, getVariable, getWidgetClass, getWidgetListener, getWidgetListenerNames, getWidgetOverride, getWidgetOverrideNames, hasAttribute, hasAttribute, hasAttributeOrFellow, hasFellow, hasFellow, insertBefore, invalidate, isInvalidated, isListenerAvailable, isVisible, removeAttribute, removeAttribute, removeChild, removeEventListener, removeForward, removeForward, setAttribute, setAttribute, setAuService, setId, setMold, setPage, setPageBefore, setParent, setVariable, setVisible, setWidgetListener, setWidgetOverride, unsetVariable
 
Methods inherited from interface org.zkoss.zk.ui.ext.Scope
addScopeListener, getAttribute, hasAttribute, removeAttribute, removeScopeListener, setAttribute
 
Methods inherited from interface org.zkoss.zul.ext.Paginated
getPagingPosition
 

Method Detail

setPagingPosition

void setPagingPosition(java.lang.String pagingPosition)
Sets how to position the paging of tree at the client screen. It is meaningless if the mold is not in "paging".

Parameters:
pagingPosition - how to position. It can only be "bottom" (the default), or "top", or "both".

getPaginal

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

If mold is "paging", this method never returns null, because a child paging controller is created automcatically (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 Component.setMold(java.lang.String) with "paging"), the tree will rely on the paging controller to handle long-content instead of scrolling.


setPaginal

void setPaginal(Paginal pgi)
Specifies the paging controller. Note: the paging controller is used only if Component.getMold() is "paging".

It is OK, though without any effect, to specify a paging controller even if mold is not "paging".

Parameters:
pgi - the paging controller. If null and Component.getMold() is "paging", a paging controller is created automatically as a child component (see getPagingChildApi() ).

getPagingChildApi

Paging getPagingChildApi()
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).


getPageSize

int getPageSize()
Returns the page size, aka., the number items per page.

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

setPageSize

void setPageSize(int pgsz)
                 throws WrongValueException
Sets the page size, aka., the number items per page.

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

Throws:
WrongValueException

getPageCount

int getPageCount()
Returns the number of pages. Note: there is at least one page even no item at all.


getActivePage

int getActivePage()
Returns the active page (starting from 0).


setActivePage

void setActivePage(int pg)
                   throws WrongValueException
Sets the active page (starting from 0).

Throws:
WrongValueException

setSizedByContent

void setSizedByContent(boolean byContent)
Sets whether sizing tree grid column width by its content. Default is false, i.e. the outline of grid is dependent on browser. It means, we don't calculate the width of each cell. If set to true, the outline will count on the content of body. In other words, the outline of grid will be like ZK version 2.4.1 that the header's width is only for reference.

You can also specify the "sized-by-content" attribute of component in lang-addon.xml directly, it will then take higher priority.

Parameters:
byContent -
Since:
5.0.0

isSizedByContent

boolean isSizedByContent()
Returns whether sizing tree grid column width by its content. Default is false.

Note: if the "sized-by-content" attribute of component is specified, it's prior to the original value.

Since:
5.0.0
See Also:
setSizedByContent(boolean)

setFixedLayout

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

Sets the outline of grid whether is fixed layout. If true, the outline of grid will be depended on browser. It means, we don't calculate the width of each cell. Otherwise, the outline will count on the content of body. In other words, the outline of grid is like ZK 2.4.1 version that the header's width is only for reference.

You can also specify the "fixed-layout" attribute of component in lang-addon.xml directly, it's a top priority.


isFixedLayout

boolean isFixedLayout()
Deprecated. since 5.0.0, use !isSizedByContent() instead

Returns the outline of grid whether is fixed layout.

Default: false.

Note: if the "fixed-layout" attribute of component is specified, it's prior to the original value.


getTreecolsApi

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


getTreefootApi

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


getTreechildrenApi

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


getHeads

java.util.Collection getHeads()
Returns a collection of heads, including getTreecolsApi() and auxiliary heads (Auxhead) (never null).


getRows

int getRows()
Returns the rows. Zero means no limitation.

Default: 0.


setRows

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

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

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.

setCheckmark

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.


setVflex

void setVflex(boolean vflex)
Sets whether to grow and shrink vertical to fit their given space, so called vertial flexibility.

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


setInnerWidth

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.

getInnerWidth

java.lang.String getInnerWidth()
Returns the inner width of this component. The inner width is the width of the inner table.

Default: "100%"

See Also:
setInnerWidth(java.lang.String)

getSeltype

java.lang.String getSeltype()
Returns the seltype.

Default: "single".


setSeltype

void setSeltype(java.lang.String seltype)
                throws WrongValueException
Sets the seltype. Currently, only "single" is supported.

Throws:
WrongValueException

isMultiple

boolean isMultiple()
Returns whether multiple selections are allowed.

Default: false.


setMultiple

void setMultiple(boolean multiple)
Sets whether multiple selections are allowed.


setActivePageApi

void setActivePageApi(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.

getItems

java.util.Collection 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

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

Note: the performance of this method is no good.


selectItemApi

void selectItemApi(Treeitem item)
Deselects all of the currently selected items and selects the given item.

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

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

addItemToSelectionApi

void addItemToSelectionApi(Treeitem item)
Selects the given item, without deselecting any other items that are already selected..


removeItemFromSelectionApi

void removeItemFromSelectionApi(Treeitem item)
Deselects the given item without deselecting other items.


toggleItemSelectionApi

void toggleItemSelectionApi(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

void clearSelection()
Clears the selection.


selectAll

void selectAll()
Selects all items.


getSelectedItemApi

Treeitem getSelectedItemApi()
Returns the selected item.


setSelectedItemApi

void setSelectedItemApi(Treeitem item)
Deselects all of the currently selected items and selects the given item.

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


getSelectedItems

java.util.Set getSelectedItems()
Returns all selected items.


getSelectedCount

int getSelectedCount()
Returns the number of items being selected.


clear

void clear()
Clears all child tree items (Treeitem.

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


setModel

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.

Author: jeffliu

Parameters:
model - the tree model to associate, or null to dis-associate any previous model.
Throws:
UiException - if failed to initialize with the model

getModel

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

Author: jeffliu

Returns:
the list model associated with this tree

setTreeitemRenderer

void setTreeitemRenderer(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.

Author: jeffliu

Parameters:
renderer - the renderer, or null to use the default.
Throws:
UiException - if failed to initialize with the model

getTreeitemRenderer

TreeitemRenderer getTreeitemRenderer()
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

renderItemApi

void renderItemApi(Treeitem item)
Renders the specified Treeitem, if not loaded yet, with getTreeitemRenderer().

It does nothing if getModel() returns null.

To unload treeitem, use Treeitem.unload().

See Also:
renderItems(java.util.Set)

renderItemApi

void renderItemApi(Treeitem item,
                   java.lang.Object node)
Renders the specified Treeitem, if not loaded yet, with getTreeitemRenderer().

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().

See Also:
renderItems(java.util.Set)

renderItems

void renderItems(java.util.Set items)
Renders the specified Treeitem if not loaded yet, with getTreeitemRenderer().

It does nothing if getModel() returns null.

To unload treeitem, with Treeitem.unload().

See Also:
Tree.renderItem(org.zkoss.zul.Treeitem)

renderItemByPathApi

Treeitem renderItemByPathApi(int[] path)
Load treeitems through path path
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 setActivePageApi(Treeitem).

Parameters:
path - - an int[] path, see TreeModel.getPath(java.lang.Object, java.lang.Object)
Returns:
the treeitem from tree by given path


Copyright © 2005-2009 Potix Corporation. All Rights Reserved. SourceForge.net Logo