A listbox.
Event:
-
org.zkoss.zk.ui.event.SelectEvent is sent when user changes the
selection.
- onAfterRender is sent when the model's data has been rendered.(since 5.0.4)
- onCheckSelectAll is sent when user click on selectAll checkbox.(since 6.5.5)
See Specification.
Besides creating
Listitem programmatically, you could assign a data
model (a
ListModel or
GroupsModel instance) to a listbox via
#setModel(ListModel) or
#setModel(GroupsModel) and then the
listbox will retrieve data via
ListModel#getElementAt 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 Listitem by calling toString against the object returned by
ListModel#getElementAt
To retrieve what are selected in Listbox with a
SelectableListModel, you shall use
Selectable#getSelection to get what
is currently selected object in
ListModel rather than using
Listbox#getSelectedItems. That is, you shall operate on the item of
the
ListModel rather than on the
Listitem of the
Listboxif 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.
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
#getMold is "default", scrolling is used if
#setHeight is
called and too much content to display. If
#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.
If paging is used, the page controller is either created automatically or
assigned explicitly by
#setPaginal. The paging controller specified
explicitly by
#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
#getZclass: z-listbox.(since 3.5.0)
To have a list box without stripping, you can specify a non-existent style
class to
#setOddRowSclass.
Clustering and Serialization
When used in a clustering environment, you have to make
ListitemRenderer (
#setItemRenderer) and
ListModel (
#setModel) either serializable or re-assign them when
#sessionDidActivate 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
#setHeight(String),
#setVflex(String),
or
#setRows(int) of the Listbox to make ROD works.
You can turn on/off ROD for all Listboxes in the application or only
for a specific Listbox. To turn on ROD for all Listboxes in the application,
you have to specify the Library Property "org.zkoss.zul.listbox.rod" to
"true" in WEB-INF/zk.xml. If you did not specify the Library Property,
default is false.
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
Listitemin your application if you turn the ROD on because Listitems might be removed
later. Basically, you shall operate on the item of the
ListModelrather 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:
-
#setModel is called and
Listheader#setSortDirection is set.
-
Listheader#setSortDirection is called.
- Model receives
ListDataEvent and
Listheader#setSortDirection is set.
If you want to ignore sort when receiving
ListDataEvent,
you can specifies the value as "ignore.change".
Notice that you could specify this attribute in any of its ancestor's attributes.
It will be inherited.
org.zkoss.zul.listbox.groupSelect
Specifies whether Listgroups under this Listbox are selectable. Notice that
you could specify this attribute in any of its ancestor's attributes. It will
be inherited. Default value is false.
org.zkoss.zul.listbox.preloadSize.(since 5.0.8)
Specifies the number of items to preload when receiving
the rendering request from the client.
It is used only if live data (
#setModel(ListModel) and
not paging (
#getPagingChild).
org.zkoss.zul.listbox.initRodSize.(since 5.0.8)
Specifies the number of items rendered when the Listbox first render.
It is used only if live data (
#setModel(ListModel) and not paging
(
#getPagingChild).
org.zkoss.zul.listbox.selectOnHighlight.disabled.(since 7.0.4)
Sets whether to disable select functionality when highlighting text
content with mouse dragging or not.