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)

See Specification.

Besides creating Listitem programmingly, 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 HtmlBasedComponent.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 MeshElement.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 HtmlBasedComponent.setHeight(String),HtmlBasedComponent.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.

        
                org.zkoss.zul.listbox.rod
                true
        
 

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:

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()).

Author:

tomyeh

See Also:

ListModel, ListitemRenderer, ListitemRendererExt, Serialized Form

Nested Class Summary

protected class	Listbox.Children
protected class	Listbox.ExtraCtrl A utility class to implement HtmlBasedComponent.getExtraCtrl().

Field Summary

static java.lang.String	LOADING_MODEL
static java.lang.String	SYNCING_MODEL

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

CE_BUSY_IGNORE, CE_DUPLICATE_IGNORE, CE_IMPORTANT, CE_NON_DEFERRABLE, CE_REPEAT_IGNORE

Constructor Summary

Listbox()

Method Summary

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.
java.util.List<Component>	getChildren() Returns a live list of children.
java.lang.String	getEmptyMessage()
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).
int	getPreloadSize() Deprecated. As of release 5.0.8, use custom attributes (org.zkoss.zul.listbox.preloadSize) instead. Returns the number of items to preload when receiving the rendering request from the client. Default: 50. (Since 6.0.1) It is used only if live data (setModel(ListModel) and not paging (getPagingChild(). Note: if the "pre-load-size" attribute of component is specified, it's prior to the original value.(@since 3.0.4)
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	getTabindex() Returns the tab order of this component.
int	getVisibleItemCount() Returns the number of visible descendant Listitem.
java.lang.String	getZclass() Returns the ZK Cascading Style class(es) for this component.
boolean	hasGroup() Returns whether listgroup exists.
boolean	insertBefore(Component newChild, Component refChild) Inserts a child before the reference child.
boolean	isCheckmark() Returns whether the check mark shall be displayed in front of each item.
boolean	isDisabled() Returns whether it is disabled.
boolean	isFixedLayout() Deprecated. since 5.0.0, use !MeshElement.isSizedByContent() instead
boolean	isMultiple() Returns whether multiple selections are allowed.
boolean	isVflex() Returns whether to grow and shrink vertical to fit their given space, so called vertial flexibility.
void	onInitRender() Handles a private event, onInitRender.
void	onPageAttached(Page newpage, Page oldpage) 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	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 (aka., deserialized).
void	sessionWillPassivate(Page page) Notification that the session, which owns this component, is about to be passivated (aka., serialized).
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)
void	setFixedLayout(boolean fixedLayout) Deprecated. since 5.0.0, use MeshElement.setSizedByContent(boolean)(!fixedLayout) instead
void	setInnerWidth(java.lang.String innerWidth) Sets the inner width of this component.
void	setItemRenderer(ListitemRenderer<?> renderer) Sets the renderer which is used to render each item if getModel() is not null.
void	setItemRenderer(java.lang.String clsnm) Sets the renderer by use of a class name.
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	setPaginal(Paginal pgi)
void	setPreloadSize(int sz) Deprecated. As of release 5.0.8, use custom attributes (org.zkoss.zul.listbox.preloadSize) instead. Sets 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().
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 listItems) Selects the given listitems.
void	setSeltype(java.lang.String seltype) Sets the seltype.
void	setTabindex(int tabindex) Sets the tab order of this component.
void	setVflex(boolean vflex) Sets whether to grow and shrink vertical to fit their given space, so called vertial flexibility.
void	toggleItemSelection(Listitem item) If the specified item is selected, it is deselected.

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

getActivePage, getPageCount, getPageSize, getPagingPosition, getSpan, isAutopaging, isSizedByContent, isSpan, setActivePage, setAutopaging, setPageSize, setPagingPosition, setSizedByContent, setSpan, setSpan

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

getContext, getCtrlKeys, getPopup, getTooltip, setContext, setContext, setCtrlKeys, setPopup, setPopup, setTooltip, setTooltip

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

focus, getAction, getDraggable, getDroppable, getHeight, getHflex, getLeft, getRenderdefer, getSclass, getStyle, getTooltiptext, getTop, getVflex, getWidth, getZindex, getZIndex, setAction, setClass, setDraggable, setDroppable, setFocus, setHeight, setHeightDirectly, setHflex, setHflexDirectly, setLeft, setLeftDirectly, setRenderdefer, setSclass, setStyle, setTooltiptext, setTop, setTopDirectly, setVflex, setWidth, setWidthDirectly, setZclass, setZindex, setZIndex, setZIndexDirectly

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

addAnnotation, addAnnotation, addClientEvent, addEventHandler, addEventListener, addEventListener, addForward, addForward, addForward, addForward, addMoved, addScopeListener, addSharedEventHandlerMap, appendChild, applyProperties, beforeChildRemoved, beforeParentChanged, detach, didActivate, didActivate, didDeserialize, didDeserialize, disableClientUpdate, equals, getAnnotatedProperties, getAnnotatedPropertiesBy, getAnnotation, getAnnotation, getAnnotations, getAnnotations, getAnnotations, getAttribute, getAttribute, getAttribute, getAttributeOrFellow, getAttributes, getAttributes, getAuService, getAutag, getClientEvents, getDefaultMold, getDefinition, getDesktop, getEventHandler, getEventHandlerNames, getEventListenerMap, getEventListeners, getFellow, getFellow, getFellowIfAny, getFellowIfAny, getFellows, getFirstChild, getId, getLastChild, getListenerIterator, getMold, getNextSibling, getPage, getParent, getPreviousSibling, getRoot, getSpaceOwner, getStubonly, getTemplate, getTemplateNames, getUuid, getWidgetAttribute, getWidgetAttributeNames, getWidgetClass, getWidgetListener, getWidgetListenerNames, getWidgetOverride, getWidgetOverrideNames, hasAttribute, hasAttribute, hasAttribute, hasAttributeOrFellow, hasFellow, hasFellow, invalidate, isChildable, isInvalidated, isListenerAvailable, isVisible, onChildAdded, onChildRemoved, onPageDetached, onWrongValue, query, queryAll, redraw, redrawChildren, removeAttribute, removeAttribute, removeAttribute, removeEventListener, removeForward, removeForward, removeScopeListener, render, render, render, replace, response, response, response, service, setAttribute, setAttribute, setAttribute, setAuService, setAutag, setDefinition, setDefinition, setId, setPage, setPageBefore, setParent, setStubonly, setStubonly, setTemplate, setVisible, setVisibleDirectly, setWidgetAttribute, setWidgetClass, setWidgetListener, setWidgetOverride, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdateWidgetListener, smartUpdateWidgetOverride, toString, updateByClient, willPassivate, willPassivate, willSerialize, willSerialize

Methods inherited from class java.lang.Object

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 java.util.List<Component> 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

setFixedLayout

public void setFixedLayout(boolean fixedLayout)

Deprecated. since 5.0.0, use MeshElement.setSizedByContent(boolean)(!fixedLayout) instead

Parameters:

fixedLayout - true to outline this listbox by browser

isFixedLayout

public boolean isFixedLayout()

Deprecated. since 5.0.0, use !MeshElement.isSizedByContent() instead

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 vertial 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 vertial flexibility.

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

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".

getTabindex

public int getTabindex()

Returns the tab order of this component.

Currently, only the "select" mold supports this property.

Default: 0 (means the same as browser's default).

setTabindex

public void setTabindex(int tabindex)
                 throws WrongValueException

Sets the tab order of this component.

Currently, only the "select" mold supports this property.

Throws:

WrongValueException

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: if both HtmlBasedComponent.setHeight(java.lang.String) is specified with non-empty, setRows(int) is ignored

Throws:

WrongValueException

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 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 automcatically (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)

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:

MeshElement.setActivePage(int)

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

getPreloadSize

public int getPreloadSize()

Deprecated. As of release 5.0.8, use custom attributes (org.zkoss.zul.listbox.preloadSize) instead. Returns the number of items to preload when receiving the rendering request from the client.

Default: 50. (Since 6.0.1)

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

Note: if the "pre-load-size" attribute of component is specified, it's prior to the original value.(@since 3.0.4)

Since:

2.4.1

setPreloadSize

public void setPreloadSize(int sz)

Deprecated. As of release 5.0.8, use custom attributes (org.zkoss.zul.listbox.preloadSize) instead. Sets 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().

Parameters:

sz - the number of items to preload. If zero, no preload at all.

Throws:

UiException - if sz is negative

Since:

2.4.1

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), 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)

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()

setEmptyMessage

public void setEmptyMessage(java.lang.String emptyMessage)

getZclass

public java.lang.String getZclass()

Description copied from class: HtmlBasedComponent

Returns the ZK Cascading Style class(es) for this component. It usually depends on the implementation of the mold (@{link #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)

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 (aka., 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 (aka., 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

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()