Package org.zkoss.zkmax.zul

## Class Chosenbox

- java.lang.Object
- - org.zkoss.zk.ui.AbstractComponent
  - - org.zkoss.zk.ui.HtmlBasedComponent
    - - org.zkoss.zkmax.zul.Chosenbox

- All Implemented Interfaces:
    `java.io.Serializable`, `java.lang.Cloneable`, `Component`, `Scope`, `ComponentCtrl`

      public class Chosenbox
      extends HtmlBasedComponent

  A component that similar to Combobox but handle the multi-selection and the select order.

  Default `getZclass()`: z-chosenbox. It does not create child widgets for each data, so the memory usage is much lower at the server.

  Since:
    6.0.1
  Author:
    benbai
  See Also:
    Serialized Form

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `protected class` | `Chosenbox.ExtraCtrl` | A utility class to implement `HtmlBasedComponent.getExtraCtrl()`.

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

      `AbstractComponent.Children, AbstractComponent.ForwardInfo, AbstractComponent.TargetInfo`

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static java.lang.String` | `ATTR_FILTER_LOGIC` |
    `static java.lang.String` | `ATTR_FILTER_LOGIC_CONTAINS` |
    `static java.lang.String` | `ATTR_FILTER_LOGIC_STARTS_WITH` |

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

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addItemToSelection​(java.lang.Object o)` | Add an item into selection.
    `void` | `clearSelection()` | Clear all selected objects.
    `java.lang.Object` | `clone()` | Clones the component.
    `java.lang.String` | `getCreateMessage()` | Returns the create message of this component.
    `java.lang.String` | `getEmptyMessage()` | Returns the emptyMessage of the input of this component.
    `java.lang.Object` | `getExtraCtrl()` | Returns the client control for this component.
    `<T> ItemRenderer<T>` | `getItemRenderer()` | Returns the renderer to render each item, or null if the default renderer is used.
    `<T> ListModel<T>` | `getModel()` | Returns the model associated with this chosenbox, or null if this chosenbox is not associated with any list data model.
    `java.lang.String` | `getName()` | Returns the name of this component.
    `java.lang.String` | `getNoResultsText()` | Returns the no-result text of this component.
    `<T> ItemRenderer<T>` | `getRealRenderer()` |
    `int` | `getSelectedIndex()` | Returns the index of the selected item (-1 if no one is selected).
    `<T> java.util.Set<T>` | `getSelectedObjects()` | Returns the selected objects.
    `java.lang.String` | `getSeparator()` | Returns the separate chars of this component.
    `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.
    `protected boolean` | `isChildable()` | Returns whether this component can have a child.
    `boolean` | `isCreatable()` | Returns whether creates new item.
    `boolean` | `isDisabled()` | Returns whether it is disabled.
    `boolean` | `isInplace()` | Return whether to display Chosenbox's selection as a comma separate label, under inplace="true", when user clicks the label, it turns into a chosenbox.
    `boolean` | `isOpen()` |
    `void` | `onInitRender()` |
    `void` | `onInitSelection()` |
    `void` | `onPageAttached​(Page newpage, Page oldpage)` | Default: handles special event listeners.
    `void` | `onPageDetached​(Page page)` | Default: handles special event listeners.
    `void` | `removeItemFromSelection​(java.lang.Object o)` | Remove an item from selection.
    `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` | `setCreatable​(boolean creatable)` | Sets whether can create new item.
    `void` | `setCreateMessage​(java.lang.String createMessage)` | Sets the create message of this component.
    `void` | `setDisabled​(boolean disabled)` | Sets whether it is disabled.
    `void` | `setEmptyMessage​(java.lang.String emptyMessage)` | Sets the emptyMessage of the input of this component.
    `void` | `setInplace​(boolean inplace)` | Set whether to display Chosenbox's selection as a comma separate label, under inplace="true", when user clicks the label, it turns into a chosenbox.
    `void` | `setItemRenderer​(java.lang.String clsnm)` | Sets the renderer by use of a class name.
    `void` | `setItemRenderer​(ItemRenderer<?> renderer)` | Sets the renderer which is used to render each item if `getModel()` is not null.
    `void` | `setModel​(ListModel<?> model)` | Sets the list model associated with this chosenbox.
    `void` | `setName​(java.lang.String name)` | Sets the name of the input element of this component.
    `void` | `setNoResultsText​(java.lang.String noResultsText)` | Sets the no-result text of this component.
    `void` | `setOpen​(boolean open)` |
    `void` | `setSelectedIndex​(int jsel)` | Sets the index of the selected item (-1 if no one is selected).
    `void` | `setSelectedObjects​(java.util.Collection<?> objects)` | Sets the selected objects.
    `void` | `setSeparator​(java.lang.String separator)` | Sets the separate chars of this component.

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

      `addSclass, evalCSSFlex, focus, getAction, getClientAction, getDraggable, getDroppable, 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, 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`

- - ### Field Detail

    - #### ATTR_FILTER_LOGIC

          public static final java.lang.String ATTR_FILTER_LOGIC

      See Also:
        Constant Field Values

    - #### ATTR_FILTER_LOGIC_CONTAINS

          public static final java.lang.String ATTR_FILTER_LOGIC_CONTAINS

      See Also:
        Constant Field Values

    - #### ATTR_FILTER_LOGIC_STARTS_WITH

          public static final java.lang.String ATTR_FILTER_LOGIC_STARTS_WITH

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Chosenbox

          public Chosenbox()

  - ### Method Detail

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

    - #### setOpen

          public void setOpen​(boolean open)

    - #### isOpen

          public boolean isOpen()

    - #### isDisabled

          public boolean isDisabled()

      Returns whether it is disabled.

      Default: false.

    - #### setDisabled

          public void setDisabled​(boolean disabled)

      Sets whether it is disabled.

    - #### 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 the input element 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.

    - #### getEmptyMessage

          public java.lang.String getEmptyMessage()

      Returns the emptyMessage of the input of this component.

      Default: null.

      The emptyMessage will be displayed in input if nothing selected and not focused.

    - #### setEmptyMessage

          public void setEmptyMessage​(java.lang.String emptyMessage)

      Sets the emptyMessage of the input of this component.

      The emptyMessage will be displayed in input if nothing selected and not focused.

      Parameters:
        `emptyMessage` - the emptyMessage of the input of this component.

    - #### getNoResultsText

          public java.lang.String getNoResultsText()

      Returns the no-result text of this component.

      Default: null.

      The no-result text will be displayed in popup if nothing match to the input value and can not create either, the syntax "{0}" will be replaced with the input value at client side.

    - #### setNoResultsText

          public void setNoResultsText​(java.lang.String noResultsText)

      Sets the no-result text of this component.

      The no-result text will be displayed in popup if nothing match to the input value and can not create either, the syntax "{0}" will be replaced with the input value at client side.

      Parameters:
        `noResultsText` - the no-result text of this component.

    - #### getCreateMessage

          public java.lang.String getCreateMessage()

      Returns the create message of this component.

      Default: null.

      The create message will be displayed in popup if nothing match to the input value but can create as new label, the syntax "{0}" will be replaced with the input value at client side.

    - #### setCreateMessage

          public void setCreateMessage​(java.lang.String createMessage)

      Sets the create message of this component.

      The create message will be displayed in popup if nothing match to the input value but can create as new label, the syntax "{0}" will be replaced with the input value at client side.

      Parameters:
        `createMessage` - the create message of this component.

    - #### getSeparator

          public java.lang.String getSeparator()

      Returns the separate chars of this component.

      Support: 0-9, A-Z (case-insensitive), and ,.;'[]/\-=

      Default: null.

      The separate chars will work as 'Enter' key, it will be not considered as input value but send onSerch or onSearching while key up.

    - #### setSeparator

          public void setSeparator​(java.lang.String separator)

      Sets the separate chars of this component.

      Support: 0-9, A-Z (case insensitive), and ,.;'[]/\-=

      The separate chars will work as 'Enter' key, it will not considered as input value but send onSerch or onSelect while key up.

    - #### getSelectedObjects

          public <T> java.util.Set<T> getSelectedObjects()

      Returns the selected objects.

    - #### setSelectedObjects

          public void setSelectedObjects​(java.util.Collection<?> objects)

      Sets the selected objects.
      Parameters:
        `objects` - the objects to select.

    - #### getSelectedIndex

          public int getSelectedIndex()

      Returns the index of the selected item (-1 if no one is selected).

    - #### setSelectedIndex

          public void setSelectedIndex​(int jsel)

      Sets the index of the selected item (-1 if no one is selected). If model already exists, it will update the selection of model.
      Parameters:
        `jsel` - the index to select.

    - #### isCreatable

          public boolean isCreatable()

      Returns whether creates new item.

      Default: false.

      true: will show create message while value of input not exists.

      false: will show no result message while value of input not exists.

    - #### setCreatable

          public void setCreatable​(boolean creatable)

      Sets whether can create new item.

      Default: false.

      true: will show create message while value of input not exists.

      false: will show no-result text while value of input not exists.

      Parameters:
        `creatable` - the boolean value.

    - #### isInplace

          public boolean isInplace()

      Return whether to display Chosenbox's selection as a comma separate label, under inplace="true", when user clicks the label, it turns into a chosenbox.
      Returns:
        whether to display Chosenbox's selection as a comma separate label
      Since:
        8.5.2

    - #### setInplace

          public void setInplace​(boolean inplace)

      Set whether to display Chosenbox's selection as a comma separate label, under inplace="true", when user clicks the label, it turns into a chosenbox.
      Parameters:
        `inplace` - to display Chosenbox's selection as a comma separate label
      Since:
        8.5.2

    - #### getRealRenderer

          public <T> ItemRenderer<T> getRealRenderer()

    - #### getItemRenderer

          public <T> ItemRenderer<T> getItemRenderer()

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

    - #### getModel

          public <T> ListModel<T> getModel()

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

    - #### setModel

          public void setModel​(ListModel<?> model)

      Sets the list model associated with this chosenbox. If a non-null model is assigned, no matter whether it is the same as the previous, it will always cause re-render.
      Parameters:
        `model` - the list model to associate, or null to dis-associate any previous model.
      Throws:
        `UiException` - if failed to initialize with the model

    - #### clearSelection

          public void clearSelection()

      Clear all selected objects.

    - #### addItemToSelection

          public void addItemToSelection​(java.lang.Object o)

      Add an item into selection.
      Parameters:
        `o` - the object to add.

    - #### removeItemFromSelection

          public void removeItemFromSelection​(java.lang.Object o)

      Remove an item from selection.
      Parameters:
        `o` - the object to remove.

    - #### isChildable

          protected boolean isChildable()

      Description copied from class: `AbstractComponent`
      Returns whether this component can have a child.

      Default: return true (means it can have children).

      Overrides:
        `isChildable` in class `AbstractComponent`

    - #### setItemRenderer

          public void setItemRenderer​(ItemRenderer<?> renderer)

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

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

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

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

    - #### onInitRender

          public void onInitRender()

    - #### onInitSelection

          public void onInitSelection()

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

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

    - #### getExtraCtrl

          public java.lang.Object getExtraCtrl()

      Description copied from class: `HtmlBasedComponent`
      Returns the client control for this component. It is used only by component developers.

      Default: creates an instance of `HtmlBasedComponent.ExtraCtrl`.

      Specified by:
        `getExtraCtrl` in interface `ComponentCtrl`
      Overrides:
        `getExtraCtrl` in class `HtmlBasedComponent`
      Returns:
        null if no special handling required. If the component requires some special controls, it could return an object that implements one or several interfaces in the org.zkoss.zk.ui.ext.render package. For example, `Cropper`.
      See Also:
        `ComponentCtrl.getExtraCtrl()`

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