org.zkoss.zul
Class Datebox

java.lang.Object
  org.zkoss.zk.ui.AbstractComponent
      org.zkoss.zk.ui.HtmlBasedComponent
          org.zkoss.zul.impl.XulElement
              org.zkoss.zul.impl.InputElement
                  org.zkoss.zul.impl.FormatInputElement
                      org.zkoss.zul.Datebox

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, Component, Disable, Readonly, Scope, ComponentCtrl, Constrainted

public class Datebox
extends FormatInputElement

An edit box for holding a date.

The default format (FormatInputElement.getFormat()) depends on DateFormats.getDateFormat(int, java.util.Locale, java.lang.String) and the current user's locale (unless setLocale(java.util.Locale) is assigned. Please refer to setFormat(java.lang.String) for more details.

Default getZclass(): z-datebox.(since 3.5.0)

Author:

tomyeh

See Also:

Serialized Form

Nested Class Summary

protected class

Datebox.ExtraCtrl A utility class to implement HtmlBasedComponent.getExtraCtrl().

Nested classes/interfaces inherited from class org.zkoss.zk.ui.AbstractComponent

AbstractComponent.Children

Field Summary

Fields inherited from class org.zkoss.zul.impl.InputElement

_value

Fields inherited from class org.zkoss.zk.ui.HtmlBasedComponent

_zclass

Fields inherited from interface org.zkoss.zk.ui.Component

APPLICATION_SCOPE, COMPONENT_SCOPE, DESKTOP_SCOPE, PAGE_SCOPE, REQUEST_SCOPE, SESSION_SCOPE, SPACE_SCOPE

Fields inherited from interface org.zkoss.zk.ui.sys.ComponentCtrl

CE_BUSY_IGNORE, CE_DUPLICATE_IGNORE, CE_IMPORTANT, CE_NON_DEFERRABLE, CE_REPEAT_IGNORE

Constructor Summary

Datebox()

Datebox(java.util.Date date)
Constructor with a given date.

Method Summary

void	close() Closes the calendar if it was dropped down.
protected java.lang.Object	coerceFromString(java.lang.String value) Coerces the value passed to InputElement.setText(java.lang.String).
protected java.lang.String	coerceToString(java.lang.Object value) Coerces the value passed to InputElement.setText(java.lang.String).
protected java.text.DateFormat	getDateFormat(java.lang.String fmt) Returns the date format of the specified format Default: it uses SimpleDateFormat to format the date.
protected java.lang.String	getDefaultFormat() Returns the default format, which is used when constructing a datebox, or when setFormat(java.lang.String) is called with null or empty.
java.util.List<java.util.TimeZone>	getDisplayedTimeZones() Returns a list of the time zones that will be displayed at the client and allow user to select.
java.lang.Object	getExtraCtrl() Returns the client control for this component.
java.util.Locale	getLocale() Returns the locale associated with this datebox, or null if Locales.getCurrent() is preferred.
protected java.lang.String	getLocalizedFormat() Returns the localized format, which is used when constructing a datebox.
java.lang.String	getRealFormat() Returns the real format, i.e., the combination of the format patterns, such as yyyy-MM-dd.
boolean	getShowTodayLink() Returns whether enable to show the link that jump to today in day view Default: false
java.util.TimeZone	getTimeZone() Returns the time zone that this date box belongs to, or null if the default time zone is used.
java.util.Date	getValue() Returns the value (in Date), might be null unless a constraint stops it.
java.lang.String	getZclass() Returns the ZK Cascading Style class(es) for this component.
boolean	isButtonVisible() Returns whether the button (on the right of the textbox) is visible.
boolean	isCompact() Deprecated. As of release 5.0.0, it is no longer supported.
boolean	isLenient() Returns whether or not date/time parsing is to be lenient.
boolean	isTimeZonesReadonly() Returns whether the list of the time zones to display is readonly.
boolean	isWeekOfYear() Returns whether enable to show the week number in the current calendar or not.
protected java.lang.Object	marshall(java.lang.Object value) Marshall value to be sent to the client if needed.
void	open() Drops down the calendar to select a date.
protected void	renderProperties(ContentRenderer renderer) Renders the content of this component, excluding the enclosing tags and children.
void	service(AuRequest request, boolean everError) Processes an AU request.
void	setButtonVisible(boolean visible) Sets whether the button (on the right of the textbox) is visible.
void	setCompact(boolean compact) Deprecated. As of release 5.0.0, it is no longer supported.
void	setConstraint(java.lang.String constr)
void	setDisplayedTimeZones(java.util.List<java.util.TimeZone> dtzones) Sets a list of the time zones that will be displayed at the client and allow user to select.
void	setDisplayedTimeZones(java.lang.String dtzones) Sets a concatenation of a list of the time zones' ID, separated by comma, that will be displayed at the client and allow user to select.
void	setFormat(java.lang.String format) Sets the date format.
void	setLenient(boolean lenient) Sets whether or not date/time parsing is to be lenient.
void	setLocale(java.util.Locale locale) Sets the locale used to identify the format of this datebox.
void	setLocale(java.lang.String locale) Sets the locale used to identify the format of this datebox.
void	setOpen(boolean open) Drops down or closes the calendar to select a date.
void	setShowTodayLink(boolean showTodayLink) Sets whether enable to show the link that jump to today in day view
void	setTimeZone(java.lang.String id) Sets the time zone that this date box belongs to, or null if the default time zone is used.
void	setTimeZone(java.util.TimeZone tzone) Sets the time zone that this date box belongs to, or null if the default time zone is used.
void	setTimeZonesReadonly(boolean readonly) Sets whether the list of the time zones to display is readonly.
void	setValue(java.util.Date value) Sets the value (in Date).
void	setWeekOfYear(boolean weekOfYear) Sets whether enable to show the week number in the current calendar or not.
static int	toStyle(java.lang.String format) Returns the styling index, or -111 if not matched.
protected java.lang.Object	unmarshall(java.lang.Object value) Unmarshall value returned from client if needed.

Methods inherited from class org.zkoss.zul.impl.FormatInputElement

getFormat

Methods inherited from class org.zkoss.zul.impl.InputElement

checkUserError, clearErrorMessage, clearErrorMessage, clone, getCols, getConstraint, getErrorMessage, getInstant, getMaxlength, getName, getPlaceholder, getRawText, getRawValue, getTabindex, getTargetValue, getText, getType, isChildable, isDisabled, isInplace, isMultiline, isReadonly, isValid, onWrongValue, select, setCols, setConstraint, setDisabled, setErrorMessage, setInplace, setInstant, setMaxlength, setName, setPlaceholder, setRawValue, setReadonly, setSelectedText, setSelectionRange, setTabindex, setText, setValueDirectly, showCustomError, validate

Methods inherited from class org.zkoss.zul.impl.XulElement

getContext, getCtrlKeys, getPopup, getTooltip, setContext, setContext, setCtrlKeys, setPopup, setPopup, setTooltip, setTooltip

Methods inherited from class org.zkoss.zk.ui.HtmlBasedComponent

focus, getAction, getDraggable, getDroppable, getHeight, getHflex, getLeft, getRenderdefer, getSclass, getStyle, getTooltiptext, getTop, getVflex, getWidth, getZindex, getZIndex, setAction, setClass, setDraggable, setDroppable, setFocus, setHeight, setHeightDirectly, setHflex, setHflexDirectly, setLeft, setLeftDirectly, setRenderdefer, setSclass, setStyle, setTooltiptext, setTop, setTopDirectly, setVflex, setWidth, setWidthDirectly, setZclass, setZindex, setZIndex, setZIndexDirectly

Methods inherited from class org.zkoss.zk.ui.AbstractComponent

addAnnotation, addAnnotation, addClientEvent, addEventHandler, addEventListener, addEventListener, addForward, addForward, addForward, addForward, addMoved, addRedrawCallback, addScopeListener, addShadowRoot, addShadowRootBefore, addSharedEventHandlerMap, appendChild, applyProperties, beforeChildAdded, beforeChildRemoved, beforeParentChanged, detach, didActivate, didActivate, didDeserialize, didDeserialize, disableBindingAnnotation, disableClientUpdate, enableBindingAnnotation, equals, getAnnotatedProperties, getAnnotatedPropertiesBy, getAnnotation, getAnnotation, getAnnotations, getAnnotations, getAnnotations, getAttribute, getAttribute, getAttribute, getAttributeOrFellow, getAttributes, getAttributes, getAuService, getAutag, getChildren, getClientAttribute, getClientEvents, getDefaultMold, getDefinition, getDesktop, getEventHandler, getEventHandlerNames, getEventListenerMap, getEventListeners, getFellow, getFellow, getFellowIfAny, getFellowIfAny, getFellows, getFirstChild, getId, getLastChild, getListenerIterator, getMold, getNextSibling, getPage, getParent, getPreviousSibling, getRedrawCallback, getRoot, getShadowRoots, getShadowVariable, getShadowVariable0, getSpaceOwner, getSpecialRendererOutput, getStubonly, getSubBindingAnnotationCount, getTemplate, getTemplateNames, getUuid, getWidgetAttribute, getWidgetAttributeNames, getWidgetClass, getWidgetListener, getWidgetListenerNames, getWidgetOverride, getWidgetOverrideNames, hasAttribute, hasAttribute, hasAttribute, hasAttributeOrFellow, hasBindingAnnotation, hasFellow, hasFellow, hasSubBindingAnnotation, insertBefore, invalidate, isInvalidated, isListenerAvailable, isVisible, onChildAdded, onChildRemoved, onPageAttached, onPageDetached, query, queryAll, redraw, redrawChildren, removeAttribute, removeAttribute, removeAttribute, removeChild, removeEventListener, removeForward, removeForward, removeRedrawCallback, removeScopeListener, removeShadowRoot, render, render, render, replace, response, response, response, service, sessionDidActivate, sessionWillPassivate, setAttribute, setAttribute, setAttribute, setAuService, setAutag, setClientAttribute, setDefinition, setDefinition, setId, setMold, setPage, setPageBefore, setParent, setStubonly, setStubonly, setSubBindingAnnotationCount, setTemplate, setVisible, setVisibleDirectly, setWidgetAttribute, setWidgetClass, setWidgetListener, setWidgetOverride, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdateWidgetListener, smartUpdateWidgetOverride, toString, updateByClient, updateSubBindingAnnotationCount, willPassivate, willPassivate, willSerialize, willSerialize

Methods inherited from class java.lang.Object

finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Datebox

public Datebox()

Datebox

public Datebox(java.util.Date date)
        throws WrongValueException

Constructor with a given date.

Parameters:

date - the date to be assigned to this datebox initially.
Notice that, if this datebox does not allow users to select the time (i.e., the format limited to year, month and day), the date specified here is better to set hour, minutes, seconds and milliseconds to zero (for the current timezone, TimeZones.getCurrent()), so it is easier to work with other libraries, such as SQL. Dates has a set of utilities to simplify the task.

Throws:

WrongValueException

Method Detail

setWeekOfYear

public void setWeekOfYear(boolean weekOfYear)

Sets whether enable to show the week number in the current calendar or not. [ZK EE]

Since:

6.5.0

isWeekOfYear

public boolean isWeekOfYear()

Returns whether enable to show the week number in the current calendar or not.

Default: false

Since:

6.5.0

getDefaultFormat

protected java.lang.String getDefaultFormat()

Returns the default format, which is used when constructing a datebox, or when setFormat(java.lang.String) is called with null or empty.

Default: DateFormats.getDateFormat(DEFAULT, null, "yyyy/MM/dd") (see DateFormats.getDateFormat(int, java.util.Locale, java.lang.String)).

Though you might override this method to provide your own default format, it is suggested to specify the format for the current thread with DateFormats.setLocalFormatInfo(org.zkoss.text.DateFormatInfo).

getLocalizedFormat

protected java.lang.String getLocalizedFormat()

Returns the localized format, which is used when constructing a datebox.

You might override this method to provide your own localized format.

isLenient

public boolean isLenient()

Returns whether or not date/time parsing is to be lenient.

With lenient parsing, the parser may use heuristics to interpret inputs that do not precisely match this object's format. With strict parsing, inputs must match this object's format.

setLenient

public void setLenient(boolean lenient)

Sets whether or not date/time parsing is to be lenient.

Default: true.

With lenient parsing, the parser may use heuristics to interpret inputs that do not precisely match this object's format. With strict parsing, inputs must match this object's format.

isCompact

public boolean isCompact()

Deprecated. As of release 5.0.0, it is no longer supported.

setCompact

public void setCompact(boolean compact)

Deprecated. As of release 5.0.0, it is no longer supported.

isButtonVisible

public boolean isButtonVisible()

Returns whether the button (on the right of the textbox) is visible.

Default: true.

Since:

2.4.1

setButtonVisible

public void setButtonVisible(boolean visible)

Sets whether the button (on the right of the textbox) is visible.

Since:

2.4.1

getValue

public java.util.Date getValue()
                        throws WrongValueException

Returns the value (in Date), might be null unless a constraint stops it.

Throws:

WrongValueException - if user entered a wrong value

setValue

public void setValue(java.util.Date value)
              throws WrongValueException

Sets the value (in Date).

Parameters:

value - the date to be assigned to this datebox.
Notice that, if this datebox does not allow users to select the time (i.e., the format limited to year, month and day), the date specified here is better to set hour, minutes, seconds and milliseconds to zero (for the current timezone, TimeZones.getCurrent()), so it is easier to work with other libraries, such as SQL. Dates has a set of utilities to simplify the task.

Throws:

WrongValueException - if value is wrong

setFormat

public void setFormat(java.lang.String format)
               throws WrongValueException

Sets the date format.

If null or empty is specified, getDefaultFormat() is assumed. Since 5.0.7, you could specify one of the following reserved words, and DateFormats.getDateFormat(int, java.util.Locale, java.lang.String) or DateFormats.getDateTimeFormat(int, int, java.util.Locale, java.lang.String) will be used to retrieve the real format.

short	DateFormats.getDateFormat(int, java.util.Locale, java.lang.String) with DateFormat.SHORT
medium	DateFormats.getDateFormat(int, java.util.Locale, java.lang.String) with DateFormat.MEDIUM
long	DateFormats.getDateFormat(int, java.util.Locale, java.lang.String) with DateFormat.LONG
full	DateFormats.getDateFormat(int, java.util.Locale, java.lang.String) with DateFormat.FULL

To specify a date/time format, you could specify two reserved words, separated by a plus. For example, "medium+short" means DateFormats.getDateTimeFormat(int, int, java.util.Locale, java.lang.String) with the medium date styling and the short time styling.

In additions, the format could be a combination of the following pattern letters:

Letter	Date or Time Component	Presentation	Examples
G	Era designator	Text	AD
y	Year	Year	1996; 96
M	Month in year	Month	July; Jul; 07
w	Week in year (starting at 1)	Number	27
W	Week in month (starting at 1)	Number	2
D	Day in year (starting at 1)	Number	189
d	Day in month (starting at 1)	Number	10
F	Day of week in month	Number	2
E	Day in week	Text	Tuesday; Tue

Overrides:

setFormat in class FormatInputElement

Throws:

WrongValueException

toStyle

public static int toStyle(java.lang.String format)

Returns the styling index, or -111 if not matched.

getRealFormat

public java.lang.String getRealFormat()

Returns the real format, i.e., the combination of the format patterns, such as yyyy-MM-dd.

As described in setFormat(java.lang.String), a developer could specify an abstract name, such as short, or an empty string as the format, and this method will convert it to a real date/time format.

Overrides:

getRealFormat in class FormatInputElement

Since:

5.0.7

getTimeZone

public java.util.TimeZone getTimeZone()

Returns the time zone that this date box belongs to, or null if the default time zone is used.

The default time zone is determined by TimeZones.getCurrent().

setTimeZone

public void setTimeZone(java.util.TimeZone tzone)

Sets the time zone that this date box belongs to, or null if the default time zone is used.

The default time zone is determined by TimeZones.getCurrent().

Notice that if getDisplayedTimeZones() was called with a non-empty list, the time zone must be one of it. Otherwise (including tzone is null), the first timezone is selected.

setTimeZone

public void setTimeZone(java.lang.String id)

Sets the time zone that this date box belongs to, or null if the default time zone is used.

The default time zone is determined by TimeZones.getCurrent().

Parameters:

id - the time zone's ID, such as "America/Los_Angeles". The time zone will be retrieved by calling TimeZone.getTimeZone(id).

getDisplayedTimeZones

public java.util.List<java.util.TimeZone> getDisplayedTimeZones()

Returns a list of the time zones that will be displayed at the client and allow user to select.

Default: null

Since:

3.6.3

setDisplayedTimeZones

public void setDisplayedTimeZones(java.util.List<java.util.TimeZone> dtzones)

Sets a list of the time zones that will be displayed at the client and allow user to select.

If the getTimeZone() is null, the first time zone in the list is assumed.

Parameters:

dtzones - a list of the time zones to display. If empty, it assumed to be null.

Since:

3.6.3

setDisplayedTimeZones

public void setDisplayedTimeZones(java.lang.String dtzones)

Sets a concatenation of a list of the time zones' ID, separated by comma, that will be displayed at the client and allow user to select.

The time zone is retrieved by calling TimeZone.getTimeZone().

Parameters:

dtzones - a concatenation of a list of the timezones' ID, such as "America/Los_Angeles,GMT+8"

Since:

3.6.3

See Also:

setDisplayedTimeZones(List)

isTimeZonesReadonly

public boolean isTimeZonesReadonly()

Returns whether the list of the time zones to display is readonly. If readonly, the user cannot change the time zone at the client.

Since:

3.6.3

setTimeZonesReadonly

public void setTimeZonesReadonly(boolean readonly)

Sets whether the list of the time zones to display is readonly. If readonly, the user cannot change the time zone at the client.

Since:

3.6.3

getLocale

public java.util.Locale getLocale()

Returns the locale associated with this datebox, or null if Locales.getCurrent() is preferred.

Since:

5.0.7

setLocale

public void setLocale(java.util.Locale locale)

Sets the locale used to identify the format of this datebox.

Default: null (i.e., Locales.getCurrent(), the current locale is assumed)

Since:

5.0.7

setLocale

public void setLocale(java.lang.String locale)

Sets the locale used to identify the format of this datebox.

Default: null (i.e., Locales.getCurrent(), the current locale is assumed)

Since:

5.0.7

setOpen

public void setOpen(boolean open)

Drops down or closes the calendar to select a date. only works while visible

Since:

3.0.1

See Also:

open(), close()

open

public void open()

Drops down the calendar to select a date. The same as setOpen(true).

Since:

3.0.1

close

public void close()

Closes the calendar if it was dropped down. The same as setOpen(false).

Since:

3.0.1

service

public void service(AuRequest request,
                    boolean everError)

Processes an AU request.

Default: in addition to what are handled by HtmlBasedComponent.service(org.zkoss.zk.au.AuRequest, boolean), it also handles onTimeZoneChange, onChange, onChanging and onError.

Specified by:

service in interface ComponentCtrl

Overrides:

service in class InputElement

everError - whether any error ever occurred before processing this request.

Since:

5.0.0

See Also:

AbstractComponent.setAuService(org.zkoss.zk.au.AuService)

getExtraCtrl

public java.lang.Object getExtraCtrl()

Description copied from class: HtmlBasedComponent

Returns the client control for this component. It is used only by component developers.

Default: creates an instance of HtmlBasedComponent.ExtraCtrl.

Specified by:

getExtraCtrl in interface ComponentCtrl

Overrides:

getExtraCtrl in class HtmlBasedComponent

Returns:

null if no special handling required. If the component requires some special controls, it could return an object that implements one or several interfaces in the org.zkoss.zk.ui.ext.render package. For example, Cropper.

See Also:

ComponentCtrl.getExtraCtrl()

setConstraint

public void setConstraint(java.lang.String constr)

Overrides:

setConstraint in class InputElement

Parameters:

constr - a list of constraints separated by comma. Example: "between 20071012 and 20071223", "before 20080103"

marshall

protected java.lang.Object marshall(java.lang.Object value)

Description copied from class: InputElement

Marshall value to be sent to the client if needed.

Overrides it if the value to be sent to the client is not JSON Compatible.

Overrides:

marshall in class InputElement

Parameters:

value - the value to be sent to the client

Returns:

the marshalled value

unmarshall

protected java.lang.Object unmarshall(java.lang.Object value)

Description copied from class: InputElement

Unmarshall value returned from client if needed.

Overrides it if the value returned is not JSON Compatible.

Overrides:

unmarshall in class InputElement

Parameters:

value - the value returned from client

Returns:

the unmarshalled value

coerceFromString

protected java.lang.Object coerceFromString(java.lang.String value)
                                     throws WrongValueException

Description copied from class: InputElement

Coerces the value passed to InputElement.setText(java.lang.String).

Deriving note:
If you want to store the value in other type, say BigDecimal, you have to override InputElement.coerceToString(java.lang.Object) and InputElement.coerceFromString(java.lang.String) to convert between a string and your targeting type.

Moreover, when Textbox is called, it calls this method with value = null. Derives shall handle this case properly.

Specified by:

coerceFromString in class InputElement

Throws:

WrongValueException

coerceToString

protected java.lang.String coerceToString(java.lang.Object value)

Description copied from class: InputElement

Coerces the value passed to InputElement.setText(java.lang.String).

Default: convert null to an empty string.

Deriving note:
If you want to store the value in other type, say BigDecimal, you have to override InputElement.coerceToString(java.lang.Object) and InputElement.coerceFromString(java.lang.String) to convert between a string and your targeting type.

Specified by:

coerceToString in class InputElement

getDateFormat

protected java.text.DateFormat getDateFormat(java.lang.String fmt)

Returns the date format of the specified format

Default: it uses SimpleDateFormat to format the date.

Parameters:

fmt - the pattern.

getZclass

public java.lang.String getZclass()

Description copied from class: HtmlBasedComponent

Returns the ZK Cascading Style class(es) for this component. It usually depends on the implementation of the mold (AbstractComponent.getMold()).

Default: null (the default value depends on element).

HtmlBasedComponent.setZclass(java.lang.String)) will completely replace the default style of a component. In other words, the default style of a component is associated with the default value of HtmlBasedComponent.getZclass(). Once it is changed, the default style won't be applied at all. If you want to perform small adjustments, use HtmlBasedComponent.setSclass(java.lang.String) instead.

Overrides:

getZclass in class HtmlBasedComponent

See Also:

HtmlBasedComponent.getSclass()

getShowTodayLink

public boolean getShowTodayLink()

Returns whether enable to show the link that jump to today in day view

Default: false

Returns:

boolean

Since:

8.0.0

setShowTodayLink

public void setShowTodayLink(boolean showTodayLink)

Sets whether enable to show the link that jump to today in day view

Parameters:

showTodayLink - show or hidden

Since:

8.0.0

renderProperties

protected void renderProperties(ContentRenderer renderer)
                         throws java.io.IOException

Description copied from class: HtmlBasedComponent

Renders the content of this component, excluding the enclosing tags and children.

See also ZK Client-side Reference: Property Rendering

Overrides:

renderProperties in class FormatInputElement

Throws:

java.io.IOException