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, HtmlBasedComponent, Component, Scope, ComponentCtrl, Datebox, Constrainted, FormatInputElement, InputElement, XulElement

public class Datebox
extends FormatInputElement
implements Datebox

An edit box for holding a date.

The default format (FormatInputElement.getFormat()) depends on JVM's setting and the current user's locale. That is, DateFormat.getDateInstance(DateFormat,DEFAULT, Locales.getCurrent). You might override getDefaultFormat() to provide your own default format.

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

Author:

tomyeh

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class org.zkoss.zul.impl.InputElement

InputElement.ExtraCtrl

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

AbstractComponent.Children

Field Summary

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

_zclass, RS_NO_DISPLAY, RS_NO_HEIGHT, RS_NO_WIDTH

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

_visible

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

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

Constructor Summary

Datebox()

Datebox(java.util.Date 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 contructing a datebox.
java.lang.String	getImage() Deprecated. As of release 3.5.0
java.lang.String	getInnerAttrs() Generates the Client-Side-Action attributes to the interior tag.
java.lang.String	getOuterAttrs() Returns the exterior attributes for generating the enclosing HTML tag; never return null.
protected int	getRealStyleFlags() Returns RS_NO_WIDTH|RS_NO_HEIGHT.
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() Returns whether to use a compact layout.
boolean	isLenient() Returns whether or not date/time parsing is to be lenient.
void	open() Drops down the calendar to select a date.
void	setButtonVisible(boolean visible) Sets whether the button (on the right of the textbox) is visible.
void	setCompact(boolean compact) Sets whether to use a compact layout.
void	setConstraint(java.lang.String constr)
void	setFormat(java.lang.String format) Sets the date format.
void	setImage(java.lang.String img) Deprecated. As of release 3.5.0
void	setLenient(boolean lenient) Returns whether or not date/time parsing is to be lenient.
void	setOpen(boolean open) Drops down or closes the calendar to select a date.
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	setValue(java.util.Date value) Sets the value (in Date).
protected boolean	shallServerFormat() Returns whether the server-side formatting shall take place.

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

getFormat

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

checkUserError, clearErrorMessage, clearErrorMessage, getAreaText, getCols, getConstraint, getErrorMessage, getMaxlength, getName, getRawText, getRawValue, getTabindex, getTargetValue, getText, getType, isChildable, isDisabled, isMultiline, isReadonly, isValid, newExtraCtrl, onWrongValue, select, setCols, setConstraint, setDisabled, setMaxlength, setName, setRawValue, setReadonly, setSelectedText, setSelectionRange, setTabindex, setText, setValueDirectly, showCustomError, validate

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

getAction, getActionAttrs, getAllOnClickAttrs, getContext, getCtrlKeys, getPopup, getTooltip, setAction, setContext, setContext, setCtrlKeys, setPopup, setPopup, setTooltip, setTooltip

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

focus, getAllOnClickAttrs, getDraggable, getDroppable, getHeight, getLeft, getMoldSclass, getRealSclass, getRealStyle, getSclass, getStyle, getTooltiptext, getTop, getWidth, getZindex, getZIndex, redraw, setClass, setDraggable, setDroppable, setFocus, setHeight, setLeft, setMoldSclass, setSclass, setStyle, setTooltiptext, setTop, setWidth, setZclass, setZindex, setZIndex

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

addAnnotation, addAnnotation, addEventHandler, addEventListener, addForward, addForward, addForward, addForward, addMoved, addSharedAnnotationMap, addSharedEventHandlerMap, appendAsapAttr, appendAsapAttr, appendChild, applyProperties, clone, containsVariable, detach, equals, getAnnotatedProperties, getAnnotatedPropertiesBy, getAnnotation, getAnnotation, getAnnotations, getAnnotations, getAttribute, getAttribute, getAttributes, getAttributes, getChildren, getCommand, getDefinition, getDesktop, getEventHandler, getEventHandlerNames, getExtraCtrl, getFellow, getFellowIfAny, getFellows, getFirstChild, getId, getLastChild, getListenerIterator, getMold, getMoldURI, getNamespace, getNextSibling, getPage, getParent, getPreviousSibling, getRoot, getSpaceOwner, getUuid, getVariable, hasFellow, insertBefore, invalidate, isAsapRequired, isInvalidated, isListenerAvailable, isVisible, newChildren, onChildAdded, onChildRemoved, onDrawNewChild, onPageAttached, onPageDetached, removeAttribute, removeAttribute, removeChild, removeEventListener, removeForward, removeForward, response, sessionDidActivate, sessionWillPassivate, setAttribute, setAttribute, setComponentDefinition, setId, setMold, setPage, setPageBefore, setParent, setVariable, setVisible, smartUpdate, smartUpdate, smartUpdate, smartUpdateDeferred, smartUpdateValues, toString, unsetVariable

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.zkoss.zul.impl.api.FormatInputElement

getFormat

Methods inherited from interface org.zkoss.zul.impl.api.InputElement

clearErrorMessage, clearErrorMessage, getAreaText, getCols, getErrorMessage, getMaxlength, getName, getRawText, getRawValue, getTabindex, getText, getType, isDisabled, isMultiline, isReadonly, isValid, select, setCols, setDisabled, setMaxlength, setName, setRawValue, setReadonly, setSelectedText, setSelectionRange, setTabindex, setText

Methods inherited from interface org.zkoss.zul.impl.api.XulElement

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

Methods inherited from interface org.zkoss.zk.ui.api.HtmlBasedComponent

focus, getHeight, getLeft, getSclass, getStyle, getTooltiptext, getTop, getWidth, getZindex, getZIndex, setDraggable, setDroppable, setFocus, setHeight, setLeft, setSclass, setStyle, setTooltiptext, setTop, setWidth, setZclass, setZindex, setZIndex

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

addEventListener, addForward, addForward, addForward, addForward, appendChild, applyProperties, clone, containsVariable, detach, getAttribute, getAttribute, getAttributes, getAttributes, getChildren, getDefinition, getDesktop, getFellow, getFellowIfAny, getFellows, getFirstChild, getId, getLastChild, getListenerIterator, getMold, getNamespace, getNextSibling, getPage, getParent, getPreviousSibling, getRoot, getSpaceOwner, getUuid, getVariable, insertBefore, invalidate, isChildable, isInvalidated, isListenerAvailable, isVisible, redraw, removeAttribute, removeAttribute, removeChild, removeEventListener, removeForward, removeForward, setAttribute, setAttribute, setId, setMold, setPage, setPageBefore, setParent, setVariable, setVisible, unsetVariable

Methods inherited from interface org.zkoss.zul.ext.Constrainted

getConstraint, setConstraint

Constructor Detail

Datebox

public Datebox()

Datebox

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

Throws:

WrongValueException

Method Detail

getDefaultFormat

protected java.lang.String getDefaultFormat()

Returns the default format, which is used when contructing a datebox.

The default format (FormatInputElement.getFormat()) depends on JVM's setting and the current user's locale. That is, DateFormat.getDateInstance(DateFormat,DEFAULT, Locales.getCurrent).

You might override this method to provide your own default 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.

Specified by:

isLenient in interface Datebox

setLenient

public void setLenient(boolean lenient)

Returns 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.

Specified by:

setLenient in interface Datebox

isCompact

public boolean isCompact()

Returns whether to use a compact layout.

Default: true if zh_TW or zh_CN; false otherwise.

Specified by:

isCompact in interface Datebox

setCompact

public void setCompact(boolean compact)

Sets whether to use a compact layout.

Specified by:

setCompact in interface Datebox

isButtonVisible

public boolean isButtonVisible()

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

Default: true.

Specified by:

isButtonVisible in interface Datebox

Since:

2.4.1

setButtonVisible

public void setButtonVisible(boolean visible)

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

Specified by:

setButtonVisible in interface Datebox

Since:

2.4.1

getImage

public java.lang.String getImage()

Deprecated. As of release 3.5.0

Returns the URI of the button image.

Default: null. (since 3.5.0)

Since:

3.0.0

setImage

public void setImage(java.lang.String img)

Deprecated. As of release 3.5.0

Sets the URI of the button image.

Parameters:

img - the URI of the button image.

Since:

3.0.0

getValue

public java.util.Date getValue()
                        throws WrongValueException

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

Specified by:

getValue in interface Datebox

Throws:

WrongValueException - if user entered a wrong value

setValue

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

Sets the value (in Date).

Specified by:

setValue in interface Datebox

Throws:

WrongValueException - if value is wrong

setFormat

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

Sets the date format.

The following pattern letters are defined:

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

Specified by:

setFormat in interface FormatInputElement

Overrides:

setFormat in class FormatInputElement

Throws:

WrongValueException

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().

Specified by:

getTimeZone in interface Datebox

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().

Specified by:

setTimeZone in interface Datebox

setOpen

public void setOpen(boolean open)

Drops down or closes the calendar to select a date.

Specified by:

setOpen in interface Datebox

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).

Specified by:

open in interface Datebox

Since:

3.0.1

close

public void close()

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

Specified by:

close in interface Datebox

Since:

3.0.1

setConstraint

public void setConstraint(java.lang.String constr)

Specified by:

setConstraint in interface InputElement

Overrides:

setConstraint in class InputElement

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 (@{link #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.

Specified by:

getZclass in interface HtmlBasedComponent

Overrides:

getZclass in class HtmlBasedComponent

See Also:

HtmlBasedComponent.getSclass(), HtmlBasedComponent.getRealSclass()

getOuterAttrs

public java.lang.String getOuterAttrs()

Description copied from class: HtmlBasedComponent

Returns the exterior attributes for generating the enclosing HTML tag; never return null.

Used only by component developers.

Default: Generates the tooltip text, style, sclass, draggable and droppable attribute if necessary. In other words, the corresponding attribute is generated if HtmlBasedComponent.getTooltiptext(), HtmlBasedComponent.getRealStyle(), HtmlBasedComponent.getSclass(), HtmlBasedComponent.getDraggable(), HtmlBasedComponent.getDroppable() are defined.

You have to call both HtmlBasedComponent.getOuterAttrs() and HtmlBasedComponent.getInnerAttrs() to generate complete attributes.

For simple components that all attributes are put on the outest HTML element, all you need is as follows.

<xx id="${self.uuid}"${self.outerAttrs}${self.innerAttrs}>

If you want to put attributes in a nested HTML element, you shall use the following pattern. Notice: if HtmlBasedComponent.getInnerAttrs() in a different tag, the tag must be named with "${self.uuid}!real".

<xx id="${self.uuid}"${self.outerAttrs}>
 <yy id="${self.uuid}!real"${self.innerAttrs}>...

Note: This class handles non-deferrable event listeners automatically. However, you have to invoke AbstractComponent.appendAsapAttr(java.lang.StringBuffer, java.lang.String) for each event the component handles in HtmlBasedComponent.getOuterAttrs() as follows.

        appendAsapAttr(sb, Events.ON_OPEN);
  appendAsapAttr(sb, Events.ON_CHANGE);

Theorectically, you could put any attributes in either HtmlBasedComponent.getInnerAttrs() or HtmlBasedComponent.getOuterAttrs(). However, zkau.js assumes all attributes are put at the outer one. If you want something different, you have to provide your own setAttr (refer to how checkbox is implemented).

Overrides:

getOuterAttrs in class FormatInputElement

getInnerAttrs

public java.lang.String getInnerAttrs()

Description copied from class: XulElement

Generates the Client-Side-Action attributes to the interior tag. Reason: onfocus is the main use.

Overrides:

getInnerAttrs in class InputElement

getRealStyleFlags

protected int getRealStyleFlags()

Returns RS_NO_WIDTH|RS_NO_HEIGHT.

Overrides:

getRealStyleFlags in class HtmlBasedComponent

shallServerFormat

protected boolean shallServerFormat()

Returns whether the server-side formatting shall take place. It always returns false since the client is smart enought to handle the date format.

Overrides:

shallServerFormat in class FormatInputElement

Since:

3.5.0