Package org.zkoss.stateless.sul

## Interface IChosenbox

- All Superinterfaces:
    `IAnyGroup<IChosenbox>`, `IComponent<IChosenbox>`, `IHtmlBasedComponent<IChosenbox>`

      public interface IChosenbox
      extends IHtmlBasedComponent<IChosenbox>, IAnyGroup<IChosenbox>

  Immutable `Chosenbox` component

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

  It does not create child widgets for each data, so the memory usage is much lower at the server.

  ### Support @Action

  Name | Action Type
  --- | ---
  onSelect | ActionData: `SelectData` Represents an action caused by user's the selection changed at the client.
  onOpen | ActionData: `OpenData` Represents an action that indicates an open state that is changed at the client.
  onSearch | ActionData: `InputData` Represents an action that indicates users inputting an non-existing value by clicking `ENTER` or separator.
  onSearching | ActionData: `InputData` Represents an action sent back to the server caused by user's input text.
  onItemClick | Represents an action sent back to the server caused by clicking a selected tag.

  ## Mouseless Entry

  - Press `UP` and `DOWN` to move the focus up and down by one option
  - Press `LEFT` and `RIGHT` to move focus between selected item(s) and the input field.
  - Press `ESC` to clear input and close drop-down list.
  - Press `DELETE` to delete the focused item and move focus to next item if any or input field.
  - Press `BACKSPACE` to delete the focused item and move focus to previous item if any or input field.
  - Press `ENTER` or specified separator to select the focused option.
  Author:
    katherine
  See Also:
    `Chosenbox`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface | Description
    --- | --- | ---
    `static class` | `IChosenbox.Builder` | Builds instances of type `IChosenbox`.
    `static class` | `IChosenbox.Updater` | Builds an updater of type `IChosenbox` for `UiAgent.smartUpdate(Locator, SmartUpdater)`.

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static IChosenbox` | `DEFAULT` | Constant for default attributes of this immutable component.

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `java.lang.String` | `getCreateMessage()` | Returns the creating message of this component.
    `java.lang.String` | `getEmptyMessage()` | Returns the emptyMessage of the input of this component.
    `java.lang.String` | `getName()` | Returns the name of this component.
    `java.lang.String` | `getNoResultsText()` | Returns the no-result text of this component.
    `java.lang.String` | `getSeparator()` | Returns the separate chars of this component.
    `default java.lang.String` | `getWidgetClass()` | Returns the client widget class.
    `default boolean` | `isCreatable()` | Returns whether creates new item by default.
    `default boolean` | `isDisabled()` | Returns whether it is disabled.
    `default boolean` | `isInplace()` | Return whether to display Chosenbox's selection as a comma separate label, under `withIinplace(true)`, when user clicks the label, it turns into a chosenbox.
    `default boolean` | `isOpen()` | Returns whether to open or not.
    `static IChosenbox` | `ofId​(java.lang.String id)` | Returns the instance with the given id.
    `IChosenbox` | `withCreatable​(boolean creatable)` | Returns a copy of `this` immutable component with the specified `creatable`.
    `IChosenbox` | `withCreateMessage​(java.lang.String createMessage)` | Returns a copy of `this` immutable component with the specified `createMessage`.
    `IChosenbox` | `withDisabled​(boolean disabled)` | Returns a copy of `this` immutable component with the specified `disabled`.
    `IChosenbox` | `withEmptyMessage​(java.lang.String emptyMessage)` | Returns a copy of `this` immutable component with the specified `emptyMessage`.
    `IChosenbox` | `withInplace​(boolean inplace)` | Returns a copy of `this` immutable component with the specified `inplace`.
    `IChosenbox` | `withName​(java.lang.String name)` | Returns a copy of `this` immutable component with the specified `name`.
    `IChosenbox` | `withNoResultsText​(java.lang.String noResultsText)` | Returns a copy of `this` immutable component with the specified `noResultsText`.
    `IChosenbox` | `withOpen​(boolean open)` | Returns a copy of `this` immutable component with the specified `open`.
    `IChosenbox` | `withSeparator​(java.lang.String separator)` | Returns a copy of `this` immutable component with the specified `separator`.

    - ### Methods inherited from interface org.zkoss.stateless.sul.IComponent

      `getAction, getActions, getClientAttributes, getId, getMold, getWidgetListeners, getWidgetOverrides, isVisible, withAction, withAction, withAction, withAction, withAction, withAction, withAction, withAction, withAction, withAction, withAction, withActions, withActions, withClientAttribute, withClientAttributes, withId, withMold, withVisible, withWidgetClass, withWidgetListener, withWidgetListeners, withWidgetOverride, withWidgetOverrides`

    - ### Methods inherited from interface org.zkoss.stateless.sul.IHtmlBasedComponent

      `getClientAction, getDraggable, getDroppable, getHeight, getHflex, getLeft, getRenderdefer, getSclass, getStyle, getTabindex, getTooltiptext, getTop, getVflex, getWidth, getZclass, getZIndex, isFocus, withClientAction, withDraggable, withDroppable, withFocus, withHeight, withHflex, withLeft, withRenderdefer, withSclass, withStyle, withTabindex, withTabindex, withTooltiptext, withTop, withVflex, withWidth, withZclass, withZIndex`

- - ### Field Detail

    - #### DEFAULT

          static final IChosenbox DEFAULT

      Constant for default attributes of this immutable component.

  - ### Method Detail

    - #### getWidgetClass

          default java.lang.String getWidgetClass()

      Returns the client widget class.

      Default: `"zkmax.inp.Chosenbox"`

      Specified by:
        `getWidgetClass` in interface `IComponent<IChosenbox>`

    - #### getName

          @Nullable
          java.lang.String getName()

      Returns the name of this component.

      Default: `null`.

      Don't use this method if your application is purely based on ZK's event-driven model.

      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.

    - #### withName

          IChosenbox withName​(@Nullable
                              java.lang.String name)

      Returns a copy of `this` immutable component with the specified `name`.

      Sets the name of this component.

      Don't use this method if your application is purely based on ZK's event-driven model.

      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.

      Parameters:
        `name` - The value of the component.

        Default: `null`.

      Returns:
        A modified copy of the `this` object

    - #### getEmptyMessage

          @Nullable
          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.

    - #### withEmptyMessage

          IChosenbox withEmptyMessage​(@Nullable
                                      java.lang.String emptyMessage)

      Returns a copy of `this` immutable component with the specified `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 empty message of the input of this component.

        Default: `null`.

      Returns:
        A modified copy of the `this` object

    - #### getNoResultsText

          @Nullable
          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.

    - #### withNoResultsText

          IChosenbox withNoResultsText​(@Nullable
                                       java.lang.String noResultsText)

      Returns a copy of `this` immutable component with the specified `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.

        Default: `null`.

      Returns:
        A modified copy of the `this` object

    - #### getSeparator

          @Nullable
          java.lang.String getSeparator()

      Returns the separate chars of this component.

      Default: `null`.

    - #### withSeparator

          IChosenbox withSeparator​(@Nullable
                                   java.lang.String separator)

      Returns a copy of `this` immutable component with the specified `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 be not considered as input value but send `onSearch` or `onSearching` while key up.

      Parameters:
        `separator` - The separate chars of this component.

        Default: `null`.

      Returns:
        A modified copy of the `this` object

    - #### getCreateMessage

          @Nullable
          java.lang.String getCreateMessage()

      Returns the creating message of this component.

      Default: `null`.

    - #### withCreateMessage

          IChosenbox withCreateMessage​(@Nullable
                                       java.lang.String createMessage)

      Returns a copy of `this` immutable component with the specified `createMessage`.

      Sets the creating message of this component.

      The creating 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 creating message of this component

        Default: `null`.

      Returns:
        A modified copy of the `this` object

    - #### isOpen

          default boolean isOpen()

      Returns whether to open or not.

      Default: `folse`

    - #### withOpen

          IChosenbox withOpen​(boolean open)

      Returns a copy of `this` immutable component with the specified `open`.

      Sets whether to open or not.

      Parameters:
        `open` - `ture` to open the dropdown of this component.

        Default: `false`.

      Returns:
        A modified copy of the `this` object

    - #### isDisabled

          default boolean isDisabled()

      Returns whether it is disabled.

      Default: `false`.

    - #### withDisabled

          IChosenbox withDisabled​(boolean disabled)

      Returns a copy of `this` immutable component with the specified `disabled`.

      Sets whether it is disabled.

      Parameters:
        `disabled` - `ture` to disable this component.

        Default: `false`.

      Returns:
        A modified copy of the `this` object

    - #### isCreatable

          default boolean isCreatable()

      Returns whether creates new item by default.

      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.

    - #### withCreatable

          IChosenbox withCreatable​(boolean creatable)

      Returns a copy of `this` immutable component with the specified `creatable`.

      Sets whether creates new item by default.

      - `true`: will show create message while value of input not exists.
      - `false`: will show no result message while value of input not exists.
      Parameters:
        `creatable` - Whether creates new item by default.

        Default: `false`.

      Returns:
        A modified copy of the `this` object

    - #### isInplace

          default boolean isInplace()

      Return whether to display Chosenbox's selection as a comma separate label, under `withIinplace(true)`, when user clicks the label, it turns into a chosenbox.

      Default: `false`

    - #### withInplace

          IChosenbox withInplace​(boolean inplace)

      Returns a copy of `this` immutable component with the specified `inplace`.

      Sets whether to display Chosenbox's selection as a comma separate label, under `withIinplace(true)`, when user clicks the label, it turns into a chosenbox.

      Parameters:
        `inplace` - Whether enables inplace-editing facility.

        Default: `false`.

      Returns:
        A modified copy of the `this` object

    - #### ofId

          static IChosenbox ofId​(java.lang.String id)

      Returns the instance with the given id.
      Parameters:
        `id` - The id to identify this component