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

    • 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

      • 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