Package org.zkoss.stateless.sul

Interface ICombobox

All Superinterfaces:
IAnyGroup<ICombobox>, IChildable<ICombobox,IComboitem>, IChildrenOfInputgroup<ICombobox>, IComponent<ICombobox>, IHtmlBasedComponent<ICombobox>, IInputElement<ICombobox,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

  • Field Details

    • DEFAULT

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

  • Method Details

    • getWidgetClass

      default String getWidgetClass()
      Returns the client widget class.

      Default: "zul.inp.Combobox"

      Specified by:
      getWidgetClass in interface IComponent<ICombobox>

    • getPopupWidth

      @Nullable String getPopupWidth()
      Returns the width of the popup of this component

      Default: null

    • withPopupWidth

      ICombobox withPopupWidth(@Nullable 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 String getEmptySearchMessage()
      Returns the empty search message if any. Default: null

    • withEmptySearchMessage

      ICombobox withEmptySearchMessage(@Nullable 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 String getIconSclass()
      Returns the iconSclass name of this Combobox.

      Default: Combobox.ICON_SCLASS

    • withIconSclass

      ICombobox withIconSclass(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(String value)
      Returns the instance with the given value.
      Parameters:
      value - The value of the component

    • of

      static ICombobox of(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(String constraint)
      Returns the instance with the given constraint.
      Parameters:
      constraint - The combobox constraint

    • ofId

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