Package org.zkoss.stateless.sul

## Interface ICombobox

- All Superinterfaces:
    `IAnyGroup<ICombobox>`, `IChildable<ICombobox,​IComboitem>`, `IChildrenOfInputgroup<ICombobox>`, `IComponent<ICombobox>`, `IHtmlBasedComponent<ICombobox>`, `IInputElement<ICombobox,​java.lang.String>`, `IReadonly<ICombobox>`, `ITextboxBase<ICombobox>`, `IXulElement<ICombobox>`

      public interface ICombobox
      extends ITextboxBase<ICombobox>, IChildable<ICombobox,​IComboitem>, IAnyGroup<ICombobox>

  Immutable `Combobox` component

  A combobox is a special text box that embeds a drop-down list. With comboboxes, users are allowed to select from a drop-down list, in addition to entering the text manually.

  ### Support @Action

  Name | Action Type
  --- | ---
  onSelect | ActionData: `SelectData` Represents an action caused by user's the list selection is changed at the client.
  onOpen | ActionData: `OpenData` Denotes that the user has opened or closed a component. Note: unlike `onClose`, this action is only a notification. The client sends this action after opening or closing the component. It is useful to implement load-on-demand by listening to the `onOpen` action, and creating components when the first time the component is opened.

  ## Mouseless Entry

  - `Alt+DOWN` to pop up the list.
  - `Alt+UP` or `ESC` to close the list.
  - `UP` and `DOWN` to change the selection of the items from the list.
  - `ENTER` to confirm the change of selection.
  - `ESC` to abort the change of selection. It is meaningful if `instantSelect` is false.

  ## Autocomplete

  By default, it will autocomplete your input with the first item in the list that has the same starting string in a case-insensitive way.

  Author:
    katherine
  See Also:
    `Combobox`

- - ### Nested Class Summary

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

    - ### Nested classes/interfaces inherited from interface org.zkoss.stateless.sul.ITextboxBase

      `ITextboxBase.Type`

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static ICombobox` | `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` | `getEmptySearchMessage()` | Returns the empty search message if any.
    `default java.lang.String` | `getIconSclass()` | Returns the iconSclass name of this Combobox.
    `java.lang.String` | `getPopupWidth()` | Returns the width of the popup of this component
    `default int` | `getSelectedIndex()` | Returns the index of the selected item, or -1 if not selected.
    `default java.lang.String` | `getWidgetClass()` | Returns the client widget class.
    `default boolean` | `isAutocomplete()` | Returns whether to automatically complete this text box by matching the nearest item (`IComboitem`.
    `default boolean` | `isAutodrop()` | Returns whether to automatically drop the list if users is changing this text box.
    `default boolean` | `isButtonVisible()` | Returns whether the button (on the right of the timebox) is visible.
    `default boolean` | `isInstantSelect()` | Returns true if onSelect event is sent as soon as user selects using keyboard navigation.
    `default boolean` | `isOpen()` | Returns whether this combobox is open.
    `static ICombobox` | `of​(java.lang.Iterable<? extends IComboitem> children)` | Returns the instance with the given `IComboitem` children.
    `static ICombobox` | `of​(java.lang.String value)` | Returns the instance with the given value.
    `static ICombobox` | `of​(IComboitem... children)` | Returns the instance with the given `IComboitem` children.
    `static ICombobox` | `ofConstraint​(java.lang.String constraint)` | Returns the instance with the given constraint.
    `static ICombobox` | `ofId​(java.lang.String id)` | Returns the instance with the given id.
    `ICombobox` | `withAutocomplete​(boolean autocomplete)` | Returns a copy of `this` immutable component with the specified `autocomplete`.
    `ICombobox` | `withAutodrop​(boolean autodrop)` | Returns a copy of `this` immutable component with the specified `autodrop`.
    `ICombobox` | `withButtonVisible​(boolean buttonVisible)` | Returns a copy of `this` immutable component with the specified `buttonVisible`.
    `ICombobox` | `withEmptySearchMessage​(java.lang.String emptySearchMessage)` | Returns a copy of `this` immutable component with the specified `emptySearchMessage`.
    `ICombobox` | `withIconSclass​(java.lang.String iconSclass)` | Returns a copy of `this` immutable component with the specified `iconSclass`.
    `ICombobox` | `withInstantSelect​(boolean instantSelect)` | Returns a copy of `this` immutable component with the specified `instantSelect`.
    `ICombobox` | `withOpen​(boolean open)` | Returns a copy of `this` immutable component with the specified `sclass`.
    `ICombobox` | `withPopupWidth​(java.lang.String popupWidth)` | Returns a copy of `this` immutable component with the specified `popupWidth`.
    `ICombobox` | `withSelectedIndex​(int selectedIndex)` | Returns a copy of `this` immutable component with the specified `selectedIndex`.

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

      `getChildren, withChildren, withChildren`

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

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

      `getCols, getConstraint, getErrorboxIconSclass, getErrorboxSclass, getErrorMessage, getInputAttributes, getInstant, getMaxlength, getName, getPlaceholder, getValue, isDisabled, isInplace, withCols, withConstraint, withDisabled, withErrorboxIconSclass, withErrorboxSclass, withErrorMessage, withInplace, withInputAttributes, withInstant, withMaxlength, withName, withPlaceholder`

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

      `isReadonly, withReadonly`

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

      `getRows, getType, isMultiline, isSubmitByEnter, isTabbable, withMultiline, withRows, withSubmitByEnter, withTabbable, withType, withType, withValue`

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

      `getContext, getCtrlKeys, getPopup, getTooltip, withContext, withCtrlKeys, withPopup, withTooltip`

- - ### Field Detail

    - #### DEFAULT

          static final ICombobox DEFAULT

      Constant for default attributes of this immutable component.

  - ### Method Detail

    - #### getWidgetClass

          default java.lang.String getWidgetClass()

      Returns the client widget class.

      Default: `"zul.inp.Combobox"`

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

    - #### getPopupWidth

          @Nullable
          java.lang.String getPopupWidth()

      Returns the width of the popup of this component

      Default: `null`

    - #### withPopupWidth

          ICombobox withPopupWidth​(@Nullable
                                   java.lang.String popupWidth)

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

      Sets the width of the popup of this component. If the input is a percentage, the popup width will be calculated by multiplying the width of this component with the percentage. (e.g. if the input string is `130%`, and the width of this component is `300px`, the popup width will be `390px = 300px * 130%`) Others will be set directly.

      Parameters:
        `popupWidth` - The width of the popup of this component.

        Default: `null`.

      Returns:
        A modified copy of the `this` object

    - #### getEmptySearchMessage

          @Nullable
          java.lang.String getEmptySearchMessage()

      Returns the empty search message if any. Default: `null`

    - #### withEmptySearchMessage

          ICombobox withEmptySearchMessage​(@Nullable
                                           java.lang.String emptySearchMessage)

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

      Sets empty search message. This message would be displayed, when no matching results was found. Note: it's meaningless if no model case.

      Parameters:
        `emptySearchMessage` - The empty search message to display.

        Default: `null`.

      Returns:
        A modified copy of the `this` object

    - #### getSelectedIndex

          default int getSelectedIndex()

      Returns the index of the selected item, or -1 if not selected.

    - #### withSelectedIndex

          ICombobox withSelectedIndex​(int selectedIndex)

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

      Deselects the currently selected items and selects the item with the given index.

      Note: if the label of `IComboitem` has the same more than one, the first `IComboitem` will be selected at client side, it is a limitation of `ICombobox` and it is different from `IListbox`.

      Parameters:
        `selectedIndex` - The selected index of the combobox.

        Default: `-1`, meaning not selected.

      Returns:
        A modified copy of the `this` object

    - #### isAutodrop

          default boolean isAutodrop()

      Returns whether to automatically drop the list if users is changing this text box.

      Default: `false`.

    - #### withAutodrop

          ICombobox withAutodrop​(boolean autodrop)

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

      Sets whether to automatically drop the list if users is changing this text box.

      Parameters:
        `autodrop` - `true` to enable the auto-drop facility.

        Default: `false`.

      Returns:
        A modified copy of the `this` object

    - #### isAutocomplete

          default boolean isAutocomplete()

      Returns whether to automatically complete this text box by matching the nearest item (`IComboitem`. It is also known as auto-type-ahead.

      If true, the nearest item will be searched and the text box is updated automatically. If false, user has to click the item or use the DOWN or UP keys to select it back.

      Don't confuse it with the auto-completion feature mentioned by other framework. Such kind of auto-completion is supported well by listening to the `onChanging` action.

      Default: `true`

    - #### withAutocomplete

          ICombobox withAutocomplete​(boolean autocomplete)

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

      Sets whether to automatically complete this text box by matching the nearest item (`IComboitem`.

      Parameters:
        `autocomplete` - `false` to disable the auto-completion feature.

        Default: `true`.

      Returns:
        A modified copy of the `this` object

    - #### isButtonVisible

          default boolean isButtonVisible()

      Returns whether the button (on the right of the timebox) is visible.

      Default: `true`.

    - #### withButtonVisible

          ICombobox withButtonVisible​(boolean buttonVisible)

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

      Sets whether the button (on the right of the combobox) is visible.

      Parameters:
        `buttonVisible` - `false` to disable the button visibility.

        Default: `true`.

      Returns:
        A modified copy of the `this` object

    - #### isInstantSelect

          default boolean isInstantSelect()

      Returns true if onSelect event is sent as soon as user selects using keyboard navigation.

      Default: `true`

    - #### withInstantSelect

          ICombobox withInstantSelect​(boolean instantSelect)

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

      Sets the instantSelect attribute. When the attribute is true, `onSelect` action will be fired as soon as user selects using keyboard navigation. If the attribute is false, user needs to press `Enter key` to finish the selection using keyboard navigation.

      Parameters:
        `instantSelect` - `false` to disable the button visibility.

        Default: `true`.

      Returns:
        A modified copy of the `this` object

    - #### getIconSclass

          default java.lang.String getIconSclass()

      Returns the iconSclass name of this Combobox.

      Default: `Combobox.ICON_SCLASS`

    - #### withIconSclass

          ICombobox withIconSclass​(java.lang.String iconSclass)

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

      Sets the iconSclass name of this Combobox.

      Parameters:
        `iconSclass` - The iconSclass name of this Combobox.

        Default: `Combobox.ICON_SCLASS`

      Returns:
        A modified copy of the `this` object

    - #### isOpen

          default boolean isOpen()

      Returns whether this combobox is open.

      Default: `false`.

    - #### withOpen

          ICombobox withOpen​(boolean open)

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

      Sets whether this combobox is open or not.

      Parameters:
        `open` - `true` to open the dropdown.

        Default: `false`

      Returns:
        A modified copy of the `this` object

    - #### of

          static ICombobox of​(java.lang.String value)

      Returns the instance with the given value.
      Parameters:
        `value` - The value of the component

    - #### of

          static ICombobox of​(java.lang.Iterable<? extends IComboitem> children)

      Returns the instance with the given `IComboitem` children.
      Parameters:
        `children` - The children of `IComboitem`

    - #### of

          static ICombobox of​(IComboitem... children)

      Returns the instance with the given `IComboitem` children.
      Parameters:
        `children` - The children of `IComboitem`

    - #### ofConstraint

          static ICombobox ofConstraint​(java.lang.String constraint)

      Returns the instance with the given constraint.
      Parameters:
        `constraint` - The combobox constraint

    - #### ofId

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

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