org.zkoss.zul.api
Interface Listbox

All Superinterfaces:
java.lang.Cloneable, Component, HtmlBasedComponent, Paginated, Scope, java.io.Serializable, XulElement
All Known Implementing Classes:
Listbox

public interface Listbox
extends XulElement, Paginated

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 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 row by calling toString against the object returned by ListModel.getElementAt(int)

There are two ways to handle long content: scrolling and paging. If Component.getMold() is "default", scrolling is used if HtmlBasedComponent.setHeight(java.lang.String) is called and too much content to display. If Component.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.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).

Since:
3.5.2
Author:
tomyeh
See Also:
ListModel, ListitemRenderer, ListitemRendererExt

Field Summary
 
Fields inherited from interface org.zkoss.zk.ui.Component
APPLICATION_SCOPE, COMPONENT_SCOPE, DESKTOP_SCOPE, PAGE_SCOPE, REQUEST_SCOPE, SESSION_SCOPE, SPACE_SCOPE
 
Method Summary
 void addItemToSelectionApi(Listitem item)
          Selects the given item, without deselecting any other items that are already selected..
 Listitem appendItemApi(java.lang.String label, java.lang.String value)
          Appends an item.
 void clearSelection()
          Clears the selection.
 int getActivePage()
          Returns the active page (starting from 0).
 int getGroupCount()
          Returns the number of listgroup
 java.util.List getGroups()
          Returns a list of all Listgroup.
 GroupsModel 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 getHeads()
          Returns a collection of heads, including getListheadApi() and auxiliary heads (Auxhead) (never null).
 int getIndexOfItemApi(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 getItemAtIndexApi(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 getListfootApi()
          Returns Listfoot belonging to this listbox, or null if no list footers at all.
 Listhead getListheadApi()
          Returns Listhead belonging to this listbox, or null if no list headers at all.
 ListModel 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.
 ListModel 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 getOddRowSclass()
          Returns the style class for the odd rows.
 int getPageCount()
          Returns the number of pages.
 int getPageSize()
          Returns the page size, aka., the number items per page.
 Paginal getPaginal()
          Returns the paging controller, or null if not available.
 Paging getPagingChildApi()
          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 getSelectedItemApi()
          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 getVisibleItemCount()
          Returns the number of visible descendant Listitem.
 boolean hasGroup()
          Returns whether listgroup exists.
 boolean isFixedLayout()
          Deprecated. since 5.0.0, use !isSizedByContent() instead
 boolean isMultiple()
          Returns whether multiple selections are allowed.
 boolean isSizedByContent()
          Returns whether sizing listbox column width by its content.
 Listitem removeItemAtApi(int index)
          Removes the child item in the list box at the given index.
 void removeItemFromSelectionApi(Listitem item)
          Deselects the given item without deselecting other items.
 void renderAll()
          Renders all Listitem if not loaded yet, with getItemRenderer().
 Listitem renderItemApi(Listitem li)
          Renders the specified Listitem if not loaded yet, with getItemRenderer().
 void renderItems(java.util.Set items)
           
 void selectAll()
          Selects all items.
 void selectItemApi(Listitem item)
          Deselects all of the currently selected items and selects the given item.
 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 setFixedLayout(boolean fixedLayout)
          Deprecated. since 5.0.0, use 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 setMultiple(boolean multiple)
          Sets whether multiple selections are allowed.
 void setName(java.lang.String name)
          Sets the name of this component.
 void setOddRowSclass(java.lang.String scls)
          Sets the style class for the odd rows.
 void setPageSize(int pgsz)
          Sets the page size, aka., the number items per page.
 void setPaginal(Paginal pgi)
          Specifies the paging controller.
 void setPagingPosition(java.lang.String pagingPosition)
          Sets how to position the paging of listbox at the client screen.
 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 setSelectedItemApi(Listitem item)
          Deselects all of the currently selected items and selects the given item.
 void setSeltype(java.lang.String seltype)
          Sets the seltype.
 void setSizedByContent(boolean byContent)
          Sets whether sizing listbox column width by its content.
 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 toggleItemSelectionApi(Listitem item)
          If the specified item is selected, it is deselected.
 
Methods inherited from interface org.zkoss.zul.impl.api.XulElement
getAction, getContext, getCtrlKeys, getPopup, getTooltip, setAction, setContext, setContext, setCtrlKeys, setPopup, setPopup, setTooltip, setTooltip
 
Methods inherited from interface org.zkoss.zk.ui.api.HtmlBasedComponent
focus, getHeight, getLeft, getSclass, getStyle, getTooltiptext, getTop, getWidth, getZclass, getZindex, getZIndex, setDraggable, setDroppable, setFocus, setHeight, setLeft, setSclass, setStyle, setTooltiptext, setTop, setWidth, setZclass, setZindex, setZIndex
 
Methods inherited from interface org.zkoss.zk.ui.Component
addEventListener, addForward, addForward, addForward, addForward, appendChild, applyProperties, clone, containsVariable, detach, getAttribute, getAttribute, getAttributeOrFellow, getAttributes, getAttributes, getAuService, getChildren, getDefinition, getDesktop, getFellow, getFellow, getFellowIfAny, getFellowIfAny, getFellows, getFirstChild, getId, getLastChild, getListenerIterator, getMold, getNamespace, getNextSibling, getPage, getParent, getPreviousSibling, getRoot, getSpaceOwner, getUuid, getVariable, getWidgetClass, getWidgetListener, getWidgetListenerNames, getWidgetOverride, getWidgetOverrideNames, hasAttribute, hasAttribute, hasAttributeOrFellow, hasFellow, hasFellow, insertBefore, invalidate, isInvalidated, isListenerAvailable, isVisible, removeAttribute, removeAttribute, removeChild, removeEventListener, removeForward, removeForward, setAttribute, setAttribute, setAuService, setId, setMold, setPage, setPageBefore, setParent, setVariable, setVisible, setWidgetListener, setWidgetOverride, unsetVariable
 
Methods inherited from interface org.zkoss.zk.ui.ext.Scope
addScopeListener, getAttribute, hasAttribute, removeAttribute, removeScopeListener, setAttribute
 
Methods inherited from interface org.zkoss.zul.ext.Paginated
getPagingPosition
 

Method Detail

setSizedByContent

void setSizedByContent(boolean byContent)
Sets whether sizing listbox column width by its content. Default is false, i.e. the outline of grid is dependent on browser. It means, we don't calculate the width of each cell. If set to true, the outline will count on the content of body. In other words, the outline of grid will be like ZK version 2.4.1 that the header's width is only for reference.

You can also specify the "sized-by-content" attribute of component in lang-addon.xml directly, it will then take higher priority.

Parameters:
byContent -
Since:
5.0.0

isSizedByContent

boolean isSizedByContent()
Returns whether sizing listbox column width by its content. Default is false.

Note: if the "sized-by-content" attribute of component is specified, it's prior to the original value.

Since:
5.0.0
See Also:
setSizedByContent(boolean)

setFixedLayout

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

Sets the outline of listbox whether is fixed layout. If true, the outline of grid will be depended on browser. It means, we don't calculate the width of each cell. Otherwise, the outline will count on the content of body. In other words, the outline of grid is like ZK 2.4.1 version that the header's width is only for reference.

You can also specify the "fixed-layout" attribute of component in lang-addon.xml directly, it's a top priority.


isFixedLayout

boolean isFixedLayout()
Deprecated. since 5.0.0, use !isSizedByContent() instead

Returns the outline of listbox whether is fixed layout.

Default: false.

Note: if the "fixed-layout" attribute of component is specified, it's prior to the original value.


getListheadApi

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


getListfootApi

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


getHeads

java.util.Collection getHeads()
Returns a collection of heads, including getListheadApi() and auxiliary heads (Auxhead) (never null).


setCheckmark

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

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.

getInnerWidth

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

Default: "100%"

See Also:
setInnerWidth(java.lang.String)

setVflex

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


setDisabled

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


getTabindex

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

void setTabindex(int tabindex)
                 throws WrongValueException
Sets the tab order of this component.

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

Throws:
WrongValueException

getRows

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

Default: 0.


setRows

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

java.lang.String getSeltype()
Returns the seltype.

Default: "single".


setSeltype

void setSeltype(java.lang.String seltype)
                throws WrongValueException
Sets the seltype.

Throws:
WrongValueException

isMultiple

boolean isMultiple()
Returns whether multiple selections are allowed.

Default: false.


setMultiple

void setMultiple(boolean multiple)
Sets whether multiple selections are allowed.


getMaxlength

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


setMaxlength

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


getName

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

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.

getItems

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

int getItemCount()
Returns the number of items.


getItemAtIndexApi

Listitem getItemAtIndexApi(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 renderItemApi(org.zkoss.zul.api.Listitem).


getIndexOfItemApi

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


getSelectedIndex

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


setSelectedIndex

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


selectItemApi

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

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

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

addItemToSelectionApi

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


removeItemFromSelectionApi

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


toggleItemSelectionApi

void toggleItemSelectionApi(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

void clearSelection()
Clears the selection.


selectAll

void selectAll()
Selects all items.


getSelectedItemApi

Listitem getSelectedItemApi()
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 renderItemApi(org.zkoss.zul.api.Listitem).


setSelectedItemApi

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

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


getSelectedItems

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 renderItemApi(org.zkoss.zul.api.Listitem).


getSelectedCount

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


appendItemApi

Listitem appendItemApi(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 renderItemApi(org.zkoss.zul.api.Listitem).


removeItemAtApi

Listitem removeItemAtApi(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 renderItemApi(org.zkoss.zul.api.Listitem).

Returns:
the removed item.

setPagingPosition

void setPagingPosition(java.lang.String pagingPosition)
Sets how to position the paging of listbox at the client screen. It is meaningless if the mold is not in "paging".

Parameters:
pagingPosition - how to position. It can only be "bottom" (the default), or "top", or "both".

getPaginal

Paginal getPaginal()
Returns the paging controller, or null if not available. Note: the paging controller is used only if Component.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 Component.setMold(java.lang.String) with "paging"), the listbox will rely on the paging controller to handle long-content instead of scrolling.


setPaginal

void setPaginal(Paginal pgi)
Specifies the paging controller. Note: the paging controller is used only if Component.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 Component.getMold() is "paging", a paging controller is created automatically as a child component (see getPagingChildApi()).

getPagingChildApi

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

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

void setPageSize(int pgsz)
                 throws WrongValueException
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.
WrongValueException

getPageCount

int getPageCount()
Returns the number of pages. Note: there is at least one page even no item at all.


getActivePage

int getActivePage()
Returns the active page (starting from 0).


setActivePage

void setActivePage(int pg)
                   throws WrongValueException
Sets the active page (starting from 0).

Throws:
WrongValueException
See Also:
setActivePage(Listitem)

setActivePage

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.
See Also:
setActivePage(int)

getVisibleItemCount

int getVisibleItemCount()
Returns the number of visible descendant Listitem.


getOddRowSclass

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

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


setOddRowSclass

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.


getGroupCount

int getGroupCount()
Returns the number of listgroup


getGroups

java.util.List getGroups()
Returns a list of all Listgroup.


hasGroup

boolean hasGroup()
Returns whether listgroup exists.


getModel

ListModel 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

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

See Also:
setModel(ListModel)

getGroupsModel

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

See Also:
setModel(GroupsModel)

setModel

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

setModel

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
See Also:
setModel(ListModel), getGroupsModel()

getItemRenderer

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


setItemRenderer

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

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

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(ListModel) and not paging (getPagingChildApi().

Note: if the "pre-load-size" attribute of component is specified, it's


setPreloadSize

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(ListModel) and not paging (getPagingChildApi().

Parameters:
sz - the number of items to preload. If zero, no preload at all.
Throws:
UiException - if sz is negative

renderItemApi

Listitem renderItemApi(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

void renderAll()
Renders all Listitem if not loaded yet, with getItemRenderer().

See Also:
Listbox.renderItem(org.zkoss.zul.Listitem), renderItems(java.util.Set)

renderItems

void renderItems(java.util.Set items)


Copyright © 2005-2009 Potix Corporation. All Rights Reserved. SourceForge.net Logo