Comboboxes"

From Documentation
m (Created page with '{{ZKDevelopersGuidePageHeader}} Components: <tt>combobox</tt> and <tt>comboitem</tt>. A combobox is a special text box which embeds a drop-down list. Using comboboxes, users ar…')
 
m (correct highlight (via JWB))
 
(2 intermediate revisions by one other user not shown)
Line 1: Line 1:
 
{{ZKDevelopersGuidePageHeader}}
 
{{ZKDevelopersGuidePageHeader}}
  
Components: <tt>combobox</tt> and <tt>comboitem</tt>.
+
__TOC__
 +
 
 +
Components: <code>combobox</code> and <code>comboitem</code>.
  
 
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.
 
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.
Line 17: Line 19:
 
</source>
 
</source>
  
'''Mouseless Entry<tt>combobox'''</tt>
+
'''Mouseless Entry<code>combobox'''</code>
  
* <tt>Alt+DOWN</tt> to pop up the list.
+
* <code>Alt+DOWN</code> to pop up the list.
* <tt>Alt+UP</tt> or <tt>ESC</tt> to close the list.
+
* <code>Alt+UP</code> or <code>ESC</code> to close the list.
* <tt>UP</tt> and <tt>DOWN</tt> to change the selection of the items from the list.
+
* <code>UP</code> and <code>DOWN</code> to change the selection of the items from the list.
  
 
=== The autodrop Property ===
 
=== The autodrop Property ===
Line 27: Line 29:
 
[[Image:FormAndInput_8.png]]
 
[[Image:FormAndInput_8.png]]
  
By default, the drop-down list won't be opened until user clicks the button, or presses <tt>Alt+DOWN</tt>. However, you could set the <tt>autodrop</tt> 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.
+
By default, the drop-down list won't be opened until user clicks the button, or presses <code>Alt+DOWN</code>. However, you could set the <code>autodrop</code> 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.
  
 
<source lang="xml" >
 
<source lang="xml" >
Line 51: Line 53:
 
[[Image:FormAndInput_9.png]]
 
[[Image:FormAndInput_9.png]]
  
Akin to other components that support images, you are able to use the <tt>setImageContent</tt> method to assign a dynamically generated image to the <tt>comboitem</tt> component. Please refer to the '''Image''' section for details.
+
Akin to other components that support images, you are able to use the <code>setImageContent</code> method to assign a dynamically generated image to the <code>comboitem</code> component. Please refer to the '''Image''' section for details.
  
 
=== The onOpen Event ===
 
=== The onOpen Event ===
The <tt>onOpen</tt> 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 <tt>fulfill</tt> attribute as shown below.
+
The <code>onOpen</code> 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 <code>fulfill</code> attribute as shown below.
  
 
[[Image:FormAndInput_10.png]]
 
[[Image:FormAndInput_10.png]]
Line 68: Line 70:
 
</source>
 
</source>
  
Alternatively, you can listen to the <tt>onOpen</tt> event and prepare the drop-down list or change it dynamically as demonstrated below.  
+
Alternatively, you can listen to the <code>onOpen</code> event and prepare the drop-down list or change it dynamically as demonstrated below.  
  
 
<source lang="xml" >
 
<source lang="xml" >
Line 87: Line 89:
 
</source>
 
</source>
  
The <tt>appendItem</tt> method is equivalent to creating a combo item and then setting the combobox as its parent.
+
The <code>appendItem</code> method is equivalent to creating a combo item and then setting the combobox as its parent.
  
 
=== The onChanging Event ===
 
=== The onChanging Event ===
Since a combobox is also a text box, you are also able to listen to an <tt>onChanging</tt> event. By listening to this event, you can manipulate the drop-down list as demonstrated by Google Suggests<ref name="ftn42">http://www.google.com/webhp?complete=1&hl=en</ref>. This feature is sometimes called auto-complete.
+
Since a combobox is also a text box, you are also able to listen to an <code>onChanging</code> event. By listening to this event, you can manipulate the drop-down list as demonstrated by Google Suggests<ref name="ftn42">http://www.google.com/webhp?complete=1&hl=en</ref>. This feature is sometimes called auto-complete.
  
 
As illustrated below, you can populate the drop-down list based on what user is entering.
 
As illustrated below, you can populate the drop-down list based on what user is entering.
Line 115: Line 117:
 
</source>
 
</source>
  
Notice that, when the <tt>onChanging</tt> event is received, the content of the combobox has not changed. Therefore, you cannot use the <tt>value</tt> property of the combobox. Instead, you should use the <tt>value</tt> property of the event (<tt>org.zkoss.zk.ui.event.InputEvent</tt>).
+
Notice that, when the <code>onChanging</code> event is received, the content of the combobox has not changed. Therefore, you cannot use the <code>value</code> property of the combobox. Instead, you should use the <code>value</code> property of the event (<javadoc>org.zkoss.zk.ui.event.InputEvent</javadoc>).
 +
 
 +
=== Notes ===
 +
 
 +
<references />
  
 
{{ ZKDevelopersGuidePageFooter}}
 
{{ ZKDevelopersGuidePageFooter}}

Latest revision as of 10:41, 19 January 2022

Stop.png 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.

FormAndInput 7.png

 
<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

FormAndInput 8.png

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>

FormAndInput 9.png

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.

FormAndInput 10.png

<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[1]. 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 (InputEvent).

Notes



Last Update : 2022/01/19

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