Package org.zkoss.zul

Class 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<E> selected = new ArrayList<E>();
 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<E> opened = new ArrayList<E>();
 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

    • Field Detail

      • DEFAULT_THROTTLE_MILLIS

        public static final int DEFAULT_THROTTLE_MILLIS
        See Also:
        Constant Field Values

    • Constructor Detail

      • Tree

        public Tree()

    • Method Detail

      • 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

      • 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

      • pgi

        protected Paginal pgi()
        Description copied from class: MeshElement
        Returns the instance of the @{link Paginal}
        Specified by:
        pgi in class MeshElement

      • 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.

      • 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

      • setVflex

        public void setVflex​(java.lang.String flex)
        Description copied from class: HtmlBasedComponent
        Sets vertical flexibility hint of this component.

        Number flex indicates how this component's container distributes remaining empty space among its children vertically. Flexible component grow and shrink to fit their given space. Flexible components with larger flex values will be made larger than components with lower flex values, at the ratio determined by all flexible components. The actual flex value is not relevant unless there are other flexible components within the same container. Once the default sizes of components in a container are calculated, the remaining space in the container is divided among the flexible components, according to their flex ratios.

        Specify a flex value of negative value, 0, or "false" has the same effect as leaving the flex attribute out entirely. Specify a flex value of "true" has the same effect as a flex value of 1.

        Special flex hint, "min", indicates that the minimum space shall be given to this flexible component to enclose all of its children components. That is, the flexible component grow and shrink to fit its children components.

        Overrides:
        setVflex in class HtmlBasedComponent
        Parameters:
        flex - the vertical flex hint.
        See Also:
        HtmlBasedComponent.setHflex(java.lang.String), HtmlBasedComponent.getVflex()

      • 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".

      • 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

      • 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.

      • 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

      • 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.

      • 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

      • 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

      • isSelectOnHighlightDisabled

        protected boolean isSelectOnHighlightDisabled()

      • getPropertyAccess

        public PropertyAccess getPropertyAccess​(java.lang.String prop)
        Description copied from interface: ComponentCtrl
        Returns the corresponding property access object from the given property name, if any.
        Specified by:
        getPropertyAccess in interface ComponentCtrl
        Overrides:
        getPropertyAccess in class XulElement
        Parameters:
        prop - the name of the property
        Returns:
        null it means not to support for the property name.

      • getActivePage

        public int getActivePage()
        Description copied from class: MeshElement
        Returns the active page (starting from 0).
        Overrides:
        getActivePage in class MeshElement

      • onAfterRender

        public void onAfterRender()