Package org.zkoss.stateless.sul

Interface IListbox

  • All Superinterfaces:
    IAnyGroup<IListbox>, IChildable<IListbox,​IListitemBase>, IComponent<IListbox>, IComposite<IListbox,​IMeshComposite>, IHtmlBasedComponent<IListbox>, IMeshElement<IListbox>, IXulElement<IListbox>
    public interface IListbox
extends IMeshElement<IListbox>, IComposite<IListbox,​IMeshComposite>, IChildable<IListbox,​IListitemBase>, IAnyGroup<IListbox>
    Immutable Listbox component

    Note: unlike Listbox, there is no "select" mold in stateless API, please use ISelectbox instead.

    Support @Action

    Name Action Type
    onSelect ActionData: SelectData
    Notifies one that the user has selected a new item in the listbox.
    onFocus Denotes when a component gets the focus. Remember event listeners execute at the server, so the focus at the client might be changed when the event listener for onFocus got executed.
    onBlur Denotes when a component loses the focus. Remember event listeners execute at the server, so the focus at the client might be changed when the event listener for onBlur got executed.
    onPageSize ActionData: PageSizeData
    Notifies the paging size has been changed when the autopaging (iListbox.withAutopaging(boolean)) is enabled and a user changed the size of the content.
    onCheckSelectAll ActionData: CheckData
    Notifies the checkbox on a listheader is checked to select all checkable items.

    Support Molds

    Name Snapshot
    "default"
    "paging"

    Support Application Library Properties

    • To turn on the auto-sort facility to sort the model for this component, you have to specify withAutosort(Autosort) to IListbox.Autosort.ENABLE or IListbox.Autosort.IGNORE_CHANGE.

      Or configure it from zk.xml by setting library properties. For example, 

        <library-property/>
     <name>org.zkoss.zul.listbox.autoSort</name/>
     <value>true</value/>
 </library-property/>

    • To set to prefer to deselect all other items and select the item being clicked when isCheckmark() is enabled, you have to specify withCheckmarkDeselectOther(boolean) to true.

      Or configure it from zk.xml by setting library properties. For example, 

        <library-property/>
     <name>org.zkoss.zul.listbox.checkmarkDeselectOthers</name/>
     <value>true</value/>
 </library-property/>

    • To set whether to disable select functionality when highlighting text content with mouse dragging or not, you have to specify withSelectOnHighlightDisabled(boolean) to true.

      Or configure it from zk.xml by setting library properties. For example, 

        <library-property/>
     <name>org.zkoss.zul.listbox.selectOnHighlight.disabled</name/>
     <value>true</value/>
 </library-property/>

    • To set whether to disable the selection will be toggled when the user right clicks item, only if isCheckmark() is enabled. You have to specify withRightSelect(boolean) to false.

      Or configure it from zk.xml by setting library properties. For example, 

        <library-property/>
     <name>org.zkoss.zul.listbox.rightSelect</name/>
     <value>false</value/>
 </library-property/>

    • To set whether to enable the selection will be toggled when the user clicks listgroup item, only if IListgroupChild in used. You have to specify withListgroupSelectable(boolean) to true.

      Or configure it from zk.xml by setting library properties. For example, 

        <library-property/>
     <name>org.zkoss.zul.listbox.groupSelect</name/>
     <value>true</value/>
 </library-property/>
    Note: with zk.xml setting, it will affect to all tree components.
    Author:
    katherine
    See Also:
    Listbox

    • Field Detail

      • DEFAULT

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

      • PAGING

        static final IListbox PAGING
        Constant for "paging" mold attributes of this immutable component.

    • Method Detail

      • getWidgetClass

        default java.lang.String getWidgetClass()
        Returns the client widget class.

        Default: "zul.sel.Listbox"

        Specified by:
        getWidgetClass in interface IComponent<IListbox>

      • getListhead

        @Nullable
IListhead getListhead()
        Returns the listhead.

        Default: null

      • withListhead

        IListbox withListhead​(@Nullable
                      IListhead listhead)
        Returns a copy of this immutable component with the specified listhead.

        Sets the listhead as a child to this component

        Parameters:
        listhead - The listhead child.

        Default: null.

        Returns:
        A modified copy of the this object

      • getListfoot

        @Nullable
IListfoot getListfoot()
        Returns the foot.

        Default: null

      • withListfoot

        IListbox withListfoot​(@Nullable
                      IListfoot listfoot)
        Returns a copy of this immutable component with the specified listfoot.

        Sets the listfoot as a child to this component

        Parameters:
        listfoot - The listfoot child.

        Default: null.

        Returns:
        A modified copy of the this object

      • getFrozen

        @Nullable
IFrozen getFrozen()
        Returns the frozen child.

        Default: null.

      • withFrozen

        IListbox withFrozen​(@Nullable
                    IFrozen frozen)
        Returns a copy of this immutable component with the specified frozen.

        Sets the frozen as a child to this component

        Parameters:
        frozen - The foot child.

        Default: null.

        Returns:
        A modified copy of the this object

      • getAuxhead

        default java.util.List<IAuxhead> getAuxhead()
        Returns the auxhead child.

      • withAuxhead

        IListbox withAuxhead​(java.lang.Iterable<? extends IAuxhead> auxhead)
        Returns a copy of this immutable component with the specified auxhead.

        Sets the list of auxhead as children to this component

        Parameters:
        auxhead - The auxhead children.

        Default: null.

        Returns:
        A modified copy of the this object

      • withAuxhead

        default IListbox withAuxhead​(IAuxhead... auxhead)
        Returns a copy of this immutable component with the specified auxhead.

        Sets the list of auxhead as children to this component

        Parameters:
        auxhead - The auxhead child.

        Default: null.

        Returns:
        A modified copy of the this object

      • withAllComponents

        default IListbox withAllComponents​(java.lang.Iterable<? extends IMeshComposite> elements)
        Description copied from interface: IComposite
        Copy the current immutable object with elements that replace the content of children. A shallow reference equality check is used to prevent copying of the same value by returning this.
        Specified by:
        withAllComponents in interface IComposite<IListbox,​IMeshComposite>
        Parameters:
        elements - An iterable of children elements to set
        Returns:
        A modified copy of this object

      • getRows

        default int getRows()
        Returns the number of the rows to display at screen. Zero means no limitation.

        Default: 0

      • withRows

        IListbox withRows​(int rows)
        Returns a copy of this immutable component with the specified rows.

        Sets the number of the rows of the listbox to display at a screen, which means the height of the listbox is based on the calculation of the number of the rows by multiplying with each row height.

        Note: Not allowed to set rows and height/vflex at the same time.

        Parameters:
        rows - The number of rows to display.

        Default: 0. (Meaning no limitation)

        Returns:
        A modified copy of the this object

      • getAutosort

        @Nullable
default java.lang.String getAutosort()
        Returns whether to sort all items when model or sort direction be changed.

        Default: false, if the "org.zkoss.zul.listbox.autoSort" library property is not set in zk.xml.

        Note: it's meaningless if ListModel is not set.

      • withAutosort

        IListbox withAutosort​(@Nullable
                      java.lang.String autosort)
        Returns a copy of this immutable component with the specified autosort.

        Sets to enable the auto-sort facility to sort the model for this component. Meaningless if ListModel is not set.

        Parameters:
        autosort - The allowed values are null, "false", "true", and "ignore.change".

        Default: null.

        Returns:
        A modified copy of the this object

      • withAutosort

        default IListbox withAutosort​(@Nullable
                              IListbox.Autosort autosort)
        Returns a copy of this immutable component with the specified autosort.

        Sets to enable the auto-sort facility to sort the model for this component. Meaningless if ListModel is not set.

        Parameters:
        autosort - The allowed values are null, "false", "true", and "ignore.change".

        Default: null.

        Returns:
        A modified copy of the this object

      • isMultiple

        default boolean isMultiple()
        Returns whether multiple selections are allowed.

        Default: false.

      • withMultiple

        IListbox withMultiple​(boolean multiple)
        Returns a copy of this immutable component with the specified multiple.

        Sets whether multiple selections are allowed.

        Notice that, if a model is assigned, it will change the model's state (by Selectable.setMultiple(boolean)).

        Parameters:
        multiple - True to allow multiple selections.

        Default: false.

        Returns:
        A modified copy of the this object

      • isCheckmark

        default boolean isCheckmark()
        Returns whether the check mark shall be displayed in front of each item.

        Default: false.

      • withCheckmark

        IListbox withCheckmark​(boolean checkmark)
        Returns a copy of this immutable component with the specified checkmark.

        Sets whether the check mark shall be displayed in front of each item.

        The check mark is a checkbox if isMultiple() returns true. It is a radio button if isMultiple() returns false.

        Parameters:
        checkmark - True to enable the check mark in front of each item.

        Default: false.

        Returns:
        A modified copy of the this object

      • getNonselectableTags

        @Nullable
java.lang.String getNonselectableTags()
        Returns a list of HTML tag names that shall not cause the tree item being selected if they are clicked.

        Default: null (it means button, input, textarea and a HTML elements). If you want to select no matter which tag is clicked, please specify an empty string. Specify null to use the default and "" to indicate none.

      • withNonselectableTags

        IListbox withNonselectableTags​(@Nullable
                               java.lang.String nonselectableTags)
        Returns a copy of this immutable component with the specified name.

        Sets a list of HTML tag names that shall not cause the tree item being selected if they are clicked.

        Default: null (it means button, input, textarea and a HTML elements). If you want to select no matter which tag is clicked, please specify an empty string.

        Parameters:
        nonselectableTags - A list of HTML tag names that will not cause the tree item being selected if clicked. Specify null to use the default and "" to indicate none.
        Returns:
        A modified copy of the this object

      • isCheckmarkDeselectOther

        default boolean isCheckmarkDeselectOther()
        Returns whether to toggle the selection if clicking on a tree item with a checkmark. Meaningless if isCheckmark() is false

        Default: false, if the "org.zkoss.zul.listbox.checkmarkDeselectOthers" library property is not set in zk.xml.

      • withCheckmarkDeselectOther

        IListbox withCheckmarkDeselectOther​(boolean checkmarkDeselectOther)
        Returns a copy of this immutable component with the specified checkmarkDeselectOther.

        Sets true to prefer to deselect all other items and select the item being clicked. If isCheckmark() is enabled.

        Default: false (not to deselect other items).

        Parameters:
        checkmarkDeselectOther - True to deselect other items and select the item being clicked.

        Default: false

        Returns:
        A modified copy of the this object

      • isSelectOnHighlightDisabled

        default boolean isSelectOnHighlightDisabled()
        Returns whether to disable select functionality when highlighting text content with mouse dragging or not.

        Default: false, if the "org.zkoss.zul.listbox.selectOnHighlight.disabled" library property is not set in zk.xml.

      • withSelectOnHighlightDisabled

        IListbox withSelectOnHighlightDisabled​(boolean selectOnHighlightDisabled)
        Returns a copy of this immutable component with the specified selectOnHighlightDisabled.

        Sets whether to disable select functionality when highlighting text content with mouse dragging or not.

        Parameters:
        selectOnHighlightDisabled - True to disable select functionality when highlighting text content with mouse dragging or not.

        Default: false

        Returns:
        A modified copy of the this object

      • isRightSelect

        default boolean isRightSelect()
        Returns whether to toggle a list item selection on right click, only if isCheckmark() is enabled.

        Default: true, if the "org.zkoss.zul.listbox.rightSelect" library property is not set in zk.xml.

      • withRightSelect

        IListbox withRightSelect​(boolean rightSelect)
        Returns a copy of this immutable component with the specified rightSelect.

        Sets whether to enable the selection will be toggled when the user right clicks item, only if isCheckmark() is enabled.

        Parameters:
        rightSelect - False not to select/deselect item on right click

        Default: true

        Returns:
        A modified copy of the this object

      • isListgroupSelectable

        default boolean isListgroupSelectable()
        Returns whether Listgroup is selectable.

        Default: false

      • withListgroupSelectable

        IListbox withListgroupSelectable​(boolean listgroupSelectable)
        Returns a copy of this immutable component with the specified listgroupSelectable.

        Sets whether to enable or disable the selection will be toggled when the user clicks item on IListgroupChild.

        Parameters:
        listgroupSelectable - False not to select/deselect item on click

        Default: false

        Returns:
        A modified copy of the this object

      • getInnerWidth

        default java.lang.String getInnerWidth()
        Returns the inner width of this component. The inner width is the width of the inner table.

        Default: "100%"

      • withInnerWidth

        IListbox withInnerWidth​(java.lang.String innerWidth)
        Returns a copy of this immutable component with the specified innerWidth.

        Sets the inner width of this component. The inner width is the width of the inner table. By default, it is 100%. That is, it is the same as the width of this component. However, it is changed when the user is sizing the column's width.

        Application developers rarely call this method, unless they want to preserve the widths of sizable columns changed by the user. To preserve the widths, the developer have to store the widths of all columns and the inner width (getInnerWidth()), and then restore them when re-creating this component.

        Parameters:
        innerWidth - The inner width of this component.

        Default: "100%".

        Returns:
        A modified copy of the this object

      • getOddRowSclass

        @Nullable
java.lang.String getOddRowSclass()
        Returns the style class for the odd rows.

        Default: null

      • withOddRowSclass

        IListbox withOddRowSclass​(@Nullable
                          java.lang.String oddRowSclass)
        Returns a copy of this immutable component with the specified oddRowSclass.

        Sets the style class for the odd rows. If the style class doesn't exist, the striping effect disappears. You can provide different effects by providing the proper style classes.

        Parameters:
        oddRowSclass - The style class for the odd rows

        Default: null

        Returns:
        A modified copy of the this object

      • ofId

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