Event:
See Specification.
Besides creating {@link Listitem} programmingly, you could assign a datamodel (a {@link ListModel} or {@link GroupsModel} instance) to a listbox via{@link #setModel(ListModel)} or {@link #setModel(GroupsModel)} and then thelistbox will retrieve data via {@link ListModel#getElementAt} when necessary.
Besides assign a list model, you could assign a renderer (a {@link ListitemRenderer} instance) to a listbox, such that the listbox willuse this renderer to render the data returned by {@link 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 {@link ListModel#getElementAt}[Since 5.0.4]
To retrieve what are selected in Listbox with a {@link Selectable} {@link ListModel}, you shall use {@link Selectable#getSelection} to get what is currently selected object in {@link ListModel} rather than using {@link Listbox#getSelectedItems}. That is, you shall operate on the item of the {@link ListModel} rather than on the {@link Listitem} of the {@link Listbox} if you use the {@link Selectable} {@link ListModel}.
Set selection = ((Selectable)getModel()).getSelection();
There are two ways to handle long content: scrolling and paging. If {@link #getMold} is "default", scrolling is used if {@link #setHeight} iscalled and too much content to display. If {@link #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 {@link #setPageSize}.
If paging is used, the page controller is either created automatically or assigned explicitly by {@link #setPaginal}. The paging controller specified explicitly by {@link #setPaginal} is called the external page controller. Itis 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 {@link #getZclass}: z-listbox.(since 3.5.0)
To have a list box without stripping, you can specify a non-existent style class to {@link #setOddRowSclass}.
When used in a clustering environment, you have to make {@link ListitemRenderer} ({@link #setItemRenderer}) and {@link ListModel} ({@link #setModel}) either serializable or re-assign them when {@link #sessionDidActivate} is called.
For huge data, you can turn on Listbox's ROD to request ZK engine to load from {@link ListModel} only the required data chunk and create only the required{@link Listitem}s 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 {@link 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 {@link #setHeight(String)}, {@link #setVflex(String)}, or {@link #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 {@link Listitem}s are created and rendered in the Listbox if you turn the ROD on, there will be some limitations on accessing {@link Listitem}s. For example, if you call
Listitem itemAt100 = (Listitem) getItemAtIndex(100);
The {@link 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 {@link 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 {@link ListModel} rather than on the {@link Listitem} of the {@link Listbox} if you use the {@link ListModel} and ROD.
@author tomyeh @see ListModel @see ListitemRenderer @see ListitemRendererExt
|
|
|
|
|
|
|
|
|
|