Bandbox"

From Documentation
(4 intermediate revisions by 2 users not shown)
Line 8: Line 8:
  
 
= Employment/Purpose =
 
= Employment/Purpose =
A bandbox is a special text box that embeds a customizable popup window (aka., a dropdown window). Like comboboxes, a bandbox  consists of an input box and a popup window. The popup window is opened automatically, when users presses Alt+DOWN or clicks the magnifier button.  
+
A bandbox is a special text box that embeds a customizable popup window (aka., a dropdown window). Like comboboxes, a bandbox  consists of an input box and a popup window. The popup window is opened automatically, when a user presses Alt+DOWN or clicks the magnifier button.  
  
 
Unlike comboboxes, the popup window of a bandbox could be anything. It is designed to give developers the maximal flexibility. A typical use is to represent the popup window as a search dialog.
 
Unlike comboboxes, the popup window of a bandbox could be anything. It is designed to give developers the maximal flexibility. A typical use is to represent the popup window as a search dialog.
Line 50: Line 50:
 
=Mouseless Entry bandbox=
 
=Mouseless Entry bandbox=
  
* <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.
  
 
=Properties=
 
=Properties=
Line 67: Line 67:
 
[[Image:ZKComRef_Bandbox_Autodrop.PNG]]
 
[[Image:ZKComRef_Bandbox_Autodrop.PNG]]
  
By default, the popup window won't be opened until user clicks the button, or presses <tt>Alt+DOWN</tt> on the keyboard. However, you can set the <tt>autodrop</tt> property to true and as soon as the user types a character the popup will be opened. This is helpful for novice users, but it might be annoying for experienced users.
+
By default, the popup window won't be opened until user clicks the button, or presses <code>Alt+DOWN</code> on the keyboard. However, you can set the <code>autodrop</code> property to true and as soon as the user types a character the popup will be opened. This is helpful for novice users, but it might be annoying for experienced users.
  
 
<source lang="xml" >
 
<source lang="xml" >
Line 80: Line 80:
  
 
== The onOpen Event ==
 
== The onOpen Event ==
If the user opens the popup window the <tt>onOpen</tt> event is sent to the application. By using the <tt>fulfill</tt> attribute with the <tt>onOpen</tt> value as shown below, you can defer the creation of the popup window.
+
If the user opens the popup window the <code>onOpen</code> event is sent to the application. By using the <code>fulfill</code> attribute with the <code>onOpen</code> value as shown below, you can defer the creation of the popup window.
  
 
<source lang="xml" >
 
<source lang="xml" >
Line 90: Line 90:
 
</source>
 
</source>
  
Alternatively, you can prepare the popup window in Java by listening to the <tt>onOpen</tt> event, as depicted below.  
+
Alternatively, you can prepare the popup window in Java by listening to the <code>onOpen</code> event, as depicted below.  
  
 
<source lang="xml" >
 
<source lang="xml" >
Line 108: Line 108:
  
 
== The onChanging Event ==
 
== The onChanging Event ==
Since a bandbox 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 popup window in any fashion.
+
Since a bandbox 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 popup window in any fashion.
 
The code below illustrates capturing the user key and displaying information accordingly.
 
The code below illustrates capturing the user key and displaying information accordingly.
  
Line 128: Line 128:
  
  
Notice that, when the <tt>onChanging</tt> event is received, the content of the bandbox has not changed. Therefore, you cannot use the <tt>value</tt> property of the bandbox. 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 bandbox has not changed. Therefore, you cannot get the <code>value</code> property of the bandbox. Instead, you should call [https://www.zkoss.org/javadoc/latest/zk/org/zkoss/zk/ui/event/InputEvent.html#getValue-- org.zkoss.zk.ui.event.InputEvent.getValue()].
  
 
== Constraint ==
 
== Constraint ==
You could specify what value to accept for input controls by the use of the <tt>constraint </tt>property.  
+
You could specify what value to accept for input controls by the use of the <code>constraint </code>property.  
It could be a combination of <tt>no empty</tt>, and/or a regular expression.  
+
It could be a combination of <code>no empty</code>, and/or a regular expression.  
  
 
To specify two or more constraints, use comma to separate them as follows.
 
To specify two or more constraints, use comma to separate them as follows.
Line 141: Line 141:
 
</source>
 
</source>
  
To specify a regular expression, you may have to use the character <tt>/</tt> to enclose the regular expression as follows.  
+
To specify a regular expression, you may have to use the character <code>/</code> to enclose the regular expression as follows.  
  
 
<source lang="xml" >
 
<source lang="xml" >
Line 149: Line 149:
 
Notes:
 
Notes:
  
* The above statement is XML, so do ''not'' use <tt>\\</tt> to specify a backslash. However typing <tt>\\</tt> is necessary, if writing in Java.
+
* The above statement is XML, so do ''not'' use <code>\\</code> to specify a backslash. However typing <code>\\</code> is necessary, if writing in Java.
  
 
<source lang="java" >
 
<source lang="java" >
Line 173: Line 173:
  
 
==IconSclass==
 
==IconSclass==
[Since 8.6.2]
+
{{versionSince| 8.6.2}}
 
Specify the sclass name of the Bandbox button icon. For built-in icon, please see [[ZK_Component_Reference/Base_Components/LabelImageElement]].
 
Specify the sclass name of the Bandbox button icon. For built-in icon, please see [[ZK_Component_Reference/Base_Components/LabelImageElement]].
  
Line 182: Line 182:
 
=Supported Events=
 
=Supported Events=
  
{| border="1" | width="100%"
+
{| class='wikitable' | width="100%"
 
! <center>Name</center>
 
! <center>Name</center>
 
! <center>Event Type</center>
 
! <center>Event Type</center>
Line 195: Line 195:
 
=Supported Molds=
 
=Supported Molds=
 
Available molds of a component are defined in lang.xml embedded in zul.jar.
 
Available molds of a component are defined in lang.xml embedded in zul.jar.
{| border="1" | width="100%"
+
{| class='wikitable' | width="100%"
 
! <center>Name</center>
 
! <center>Name</center>
 
! <center>Snapshot</center>
 
! <center>Snapshot</center>
Line 204: Line 204:
 
| <center>rounded</center>
 
| <center>rounded</center>
 
|[[Image:bandbox_mold_rounded.png ]]  
 
|[[Image:bandbox_mold_rounded.png ]]  
[Since 5.0.0]
+
{{versionSince| 5.0.0}}
 
|}
 
|}
  
Line 213: Line 213:
 
=Use Cases=
 
=Use Cases=
  
{| border='1px' | width="100%"
+
{| class='wikitable' | width="100%"
 
! Version !! Description !! Example Location
 
! Version !! Description !! Example Location
 
|-
 
|-
Line 223: Line 223:
 
=Version History=
 
=Version History=
 
{{LastUpdated}}
 
{{LastUpdated}}
{| border='1px' | width="100%"
+
{| class='wikitable' | width="100%"
 
! Version !! Date !! Content
 
! Version !! Date !! Content
 
|-
 
|-

Revision as of 06:23, 26 April 2023

Bandbox

Employment/Purpose

A bandbox is a special text box that embeds a customizable popup window (aka., a dropdown window). Like comboboxes, a bandbox consists of an input box and a popup window. The popup window is opened automatically, when a user presses Alt+DOWN or clicks the magnifier button.

Unlike comboboxes, the popup window of a bandbox could be anything. It is designed to give developers the maximal flexibility. A typical use is to represent the popup window as a search dialog.

Example

ZKComRef Bandbox Example.png

<bandbox id="bd">
	<bandpopup>
		<vbox>
			<hbox>
				Search
				<textbox />
			</hbox>
			<listbox width="200px"
				onSelect="bd.value=self.selectedItem.label;bd.close();">
				<listhead>
					<listheader label="Name" />
					<listheader label="Description" />
				</listhead>
				<listitem>
					<listcell label="John" />
					<listcell label="CEO" />
				</listitem>
				<listitem>
					<listcell label="Joe" />
					<listcell label="Engineer" />
				</listitem>
				<listitem>
					<listcell label="Mary" />
					<listcell label="Supervisor" />
				</listitem>
			</listbox>
		</vbox>
	</bandpopup>
</bandbox>

Mouseless Entry bandbox

  • Alt+DOWN to pop up the list.
  • Alt+UP or ESC to close the list.

Properties

The Close Method

A popup window could contain any components, so it is the developer’s job to close the popup and copy any needed value from it.

<listbox width="200px"
   onSelect="bd.value=self.selectedItem.label; bd.close();">

In the above example, we copy the selected item's label to the bandbox, and then close the popup.

Autodrop

ZKComRef Bandbox Autodrop.PNG

By default, the popup window won't be opened until user clicks the button, or presses Alt+DOWN on the keyboard. However, you can set the autodrop property to true and as soon as the user types a character the popup will be opened. This is helpful for novice users, but it might be annoying for experienced users.

<zk>
	<bandbox id="bd" autodrop="true">
		<bandpopup>
			...
		</bandpopup>
	</bandbox>
</zk>

The onOpen Event

If the user opens the popup window the onOpen event is sent to the application. By using the fulfill attribute with the onOpen value as shown below, you can defer the creation of the popup window.

<bandbox id="test">
    <bandpopup fulfill="test.onOpen">
     ...
    </bandpopup>
</bandbox>

Alternatively, you can prepare the popup window in Java by listening to the onOpen event, as depicted below.

<zk>
	<bandbox id="band" onOpen="prepare()"/>
	
	<zscript>
	     void prepare() 
	     {
	         if (band.getPopup() == null) {
	             //create child elements
	         }
	     }
	</zscript>
</zk>

The onChanging Event

Since a bandbox is also a text box, you are also able to listen to an onChanging event. By listening to this event, you can manipulate the popup window in any fashion. The code below illustrates capturing the user key and displaying information accordingly.

<zk>
	<bandbox id="band" autodrop="true" onChanging="suggest()"/>
	<zscript>
	     void suggest() 
	     {
	         if (event.value.startsWith("A")) {
	             //do something
	         } else if (event.value.startsWith("B")) {
	             //do another
	         }
	     }
	</zscript>
</zk>


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

Constraint

You could specify what value to accept for input controls by the use of the constraint property. It could be a combination of no empty, and/or a regular expression.

To specify two or more constraints, use comma to separate them as follows.

<bandbox constraint="no empty,/^A/"/>

To specify a regular expression, you may have to use the character / to enclose the regular expression as follows.

<bandbox constraint="/^A/"/>

Notes:

  • The above statement is XML, so do not use \\ to specify a backslash. However typing \\ is necessary, if writing in Java.
new Bandbox().setConstraint("/.+@.+\\.[a-z]+/");
  • You are allowed to mix regular expressions with other constraints by separating them with a comma.

If you prefer to display different message to the default one, you can append the error message to the constraint with a colon.

<bandbox constraint="/^A/: only allowed the item start with A"/>

Notes:

  • The error message, if specified, must be the last element and start with colon.
  • To support multiple languages, you could use the 「l」 function as depicted in the Internationalization chapter.
<bandbox constraint="/^A/: ${c:l('err.startwith.required')}"/>

IconSclass

Since 8.6.2 Specify the sclass name of the Bandbox button icon. For built-in icon, please see ZK_Component_Reference/Base_Components/LabelImageElement.

Inherited Functions

Please refer to Textbox for inherited functions.

Supported Events

Name
Event Type
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.

Supported Molds

Available molds of a component are defined in lang.xml embedded in zul.jar.

Name
Snapshot
default
Bandbox mold default.png
rounded
Bandbox mold rounded.png

Since 5.0.0

Supported Children

* Bandpopup 

Use Cases

Version Description Example Location
     

Version History

Last Update : 2023/04/26


Version Date Content
     



Last Update : 2023/04/26

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