ZK Component Reference/Input/Timebox

Timebox

• Demonstration: Date and Time
• Java API: Timebox
• JavaScript API: Timebox
• Style Guide: Timebox

Employment/Purpose

An edit box for holding a time (a java.util.Date Object) , but only Hour & Minute are used.

Example

 <window title="Simple" width="300px" border="normal">
     <timebox id="tb0"/>
 </window>

Properties

Constraint

You could specify what value to accept for input controls by use of the constraint property. It could be no empty.

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

<timebox constraint="no empty: cannot be empty"/>

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.

<timebox constraint="no empty: ${c:l('err.time.required')}"/>

Format

Use a to signify it is am or pm. The input string follows the formatting of the SimpleDateFormat.

Below is an example of using a within the format.

<zk>
	<window title="Test">
		<timebox cols="20" format="a hh:mm:ss"/>
	</window>
</zk>

In addition to specifying the format explicitly, you could specify the styling. There are four different types of styling: short, medium, long and full (representing the styling of java.text.DateFormat). For example, you could specify the styling rather than the real format as follows.

<timebox format="short"/>
<timebox format="long"/>

Then the real format of the timebox will be decided at run time depending the configuration. For more information, please refer to ZK Developer's Reference: Date and Time Formatting.

---

Locale

By default, the real format depends on the current locale (i.e., Locales.getCurrent(). However, you could specify the locale for an individual instance such as:

<timebox format="medium" locale="de_DE"/>
<timebox format="long" locale="fr"/>

Text

You should set text attribute after format attribute or ZK might not convert the specified text well.

<timebox format="hh:mm:ss a" locale="en" text="12:00:00 AM"/>

• If you set format later than setting text attribute, ZK might probably fail to convert the text to a Date object according to default format and throw org.zkoss.zk.ui.WrongValueException.

Inherited Functions

Please refer to FormatInputElement for inherited functions.

Supported Events

Name	Event Type
None	None

• Inherited Supported Events: FormatInputElement

Supported Molds

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

Name	Snapshot
default
rounded	[Since 5.0.0]

Supported Children

*NONE

Use Cases

Version	Description	Example Location

Version History

Version	Date	Content
5.0.7	April, 2011	Timebox.setFormat(String) supported the styling.
5.0.7	April, 2011	Timebox.setLocale(Locale) was introduced to specify a locale other than the current locale.