Comboboxes

This documentation is for an older version of ZK. For the latest one, please click here.

Components: combobox and comboitem.

A combobox is a special text box which embeds a drop-down list. Using comboboxes, users are allowed to select items from a drop-down list, in addition to entering text manually.

 
<zk>
	<combobox>
	    <comboitem label="Simple and Rich"/>
	    <comboitem label="Cool!"/>
	    <comboitem label="Ajax and RIA"/>
	</combobox>
</zk>

Mouseless Entrycombobox

• Alt+DOWN to pop up the list.
• Alt+UP or ESC to close the list.
• UP and DOWN to change the selection of the items from the list.

The autodrop Property

By default, the drop-down list won't be opened until user clicks the button, or presses Alt+DOWN. However, you could set the autodrop property to true, meaning as soon as the user types a character the drop-down list will be opened. This is helpful for novice users, but it might be annoying for experienced users.

<combobox autodrop="true"/>

The description Property

You are able add a description to each combo item to make it more descriptive or assign an image to every item.

<zk>
	<combobox>
	    <comboitem label="Simple and Rich" image="/img/coffee.gif"
	     description="The simplest way to make Web applications rich"/>
	    <comboitem label="Cool!" image="/img/corner.gif"
	     description="The coolest technology"/>
	    <comboitem label="Ajax and RIA" image="/img/cubfirs.gif"
	     description="Rich Internet Application by Ajax"/>
	</combobox>
</zk>

Akin to other components that support images, you are able to use the setImageContent method to assign a dynamically generated image to the comboitem component. Please refer to the Image section for details.

The onOpen Event

The onOpen event is sent to the application when a user opens the drop-down list. To defer the creation of combo items, you can use the fulfill attribute as shown below.

<zk>
	<combobox fulfill="onOpen">
	    <comboitem label="Simple and Rich"/>
	    <comboitem label="Cool!"/>
	    <comboitem label="Ajax and RIA"/>
	</combobox>	
</zk>

Alternatively, you can listen to the onOpen event and prepare the drop-down list or change it dynamically as demonstrated below.

<zk>
	<zscript>
		void prepare() 
		{
			if (combo.getItemCount() == 0) 
			{
				combo.appendItem("Simple and Rich");
				combo.appendItem("Cool!");
				combo.appendItem("Ajax and RIA");
			}
		}
	</zscript>
	<combobox id="combo" onOpen="prepare()" />		
</zk>

The appendItem method is equivalent to creating a combo item and then setting the combobox as its parent.

The onChanging Event

Since a combobox is also a text box, you are also able to listen to an onChanging event. By listening to this event, you can manipulate the drop-down list as demonstrated by Google Suggests. This feature is sometimes called auto-complete.

As illustrated below, you can populate the drop-down list based on what user is entering.

<zk>
	<zscript>
	     void suggest() 
	     {
	         combo.getItems().clear();
	         if (event.value.startsWith("A")) {
	             combo.appendItem("Ace");
	             combo.appendItem("Ajax");
	             combo.appendItem("Apple");
	         } else if (event.value.startsWith("B")) {
	             combo.appendItem("Best");
	             combo.appendItem("Blog");
	         }
	     }
	</zscript>
	
	<combobox id="combo" autodrop="true" onChanging="suggest()"/>
</zk>

Notice that, when the onChanging event is received, the content of the combobox has not changed. Therefore, you cannot use the value property of the combobox. Instead, you should use the value property of the event (org.zkoss.zk.ui.event.InputEvent).