Listbox

From Documentation

Listbox

Employment/Purpose

Components: listbox, listitem, listcell, listhead and listheader.

A list box is used to display a number of items in a list. The user may select an item from the list.


Example

ZKComRef Listbox Example.png


 <window title="listbox demo" border="normal">
         <listbox id="box" width="250px">
             <listhead sizable="true">
                 <listheader label="name" sort="auto"/>
                 <listheader label="gender" sort="auto"/>
             </listhead>
             <listitem>
                 <listcell label="Mary"/>
                 <listcell label="FEMALE"/>
             </listitem>
             <listitem>
                 <listcell label="John"/>
                 <listcell label="MALE"/>
             </listitem>
             <listitem>
                 <listcell label="Jane"/>
                 <listcell label="FEMALE"/>
             </listitem>
             <listitem>
                 <listcell label="Henry"/>
                 <listcell label="MALE"/>
             </listitem>
             <listfoot >
                 <listfooter><label value="This is footer1"/></listfooter>
                 <listfooter><label value="This is footer2"/></listfooter>
             </listfoot>
         </listbox>        
 </window>

Listbox has two molds: default and select. If the select mold is used, the HTML's SELECT tag is generated instead.

Listbox onAfterRender.png

<zk>
	<zscript><![CDATA[
		ListModelList lm = new ListModelList(Arrays.asList(new String[] { "David",
				"Thomas", "Steven" }));
	]]></zscript>
	
	<listbox width="300px" model="${lm}" onAfterRender="self.setSelectedIndex(2)"/>
</zk>

Autopaging

When using the paging mold and vflex, you could also turn on autopaging (Listbox.setAutopaging(boolean)) such that the page size will be adjusted automatically based on the available space.

Nonselectable tags

By default, when an user clicks on a BUTTON, INPUT, TEXTAREA or A tag, the selection state of the item won't be changed. For example, when an user clicks the textbox in the following example, the selection state of the item won't be changed (only the textbox gains the focus).

<listitem>
  <listcell><textbox/></listcell>

Sometimes it is not intuitive, such as using with inplace editing (InputElement.isInplace()). If you want to have more control of whether to select an item, you could specify a list of tags in the nonselectableTags property (Listbox.setNonselectableTags(String)). For example, if you want to select the item, no matter what tag the user clicks, you could specify an empty string as follows.

<listbox nonselectableTags="">
    <listitem><listcell><textbox/></listcell></listitem>
    <listitem><listcell><button label="button"/></listcell></listitem>
    <listitem><listcell><h:input xmlns:h="native"/></listcell></listitem>
    <listitem><listcell><datebox/></listcell></listitem>
</listbox>

If you only want to ignore BUTTON only, you could specify nonselectableTags="button".

Deselect others when clicking an item with checkmark

If a listbox's checkmark (Listbox.isCheckmark()) is enabled, the selection will be toggled when an user clicks an item. In other words, all other items will remain the same.

If you prefer to deselect all other items and select the item being clicked (which the behavior of ZK 5.0.4 and earlier), you could specify true to this library property called org.zkoss.zul.listbox.checkmarkDeselectOthers.

Supported events

Name
Event Type
onPaging
PagingEvent

Description: Notifies one of the pages of a multi-page component is

selected by the user.

onSelect
SelectEvent

Description: Notifies one that the user has selected a new item in the list box

onAfterRender
onAfterRender

Description: Notifies one that the model's data has been rendered.

Supported Children

 Listitem,  Listhead,  Listfoot

Use cases

Version Description Example Location
     

Version History

Version Date Content
5.0.2 May 2010 Support the autopaging
5.0.4 July 2010 Support onAfterRender event



Last Update : 2010/10/06

Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License.