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

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, org.zkoss.zk.ui.Component, org.zkoss.zk.ui.sys.ComponentCtrl

public class Listbox
extends XulElement

A listbox.

Event:

1. org.zkoss.zk.ui.event.SelectEvent is sent when user changes the selection.

See Specification.

Besides creating Listitem programmingly, you could assign a data model (a ListModel instance) to a listbox via setModel(org.zkoss.zul.ListModel) 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 row by calling toString against the object returned by ListModel.getElementAt(int)

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 explicity 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 HtmlBasedComponent.getSclass(): listbox.

Author:

tomyeh

See Also:

ListModel, ListitemRenderer, ListitemRendererExt, Serialized Form

Nested Class Summary

protected class

Listbox.ExtraCtrl A utility class to implement AbstractComponent.getExtraCtrl().

Field Summary

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

RS_NO_DISPLAY, RS_NO_HEIGHT, RS_NO_WIDTH

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

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

Constructor Summary

Listbox()

Method Summary

void	addItemToSelection(Listitem item) Selects the given item, without deselecting any other items that are already selected..
Listitem	appendItem(java.lang.String label, java.lang.String value) Appends an item.
void	clearSelection() Clears the selection.
java.lang.Object	clone()
int	getIndexOfItem(Listitem item) Returns the index of the specified item, or -1 if not found.
Listitem	getItemAtIndex(int index) Returns the item at the specified index.
int	getItemCount() Returns the number of items.
ListitemRenderer	getItemRenderer() Returns the renderer to render each item, or null if the default renderer is used.
java.util.List	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.
int	getMaxlength() Returns the maximal length of each item's label.
ListModel	getModel() Returns the list model associated with this listbox, or null if this listbox is not associated with any list data model.
java.lang.String	getName() Returns the name of this component.
java.lang.String	getOuterAttrs()
int	getPageSize() Returns the page size, aka., the number items per page.
Paginal	getPaginal() Returns the paging controller, or null if not available.
Paging	getPaging() 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() Returns the number of items to preload when receiving the rendering request from the client.
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	getSelectedItems() Returns all selected items.
java.lang.String	getSeltype() Returns the seltype.
int	getTabindex() Returns the tab order of this component.
int	getVisibleBegin() Returns the index of the first visible child.
int	getVisibleEnd() Returns the index of the last visible child.
boolean	insertBefore(org.zkoss.zk.ui.Component newChild, org.zkoss.zk.ui.Component refChild)
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.
boolean	isVflex() Returns whether to grow and shrink vertical to fit their given space, so called vertial flexibility.
protected java.lang.Object	newExtraCtrl()
void	onChildAdded(org.zkoss.zk.ui.Component child)
void	onChildRemoved(org.zkoss.zk.ui.Component child)
void	onInitRender() Handles a private event, onInitRender.
void	onPaging() Called when the onPaging event is received (from getPaginal()).
boolean	removeChild(org.zkoss.zk.ui.Component child)
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 items)
void	selectAll() Selects all items.
void	selectItem(Listitem item) Deselects all of the currently selected items and selects the given item.
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	setHeight(java.lang.String height)
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(ListModel model) Sets the list model associated with this listbox.
void	setMold(java.lang.String mold)
void	setMultiple(boolean multiple) Sets whether multiple selections are allowed.
void	setName(java.lang.String name) Sets the name of this component.
void	setPageSize(int pgsz) Sets the page size, aka., the number items per page.
void	setPaginal(Paginal pgi)
void	setPreloadSize(int sz) Sets the number of items to preload when receiving the rendering request from the client.
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	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	smartUpdate(java.lang.String attr, java.lang.String value)
void	toggleItemSelection(Listitem item) If the specified item is selected, it is deselected.

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

getAction, getAllOnClickAttrs, getContext, getInnerAttrs, getPopup, getTooltip, setAction, setContext, setPopup, setTooltip

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

addEventListener, appendAsapAttr, focus, getDraggable, getDroppable, getHeight, getLeft, getRealStyle, getRealStyleFlags, getSclass, getStyle, getTooltiptext, getTop, getWidth, getZIndex, isAsapRequired, removeEventListener, setClass, setDraggable, setDroppable, setLeft, setSclass, setStyle, setTooltiptext, setTop, setWidth, setZIndex

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

addAnnotation, addAnnotation, addEventHandler, addSharedAnnotationMap, addSharedEventHandlerMap, appendChild, applyProperties, containsVariable, detach, equals, getAnnotatedProperties, getAnnotatedPropertiesBy, getAnnotation, getAnnotation, getAnnotations, getAnnotations, getAttribute, getAttribute, getAttributes, getAttributes, getChildren, getDefinition, getDesktop, getEventHandler, getExtraCtrl, getFellow, getFellowIfAny, getId, getListenerIterator, getMold, getMoldURI, getNamespace, getPage, getParent, getPropagatee, getRoot, getSpaceOwner, getUuid, getVariable, invalidate, isChildable, isListenerAvailable, isVisible, onDrawNewChild, onWrongValue, redraw, removeAttribute, removeAttribute, response, sessionDidActivate, sessionWillPassivate, setAttribute, setAttribute, setComponentDefinition, setId, setPage, setParent, setVariable, setVisible, smartUpdate, smartUpdate, toString, unsetVariable

Methods inherited from class java.lang.Object

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

Constructor Detail

Listbox

public Listbox()

Method Detail

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.

isCheckmark

public final 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.

isVflex

public final 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 final boolean isDisabled()

Returns whether it is disabled.

Default: false.

setDisabled

public void setDisabled(boolean disabled)

Sets whether it is disabled.

getTabindex

public int getTabindex()

Returns the tab order of this component.

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

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

setTabindex

public void setTabindex(int tabindex)
                 throws org.zkoss.zk.ui.WrongValueException

Sets the tab order of this component.

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

Throws:

org.zkoss.zk.ui.WrongValueException

getRows

public int getRows()

Returns the rows. Zero means no limitation.

Default: 0.

setRows

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

Sets the rows.

Note: if both setHeight(java.lang.String) is specified with non-empty, setRows(int) is ignored

Throws:

org.zkoss.zk.ui.WrongValueException

getSeltype

public java.lang.String getSeltype()

Returns the seltype.

Default: "single".

setSeltype

public void setSeltype(java.lang.String seltype)
                throws org.zkoss.zk.ui.WrongValueException

Sets the seltype.

Throws:

org.zkoss.zk.ui.WrongValueException

isMultiple

public boolean isMultiple()

Returns whether multiple selections are allowed.

Default: false.

setMultiple

public void setMultiple(boolean multiple)

Sets whether multiple selections are allowed.

getMaxlength

public int getMaxlength()

Returns the maximal length of each item's label.

setMaxlength

public void setMaxlength(int maxlength)

Sets the maximal length of each item's label.

getName

public java.lang.String getName()

Returns the name of this component.

Default: null.

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

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.

setName

public void setName(java.lang.String name)

Sets the name of this component.

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

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.

Parameters:

name - the name of this component.

getItems

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

removeItemFromSelection

public void removeItemFromSelection(Listitem item)

Deselects the given item without deselecting other items.

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

getSelectedItems

public java.util.Set 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)

onPaging

public void onPaging()

Called when the onPaging event is received (from getPaginal()).

Default: re-render, if live data, and invalidate().

getPaging

public Paging getPaging()

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

getPageSize

public int getPageSize()

Returns the page size, aka., the number items per page.

Throws:

java.lang.IllegalStateException - if getPaginal() returns null, i.e., mold is not "paging" and no external controller is specified.

setPageSize

public void setPageSize(int pgsz)

Sets the page size, aka., the number items per page.

Throws:

java.lang.IllegalStateException - if getPaginal() returns null, i.e., mold is not "paging" and no external controller is specified.

getVisibleBegin

public int getVisibleBegin()

Returns the index of the first visible child.

Used only for component development, not for application developers.

getVisibleEnd

public int getVisibleEnd()

Returns the index of the last visible child.

Used only for component development, not for application developers.

smartUpdate

public void smartUpdate(java.lang.String attr,
                        java.lang.String value)

Specified by:

smartUpdate in interface org.zkoss.zk.ui.Component

Overrides:

smartUpdate in class org.zkoss.zk.ui.AbstractComponent

onChildAdded

public void onChildAdded(org.zkoss.zk.ui.Component child)

Specified by:

onChildAdded in interface org.zkoss.zk.ui.Component

Overrides:

onChildAdded in class org.zkoss.zk.ui.AbstractComponent

onChildRemoved

public void onChildRemoved(org.zkoss.zk.ui.Component child)

Specified by:

onChildRemoved in interface org.zkoss.zk.ui.Component

Overrides:

onChildRemoved in class org.zkoss.zk.ui.AbstractComponent

insertBefore

public boolean insertBefore(org.zkoss.zk.ui.Component newChild,
                            org.zkoss.zk.ui.Component refChild)

Specified by:

insertBefore in interface org.zkoss.zk.ui.Component

Overrides:

insertBefore in class org.zkoss.zk.ui.AbstractComponent

removeChild

public boolean removeChild(org.zkoss.zk.ui.Component child)

Specified by:

removeChild in interface org.zkoss.zk.ui.Component

Overrides:

removeChild in class org.zkoss.zk.ui.AbstractComponent

getModel

public ListModel getModel()

Returns the list model associated with this listbox, or null if this listbox is not associated with any list data model.

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.

Throws:

org.zkoss.zk.ui.UiException - if failed to initialize with the model

getItemRenderer

public ListitemRenderer getItemRenderer()

Returns the renderer to render each item, or null if the default renderer is used.

setItemRenderer

public void setItemRenderer(ListitemRenderer renderer)

Sets the renderer which is used to render each item if getModel() is not null.

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

Parameters:

renderer - the renderer, or null to use the default.

Throws:

org.zkoss.zk.ui.UiException - if failed to initialize with the model

setItemRenderer

public void setItemRenderer(java.lang.String clsnm)
                     throws java.lang.ClassNotFoundException,
                            java.lang.NoSuchMethodException,
                            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.InstantiationException

java.lang.reflect.InvocationTargetException

getPreloadSize

public int getPreloadSize()

Returns the number of items to preload when receiving the rendering request from the client.

Default: 7.

It is used only if live data (setModel(org.zkoss.zul.ListModel) and not paging (getPaging().

Since:

2.4.1

setPreloadSize

public void setPreloadSize(int sz)

Sets the number of items to preload when receiving the rendering request from the client.

It is used only if live data (setModel(org.zkoss.zul.ListModel) and not paging (getPaging().

Parameters:

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

Throws:

org.zkoss.zk.ui.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.

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

setMold

public void setMold(java.lang.String mold)

Specified by:

setMold in interface org.zkoss.zk.ui.Component

Overrides:

setMold in class org.zkoss.zk.ui.AbstractComponent

setHeight

public void setHeight(java.lang.String height)

Overrides:

setHeight in class org.zkoss.zk.ui.HtmlBasedComponent

getOuterAttrs

public java.lang.String getOuterAttrs()

Overrides:

getOuterAttrs in class XulElement

clone

public java.lang.Object clone()

Specified by:

clone in interface org.zkoss.zk.ui.Component

Overrides:

clone in class org.zkoss.zk.ui.AbstractComponent

newExtraCtrl

protected java.lang.Object newExtraCtrl()

Overrides:

newExtraCtrl in class org.zkoss.zk.ui.HtmlBasedComponent