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 Details

    • 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 Details

    • getWidgetClass

      default 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 List<IAuxhead> getAuxhead()
      Returns the auxhead child.

    • withAuxhead

      IListbox withAuxhead(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(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 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 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 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 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 String getInnerWidth()
      Returns the inner width of this component. The inner width is the width of the inner table.

      Default: "100%"

    • withInnerWidth

      IListbox withInnerWidth(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 String getOddRowSclass()
      Returns the style class for the odd rows.

      Default: null

    • withOddRowSclass

      IListbox withOddRowSclass(@Nullable 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

    • getResponsive

      @Nullable String getResponsive()
      Returns the responsive policy set on this component, or null if unset.

      Like Listbox.getResponsive() this is the raw value; the zk.xml fallback is resolved by getEffectiveResponsive() at render time.

      Default: null.

      Since:
      11.0.0

    • withResponsive

      IListbox withResponsive(@Nullable String responsive)
      Returns a copy of this immutable component with the specified responsive.

      Sets the responsive policy. "stacking" turns the items into vertical key-value blocks when the container width falls below the breakpoint; "none" disables it, overriding the library property. The stacking behavior itself is drawn by ZK PE (zkmax).

      Note: UiAgent.smartUpdate(Locator, SmartUpdater) is not supported for this property — IListbox.Updater ships the raw attribute while the initial render ships getEffectiveResponsive(). Push a whole component with UiAgent.replaceWith(Locator, IComponent) instead.

      Parameters:
      responsive - one of "stacking", "none", or null (unset).

      Default: null.

      Returns:
      A modified copy of the this object
      Throws:
      org.zkoss.zk.ui.WrongValueException - if responsive is neither "stacking", "none", nor null.
      Since:
      11.0.0

    • getResponsiveColumns

      @Nullable String getResponsiveColumns()
      Returns the responsive columns token string set on this component, used by "stacking" mode, or null if unset.

      Like Listbox.getResponsiveColumns() this is the raw value; the zk.xml fallback is resolved by getEffectiveResponsiveColumns() at render time. Unset means the client applies its own default cascade "sm-1 md-none".

      Default: null.

      Since:
      11.0.0

    • withResponsiveColumns

      IListbox withResponsiveColumns(@Nullable String responsiveColumns)
      Returns a copy of this immutable component with the specified responsiveColumns.

      Sets the responsive columns token string for "stacking" mode. Bootstrap-style breakpoint tokens separated by whitespace, where each token is <breakpoint>-<value> with breakpoint in {sm, md, lg, xl, xxl} and value either a positive integer (cards per row) or none (switch back to table mode at and above this breakpoint).

      The string is stored verbatim — parsing, cascade resolution, and matching against the current container width happen on the client side. Invalid tokens are silently dropped by the client cascade resolver.

      Note: UiAgent.smartUpdate(Locator, SmartUpdater) is not supported for this property — IListbox.Updater ships the raw attribute while the initial render ships getEffectiveResponsiveColumns(). Push a whole component with UiAgent.replaceWith(Locator, IComponent) instead.

      Parameters:
      responsiveColumns - The responsive columns token string, e.g. "sm-1 md-2 lg-none".

      Default: null.

      Returns:
      A modified copy of the this object
      Since:
      11.0.0

    • of

      static IListbox of(Iterable<? extends IListitemBase> children)
      Returns the instance with the given IListitemBase children.
      Parameters:
      children - The children of IListitemBase

    • of

      static IListbox of(IListitemBase... children)
      Returns the instance with the given IListitemBase children.
      Parameters:
      children - The children of IListitemBase

    • ofListhead

      static IListbox ofListhead(IListhead listhead)
      Returns the instance with the given IListhead child.
      Parameters:
      listhead - The IListhead child

    • ofListheaders

      static IListbox ofListheaders(Iterable<? extends IListheader<IAnyGroup>> children)
      Returns the instance with the given IListheader column children.

      a shortcut of IChildable.withChildren(java.lang.Iterable<? extends I>)

      Parameters:
      children - The IListheader children

    • ofListheaders

      static IListbox ofListheaders(IListheader<IAnyGroup>... children)
      Returns the instance with the given IListheader column children.

      a shortcut of IChildable.withChildren(java.lang.Iterable<? extends I>)

      Parameters:
      children - The IListheader children

    • ofListfoot

      static IListbox ofListfoot(IListfoot foot)
      Returns the instance with the given IListfoot foot child.
      Parameters:
      foot - The IListfoot child

    • ofListfooters

      static IListbox ofListfooters(Iterable<? extends IListfooter<IAnyGroup>> children)
      Returns the instance with the given IListfooter footer children.

      a shortcut of IChildable.withChildren(java.lang.Iterable<? extends I>)

      Parameters:
      children - The IListfooter children

    • ofListfooters

      static IListbox ofListfooters(IListfooter<IAnyGroup>... children)
      Returns the instance with the given IListfooter footer children.

      a shortcut of IChildable.withChildren(java.lang.Iterable<? extends I>)

      Parameters:
      children - The IListfooter children

    • ofId

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