Package org.zkoss.zul

Class Listbox

java.lang.Object
org.zkoss.zk.ui.AbstractComponent
org.zkoss.zk.ui.HtmlBasedComponent
org.zkoss.zul.impl.XulElement
org.zkoss.zul.impl.MeshElement
org.zkoss.zul.Listbox
All Implemented Interfaces:
Serializable, Cloneable, org.zkoss.zk.ui.Component, org.zkoss.zk.ui.ext.Scope, org.zkoss.zk.ui.sys.ComponentCtrl, Paginated
public class Listbox extends MeshElement
A listbox.

Event:

  1. SelectEvent is sent when user changes the selection.
  2. onAfterRender is sent when the model's data has been rendered.(since 5.0.4)
  3. onCheckSelectAll is sent when user click on selectAll checkbox.(since 6.5.5)

See Specification.

Besides creating Listitem programmatically, you could assign a data model (a ListModel or GroupsModel instance) to a listbox via setModel(ListModel) or setModel(GroupsModel) and then the listbox will retrieve data via ListModel.getElementAt(int) when necessary.

Besides assign a list model, you could assign a renderer (a ListitemRenderer instance) to a listbox, such that the listbox will use this renderer to render the data returned by ListModel.getElementAt(int). If not assigned, the default renderer, which assumes a label per list item, is used. In other words, the default renderer adds a label to a Listitem by calling toString against the object returned by ListModel.getElementAt(int)

To retrieve what are selected in Listbox with a Selectable ListModel, you shall use Selectable.getSelection() to get what is currently selected object in ListModel rather than using getSelectedItems(). That is, you shall operate on the item of the ListModel rather than on the Listitem of the Listbox if you use the Selectable ListModel.


 Set selection = ((Selectable)getModel()).getSelection();

[Since 6.0.0] If a model is set, whether the listbox allows the multiple selection depends on Selectable.setMultiple(boolean). In other words, the application shall not access listbox directly if a model is assigned. Rather, the application shall access the model directly.

There are two ways to handle long content: scrolling and paging. If AbstractComponent.getMold() is "default", scrolling is used if setHeight(java.lang.String) is called and too much content to display. If AbstractComponent.getMold() is "paging", paging is used if two or more pages are required. To control the number of items to display in a page, use setPageSize(int).

If paging is used, the page controller is either created automatically or assigned explicitly by setPaginal(org.zkoss.zul.ext.Paginal). The paging controller specified explicitly by setPaginal(org.zkoss.zul.ext.Paginal) is called the external page controller. It is useful if you want to put the paging controller at different location (other than as a child component), or you want to use the same controller to control multiple listboxes.

Default getZclass(): z-listbox.(since 3.5.0)

To have a list box without stripping, you can specify a non-existent style class to setOddRowSclass(java.lang.String).

Clustering and Serialization

When used in a clustering environment, you have to make ListitemRenderer (setItemRenderer(org.zkoss.zul.ListitemRenderer<?>)) and ListModel ( setModel(org.zkoss.zul.ListModel<?>)) either serializable or re-assign them when sessionDidActivate(org.zkoss.zk.ui.Page) is called.

Render on Demand (rod)

[ZK EE] [Since 5.0.0]

For huge data, you can turn on Listbox's ROD to request ZK engine to load from ListModel only the required data chunk and create only the required Listitems in memory and render only the required DOM elements in browser. So it saves both the memory and the processing time in both server and browser for huge data. If you don't use the ListModel with the Listbox, turn on the ROD will still have ZK engine to render only a chunk of DOM elements in browser so it at least saves the memory and processing time in browser. Note that ROD works only if the Listbox is configured to has a limited "view port" height. That is, either the Listbox is in the "paging" mold or you have to setHeight(String),setVflex(String), or setRows(int) of the Listbox to make ROD works.

You can turn on/off ROD for all Listboxes in the application or only for a specific Listbox. To turn on ROD for all Listboxes in the application, you have to specify the Library Property "org.zkoss.zul.listbox.rod" to "true" in WEB-INF/zk.xml. If you did not specify the Library Property, default is false.


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

To turn on ROD for a specific Listbox, you have to specify the Listbox's attribute map with key "org.zkoss.zul.listbox.rod" to true. That is, for example, if in a zul file, you shall specify <custom-attributes> of the Listbox like this:


	<listbox ...>
    <custom-attributes org.zkoss.zul.listbox.rod="true"/>
  </listbox>

You can mix the Library Property and <custom-attributes> ways together. The <custom-attributes> way always takes higher priority. So you can turn OFF ROD in general and turn ON only some specific Listbox component. Or you can turn ON ROD in general and turn OFF only some specific Listbox component.

Since only partial Listitems are created and rendered in the Listbox if you turn the ROD on, there will be some limitations on accessing Listitems. For example, if you call 


 Listitem itemAt100 = (Listitem) getItemAtIndex(100);

The Listitem in index 100 is not necessary created yet if it is not in the current "view port" and you will get "null" instead.

And it is generally a bad idea to "cache" the created Listitem in your application if you turn the ROD on because Listitems might be removed later. Basically, you shall operate on the item of the ListModel rather than on the Listitem of the Listbox if you use the ListModel and ROD.

Custom Attributes

org.zkoss.zul.listbox.rightSelect
Specifies whether the selection shall be toggled when user right clicks on item, if the checkmark (isCheckmark()) is enabled.
Notice that you could specify this attribute in any of its ancestor's attributes. It will be inherited.
org.zkoss.zul.listbox.rod
Specifies whether to enable ROD (render-on-demand).
Notice that you could specify this attribute in any of its ancestor's attributes. It will be inherited.
org.zkoss.zul.listbox.autoSort
.(since 5.0.7)
Specifies whether to sort the model when the following cases:
  1. setModel(org.zkoss.zul.ListModel<?>) is called and Listheader.setSortDirection(java.lang.String) is set.
  2. Listheader.setSortDirection(java.lang.String) is called.
  3. Model receives ListDataEvent and Listheader.setSortDirection(java.lang.String) is set.
If you want to ignore sort when receiving ListDataEvent, you can specifies the value as "ignore.change".
Notice that you could specify this attribute in any of its ancestor's attributes. It will be inherited.
org.zkoss.zul.listbox.groupSelect
Specifies whether Listgroups under this Listbox are selectable. Notice that you could specify this attribute in any of its ancestor's attributes. It will be inherited. Default value is false.
org.zkoss.zul.listbox.preloadSize
.(since 5.0.8)
Specifies the number of items to preload when receiving the rendering request from the client.

It is used only if live data (setModel(ListModel) and not paging (getPagingChild()).

org.zkoss.zul.listbox.initRodSize
.(since 5.0.8)
Specifies the number of items rendered when the Listbox first render.

It is used only if live data (setModel(ListModel) and not paging (getPagingChild()).

org.zkoss.zul.listbox.selectOnHighlight.disabled
.(since 7.0.4)
Sets whether to disable select functionality when highlighting text content with mouse dragging or not.
Author:
tomyeh
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    protected class 
    Listbox.Children
     
    protected class 
    Listbox.ExtraCtrl
    A utility class to implement HtmlBasedComponent.getExtraCtrl().

    Nested classes/interfaces inherited from class org.zkoss.zul.impl.MeshElement

    MeshElement.InternalPaging

    Nested classes/interfaces inherited from class org.zkoss.zk.ui.AbstractComponent

    org.zkoss.zk.ui.AbstractComponent.ForwardInfo, org.zkoss.zk.ui.AbstractComponent.TargetInfo

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    LOADING_MODEL
     
    static final String
    SYNCING_MODEL
     

    Fields inherited from class org.zkoss.zul.impl.MeshElement

    CSS_FLEX_AUTO_DISABLED_COUNT

    Fields inherited from class org.zkoss.zk.ui.HtmlBasedComponent

    _zclass

    Fields inherited from interface org.zkoss.zk.ui.Component

    APPLICATION_SCOPE, COMPONENT_SCOPE, DESKTOP_SCOPE, PAGE_SCOPE, REQUEST_SCOPE, SESSION_SCOPE, SPACE_SCOPE

    Fields inherited from interface org.zkoss.zk.ui.sys.ComponentCtrl

    AFTER_CHILD_ADDED, AFTER_CHILD_REMOVED, AFTER_CLONED, AFTER_PAGE_ATTACHED, AFTER_PAGE_DETACHED, AFTER_PARENT_CHANGED, CE_BUSY_IGNORE, CE_DUPLICATE_IGNORE, CE_IMPORTANT, CE_NON_DEFERRABLE, CE_REPEAT_IGNORE

  • Constructor Summary

    Constructors
    Constructor
    Description
    Listbox()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addItemToSelection(Listitem item)
    Selects the given item, without deselecting any other items that are already selected..
    protected void
    afterInsert(org.zkoss.zk.ui.Component comp)
    Callback if a list item has been inserted.
    Listitem
    appendItem(String label, String value)
    Appends an item.
    void
    beforeChildAdded(org.zkoss.zk.ui.Component newChild, org.zkoss.zk.ui.Component refChild)
     
    protected void
    beforeRemove(org.zkoss.zk.ui.Component comp)
    Callback if a list item will be removed (not removed yet).
    void
    clearSelection()
    Clears the selection.
    Object
    clone()
     
    <T extends org.zkoss.zk.ui.Component>
    List<T>
    getChildren()
     
    String
    getEmptyMessage()
    Returns the message to display when there are no items
    Object
    getExtraCtrl()
     
    Frozen
    getFrozen()
    Returns the frozen child.
    int
    getGroupCount()
    Returns the number of listgroup
    List<Listgroup>
    getGroups()
    Returns a list of all Listgroup.
    <D, G, F> GroupsModel<D,G,F>
    getGroupsModel()
    Returns the groups model associated with this list box, or null if this list box is associated with a ListModel or not associated with any list data model.
    Collection<org.zkoss.zk.ui.Component>
    getHeads()
    Returns a collection of heads, including getListhead() and auxiliary heads (Auxhead) (never null).
    int
    getIndexOfItem(Listitem item)
    Returns the index of the specified item, or -1 if not found.
    String
    getInnerWidth()
    Returns the inner width of this component.
    Listitem
    getItemAtIndex(int index)
    Returns the item at the specified index.
    int
    getItemCount()
    Returns the number of items.
    <T> ListitemRenderer<T>
    getItemRenderer()
    Returns the renderer to render each item, or null if the default renderer is used.
    List<Listitem>
    getItems()
    Returns a live list of all Listitem.
    Listfoot
    getListfoot()
    Returns Listfoot belonging to this listbox, or null if no list footers at all.
    Listhead
    getListhead()
    Returns Listhead belonging to this listbox, or null if no list headers at all.
    <T> ListModel<T>
    getListModel()
    Returns the list model associated with this list box, or null if this list box is associated with a GroupsModel or not associated with any list data model.
    int
    getMaxlength()
    Returns the maximal length of each item's label.
    <T> ListModel<T>
    getModel()
    Returns the model associated with this list box, or null if this list box is not associated with any list data model.
    String
    getName()
    Returns the name of this component.
    String
    getNonselectableTags()
    Returns a list of HTML tag names that shall not cause the list item being selected if they are clicked.
    String
    getOddRowSclass()
    Returns the style class for the odd rows.
    Paginal
    getPaginal()
    Returns the paging controller, or null if not available.
    Paging
    getPagingChild()
    Returns the child paging controller that is created automatically, or null if mold is not "paging", or the controller is specified externally by setPaginal(org.zkoss.zul.ext.Paginal).
    org.zkoss.zk.ui.sys.PropertyAccess
    getPropertyAccess(String prop)
     
    String
    getResponsive()
    Returns the responsive policy.
    String
    getResponsiveColumns()
    Returns the responsive columns token string.
    int
    getRows()
    Returns the rows.
    int
    getSelectedCount()
    Returns the number of items being selected.
    int
    getSelectedIndex()
    Returns the index of the selected item (-1 if no one is selected).
    Listitem
    getSelectedItem()
    Returns the selected item.
    Set<Listitem>
    getSelectedItems()
    Returns all selected items.
    String
    getSeltype()
    Returns the seltype.
    int
    getVisibleItemCount()
    Returns the number of visible descendant Listitem.
    String
    getZclass()
     
    boolean
    hasGroup()
    Returns whether listgroup exists.
    boolean
    insertBefore(org.zkoss.zk.ui.Component newChild, org.zkoss.zk.ui.Component refChild)
     
    protected boolean
    isAutohidePaging()
     
    boolean
    isCheckmark()
    Returns whether the check mark shall be displayed in front of each item.
    boolean
    isDisabled()
    Returns whether it is disabled.
    boolean
    isMultiple()
    Returns whether multiple selections are allowed.
    protected boolean
    isSelectOnHighlightDisabled()
     
    boolean
    isVflex()
    Returns whether to grow and shrink vertical to fit their given space, so called vertical flexibility.
    void
    onAfterRender()
     
    void
    onInitRender()
    Handles a private event, onInitRender.
    void
    onPageAttached(org.zkoss.zk.ui.Page newpage, org.zkoss.zk.ui.Page oldpage)
     
    void
    onPageDetached(org.zkoss.zk.ui.Page page)
     
    void
    onPagingInitRender()
    Handles a private event, onPagingInitRender.
    protected Paginal
    pgi()
    Returns the instance of the @{link Paginal}
    boolean
    removeChild(org.zkoss.zk.ui.Component child)
    If the child is a listgroup, its listgroupfoot will be removed at the same time.
    Listitem
    removeItemAt(int index)
    Removes the child item in the list box at the given index.
    void
    removeItemFromSelection(Listitem item)
    Deselects the given item without deselecting other items.
    void
    renderAll()
    Renders all Listitem if not loaded yet, with getItemRenderer().
    Listitem
    renderItem(Listitem li)
    Renders the specified Listitem if not loaded yet, with getItemRenderer().
    void
    renderItems(Set<? extends Listitem> items)
    Renders the given set of list items.
    protected void
    renderProperties(org.zkoss.zk.ui.sys.ContentRenderer renderer)
     
    void
    scrollToIndex(int index)
    Scroll to the specified item by the given index.
    void
    selectAll()
    Selects all items.
    void
    selectItem(Listitem item)
    Deselects all of the currently selected items and selects the given item.
    void
    service(org.zkoss.zk.au.AuRequest request, boolean everError)
    Processes an AU request.
    void
    sessionDidActivate(org.zkoss.zk.ui.Page page)
     
    void
    sessionWillPassivate(org.zkoss.zk.ui.Page page)
     
    void
    setActivePage(int pg)
    Sets the active page (starting from 0).
    void
    setActivePage(Listitem item)
    Sets the active page in which the specified item is.
    void
    setCheckmark(boolean checkmark)
    Sets whether the check mark shall be displayed in front of each item.
    void
    setDisabled(boolean disabled)
    Sets whether it is disabled.
    void
    setEmptyMessage(String emptyMessage)
    Sets the message to display when there are no items
    void
    setHeight(String height)
     
    void
    setInnerWidth(String innerWidth)
    Sets the inner width of this component.
    void
    setItemRenderer(String clsnm)
    Sets the renderer by use of a class name.
    void
    setItemRenderer(ListitemRenderer<?> renderer)
    Sets the renderer which is used to render each item if getModel() is not null.
    void
    setMaxlength(int maxlength)
    Sets the maximal length of each item's label.
    void
    setModel(GroupsModel<?,?,?> model)
    Sets the groups model associated with this list box.
    void
    setModel(ListModel<?> model)
    Sets the list model associated with this listbox.
    void
    setMold(String mold)
    Sets the mold to render this component.
    void
    setMultiple(boolean multiple)
    Sets whether multiple selections are allowed.
    void
    setName(String name)
    Sets the name of this component.
    void
    setNonselectableTags(String tags)
    Sets a list of HTML tag names that shall not cause the list item being selected if they are clicked.
    void
    setOddRowSclass(String scls)
    Sets the style class for the odd rows.
    void
    setPageSize(int pgsz)
    Sets the page size, a.k.a., the number rows per page.
    void
    setPaginal(Paginal pgi)
    Specifies the paging controller.
    void
    setResponsive(String responsive)
    Sets the responsive policy.
    void
    setResponsiveColumns(String columns)
    Sets the responsive columns token string for stacking mode.
    void
    setRows(int rows)
    Sets the rows.
    void
    setSelectedIndex(int jsel)
    Deselects all of the currently selected items and selects the item with the given index.
    void
    setSelectedItem(Listitem item)
    Deselects all of the currently selected items and selects the given item.
    void
    setSelectedItems(Set<Listitem> listItems)
    Selects the given listitems.
    void
    setSeltype(String seltype)
    Sets the seltype.
    void
    setVflex(boolean vflex)
    Sets whether to grow and shrink vertical to fit their given space, so called vertical flexibility.
    void
    setVflex(String flex)
     
    void
    shallUpdateScrollPos(boolean shallUpdateScrollPos)
    Sets whether to update the scroll position on init
    void
    toggleItemSelection(Listitem item)
    If the specified item is selected, it is deselected.

    Methods inherited from class org.zkoss.zul.impl.MeshElement

    checkBeforeSetRows, evalCSSFlex, getActivePage, getPageCount, getPageSize, getPagingPosition, getSpan, isAutopaging, isPagingDisabled, isSizedByContent, isSpan, setAutopaging, setPagingDisabled, setPagingPosition, setSizedByContent, setSpan, setSpan

    Methods inherited from class org.zkoss.zul.impl.XulElement

    getContext, getCtrlKeys, getPopup, getTooltip, setContext, setContext, setContextAttributes, setCtrlKeys, setPopup, setPopup, setPopupAttributes, setTooltip, setTooltip, setTooltipAttributes

    Methods inherited from class org.zkoss.zk.ui.HtmlBasedComponent

    addSclass, focus, getAction, getClientAction, getDraggable, getDroppable, getHeight, getHflex, getLeft, getRenderdefer, getSclass, getSkeleton, getStyle, getTabindex, getTabindexInteger, getTooltiptext, getTop, getVflex, getWidth, getZindex, getZIndex, removeSclass, removeSclass, setAction, setClass, setClientAction, setDraggable, setDroppable, setFocus, setHeight0, setHeightDirectly, setHflex, setHflex0, setHflexDirectly, setLeft, setLeftDirectly, setRenderdefer, setSclass, setSkeleton, setStyle, setTabindex, setTabindex, setTooltiptext, setTop, setTopDirectly, setVflex0, setVflexDirectly, setWidth, setWidth0, setWidthDirectly, setZclass, setZindex, setZIndex, setZIndexDirectly

    Methods inherited from class org.zkoss.zk.ui.AbstractComponent

    addAnnotation, addCallback, addClientEvent, addEventHandler, addEventListener, addEventListener, addForward, addForward, addForward, addForward, addMoved, addRedrawCallback, addScopeListener, addShadowRoot, addShadowRootBefore, addSharedEventHandlerMap, appendChild, applyProperties, beforeChildRemoved, beforeParentChanged, destroyIndexCacheMap, detach, didActivate, didActivate, didDeserialize, didDeserialize, disableBindingAnnotation, disableClientUpdate, disableHostChanged, enableBindingAnnotation, enableHostChanged, getAnnotatedProperties, getAnnotatedPropertiesBy, getAnnotation, getAnnotations, getAnnotations, getAttribute, getAttribute, getAttribute, getAttributeOrFellow, getAttributes, getAttributes, getAuService, getAutag, getCallback, getClientAttribute, getClientDataAttribute, getClientEvents, getDefaultMold, getDefinition, getDesktop, getEventHandler, getEventHandlerNames, getEventListenerMap, getEventListeners, getFellow, getFellow, getFellowIfAny, getFellowIfAny, getFellows, getFirstChild, getForwards, getId, getIndexCacheMap, getLastChild, getMold, getNextSibling, getPage, getParent, getPreviousSibling, getRedrawCallback, getRoot, getShadowFellowIfAny, getShadowRoots, getShadowVariable, getShadowVariable, getShadowVariable0, getSpaceOwner, getSpecialRendererOutput, getStubonly, getSubBindingAnnotationCount, getTemplate, getTemplateNames, getUuid, getWidgetAttributeNames, getWidgetClass, getWidgetListener, getWidgetListenerNames, getWidgetOverride, getWidgetOverrideNames, hasAttribute, hasAttribute, hasAttribute, hasAttributeOrFellow, hasBindingAnnotation, hasFellow, hasFellow, hasSubBindingAnnotation, initIndexCacheMap, invalidate, isChildable, isDisabledHostChanged, isInitialized, isInvalidated, isListenerAvailable, isVisible, onChildAdded, onChildRemoved, onParentChanged, onWrongValue, query, queryAll, redraw, redrawChildren, removeAttribute, removeAttribute, removeAttribute, removeCallback, removeEventListener, removeForward, removeForward, removeRedrawCallback, removeScopeListener, removeShadowRoot, render, render, render, renderPropertiesOnly, replace, response, response, response, service, setAttribute, setAttribute, setAttribute, setAuService, setAutag, setClientAttribute, setClientDataAttribute, setDefinition, setDefinition, setId, setPage, setPageBefore, setParent, setStubonly, setStubonly, setSubBindingAnnotationCount, setTemplate, setVisible, setVisibleDirectly, setWidgetClass, setWidgetListener, setWidgetOverride, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdateWidgetListener, smartUpdateWidgetOverride, toString, updateByClient, updateSubBindingAnnotationCount, willPassivate, willPassivate, willSerialize, willSerialize

    Methods inherited from class java.lang.Object

    equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Field Details

  • Constructor Details

    • Listbox

      public Listbox()

  • Method Details

    • getChildren

      public <T extends org.zkoss.zk.ui.Component> List<T> getChildren()
      Specified by:
      getChildren in interface org.zkoss.zk.ui.Component
      Overrides:
      getChildren in class org.zkoss.zk.ui.AbstractComponent

    • getListhead

      public Listhead getListhead()
      Returns Listhead belonging to this listbox, or null if no list headers at all.

    • getListfoot

      public Listfoot getListfoot()
      Returns Listfoot belonging to this listbox, or null if no list footers at all.

    • getFrozen

      public Frozen getFrozen()
      Returns the frozen child.
      Since:
      5.0.0

    • getHeads

      public Collection<org.zkoss.zk.ui.Component> getHeads()
      Returns a collection of heads, including getListhead() and auxiliary heads (Auxhead) (never null).
      Since:
      3.0.0

    • isCheckmark

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

      Default: false.

    • setCheckmark

      public void setCheckmark(boolean 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.

    • setInnerWidth

      public void setInnerWidth(String 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. If null, "100%" is assumed.
      Since:
      3.0.0

    • getInnerWidth

      public String getInnerWidth()
      Returns the inner width of this component. The inner width is the width of the inner table.

      Default: "100%"

      Since:
      3.0.0
      See Also:

    • isVflex

      public boolean isVflex()
      Returns whether to grow and shrink vertical to fit their given space, so called vertical flexibility.

      Note: this attribute is ignored if setRows(int) is specified

      Default: false.

    • setVflex

      public void setVflex(boolean vflex)
      Sets whether to grow and shrink vertical to fit their given space, so called vertical flexibility.

      Note: this attribute is ignored if setRows(int) is specified

    • setVflex

      public void setVflex(String flex)
      Overrides:
      setVflex in class org.zkoss.zk.ui.HtmlBasedComponent

    • isDisabled

      public boolean isDisabled()
      Returns whether it is disabled.

      Default: false.

    • setDisabled

      public void setDisabled(boolean disabled)
      Sets whether it is disabled.

      Note that it is only applied when mold is "select".

    • getRows

      public int getRows()
      Returns the rows. Zero means no limitation.

      Default: 0.

    • setRows

      public void setRows(int rows) throws org.zkoss.zk.ui.WrongValueException
      Sets the rows.

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

      Throws:
      org.zkoss.zk.ui.WrongValueException

    • setHeight

      public void setHeight(String height)
      Overrides:
      setHeight in class org.zkoss.zk.ui.HtmlBasedComponent

    • getSeltype

      public String getSeltype()
      Returns the seltype.

      Default: "single".

    • setSeltype

      public void setSeltype(String seltype) throws org.zkoss.zk.ui.WrongValueException
      Sets the seltype. Allowed values:single,multiple
      Throws:
      org.zkoss.zk.ui.WrongValueException

    • isMultiple

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

      Default: false.

    • setMultiple

      public void setMultiple(boolean 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)).

    • getMaxlength

      public int getMaxlength()
      Returns the maximal length of each item's label.

      It is meaningful only for the select mold.

    • setMaxlength

      public void setMaxlength(int maxlength)
      Sets the maximal length of each item's label.

      It is meaningful only for the select mold.

    • getName

      public String getName()
      Returns the name of this component.

      Default: null.

      The name is used only to work with "legacy" Web application that handles user's request by servlets. It works only with HTTP/HTML-based browsers. It doesn't work with other kind of clients.

      Don't use this method if your application is purely based on ZK's event-driven model.

    • setName

      public void setName(String name)
      Sets the name of this component.

      The name is used only to work with "legacy" Web application that handles user's request by servlets. It works only with HTTP/HTML-based browsers. It doesn't work with other kind of clients.

      Don't use this method if your application is purely based on ZK's event-driven model.

      Parameters:
      name - the name of this component.

    • setNonselectableTags

      public void setNonselectableTags(String tags)
      Sets a list of HTML tag names that shall not cause the list item being selected if they are clicked.

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

      Parameters:
      tags - a list of HTML tag names that will not cause the list item being selected if clicked. Specify null to use the default and "" to indicate none.
      Since:
      5.0.5

    • getNonselectableTags

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

      Refer to setNonselectableTags(java.lang.String) for details.

      Since:
      5.0.5

    • getItems

      public List<Listitem> getItems()
      Returns a live list of all Listitem. By live we mean you can add or remove them directly with the List interface. In other words, you could add or remove an item by manipulating the returned list directly.

    • getItemCount

      public int getItemCount()
      Returns the number of items.

    • getItemAtIndex

      public Listitem getItemAtIndex(int index)
      Returns the item at the specified index.

      Note: if live data is used (getModel() is not null), the returned item might NOT be loaded yet. To ensure it is loaded, you have to invoke renderItem(org.zkoss.zul.Listitem).

    • getIndexOfItem

      public int getIndexOfItem(Listitem item)
      Returns the index of the specified item, or -1 if not found.

    • getSelectedIndex

      public int getSelectedIndex()
      Returns the index of the selected item (-1 if no one is selected).

    • setSelectedIndex

      public void setSelectedIndex(int jsel)
      Deselects all of the currently selected items and selects the item with the given index.

    • selectItem

      public void selectItem(Listitem item)
      Deselects all of the currently selected items and selects the given item.

      It is the same as setSelectedItem(org.zkoss.zul.Listitem).

      Parameters:
      item - the item to select. If null, all items are deselected.

    • addItemToSelection

      public void addItemToSelection(Listitem item)
      Selects the given item, without deselecting any other items that are already selected..

      Notice that if you assign a model to a listbox (setModel(org.zkoss.zul.ListModel<?>)), you shall not invoke this method directly. Rather, use Selectable instead.

    • removeItemFromSelection

      public void removeItemFromSelection(Listitem item)
      Deselects the given item without deselecting other items.

      Notice that if you assign a model to a listbox (setModel(org.zkoss.zul.ListModel<?>)), you shall not invoke this method directly. Rather, use Selectable instead.

    • toggleItemSelection

      public void toggleItemSelection(Listitem item)
      If the specified item is selected, it is deselected. If it is not selected, it is selected. Other items in the list box that are selected are not affected, and retain their selected state.

    • clearSelection

      public void clearSelection()
      Clears the selection.

    • selectAll

      public void selectAll()
      Selects all items.

    • getSelectedItem

      public Listitem getSelectedItem()
      Returns the selected item.

      Note: if live data is used (getModel() is not null), the returned item might NOT be loaded yet. To ensure it is loaded, you have to invoke renderItem(org.zkoss.zul.Listitem).

    • setSelectedItem

      public void setSelectedItem(Listitem item)
      Deselects all of the currently selected items and selects the given item.

      It is the same as selectItem(org.zkoss.zul.Listitem).

    • setSelectedItems

      public void setSelectedItems(Set<Listitem> listItems)
      Selects the given listitems.
      Since:
      3.6.0

    • getSelectedItems

      public Set<Listitem> getSelectedItems()
      Returns all selected items.

      Note: if live data is used (getModel() is not null), the returned item might NOT be loaded yet. To ensure it is loaded, you have to invoke renderItem(org.zkoss.zul.Listitem).

    • getSelectedCount

      public int getSelectedCount()
      Returns the number of items being selected.

    • appendItem

      public Listitem appendItem(String label, String value)
      Appends an item.

      Note: if live data is used (getModel() is not null), the returned item might NOT be loaded yet. To ensure it is loaded, you have to invoke renderItem(org.zkoss.zul.Listitem).

    • removeItemAt

      public Listitem removeItemAt(int index)
      Removes the child item in the list box at the given index.

      Note: if live data is used (getModel() is not null), the returned item might NOT be loaded yet. To ensure it is loaded, you have to invoke renderItem(org.zkoss.zul.Listitem).

      Returns:
      the removed item.

    • getPaginal

      public Paginal getPaginal()
      Returns the paging controller, or null if not available. Note: the paging controller is used only if AbstractComponent.getMold() is "paging".

      If mold is "paging", this method never returns null, because a child paging controller is created automatically (if not specified by developers with setPaginal(org.zkoss.zul.ext.Paginal)).

      If a paging controller is specified (either by setPaginal(org.zkoss.zul.ext.Paginal), or by setMold(java.lang.String) with "paging"), the listbox will rely on the paging controller to handle long-content instead of scrolling.

    • setPaginal

      public void setPaginal(Paginal pgi)
      Specifies the paging controller. Note: the paging controller is used only if AbstractComponent.getMold() is "paging".

      It is OK, though without any effect, to specify a paging controller even if mold is not "paging".

      Parameters:
      pgi - the paging controller. If null and AbstractComponent.getMold() is "paging", a paging controller is created automatically as a child component (see getPagingChild()).

    • getPagingChild

      public Paging getPagingChild()
      Returns the child paging controller that is created automatically, or null if mold is not "paging", or the controller is specified externally by setPaginal(org.zkoss.zul.ext.Paginal).
      Since:
      3.0.7

    • pgi

      protected Paginal pgi()
      Description copied from class: MeshElement
      Returns the instance of the @{link Paginal}
      Specified by:
      pgi in class MeshElement

    • setActivePage

      public void setActivePage(Listitem item)
      Sets the active page in which the specified item is. The active page will become the page that contains the specified item.
      Parameters:
      item - the item to show. If the item is null or doesn't belong to this listbox, nothing happens.
      Since:
      3.0.4
      See Also:

    • setActivePage

      public void setActivePage(int pg) throws org.zkoss.zk.ui.WrongValueException
      Description copied from class: MeshElement
      Sets the active page (starting from 0).
      Overrides:
      setActivePage in class MeshElement
      Throws:
      org.zkoss.zk.ui.WrongValueException

    • getVisibleItemCount

      public int getVisibleItemCount()
      Returns the number of visible descendant Listitem.
      Since:
      3.5.1

    • getOddRowSclass

      public String getOddRowSclass()
      Returns the style class for the odd rows.

      Default: getZclass()-odd. (since 3.5.0)

      Since:
      3.0.0

    • setOddRowSclass

      public void setOddRowSclass(String scls)
      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.
      Since:
      3.0.0

    • getGroupCount

      public int getGroupCount()
      Returns the number of listgroup
      Since:
      3.5.0

    • getGroups

      public List<Listgroup> getGroups()
      Returns a list of all Listgroup.
      Since:
      3.5.0

    • hasGroup

      public boolean hasGroup()
      Returns whether listgroup exists.
      Since:
      3.5.0

    • beforeChildAdded

      public void beforeChildAdded(org.zkoss.zk.ui.Component newChild, org.zkoss.zk.ui.Component refChild)
      Specified by:
      beforeChildAdded in interface org.zkoss.zk.ui.sys.ComponentCtrl
      Overrides:
      beforeChildAdded in class org.zkoss.zk.ui.AbstractComponent

    • insertBefore

      public boolean insertBefore(org.zkoss.zk.ui.Component newChild, org.zkoss.zk.ui.Component refChild)
      Specified by:
      insertBefore in interface org.zkoss.zk.ui.Component
      Overrides:
      insertBefore in class org.zkoss.zk.ui.AbstractComponent

    • removeChild

      public boolean removeChild(org.zkoss.zk.ui.Component child)
      If the child is a listgroup, its listgroupfoot will be removed at the same time.
      Specified by:
      removeChild in interface org.zkoss.zk.ui.Component
      Overrides:
      removeChild in class org.zkoss.zk.ui.AbstractComponent

    • afterInsert

      protected void afterInsert(org.zkoss.zk.ui.Component comp)
      Callback if a list item has been inserted.

      Note: it won't be called if other kind of child is inserted.

      When this method is called, the index is correct.

      Default: invalidate if it is the paging mold and it affects the view of the active page.

      Since:
      3.0.5

    • beforeRemove

      protected void beforeRemove(org.zkoss.zk.ui.Component comp)
      Callback if a list item will be removed (not removed yet). Note: it won't be called if other kind of child is removed.

      Default: invalidate if it is the paging mold and it affects the view of the active page.

      Since:
      3.0.5

    • getModel

      public <T> ListModel<T> getModel()
      Returns the model associated with this list box, or null if this list box is not associated with any list data model.

      Note: if setModel(GroupsModel) was called with a groups model, this method returns an instance of ListModel encapsulating it.

      See Also:

    • getListModel

      public <T> ListModel<T> getListModel()
      Returns the list model associated with this list box, or null if this list box is associated with a GroupsModel or not associated with any list data model.
      Since:
      3.5.0
      See Also:

    • getGroupsModel

      public <D, G, F> GroupsModel<D,G,F> getGroupsModel()
      Returns the groups model associated with this list box, or null if this list box is associated with a ListModel or not associated with any list data model.
      Since:
      3.5.0
      See Also:

    • setModel

      public void setModel(ListModel<?> model)
      Sets the list model associated with this listbox. If a non-null model is assigned, no matter whether it is the same as the previous, it will always cause re-render.
      Parameters:
      model - the list model to associate, or null to dis-associate any previous model. If not null, it must implement Selectable.
      Throws:
      org.zkoss.zk.ui.UiException - if failed to initialize with the model
      See Also:

    • setModel

      public void setModel(GroupsModel<?,?,?> model)
      Sets the groups model associated with this list box. If a non-null model is assigned, no matter whether it is the same as the previous, it will always cause re-render.

      The groups model is used to represent a list of data with grouping.

      Parameters:
      model - the groups model to associate, or null to dis-associate any previous model.
      Throws:
      org.zkoss.zk.ui.UiException - if failed to initialize with the model
      Since:
      3.5.0
      See Also:

    • getItemRenderer

      public <T> ListitemRenderer<T> getItemRenderer()
      Returns the renderer to render each item, or null if the default renderer is used.

    • setItemRenderer

      public void setItemRenderer(ListitemRenderer<?> renderer)
      Sets the renderer which is used to render each item if getModel() is not null.

      Note: changing a render will not cause the listbox to re-render. If you want it to re-render, you could assign the same model again (i.e., setModel(getModel())), or fire an ListDataEvent event.

      Parameters:
      renderer - the renderer, or null to use the default.
      Throws:
      org.zkoss.zk.ui.UiException - if failed to initialize with the model

    • setItemRenderer

      public void setItemRenderer(String clsnm) throws ClassNotFoundException, NoSuchMethodException, IllegalAccessException, InstantiationException, InvocationTargetException
      Sets the renderer by use of a class name. It creates an instance automatically.
      Throws:
      ClassNotFoundException
      NoSuchMethodException
      IllegalAccessException
      InstantiationException
      InvocationTargetException

    • onInitRender

      public void onInitRender()
      Handles a private event, onInitRender. It is used only for implementation, and you rarely need to invoke it explicitly.

    • onPagingInitRender

      public void onPagingInitRender()
      Handles a private event, onPagingInitRender. It is used only for implementation, and you rarely need to invoke it explicitly.

    • renderItem

      public Listitem renderItem(Listitem li)
      Renders the specified Listitem if not loaded yet, with getItemRenderer().

      It does nothing if getModel() returns null. In other words, it is meaningful only if live data model is used.

      Returns:
      the list item being passed to this method
      See Also:

    • renderAll

      public void renderAll()
      Renders all Listitem if not loaded yet, with getItemRenderer().
      See Also:

    • renderItems

      public void renderItems(Set<? extends Listitem> items)
      Renders the given set of list items.

    • setMold

      public void setMold(String mold)
      Sets the mold to render this component.
      Specified by:
      setMold in interface org.zkoss.zk.ui.Component
      Overrides:
      setMold in class org.zkoss.zk.ui.AbstractComponent
      Parameters:
      mold - the mold. If null or empty, "default" is assumed. Allowed values: default, select, paging
      See Also:
      • ComponentDefinition

    • getEmptyMessage

      public String getEmptyMessage()
      Returns the message to display when there are no items
      Returns:
      String
      Since:
      5.0.7

    • setEmptyMessage

      public void setEmptyMessage(String emptyMessage)
      Sets the message to display when there are no items
      Parameters:
      emptyMessage -
      Since:
      5.0.7

    • getZclass

      public String getZclass()
      Overrides:
      getZclass in class org.zkoss.zk.ui.HtmlBasedComponent

    • onPageAttached

      public void onPageAttached(org.zkoss.zk.ui.Page newpage, org.zkoss.zk.ui.Page oldpage)
      Specified by:
      onPageAttached in interface org.zkoss.zk.ui.sys.ComponentCtrl
      Overrides:
      onPageAttached in class org.zkoss.zk.ui.AbstractComponent

    • onPageDetached

      public void onPageDetached(org.zkoss.zk.ui.Page page)
      Specified by:
      onPageDetached in interface org.zkoss.zk.ui.sys.ComponentCtrl
      Overrides:
      onPageDetached in class org.zkoss.zk.ui.AbstractComponent

    • clone

      public Object clone()
      Specified by:
      clone in interface org.zkoss.zk.ui.Component
      Overrides:
      clone in class XulElement

    • sessionWillPassivate

      public void sessionWillPassivate(org.zkoss.zk.ui.Page page)
      Specified by:
      sessionWillPassivate in interface org.zkoss.zk.ui.sys.ComponentCtrl
      Overrides:
      sessionWillPassivate in class org.zkoss.zk.ui.AbstractComponent

    • sessionDidActivate

      public void sessionDidActivate(org.zkoss.zk.ui.Page page)
      Specified by:
      sessionDidActivate in interface org.zkoss.zk.ui.sys.ComponentCtrl
      Overrides:
      sessionDidActivate in class org.zkoss.zk.ui.AbstractComponent

    • renderProperties

      protected void renderProperties(org.zkoss.zk.ui.sys.ContentRenderer renderer) throws IOException
      Overrides:
      renderProperties in class MeshElement
      Throws:
      IOException

    • getResponsive

      public String getResponsive()
      Returns the responsive policy.

      Default: null (unset — inherits from zk.xml org.zkoss.zul.listbox.responsive, then framework default of no responsive).

      Stacking behavior is provided by ZK EE (zkmax); CE stores the value only.

      Returns:
      the responsive policy, or null if not set.
      Since:
      11.0.0

    • setResponsive

      public void setResponsive(String responsive) throws org.zkoss.zk.ui.WrongValueException
      Sets the responsive policy.

      Supported values: "stacking", "none", or null (unset).

      • "stacking" — list items become vertical key-value cards when the container width falls below the breakpoint (EE only).
      • "none" — explicitly disables responsive, overriding any global setting.
      • null — inherits from the global library property.
      Parameters:
      responsive - the responsive policy
      Throws:
      org.zkoss.zk.ui.WrongValueException - if responsive is neither "stacking", "none", nor null.
      Since:
      11.0.0

    • getResponsiveColumns

      public String getResponsiveColumns()
      Returns the responsive columns token string.

      Default: null (unset — inherits from zk.xml org.zkoss.zul.listbox.responsive.columns, then framework default "sm-1 md-none" resolved by the client).

      Returns:
      the responsive columns token string, or null if not set.
      Since:
      11.0.0

    • setResponsiveColumns

      public void setResponsiveColumns(String columns)
      Sets the responsive columns token string for stacking mode.

      Breakpoint tokens separated by whitespace, where each token is <breakpoint>-<value> with breakpoint in {sm, md, lg, xl} and value either a positive integer (cards per row in stacking) 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. A value whose kept tokens are all none without an sm entry is discarded as a whole and the client falls back to its default cascade.

      Parameters:
      columns - the responsive columns token string
      Since:
      11.0.0

    • isAutohidePaging

      protected boolean isAutohidePaging()
      Specified by:
      isAutohidePaging in class MeshElement

    • isSelectOnHighlightDisabled

      protected boolean isSelectOnHighlightDisabled()

    • getPropertyAccess

      public org.zkoss.zk.ui.sys.PropertyAccess getPropertyAccess(String prop)
      Specified by:
      getPropertyAccess in interface org.zkoss.zk.ui.sys.ComponentCtrl
      Overrides:
      getPropertyAccess in class XulElement

    • service

      public void service(org.zkoss.zk.au.AuRequest request, boolean everError)
      Processes an AU request.

      Default: in addition to what are handled by HtmlBasedComponent.service(org.zkoss.zk.au.AuRequest, boolean), it also handles onSelect.

      Specified by:
      service in interface org.zkoss.zk.ui.sys.ComponentCtrl
      Overrides:
      service in class org.zkoss.zk.ui.HtmlBasedComponent
      Since:
      5.0.0

    • getExtraCtrl

      public Object getExtraCtrl()
      Specified by:
      getExtraCtrl in interface org.zkoss.zk.ui.sys.ComponentCtrl
      Overrides:
      getExtraCtrl in class org.zkoss.zk.ui.HtmlBasedComponent

    • setPageSize

      public void setPageSize(int pgsz) throws org.zkoss.zk.ui.WrongValueException
      Description copied from class: MeshElement
      Sets the page size, a.k.a., the number rows per page.
      Overrides:
      setPageSize in class MeshElement
      Throws:
      org.zkoss.zk.ui.WrongValueException

    • onAfterRender

      public void onAfterRender()

    • scrollToIndex

      public void scrollToIndex(int index)
      Scroll to the specified item by the given index.
      Parameters:
      index - the index of item
      Since:
      8.5.2

    • shallUpdateScrollPos

      public void shallUpdateScrollPos(boolean shallUpdateScrollPos)
      Sets whether to update the scroll position on init

      Default: false.

      Note: internal use only

      Parameters:
      shallUpdateScrollPos - whether update the scroll position on init
      Since:
      8.6.0