Package org.zkoss.zkmax.zul

## Class Cascader<E>

- java.lang.Object
- - org.zkoss.zk.ui.AbstractComponent
  - - org.zkoss.zk.ui.HtmlBasedComponent
    - - org.zkoss.zkmax.zul.Cascader<E>

- Type Parameters:
    `E` - Element type in model
  All Implemented Interfaces:
    `java.io.Serializable`, `java.lang.Cloneable`, `Component`, `Disable`, `Scope`, `ComponentCtrl`

      public class Cascader<E>
      extends HtmlBasedComponent
      implements Disable

  A Cascader is a dropdown list in tree structure, and it supports TreeModel. It does not create child widgets for each data, so the memory usage is much lower at the server.

  Available in ZK EE.

  Default `getZclass()`: z-cascader.

  Since:
    9.0.0
  Author:
    jameschu
  See Also:
    Serialized Form

- - ### Nested Class Summary

    - ### 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, AbstractComponent.ForwardInfo, AbstractComponent.TargetInfo`

  - ### 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

      `AFTER_CHILD_ADDED, AFTER_CHILD_REMOVED, AFTER_CLONED, AFTER_PAGE_ATTACHED, AFTER_PAGE_DETACHED, AFTER_PARENT_CHANGED, CE_BUSY_IGNORE, CE_DUPLICATE_IGNORE, CE_IMPORTANT, CE_NON_DEFERRABLE, CE_REPEAT_IGNORE`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `Cascader()` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `java.lang.Object` | `clone()` | Clones the component.
    `Converter<java.util.Collection<E>,​java.lang.String>` | `getItemConverter()` | Returns the converter that generates the label text shown in the cascader from selected items, or null to use the default implementation.
    `ItemRenderer<E>` | `getItemRenderer()` | Returns the renderer to render each item, or null if the default renderer is used.
    `TreeModel<E>` | `getModel()` | Returns the model associated with this cascader, or null if this cascader is not associated with any tree data model.
    `java.lang.String` | `getPlaceholder()` | Returns the placeholder text.
    `E` | `getSelectedItem()` | Returns the selected item.
    `java.util.Set<E>` | `getSelectedItems()` | Returns all selected items.
    `java.lang.String` | `getZclass()` | Returns the ZK Cascading Style class for this component.
    `void` | `invalidate()` | Invalidates this component by setting the dirty flag such that it will be redraw the whole content of this component and its dependencies later.
    `boolean` | `isDisabled()` | Returns whether it is disabled.
    `boolean` | `isOpen()` | Returns whether this cascader is open.
    `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 void` | `renderProperties​(ContentRenderer renderer)` | Renders the content of this component, excluding the enclosing tags and children.
    `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` | `setDisabled​(boolean disabled)` | Sets whether it is disabled.
    `void` | `setItemConverter​(java.lang.String clsnm)` | Sets the converter by use of a class name.
    `void` | `setItemConverter​(Converter<java.util.Collection<E>,​java.lang.String> converter)` | Sets the converter that generates the label text shown in the cascader from selected items.
    `void` | `setItemRenderer​(java.lang.String clsnm)` | Sets the renderer by use of a class name.
    `void` | `setItemRenderer​(ItemRenderer<E> 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 cascader.
    `void` | `setOpen​(boolean open)` | Drops down or closes the list of items.
    `void` | `setPlaceholder​(java.lang.String placeholder)` | Sets the placeholder text that is displayed when the selected item is empty.
    `void` | `setSelectedItem​(E item)` | Deselects selected item and selects the given item.

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

      `addSclass, evalCSSFlex, focus, getAction, getClientAction, getDraggable, getDroppable, getExtraCtrl, getHeight, getHflex, getLeft, getPropertyAccess, getRenderdefer, getSclass, getStyle, getTabindex, getTabindexInteger, getTooltiptext, getTop, getVflex, getWidth, getZindex, getZIndex, removeSclass, removeSclass, setAction, setClass, setClientAction, setDraggable, setDroppable, setFocus, setHeight, setHeight0, setHeightDirectly, setHflex, setHflex0, setHflexDirectly, setLeft, setLeftDirectly, setRenderdefer, setSclass, setStyle, setTabindex, setTabindex, setTooltiptext, setTop, setTopDirectly, setVflex, setVflex0, setVflexDirectly, setWidth, setWidth0, setWidthDirectly, setZclass, setZindex, setZIndex, setZIndexDirectly`

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

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

    - ### Methods inherited from class java.lang.Object

      `equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### Cascader

          public Cascader()

  - ### Method Detail

    - #### getModel

          public TreeModel<E> getModel()

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

    - #### setModel

          public void setModel​(TreeModel model)

      Sets the tree model associated with this cascader.
      Parameters:
        `model` - the list model to associate, or null to dis-associate any previous model. If not null, it must implement `Selectable`.
      Throws:
        `UiException` - if failed to initialize with the model

    - #### onInitRender

          public void onInitRender()

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

    - #### getItemRenderer

          public ItemRenderer<E> getItemRenderer()

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

    - #### setItemRenderer

          public void setItemRenderer​(ItemRenderer<E> renderer)

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

      Note: changing a render will cause the cascader to re-render.

      Parameters:
        `renderer` - the renderer, or null to use the default.

    - #### setItemRenderer

          public void setItemRenderer​(java.lang.String clsnm)
                               throws java.lang.ReflectiveOperationException

      Sets the renderer by use of a class name. It creates an instance automatically.
      Parameters:
        `clsnm` - The class name
      Throws:
        `java.lang.ReflectiveOperationException` - if failed to initialize the renderer

    - #### getItemConverter

          public Converter<java.util.Collection<E>,​java.lang.String> getItemConverter()

      Returns the converter that generates the label text shown in the cascader from selected items, or null to use the default implementation. (joining by slashes, i.g. "A/B/C")

    - #### setItemConverter

          public void setItemConverter​(Converter<java.util.Collection<E>,​java.lang.String> converter)

      Sets the converter that generates the label text shown in the cascader from selected items.
      Parameters:
        `converter` - the converter, or null to use the default implementation.

    - #### setItemConverter

          public void setItemConverter​(java.lang.String clsnm)
                                throws java.lang.ReflectiveOperationException

      Sets the converter by use of a class name. It creates an instance automatically.
      Parameters:
        `clsnm` - The class name
      Throws:
        `java.lang.ReflectiveOperationException` - if failed to initialize the converter

    - #### getPlaceholder

          public java.lang.String getPlaceholder()

      Returns the placeholder text.

    - #### setPlaceholder

          public void setPlaceholder​(java.lang.String placeholder)

      Sets the placeholder text that is displayed when the selected item is empty.

    - #### isOpen

          public boolean isOpen()

      Returns whether this cascader is open.

      Default: false.

    - #### setOpen

          public void setOpen​(boolean open)

      Drops down or closes the list of items.

    - #### isDisabled

          public boolean isDisabled()

      Description copied from interface: `Disable`
      Returns whether it is disabled.

      Default: false.

      Specified by:
        `isDisabled` in interface `Disable`

    - #### setDisabled

          public void setDisabled​(boolean disabled)

      Description copied from interface: `Disable`
      Sets whether it is disabled.
      Specified by:
        `setDisabled` in interface `Disable`

    - #### getSelectedItems

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

      Returns all selected items.

    - #### getSelectedItem

          public E getSelectedItem()

      Returns the selected item.

    - #### setSelectedItem

          public void setSelectedItem​(E item)

      Deselects selected item and selects the given item.

    - #### 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 `HtmlBasedComponent`
      Throws:
        `java.io.IOException`

    - #### service

          public void service​(AuRequest request,
                              boolean everError)

      Description copied from class: `HtmlBasedComponent`
      Processes an AU request.

      Default: it handles onClick, onDoubleClick, onRightClick onMove, onSize, onZIndex.

      Specified by:
        `service` in interface `ComponentCtrl`
      Overrides:
        `service` in class `HtmlBasedComponent`
        `everError` - whether any error ever occurred before processing this request.
      See Also:
        `AbstractComponent.setAuService(org.zkoss.zk.au.AuService)`

    - #### 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)`

    - #### invalidate

          public void invalidate()

      Description copied from interface: `Component`
      Invalidates this component by setting the dirty flag such that it will be redraw the whole content of this component and its dependencies later. And, the widget associated with this component and all its descendant at the client will be deleted and recreated, too.

      If the application is totally controlled by the server side (i.e., you don't write client codes), you rarely need to access this method.

      It can be called only in the request-processing and event-processing phases. However, it is NOT allowed in the rendering phase.

      Specified by:
        `invalidate` in interface `Component`
      Overrides:
        `invalidate` in class `AbstractComponent`

    - #### 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 `HtmlBasedComponent`
      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`

    - #### getZclass

          public java.lang.String getZclass()

      Description copied from class: `HtmlBasedComponent`
      Returns the ZK Cascading Style class 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()`