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:
    `java.io.Serializable`, `java.lang.Cloneable`, `Component`, `Scope`, `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 `Listitem`s 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 `Listitem`s are created and rendered in the Listbox if you turn the ROD on, there will be some limitations on accessing `Listitem`s. 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:
    `ListModel`, `ListitemRenderer`, `ListitemRendererExt`, Serialized Form

- - ### 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

      `AbstractComponent.ForwardInfo, AbstractComponent.TargetInfo`

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static java.lang.String` | `LOADING_MODEL` |
    `static java.lang.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

    All Methods Instance Methods Concrete Methods
    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​(Component comp)` | Callback if a list item has been inserted.
    `Listitem` | `appendItem​(java.lang.String label, java.lang.String value)` | Appends an item.
    `void` | `beforeChildAdded​(Component newChild, Component refChild)` | Default: does nothing.
    `protected void` | `beforeRemove​(Component comp)` | Callback if a list item will be removed (not removed yet).
    `void` | `clearSelection()` | Clears the selection.
    `java.lang.Object` | `clone()` | Clones the component.
    `<T extends Component> java.util.List<T>` | `getChildren()` | Returns a live list of children.
    `java.lang.String` | `getEmptyMessage()` | Returns the message to display when there are no items
    `java.lang.Object` | `getExtraCtrl()` | Returns the client control for this component.
    `Frozen` | `getFrozen()` | Returns the frozen child.
    `int` | `getGroupCount()` | Returns the number of listgroup
    `java.util.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.
    `java.util.Collection<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.
    `java.lang.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.
    `java.util.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.
    `java.lang.String` | `getName()` | Returns the name of this component.
    `java.lang.String` | `getNonselectableTags()` | Returns a list of HTML tag names that shall not cause the list item being selected if they are clicked.
    `java.lang.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)`.
    `PropertyAccess` | `getPropertyAccess​(java.lang.String prop)` | Returns the corresponding property access object from the given property name, if any.
    `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.
    `java.util.Set<Listitem>` | `getSelectedItems()` | Returns all selected items.
    `java.lang.String` | `getSeltype()` | Returns the seltype.
    `int` | `getVisibleItemCount()` | Returns the number of visible descendant `Listitem`.
    `java.lang.String` | `getZclass()` | Returns the ZK Cascading Style class for this component.
    `boolean` | `hasGroup()` | Returns whether listgroup exists.
    `boolean` | `insertBefore​(Component newChild, Component refChild)` | Inserts a child before the reference child.
    `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​(Page newpage, Page oldpage)` | Default: handles special event listeners.
    `void` | `onPageDetached​(Page page)` | Default: handles special event listeners.
    `void` | `onPagingInitRender()` | Handles a private event, onPagingInitRender.
    `protected Paginal` | `pgi()` | Returns the instance of the @{link Paginal}
    `boolean` | `removeChild​(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​(java.util.Set<? extends Listitem> items)` | Renders the given set of list items.
    `protected void` | `renderProperties​(ContentRenderer renderer)` | Renders the content of this component, excluding the enclosing tags and children.
    `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​(AuRequest request, boolean everError)` | Processes an AU request.
    `void` | `sessionDidActivate​(Page page)` | Notification that the session, which owns this component, has just been activated (a.k.a., deserialized).
    `void` | `sessionWillPassivate​(Page page)` | Notification that the session, which owns this component, is about to be passivated (a.k.a., serialized).
    `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​(java.lang.String emptyMessage)` | Sets the message to display when there are no items
    `void` | `setHeight​(java.lang.String height)` | Sets the height.
    `void` | `setInnerWidth​(java.lang.String innerWidth)` | Sets the inner width of this component.
    `void` | `setItemRenderer​(java.lang.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​(java.lang.String mold)` | Sets the mold to render this component.
    `void` | `setMultiple​(boolean multiple)` | Sets whether multiple selections are allowed.
    `void` | `setName​(java.lang.String name)` | Sets the name of this component.
    `void` | `setNonselectableTags​(java.lang.String tags)` | Sets a list of HTML tag names that shall not cause the list item being selected if they are clicked.
    `void` | `setOddRowSclass​(java.lang.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` | `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​(java.util.Set<Listitem> listItems)` | Selects the given listitems.
    `void` | `setSeltype​(java.lang.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​(java.lang.String flex)` | Sets vertical flexibility hint of this component.
    `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, 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, 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 Detail

    - #### LOADING_MODEL

          public static final java.lang.String LOADING_MODEL

      See Also:
        Constant Field Values

    - #### SYNCING_MODEL

          public static final java.lang.String SYNCING_MODEL

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Listbox

          public Listbox()

  - ### Method Detail

    - #### getChildren

          public <T extends Component> java.util.List<T> getChildren()

      Description copied from class: `AbstractComponent`
      Returns a live list of children. By live we mean the developer could add or remove a child by manipulating the returned list directly.

      Default: instantiates and returns an instance of `AbstractComponent.Children`.

      Specified by:
        `getChildren` in interface `Component`
      Overrides:
        `getChildren` in class `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 java.util.Collection<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​(java.lang.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 java.lang.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:
        `setInnerWidth(java.lang.String)`

    - #### 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​(java.lang.String flex)

      Description copied from class: `HtmlBasedComponent`
      Sets vertical flexibility hint of this component.

      Number flex indicates how this component's container distributes remaining empty space among its children vertically. Flexible component grow and shrink to fit their given space. Flexible components with larger flex values will be made larger than components with lower flex values, at the ratio determined by all flexible components. The actual flex value is not relevant unless there are other flexible components within the same container. Once the default sizes of components in a container are calculated, the remaining space in the container is divided among the flexible components, according to their flex ratios.

      Specify a flex value of negative value, 0, or "false" has the same effect as leaving the flex attribute out entirely. Specify a flex value of "true" has the same effect as a flex value of 1.

      Special flex hint, "min", indicates that the minimum space shall be given to this flexible component to enclose all of its children components. That is, the flexible component grow and shrink to fit its children components.

      Overrides:
        `setVflex` in class `HtmlBasedComponent`
      Parameters:
        `flex` - the vertical flex hint.
      See Also:
        `HtmlBasedComponent.setHflex(java.lang.String)`, `HtmlBasedComponent.getVflex()`

    - #### 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 WrongValueException

      Sets the rows.

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

      Throws:
        `WrongValueException`

    - #### setHeight

          public void setHeight​(java.lang.String height)

      Description copied from class: `HtmlBasedComponent`
      Sets the height. If null, the best fit is used.
      Overrides:
        `setHeight` in class `HtmlBasedComponent`

    - #### getSeltype

          public java.lang.String getSeltype()

      Returns the seltype.

      Default: "single".

    - #### setSeltype

          public void setSeltype​(java.lang.String seltype)
                          throws WrongValueException

      Sets the seltype. Allowed values:single,multiple
      Throws:
        `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 java.lang.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​(java.lang.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​(java.lang.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 java.lang.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 java.util.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​(java.util.Set<Listitem> listItems)

      Selects the given listitems.
      Since:
        3.6.0

    - #### getSelectedItems

          public java.util.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​(java.lang.String label,
                                     java.lang.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(int)`

    - #### setActivePage

          public void setActivePage​(int pg)
                             throws WrongValueException

      Description copied from class: `MeshElement`
      Sets the active page (starting from 0).
      Overrides:
        `setActivePage` in class `MeshElement`
      Throws:
        `WrongValueException`

    - #### getVisibleItemCount

          public int getVisibleItemCount()

      Returns the number of visible descendant `Listitem`.
      Since:
        3.5.1

    - #### getOddRowSclass

          public java.lang.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​(java.lang.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 java.util.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​(Component newChild,
                                       Component refChild)

      Description copied from class: `AbstractComponent`
      Default: does nothing.
      Specified by:
        `beforeChildAdded` in interface `ComponentCtrl`
      Overrides:
        `beforeChildAdded` in class `AbstractComponent`
      Parameters:
        `newChild` - the child to be added (never null).
        `refChild` - another child component that the new child will be inserted before it. If null, the new child will be the last child.
      See Also:
        `ComponentCtrl.beforeChildAdded(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component)`

    - #### insertBefore

          public boolean insertBefore​(Component newChild,
                                      Component refChild)

      Description copied from interface: `Component`
      Inserts a child before the reference child.

      You could use `Component.setParent(org.zkoss.zk.ui.Component)` or `Component.appendChild(org.zkoss.zk.ui.Component)` instead of this method, unless you want to control where to put the child.

      Note: `Component.setParent(org.zkoss.zk.ui.Component)` always calls back `Component.insertBefore(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component)` and/or `Component.removeChild(org.zkoss.zk.ui.Component)`, while `Component.insertBefore(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component)` and `Component.removeChild(org.zkoss.zk.ui.Component)` always calls back `Component.setParent(org.zkoss.zk.ui.Component)`, if the parent is changed. Thus, you don't need to override both `Component.insertBefore(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component)` and `Component.setParent(org.zkoss.zk.ui.Component)`, if you want to customize the behavior.

      If you would like to monitor if a component is attached or detached from a page, you could register a desktop listener implementing `UiLifeCycle`.

      Specified by:
        `insertBefore` in interface `Component`
      Overrides:
        `insertBefore` in class `AbstractComponent`
      Parameters:
        `newChild` - the new child to be inserted.
        `refChild` - the child before which you want the new child being inserted. If null, the new child is append to the end.
      Returns:
        true if newChild is added successfully or moved; false if it already has the specified child and the order doesn't change.

    - #### removeChild

          public boolean removeChild​(Component child)

      If the child is a listgroup, its listgroupfoot will be removed at the same time.
      Specified by:
        `removeChild` in interface `Component`
      Overrides:
        `removeChild` in class `AbstractComponent`
      Returns:
        true if child is removed successfully; false if it doesn't have the specified child

    - #### afterInsert

          protected void afterInsert​(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​(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:
        `setModel(ListModel)`, `setModel(GroupsModel)`

    - #### 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:
        `setModel(ListModel)`

    - #### 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(GroupsModel)`

    - #### 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:
        `UiException` - if failed to initialize with the model
      See Also:
        `getListModel()`, `setModel(GroupsModel)`

    - #### 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:
        `UiException` - if failed to initialize with the model
      Since:
        3.5.0
      See Also:
        `setModel(ListModel)`, `getGroupsModel()`

    - #### 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:
        `UiException` - if failed to initialize with the model

    - #### setItemRenderer

          public void setItemRenderer​(java.lang.String clsnm)
                               throws java.lang.ClassNotFoundException,
                                      java.lang.NoSuchMethodException,
                                      java.lang.IllegalAccessException,
                                      java.lang.InstantiationException,
                                      java.lang.reflect.InvocationTargetException

      Sets the renderer by use of a class name. It creates an instance automatically.
      Throws:
        `java.lang.ClassNotFoundException`
        `java.lang.NoSuchMethodException`
        `java.lang.IllegalAccessException`
        `java.lang.InstantiationException`
        `java.lang.reflect.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:
        `renderItems(java.util.Set<? extends org.zkoss.zul.Listitem>)`, `renderAll()`

    - #### renderAll

          public void renderAll()

      Renders all `Listitem` if not loaded yet, with `getItemRenderer()`.
      See Also:
        `renderItem(org.zkoss.zul.Listitem)`, `renderItems(java.util.Set<? extends org.zkoss.zul.Listitem>)`

    - #### renderItems

          public void renderItems​(java.util.Set<? extends Listitem> items)

      Renders the given set of list items.

    - #### setMold

          public void setMold​(java.lang.String mold)

      Sets the mold to render this component.
      Specified by:
        `setMold` in interface `Component`
      Overrides:
        `setMold` in class `AbstractComponent`
      Parameters:
        `mold` - the mold. If null or empty, "default" is assumed. Allowed values: default, select, paging
      See Also:
        `ComponentDefinition`

    - #### getEmptyMessage

          public java.lang.String getEmptyMessage()

      Returns the message to display when there are no items
      Returns:
        String
      Since:
        5.0.7

    - #### setEmptyMessage

          public void setEmptyMessage​(java.lang.String emptyMessage)

      Sets the message to display when there are no items
      Parameters:
        `emptyMessage` -
      Since:
        5.0.7

    - #### getZclass

          public java.lang.String getZclass()

      Description copied from class: `HtmlBasedComponent`
      Returns the ZK Cascading Style class for this component. It usually depends on the implementation of the mold (`AbstractComponent.getMold()`).

      Default: null (the default value depends on element).

      `HtmlBasedComponent.setZclass(java.lang.String)`) will completely replace the default style of a component. In other words, the default style of a component is associated with the default value of `HtmlBasedComponent.getZclass()`. Once it is changed, the default style won't be applied at all. If you want to perform small adjustments, use `HtmlBasedComponent.setSclass(java.lang.String)` instead.

      Overrides:
        `getZclass` in class `HtmlBasedComponent`
      See Also:
        `HtmlBasedComponent.getSclass()`

    - #### onPageAttached

          public void onPageAttached​(Page newpage,
                                     Page oldpage)

      Description copied from class: `AbstractComponent`
      Default: handles special event listeners.
      Specified by:
        `onPageAttached` in interface `ComponentCtrl`
      Overrides:
        `onPageAttached` in class `AbstractComponent`
      Parameters:
        `newpage` - the new page (never null).
        `oldpage` - the previous page, if any, or null if it didn't belong to any page.
      See Also:
        `ComponentCtrl.onPageAttached(org.zkoss.zk.ui.Page, org.zkoss.zk.ui.Page)`

    - #### onPageDetached

          public void onPageDetached​(Page page)

      Description copied from class: `AbstractComponent`
      Default: handles special event listeners.
      Specified by:
        `onPageDetached` in interface `ComponentCtrl`
      Overrides:
        `onPageDetached` in class `AbstractComponent`
      Parameters:
        `page` - the previous page (never null)
      See Also:
        `ComponentCtrl.onPageDetached(org.zkoss.zk.ui.Page)`

    - #### clone

          public java.lang.Object clone()

      Description copied from interface: `Component`
      Clones the component. All of its children and descendants are cloned. Also, ID are preserved.
      Specified by:
        `clone` in interface `Component`
      Overrides:
        `clone` in class `XulElement`
      Returns:
        the new component. Notice that it doesn't belong to any page, nor desktop. It doesn't have a parent, either.

    - #### sessionWillPassivate

          public void sessionWillPassivate​(Page page)

      Description copied from interface: `ComponentCtrl`
      Notification that the session, which owns this component, is about to be passivated (a.k.a., serialized).

      Note: only root components are notified by this method.

      Specified by:
        `sessionWillPassivate` in interface `ComponentCtrl`
      Overrides:
        `sessionWillPassivate` in class `AbstractComponent`

    - #### sessionDidActivate

          public void sessionDidActivate​(Page page)

      Description copied from interface: `ComponentCtrl`
      Notification that the session, which owns this component, has just been activated (a.k.a., deserialized).

      Note: only root components are notified by this method.

      Specified by:
        `sessionDidActivate` in interface `ComponentCtrl`
      Overrides:
        `sessionDidActivate` in class `AbstractComponent`

    - #### renderProperties

          protected void renderProperties​(ContentRenderer renderer)
                                   throws java.io.IOException

      Description copied from class: `HtmlBasedComponent`
      Renders the content of this component, excluding the enclosing tags and children.

      See also ZK Client-side Reference: Property Rendering

      Overrides:
        `renderProperties` in class `MeshElement`
      Throws:
        `java.io.IOException`

    - #### isAutohidePaging

          protected boolean isAutohidePaging()

      Specified by:
        `isAutohidePaging` in class `MeshElement`

    - #### isSelectOnHighlightDisabled

          protected boolean isSelectOnHighlightDisabled()

    - #### getPropertyAccess

          public PropertyAccess getPropertyAccess​(java.lang.String prop)

      Description copied from interface: `ComponentCtrl`
      Returns the corresponding property access object from the given property name, if any.
      Specified by:
        `getPropertyAccess` in interface `ComponentCtrl`
      Overrides:
        `getPropertyAccess` in class `XulElement`
      Parameters:
        `prop` - the name of the property
      Returns:
        null it means not to support for the property name.

    - #### service

          public void service​(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 `ComponentCtrl`
      Overrides:
        `service` in class `HtmlBasedComponent`
        `everError` - whether any error ever occurred before processing this request.
      Since:
        5.0.0
      See Also:
        `AbstractComponent.setAuService(org.zkoss.zk.au.AuService)`

    - #### getExtraCtrl

          public java.lang.Object getExtraCtrl()

      Description copied from class: `HtmlBasedComponent`
      Returns the client control for this component. It is used only by component developers.

      Default: creates an instance of `HtmlBasedComponent.ExtraCtrl`.

      Specified by:
        `getExtraCtrl` in interface `ComponentCtrl`
      Overrides:
        `getExtraCtrl` in class `HtmlBasedComponent`
      Returns:
        null if no special handling required. If the component requires some special controls, it could return an object that implements one or several interfaces in the org.zkoss.zk.ui.ext.render package. For example, `Cropper`.
      See Also:
        `ComponentCtrl.getExtraCtrl()`

    - #### setPageSize

          public void setPageSize​(int pgsz)
                           throws WrongValueException

      Description copied from class: `MeshElement`
      Sets the page size, a.k.a., the number rows per page.
      Overrides:
        `setPageSize` in class `MeshElement`
      Throws:
        `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