| org.zkoss.zul.impl.XulElement
 org.zkoss.zul.Listbox
| Listbox | | public class Listbox extends XulElement (Code) | | A listbox.
Event:
- 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
Listbox.setModel and then
the listbox will retrieve data via
ListModel.getElementAt 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 .
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 There are two ways to handle long content: scrolling and paging.
If
Listbox.getMold is "default", scrolling is used if
Listbox.setHeight is called and too much content to display.
If
Listbox.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
Listbox.setPageSize .
If paging is used, the page controller is either created automatically
or assigned explicity by
Listbox.setPaginal .
The paging controller specified explicitly by
Listbox.setPaginal 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
Listbox.getSclass : listbox.
To have a list box without stripping, you can specify a non-existent
style class to
Listbox.setOddRowSclass .
If you want to disable all striping, you can specify the style:
tr.odd {
background: white;
}
author:
tomyeh
See Also: ListModel
See Also: ListitemRenderer
See Also: ListitemRendererExt |
| Constructor Summary | |
| public | Listbox()
|
| Method Summary | |
| public void | addItemToSelection(Listitem item)
Selects the given item, without deselecting any other items
that are already selected.. | | public Listitem | appendItem(String label, String value)
Appends an item. | | public void | clearSelection()
Clears the selection. | | public Object | clone()
| | public Collection | getHeads()
Returns a collection of heads, including
Listbox.getListhead and auxiliary heads (
Auxhead ) (never null). | | public int | getIndexOfItem(Listitem item)
Returns the index of the specified item, or -1 if not found. | | public String | getInnerWidth()
Returns the inner width of this component. | | public Listitem | getItemAtIndex(int index)
Returns the item at the specified index. | | public int | getItemCount()
Returns the number of items. | | public ListitemRenderer | getItemRenderer()
Returns the renderer to render each item, or null if the default
renderer is used. | | public List | getItems()
Returns a live list of all
Listitem .
By live we mean you can add or remove them directly with
the List interface. | | public Listfoot | getListfoot()
Returns
Listfoot belonging to this listbox, or null
if no list footers at all. | | public Listhead | getListhead()
Returns
Listhead belonging to this listbox, or null
if no list headers at all. | | public int | getMaxlength()
Returns the maximal length of each item's label. | | public ListModel | getModel()
Returns the list model associated with this listbox, or null
if this listbox is not associated with any list data model. | | public String | getName()
Returns the name of this component.
Default: null.
The name is used only to work with "legacy" Web application that
handles user's request by servlets.
It works only with HTTP/HTML-based browsers. | | public String | getOddRowSclass()
Returns the style class for the odd rows. | | public String | getOuterAttrs()
| | public int | getPageSize()
Returns the page size, aka., the number items per page. | | public Paginal | getPaginal()
Returns the paging controller, or null if not available. | | 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
Listbox.setPaginal . | | public int | getPreloadSize()
Returns the number of items to preload when receiving
the rendering request from the client. | | public int | getRows()
Returns the rows. | | public int | getSelectedCount()
Returns the number of items being selected. | | public int | getSelectedIndex()
Returns the index of the selected item (-1 if no one is selected). | | public Listitem | getSelectedItem()
Returns the selected item. | | public Set | getSelectedItems()
Returns all selected items. | | public String | getSeltype()
Returns the seltype. | | public int | getTabindex()
Returns the tab order of this component. | | public int | getVisibleBegin()
Returns the index of the first visible child. | | public int | getVisibleEnd()
Returns the index of the last visible child. | | boolean | inPagingMold()
Returns whether this listbox is in the paging mold. | | final boolean | inSelectMold()
Returns whether the HTML's select tag is used. | | public boolean | insertBefore(Component newChild, Component refChild)
| | final public boolean | isCheckmark()
Returns whether the check mark shall be displayed in front
of each item. | | final public boolean | isDisabled()
Returns whether it is disabled. | | public boolean | isMultiple()
Returns whether multiple selections are allowed. | | final public boolean | isVflex()
Returns whether to grow and shrink vertical to fit their given space,
so called vertial flexibility. | | protected Object | newExtraCtrl()
| | public void | onChildAdded(Component child)
| | public void | onChildRemoved(Component child)
| | public void | onInitRender()
Handles a private event, onInitRender. | | public boolean | removeChild(Component child)
| | public Listitem | removeItemAt(int index)
Removes the child item in the list box at the given index. | | public void | removeItemFromSelection(Listitem item)
Deselects the given item without deselecting other items. | | public void | renderAll()
Renders all
Listitem if not loaded yet,
with
Listbox.getItemRenderer . | | public Listitem | renderItem(Listitem li)
Renders the specified
Listitem if not loaded yet,
with
Listbox.getItemRenderer . | | public void | renderItems(Set items)
| | public void | selectAll()
Selects all items. | | public void | selectItem(Listitem item)
Deselects all of the currently selected items and selects
the given item.
It is the same as
Listbox.setSelectedItem .
Parameters:
item - the item to select. | | 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
Listbox.isMultiple returns
true. | | public void | setDisabled(boolean disabled)
Sets whether it is disabled. | | public void | setInnerWidth(String innerWidth)
Sets the inner width of this component.
The inner width is the width of the inner table.
By default, it is 100%. | | public void | setItemRenderer(ListitemRenderer renderer)
Sets the renderer which is used to render each item
if
Listbox.getModel is not null. | | public void | setItemRenderer(String clsnm)
Sets the renderer by use of a class name. | | public void | setMaxlength(int maxlength)
Sets the maximal length of each item's label. | | public void | setModel(ListModel model)
Sets the list model associated with this listbox. | | public void | setMold(String mold)
| | public void | setMultiple(boolean multiple)
Sets whether multiple selections are allowed. | | public void | setName(String name)
Sets the name of this component.
The name is used only to work with "legacy" Web application that
handles user's request by servlets.
It works only with HTTP/HTML-based browsers. | | public void | setOddRowSclass(String scls)
Sets the style class for the odd rows. | | public void | setPageSize(int pgsz)
Sets the page size, aka., the number items per page. | | public void | setPaginal(Paginal pgi)
| | 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 (
Listbox.setModel and
not paging (
Listbox.getPaging .
Parameters:
sz - the number of items to preload. | | public void | setRows(int rows)
Sets the rows. | | public void | setSelectedIndex(int jsel)
Deselects all of the currently selected items and selects
the item with the given index. | | public void | setSelectedItem(Listitem item)
Deselects all of the currently selected items and selects
the given item. | | public void | setSeltype(String seltype)
Sets the seltype. | | public void | setTabindex(int tabindex)
Sets the tab order of this component. | | public void | setVflex(boolean vflex)
Sets whether to grow and shrink vertical to fit their given space,
so called vertial flexibility. | | public void | smartUpdate(String attr, String value)
| | public void | toggleItemSelection(Listitem item)
If the specified item is selected, it is deselected.
If it is not selected, it is selected. |
| addItemToSelection | | public void addItemToSelection(Listitem item)(Code) | | Selects the given item, without deselecting any other items
that are already selected..
|
| clearSelection | | public void clearSelection()(Code) | | Clears the selection.
|
| getIndexOfItem | | public int getIndexOfItem(Listitem item)(Code) | | Returns the index of the specified item, or -1 if not found.
|
| getInnerWidth | | public String getInnerWidth()(Code) | | Returns the inner width of this component.
The inner width is the width of the inner table.
Default: "100%"
See Also: Listbox.setInnerWidth
since:
3.0.0 |
| getItemAtIndex | | public Listitem getItemAtIndex(int index)(Code) | | Returns the item at the specified index.
Note: if live data is used (
Listbox.getModel is not null),
the returned item might NOT be loaded yet.
To ensure it is loaded, you have to invoke
Listbox.renderItem .
|
| getItemCount | | public int getItemCount()(Code) | | Returns the number of items.
|
| getItemRenderer | | public ListitemRenderer getItemRenderer()(Code) | | Returns the renderer to render each item, or null if the default
renderer is used.
|
| getItems | | public List getItems()(Code) | | 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.
|
| getListfoot | | public Listfoot getListfoot()(Code) | | Returns
Listfoot belonging to this listbox, or null
if no list footers at all.
|
| getListhead | | public Listhead getListhead()(Code) | | Returns
Listhead belonging to this listbox, or null
if no list headers at all.
|
| getMaxlength | | public int getMaxlength()(Code) | | Returns the maximal length of each item's label.
|
| getModel | | public ListModel getModel()(Code) | | Returns the list model associated with this listbox, or null
if this listbox is not associated with any list data model.
|
| getName | | public String getName()(Code) | | 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.
|
| getOddRowSclass | | public String getOddRowSclass()(Code) | | Returns the style class for the odd rows.
Default: odd.
since:
3.0.0 |
| getPageSize | | public int getPageSize()(Code) | | Returns the page size, aka., the number items per page.
exception:
IllegalStateException - if Listbox.getPaginal returns null,i.e., mold is not "paging" and no external controller is specified. |
| getPaginal | | public Paginal getPaginal()(Code) | | Returns the paging controller, or null if not available.
Note: the paging controller is used only if
Listbox.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
Listbox.setPaginal ).
If a paging controller is specified (either by
Listbox.setPaginal ,
or by
Listbox.setMold with "paging"),
the listbox will rely on the paging controller to handle long-content
instead of scrolling.
|
| getPaging | | public Paging getPaging()(Code) | | Returns the child paging controller that is created automatically,
or null if mold is not "paging", or the controller is specified externally
by
Listbox.setPaginal .
|
| getPreloadSize | | public int getPreloadSize()(Code) | | Returns the number of items to preload when receiving
the rendering request from the client.
Default: 7.
It is used only if live data (
Listbox.setModel and
not paging (
Listbox.getPaging .
since:
2.4.1 |
| getRows | | public int getRows()(Code) | | Returns the rows. Zero means no limitation.
Default: 0.
|
| getSelectedCount | | public int getSelectedCount()(Code) | | Returns the number of items being selected.
|
| getSelectedIndex | | public int getSelectedIndex()(Code) | | Returns the index of the selected item (-1 if no one is selected).
|
| getSelectedItem | | public Listitem getSelectedItem()(Code) | | Returns the selected item.
Note: if live data is used (
Listbox.getModel is not null),
the returned item might NOT be loaded yet.
To ensure it is loaded, you have to invoke
Listbox.renderItem .
|
| getSelectedItems | | public Set getSelectedItems()(Code) | | Returns all selected items.
Note: if live data is used (
Listbox.getModel is not null),
the returned item might NOT be loaded yet.
To ensure it is loaded, you have to invoke
Listbox.renderItem .
|
| getSeltype | | public String getSeltype()(Code) | | Returns the seltype.
Default: "single".
|
| getTabindex | | public int getTabindex()(Code) | | Returns the tab order of this component.
Currently, only the "select" mold supports this property.
Default: -1 (means the same as browser's default).
|
| getVisibleBegin | | public int getVisibleBegin()(Code) | | Returns the index of the first visible child.
Used only for component development, not for application developers.
|
| getVisibleEnd | | public int getVisibleEnd()(Code) | | Returns the index of the last visible child.
Used only for component development, not for application developers.
|
| inPagingMold | | boolean inPagingMold()(Code) | | Returns whether this listbox is in the paging mold.
|
| inSelectMold | | final boolean inSelectMold()(Code) | | Returns whether the HTML's select tag is used.
|
| isCheckmark | | final public boolean isCheckmark()(Code) | | Returns whether the check mark shall be displayed in front
of each item.
Default: false.
|
| isDisabled | | final public boolean isDisabled()(Code) | | Returns whether it is disabled.
Default: false.
|
| isMultiple | | public boolean isMultiple()(Code) | | Returns whether multiple selections are allowed.
Default: false.
|
| isVflex | | final public boolean isVflex()(Code) | | Returns whether to grow and shrink vertical to fit their given space,
so called vertial flexibility.
Note: this attribute is ignored if
Listbox.setRows is specified
Default: false.
|
| onInitRender | | public void onInitRender()(Code) | | Handles a private event, onInitRender. It is used only for
implementation, and you rarely need to invoke it explicitly.
|
| removeItemAt | | public Listitem removeItemAt(int index)(Code) | | Removes the child item in the list box at the given index.
Note: if live data is used (
Listbox.getModel is not null),
the returned item might NOT be loaded yet.
To ensure it is loaded, you have to invoke
Listbox.renderItem .
the removed item. |
| removeItemFromSelection | | public void removeItemFromSelection(Listitem item)(Code) | | Deselects the given item without deselecting other items.
|
| renderItems | | public void renderItems(Set items)(Code) | | |
| selectAll | | public void selectAll()(Code) | | Selects all items.
|
| selectItem | | public void selectItem(Listitem item)(Code) | | Deselects all of the currently selected items and selects
the given item.
It is the same as
Listbox.setSelectedItem .
Parameters:
item - the item to select. If null, all items are deselected. |
| setCheckmark | | public void setCheckmark(boolean checkmark)(Code) | | Sets whether the check mark shall be displayed in front
of each item.
The check mark is a checkbox if
Listbox.isMultiple returns
true. It is a radio button if
Listbox.isMultiple returns false.
|
| setDisabled | | public void setDisabled(boolean disabled)(Code) | | Sets whether it is disabled.
|
| setInnerWidth | | public void setInnerWidth(String innerWidth)(Code) | | 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 (
Listbox.getInnerWidth ),
and then restore them when re-creating this component.
Parameters:
innerWidth - the inner width. If null, "100%" is assumed.
since:
3.0.0 |
| setItemRenderer | | public void setItemRenderer(ListitemRenderer renderer)(Code) | | Sets the renderer which is used to render each item
if
Listbox.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.
exception:
UiException - if failed to initialize with the model |
| setMaxlength | | public void setMaxlength(int maxlength)(Code) | | Sets the maximal length of each item's label.
|
| setModel | | public void setModel(ListModel model)(Code) | | 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-associateany previous model.
exception:
UiException - if failed to initialize with the model |
| setMultiple | | public void setMultiple(boolean multiple)(Code) | | Sets whether multiple selections are allowed.
|
| setName | | public void setName(String name)(Code) | | 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. |
| setOddRowSclass | | public void setOddRowSclass(String scls)(Code) | | 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 |
| setPageSize | | public void setPageSize(int pgsz)(Code) | | Sets the page size, aka., the number items per page.
exception:
IllegalStateException - if Listbox.getPaginal returns null,i.e., mold is not "paging" and no external controller is specified. |
| setPreloadSize | | public void setPreloadSize(int sz)(Code) | | Sets the number of items to preload when receiving
the rendering request from the client.
It is used only if live data (
Listbox.setModel and
not paging (
Listbox.getPaging .
Parameters:
sz - the number of items to preload. If zero, no preloadat all.
exception:
UiException - if sz is negative
since:
2.4.1 |
| setSelectedIndex | | public void setSelectedIndex(int jsel)(Code) | | Deselects all of the currently selected items and selects
the item with the given index.
|
| setSelectedItem | | public void setSelectedItem(Listitem item)(Code) | | Deselects all of the currently selected items and selects
the given item.
It is the same as
Listbox.selectItem .
|
| setTabindex | | public void setTabindex(int tabindex) throws WrongValueException(Code) | | Sets the tab order of this component.
Currently, only the "select" mold supports this property.
|
| setVflex | | public void setVflex(boolean vflex)(Code) | | Sets whether to grow and shrink vertical to fit their given space,
so called vertial flexibility.
Note: this attribute is ignored if
Listbox.setRows is specified
|
| toggleItemSelection | | public void toggleItemSelection(Listitem item)(Code) | | 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.
|
|
|