Combobox"

From Documentation
Line 56: Line 56:
 
== Autocomplete by ListSubModel ==
 
== Autocomplete by ListSubModel ==
  
To separate the data from the view (combobox) better, we could implement a list model with <javadoc type="interface">org.zkoss.zul.ListSubModel</javadoc>. ZK provides an utility, <javadoc>org.zkoss.zul.ListModels</javadoc>, to convert an instance of <javadoc>org.zkoss.zul.ListModel</javadoc> to another instance that also implements <javadoc type="interface">org.zkoss.zul.ListSubModel</javadoc>. For example
+
To separate the data from the view (combobox) better, we could implement a list model with <javadoc type="interface">org.zkoss.zul.ListSubModel</javadoc>. ZK provides a set of utilities in <javadoc>org.zkoss.zul.ListModels</javadoc> to convert an instance of <javadoc>org.zkoss.zul.ListModel</javadoc> to another instance that proxies the original list model and implements <javadoc type="interface">org.zkoss.zul.ListSubModel</javadoc>. For example,
  
 
<source lang="xml">
 
<source lang="xml">
Line 80: Line 80:
  
 
<blockquote>
 
<blockquote>
---
+
----
 +
'''Note''': Passing an instance of <javadoc>org.zkoss.zul.ListModelList</javadoc> directly to a combobox will show up all items in the list model, since it doesn't implement <javadoc>org.zkoss.zul.ListSubModel</javadoc>.
 +
 
 
'''Note''': Unlike <javadoc>org.zkoss.zul.ListModelList</javadoc> and others, <javadoc>org.zkoss.zul.SimpleListModel</javadoc> implements <javadoc type="interface">org.zkoss.zul.ListSubModel</javadoc> by default. You can use <javadoc>org.zkoss.zul.SimpleListModel</javadoc> directly but it handles only an array of data.
 
'''Note''': Unlike <javadoc>org.zkoss.zul.ListModelList</javadoc> and others, <javadoc>org.zkoss.zul.SimpleListModel</javadoc> implements <javadoc type="interface">org.zkoss.zul.ListSubModel</javadoc> by default. You can use <javadoc>org.zkoss.zul.SimpleListModel</javadoc> directly but it handles only an array of data.
 
</blockquote>
 
</blockquote>

Revision as of 11:07, 25 August 2010

Combobox

Employment/Purpose

Components: combobox and comboitem.

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

Example

ZKComRef Combobox Example.PNG

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

Combobox onAfterRender.png

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

Autocomplete

Autocomplete in a Brute-force Way

The straightforward way to implement the autocomplete feature is to listen the onChanging event. For example,

<combobox>
  <attribute name="onChaging"><![CDATA[
  self.getChildren().clear(); //remove all children
  for (String value: getMatched(event.getValue())
    self.appendChild(new Comboitem(value));
  ]]></attribute>
</combobox>

where we assume getMatched() is an application-specific method that returns a collection of matched values.

Autocomplete by ListSubModel

To separate the data from the view (combobox) better, we could implement a list model with ListSubModel. ZK provides a set of utilities in ListModels to convert an instance of ListModel to another instance that proxies the original list model and implements ListSubModel. For example,

<combobox id="combo" apply="MyAutoComplete">

then in MyAutoComplete.java, you could have

public class MyAutoComplete extends GenericForwardComposer {
    Combobox combo;
    public void afterCompose() {
        super.afterCompose();
        combo.setModel(ListModels.toListSubModel(new ListModelList(getAllItems())));
    }
    List getAllItems() {
        //return all items
    }
}

By default, it shows the first 15 items that matches the value entered by the user. If you want to have a different value or a different comparator to find out matched items, you could invoke ListModels.toListSubModel(ListModel, Comparator, int) instead.


Note: Passing an instance of ListModelList directly to a combobox will show up all items in the list model, since it doesn't implement ListSubModel.

Note: Unlike ListModelList and others, SimpleListModel implements ListSubModel by default. You can use SimpleListModel directly but it handles only an array of data.

Autodrop

If you prefer the combobox to drop down the list when the user types a character, you could specify the autodrop attribute as follows.

<combobox autodrop="true"/>

If you prefer to drop down the list when gaining the focus, you could provide a client-side listener as follows.

<combobox w:onfocus="this.open()" xmlns:w="client"/>

Supported events

Name
Event Type
onChange
Event: InputEvent

Denotes the content of an input component has been modified by the user.


onChanging
Event: InputEvent

Denotes that user is changing the content of an input component. Notice that the component's content (at the server) won't be changed until onChange is received.

Thus, you have to invoke the getValue method in the InputEvent class to retrieve the temporary value.

onSelect
Event: SelectEvent

Represents an event cause by user's the list selection is changed at the client.

onSelection
Event: SelectionEvent

Denotes that user is selecting a portion of the text of an input component. You can retrieve the start and end position of the selected text by use of the getStart and getEnd methods.

onOpen
Event: OpenEvent

Denotes user has opened or closed a component. Note: unlike onClose, this event is only a notification. The client sends this event after opening or closing the component.

It is useful to implement load-on-demand by listening to the onOpen event, and creating components when the first time the component is opened.


onFocus
Event: Event

Denotes when a component gets the focus.

onBlur
Event: Event

Denotes when a component loses the focus.

onCreate
Event: CreateEvent

It's used to make the combobox do some action after it has been created. For example you can make it 'ReadOnly' ( onCreate="self.setReadonly(true);" ), 'Disabled' ( onCreate="self.setDisabled(true);" ) or even 'Select' a value from the combobox ( onCreate="self.setSelectedIndex(0);" ) .

onAfterRender
onAfterRender

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

Supported Children

Comboitem

Use cases

Version Description Example Location
     

Version History

Version Date Content
5.0.4 July, 2010 Combobox supports Selectable if it is implemented with the specified ListModel.
5.0.4 July 2010 Support onAfterRender event



Last Update : 2010/08/25

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