Package org.zkoss.stateless.sul

Interface ITree

All Superinterfaces:
IAnyGroup<ITree>, IComponent<ITree>, IComposite<ITree,IMeshComposite>, IHtmlBasedComponent<ITree>, IMeshElement<ITree>, IXulElement<ITree>
public interface ITree extends IMeshElement<ITree>, IComposite<ITree,IMeshComposite>, IAnyGroup<ITree>
Immutable Tree component.

A tree consists of three parts, the set of columns, the set of footers, and the tree body. The set of columns is defined by a number of ITreecol components, one for each column. Each column will appear as a header at the top of the tree. The second part, the set of footers is defined by a number of ITreefooter components, one for each column also. Each column will appear as a footer at the bottom of the tree. The third part, the tree body, contains the data to appear in the tree and is created with a ITreechildren component.

Although ITreecols is optional, if it exists, notice that the number of its child (ITreecol) should equal the number of ITreecell, so that tree can display its content correctly. If ITreecols contains no ITreecol, the tree will display nothing in its content.

Support @Action

Name Action Type
onSelect ActionData: SelectData
Notifies one that the user has selected a new item in the tree.
onFocus Denotes when a component gets the focus. Remember event listeners execute at the server, so the focus at the client might be changed when the event listener for onFocus got executed.
onBlur Denotes when a component loses the focus. Remember event listeners execute at the server, so the focus at the client might be changed when the event listener for onBlur got executed.
onPageSize ActionData: PageSizeData
Notifies the paging size has been changed when the autopaging (iTree.withAutopaging(boolean)) is enabled and a user changed the size of the content.

Support Molds

Name Snapshot
"default"
"paging"

Support Application Library Properties

  • To turn on the auto-sort facility to sort the model for this component, you have to specify withAutosort(Autosort) to ITree.Autosort.ENABLE or ITree.Autosort.IGNORE_CHANGE.

    Or configure it from zk.xml by setting library properties. For example, 

      <library-property/>
     <name>org.zkoss.zul.tree.autoSort</name/>
     <value>true</value/>
 </library-property/>

  • To set to prefer to deselect all other items and select the item being clicked when isCheckmark() is enabled, you have to specify withCheckmarkDeselectOther(boolean) to true.

    Or configure it from zk.xml by setting library properties. For example, 

      <library-property/>
     <name>org.zkoss.zul.tree.checkmarkDeselectOthers</name/>
     <value>true</value/>
 </library-property/>

  • To set whether to disable select functionality when highlighting text content with mouse dragging or not, you have to specify withSelectOnHighlightDisabled(boolean) to true.

    Or configure it from zk.xml by setting library properties. For example, 

      <library-property/>
     <name>org.zkoss.zul.tree.selectOnHighlight.disabled</name/>
     <value>true</value/>
 </library-property/>

  • To set whether to disable the selection will be toggled when the user right clicks item, only if isCheckmark() is enabled. You have to specify withRightSelect(boolean) to false.

    Or configure it from zk.xml by setting library properties. For example, 

      <library-property/>
     <name>org.zkoss.zul.tree.rightSelect</name/>
     <value>false</value/>
 </library-property/>

  • To set the millisecond of scrolling throttling in Tree render on-demand (ROD), you have to specify withThrottleMillis(int) (ZK EE only).

    Or configure it from zk.xml by setting library properties. For example, 

      <library-property/>
     <name>org.zkoss.zul.tree.throttleMillis</name/>
     <value>300</value/>
 </library-property/>
Note: with zk.xml setting, it will affect to all tree components.

Example

2-Column Tree

 @RichletMapping("")
 public IComponent index() {
     return IWindow.ofTitle("tree demo").withBorder("normal").withWidth("500px")
         .withChildren(
         ITree.ofId("tree").withRows(5).withTreecols(
             ITreecols.of(
                 ITreecol.of("Name"),
                 ITreecol.of("Description")
             )).withTreechildren(ITreechildren.of(
                 ITreeitem.ofTreecells(
                     ITreecell.of("Item 1"),
                     ITreecell.of("Item 1 description")
                 ),
                 ITreeitem.ofTreecells(
                     ITreecell.of("Item 2"),
                     ITreecell.of("Item 2 description"))
                         .withTreechildren(
                             ITreechildren.of(
                             ITreeitem.of("Item 2.1"),
                             ITreeitem.ofTreecells(
                                 ITreecell.of("Item 2.2"),
                                 ITreecell.of("Item 2.2 is something who cares")),
                     ITreeitem.of("Item 3")))))
                 .withTreefoot(
                     ITreefoot.of(
                         ITreefooter.of("Count"),
                         ITreefooter.of("Summary")
                     )
                 )
             );
 }

Default Selection

 @RichletMapping("/defaultSelection")
 public IComponent defaultSelection() {
     return ITree.of(
             ITreeitem.of("David"),
             ITreeitem.of("Thomas"),
             ITreeitem.of("Steven").withSelected(true)
     ).withWidth("300px");
 }

Frozen Component

 @RichletMapping("/frozen")
 public IComponent frozen() {
     return ITree.ofId("tree").withRows(5).withWidth("600px").withFrozen(
         IFrozen.ofColumns(2).withStart(1)
     ).withTreecols(
         ITreecols.of(
             ITreecol.of("ID").withHflex("min"),
             ITreecol.of("Priority").withHflex("min"),
             ITreecol.of("Status").withHflex("min"),
             ITreecol.of("Summary").withHflex("min"),
             ITreecol.of("Detail").withHflex("min")
         ).withSizable(true)
    ).withTreechildren(
         ITreechildren.of(
             ITreeitem.ofTreecells(
                 ITreecell.of("0001"),
                 ITreecell.of("1"),
                 ITreecell.of("closed"),
                 ITreecell.of("Fix login issue"),
                 ITreecell.of("Login does not work at all")
             ),
             ITreeitem.ofTreecells(
                 ITreecell.of("0002"),
                 ITreecell.of("3"),
                 ITreecell.of("open"),
                 ITreecell.of("Button style broken"),
                 ITreecell.of("Check main.css")
                 ).withTreechildren(
                     ITreechildren.of(
                         ITreeitem.ofTreecells(
                         ITreecell.of("00021"),
                         ITreecell.of("1"),
                         ITreecell.of("closed"),
                         ITreecell.of("Fix logout issue"),
                         ITreecell.of("Logout does not work at all")
                     )
                 )
             ),
             ITreeitem.ofTreecells(
                 ITreecell.of("0003"),
                 ITreecell.of("2"),
                 ITreecell.of("open"),
                 ITreecell.of("Client search result"),
                 ITreecell.of("Search service returns incomplete result")
             )
         )
     );
 }

Scrollable Tree

A tree will be scrollable if you specify the rows attribute or the height attribute and there is not enough space to display all the tree items.

 @RichletMapping("/scrollable")
 public IComponent scrollable() {
     return ITree.DEFAULT.withRows(4).withTreecols(
         ITreecols.of(
             ITreecol.of("Name"),
             ITreecol.of("Description")
         )
     ).withTreechildren(
         ITreechildren.of(
             ITreeitem.ofTreecells(
                 ITreecell.of("Item 1"),
                 ITreecell.of("Item 1 description")
             ),
             ITreeitem.ofTreecells(
                 ITreecell.of("Item 2"),
                 ITreecell.of("Item 2 description")
             ).withTreechildren(
                 ITreechildren.of(
                     ITreeitem.of("Item 2.1",
                     ITreeitem.of("Item 2.1.1"),
                     ITreeitem.of("Item 2.1.2")
                 ),
                 ITreeitem.ofTreecells(
                     ITreecell.of("Item 2.2"),
                     ITreecell.of("Item 2.2 is something who cares")
                 )
             )
         ),
         ITreeitem.of("Item 3")
        )
     );
 }

Create-on-Open for Tree Controls

As illustrated below, you could listen to the onOpen event, and then load the children of a tree item. You can do the same thing using group boxes.

 @RichletMapping("/createOnOpen")
 public IComponent createOnOpen() {
     return ITree.DEFAULT.withWidth("400px")
         .withTreecols(
             ITreecols.of(
                 ITreecol.of("Subject"),
                 ITreecol.of("From")
         )
     ).withTreechildren(
         ITreechildren.of(
             ITreeitem.ofTreecells(
                 ITreecell.of("Intel Snares XML"),
                 ITreecell.of("David Needle")
             ).withTreechildren(
                 ITreechildren.DEFAULT
             ).withOpen(false).withAction(this::doCreateOnOpen)
         )
     );
 }

 @Action(type = Events.ON_OPEN)
 public void doCreateOnOpen(Self self, @ActionVariable(targetId = ActionTarget.SELF, field = "empty") boolean isEmpty) {
     if (isEmpty) {
         UiAgent.getCurrent()
             .replaceChildren(self.findChild(ITreechildren.class),
                 ITreeitem.of("New added"));
     }
 }

As you can see above, the field "empty" of the ActionVariable is used to detect whether the treeitem has an empty children, which receives the returned result from ITreeitem.isEmpty() at client widget.

Mouse-less Entry Tree

  • Press UP and DOWN to move the selection up and down by one tree item.
  • Press PgUp and PgDn to move the selection up and down by one page.
  • Press HOME to move the selection to the first item, and END to the last item.
  • Press RIGHT to open a tree item, and LEFT to close a tree item.
  • Press Ctrl+UP and Ctrl+DOWN to move the focus up and down by one tree item without changing the selection.
  • Press SPACE to select the item in focus
Author:
jumperchen
See Also:
  • Tree

  • Field Details

    • DEFAULT

      static final ITree DEFAULT
      Constant for default attributes of this immutable component.

    • PAGING

      static final ITree PAGING
      Constant for "paging" mold attributes of this immutable component.

  • Method Details

    • getWidgetClass

      default String getWidgetClass()
      Returns the client widget class.

      Default: "zul.sel.Tree"

      Specified by:
      getWidgetClass in interface IComponent<ITree>

    • getTreecols

      @Nullable ITreecols getTreecols()
      Returns the ITreecols component, if any.

      Default: null

    • withTreecols

      ITree withTreecols(@Nullable ITreecols treecols)
      Returns a copy of this immutable component with the specified treecols.

      Sets the ITreecols component as the set of columns of the tree

      Parameters:
      treecols - The ITreecols component to contain all tree columns

      Default: null.

      Returns:
      A modified copy of the this object

    • getTreefoot

      @Nullable ITreefoot getTreefoot()
      Returns the ITreefoot component, if any.

      Default: null

    • withTreefoot

      ITree withTreefoot(@Nullable ITreefoot treefoot)
      Returns a copy of this immutable component with the specified treefoot.

      Sets the ITreefoot component as the set of footers of the tree

      Parameters:
      treefoot - The ITreefoot component to contain all tree footers

      Default: null.

      Returns:
      A modified copy of the this object

    • getItems

      @Lazy default Collection<ITreeitem> getItems()
      Returns a readonly list of all descending ITreeitem (children's children and so on).

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

    • withAllComponents

      default ITree withAllComponents(Iterable<? extends IMeshComposite> elements)
      Description copied from interface: IComposite
      Copy the current immutable object with elements that replace the content of children. A shallow reference equality check is used to prevent copying of the same value by returning this.
      Specified by:
      withAllComponents in interface IComposite<ITree,IMeshComposite>
      Parameters:
      elements - An iterable of children elements to set
      Returns:
      A modified copy of this object

    • getAuxhead

      default List<IAuxhead> getAuxhead()
      Returns the IAuxhead component, if any.

      Default: null

    • withAuxhead

      ITree withAuxhead(Iterable<? extends IAuxhead> auxhead)
      Returns a copy of this immutable component with the specified auxhead.

      Sets the IAuxhead component as the set of auxiliary headers of the tree

      Parameters:
      auxhead - The IAuxhead component to contain all auxiliary headers of the tree

      Default: null.

      Returns:
      A modified copy of the this object

    • withAuxhead

      default ITree withAuxhead(IAuxhead... auxhead)
      Returns a copy of this immutable component with the specified auxhead.

      Sets the IAuxhead component as the set of auxiliary headers of the tree

      Parameters:
      auxhead - The IAuxhead component to contain all auxiliary headers of the tree

      Default: null.

      Returns:
      A modified copy of the this object

    • getTreechildren

      @Nullable ITreechildren getTreechildren()
      Returns the root ITreechildren, which contains all tree items in a hierarchical set of rows of components.

      Default: null

    • withTreechildren

      ITree withTreechildren(@Nullable ITreechildren treechildren)
      Returns a copy of this immutable component with the specified treechildren.

      Sets the ITreechildren component that the tree owns

      Parameters:
      treechildren - The ITreechildren component to contain all tree items in a hierarchical set of rows of components.

      Default: null.

      Returns:
      A modified copy of the this object

    • getFrozen

      @Nullable IFrozen getFrozen()
      Returns a IFrozen component to enable a frozen column or row facility.

      Default: null

    • withFrozen

      ITree withFrozen(@Nullable IFrozen frozen)
      Returns a copy of this immutable component with the specified frozen.

      Sets the IFrozen component that the tree owns to enable a frozen column or row facility.

      Parameters:
      frozen - The IFrozen component

      Default: null.

      Returns:
      A modified copy of the this object

    • getRows

      default int getRows()
      Returns the number of the rows to display at screen. Zero means no limitation.

      Default: 0

    • withRows

      ITree withRows(int rows)
      Returns a copy of this immutable component with the specified rows.

      Sets the number of the rows of the tree to display at a screen, which means the height of the tree is based on the calculation of the number of the rows by multiplying with each row height.

      Note: Not allowed to set rows and height/vflex at the same time.

      Parameters:
      rows - The number of rows to display.

      Default: 0. (Meaning no limitation)

      Returns:
      A modified copy of the this object

    • getAutosort

      @Nullable default String getAutosort()
      Returns whether to sort all items when model or sort direction be changed.

      Default: false, if the "org.zkoss.zul.tree.autoSort" library property is not set in zk.xml.

      Note: it's meaningless if TreeModel is not set.

    • withAutosort

      ITree withAutosort(@Nullable String autosort)
      Returns a copy of this immutable component with the specified autosort.

      Sets to enable the auto-sort facility to sort the model for this component. Meaningless if TreeModel is not set.

      Parameters:
      autosort - The allowed values are null, "false", "true", and "ignore.change".

      Default: null.

      Returns:
      A modified copy of the this object

    • withAutosort

      default ITree withAutosort(@Nullable ITree.Autosort autosort)
      Returns a copy of this immutable component with the specified autosort.

      Sets to enable the auto-sort facility to sort the model for this component. Meaningless if TreeModel is not set.

      Parameters:
      autosort - The ITree.Autosort attribute.
      Returns:
      A modified copy of the this object
      See Also:

    • isMultiple

      default boolean isMultiple()
      Returns whether multiple selections are allowed.

      Default: false.

    • withMultiple

      ITree withMultiple(boolean multiple)
      Returns a copy of this immutable component with the specified 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)).

      Parameters:
      multiple - True to allow multiple selections.

      Default: false.

      Returns:
      A modified copy of the this object

    • isCheckmark

      default boolean isCheckmark()
      Returns whether the check mark shall be displayed in front of each item.

      Default: false.

    • withCheckmark

      ITree withCheckmark(boolean checkmark)
      Returns a copy of this immutable component with the specified 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.

      Parameters:
      checkmark - True to enable the check mark in front of each item.

      Default: false.

      Returns:
      A modified copy of the this object

    • getNonselectableTags

      @Nullable String getNonselectableTags()
      Returns 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 HTML elements). If you want to select no matter which tag is clicked, please specify an empty string. Specify null to use the default and "" to indicate none.

    • withNonselectableTags

      ITree withNonselectableTags(@Nullable String nonselectableTags)
      Returns a copy of this immutable component with the specified name.

      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 HTML elements). If you want to select no matter which tag is clicked, please specify an empty string.

      Parameters:
      nonselectableTags - 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.
      Returns:
      A modified copy of the this object

    • isCheckmarkDeselectOther

      default boolean isCheckmarkDeselectOther()
      Returns whether to toggle the selection if clicking on a tree item with a checkmark. Meaningless if isCheckmark() is false

      Default: false, if the "org.zkoss.zul.tree.checkmarkDeselectOthers" library property is not set in zk.xml.

    • withCheckmarkDeselectOther

      ITree withCheckmarkDeselectOther(boolean checkmarkDeselectOther)
      Returns a copy of this immutable component with the specified checkmarkDeselectOther.

      Sets true to prefer to deselect all other items and select the item being clicked. If isCheckmark() is enabled.

      Default: false (not to deselect other items).

      Parameters:
      checkmarkDeselectOther - True to deselect other items and select the item being clicked.

      Default: false

      Returns:
      A modified copy of the this object

    • isSelectOnHighlightDisabled

      default boolean isSelectOnHighlightDisabled()
      Returns whether to disable select functionality when highlighting text content with mouse dragging or not.

      Default: false, if the "org.zkoss.zul.tree.selectOnHighlight.disabled" library property is not set in zk.xml.

    • withSelectOnHighlightDisabled

      ITree withSelectOnHighlightDisabled(boolean selectOnHighlightDisabled)
      Returns a copy of this immutable component with the specified selectOnHighlightDisabled.

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

      Parameters:
      selectOnHighlightDisabled - True to disable select functionality when highlighting text content with mouse dragging or not.

      Default: false

      Returns:
      A modified copy of the this object

    • isRightSelect

      default boolean isRightSelect()
      Returns whether to toggle a list item selection on right click, only if isCheckmark() is enabled.

      Default: true, if the "org.zkoss.zul.tree.rightSelect" library property is not set in zk.xml.

    • withRightSelect

      ITree withRightSelect(boolean rightSelect)
      Returns a copy of this immutable component with the specified rightSelect.

      Sets whether to enable the selection will be toggled when the user right clicks item, only if isCheckmark() is enabled.

      Parameters:
      rightSelect - False not to select/deselect item on right click

      Default: true

      Returns:
      A modified copy of the this object

    • getThrottleMillis

      default int getThrottleMillis()
      Returns the millisecond of scrolling throttling in Tree render on-demand (ROD).

      Default: Tree.DEFAULT_THROTTLE_MILLIS, if the ""org.zkoss.zul.tree.throttleMillis" property is not set in zk.xml when run with ZK EE.

    • withThrottleMillis

      ITree withThrottleMillis(int throttleMillis)
      Returns a copy of this immutable component with the specified throttleMillis.

      Sets the millisecond of scrolling throttling in Tree render on-demand (ROD).

      Parameters:
      throttleMillis - The millisecond of scrolling throttling

      Default: Tree.DEFAULT_THROTTLE_MILLIS

      Returns:
      A modified copy of the this object

    • of

      static ITree of(Iterable<? extends ITreeitem> children)
      Returns the instance with the given tree items which belong to root level.
      Parameters:
      children - The tree items of the root level.

    • of

      static ITree of(ITreeitem... children)
      Returns the instance with the given tree items which belong to root level.
      Parameters:
      children - The tree items of the root level.

    • ofTreecols

      static ITree ofTreecols(ITreecols treecols)
      Returns the instance with the given tree columns.
      Parameters:
      treecols - The ITreecols component to contain all tree columns.

    • ofTreecols

      static ITree ofTreecols(Iterable<? extends ITreecol<IAnyGroup>> children)
      Returns the instance with the given tree columns.
      Parameters:
      children - The children of ITreecols component.

    • ofTreecols

      static ITree ofTreecols(ITreecol<IAnyGroup>... children)
      Returns the instance with the given tree columns.
      Parameters:
      children - The children of ITreecols component.

    • ofTreefoot

      static ITree ofTreefoot(ITreefoot treefoot)
      Returns the instance with the given tree foot.
      Parameters:
      treefoot - The ITreefoot component to contain all tree footers.

    • ofTreefooters

      static ITree ofTreefooters(Iterable<? extends ITreefooter<IAnyGroup>> children)
      Returns the instance with the given tree footers.
      Parameters:
      children - The tree footers of the tree foot.

    • ofTreefooters

      static ITree ofTreefooters(ITreefooter<IAnyGroup>... children)
      Returns the instance with the given tree footers.
      Parameters:
      children - The tree footers of the tree foot.

    • ofId

      static ITree ofId(String id)
      Returns the instance with the given id.
      Parameters:
      id - The id to identify this component.