com.vaadin.ui
Class DateField

java.lang.Object
  extended by com.vaadin.terminal.AbstractClientConnector
      extended by com.vaadin.ui.AbstractComponent
          extended by com.vaadin.ui.AbstractField<Date>
              extended by com.vaadin.ui.DateField
All Implemented Interfaces:
Buffered, BufferedValidatable, Property<Date>, Property.Editor, Property.ReadOnlyStatusChangeListener, Property.ReadOnlyStatusChangeNotifier, Property.ValueChangeListener, Property.ValueChangeNotifier, Property.Viewer, Validatable, Action.ShortcutNotifier, FieldEvents.BlurNotifier, FieldEvents.FocusNotifier, MethodEventSource, Connector, ClientConnector, RpcTarget, Sizeable, Vaadin6Component, VariableOwner, Component, Component.Focusable, Field<Date>, Serializable, EventListener
Direct Known Subclasses:
InlineDateField, PopupDateField

public class DateField
extends AbstractField<Date>
implements FieldEvents.BlurNotifier, FieldEvents.FocusNotifier, Vaadin6Component

A date editor component that can be bound to any Property that is compatible with java.util.Date.

Since DateField extends AbstractField it implements the Bufferedinterface.

A DateField is in write-through mode by default, so AbstractField.setWriteThrough(boolean)must be called to enable buffering.

Since:
3.0
Version:
7.0.0.alpha3
Author:
Vaadin Ltd.
See Also:
Serialized Form

Nested Class Summary
static class DateField.Resolution
          Resolutions for DateFields
static class DateField.UnparsableDateString
           
 
Nested classes/interfaces inherited from class com.vaadin.ui.AbstractField
AbstractField.FocusShortcut, AbstractField.ReadOnlyStatusChangeEvent
 
Nested classes/interfaces inherited from class com.vaadin.ui.AbstractComponent
AbstractComponent.ComponentErrorEvent, AbstractComponent.ComponentErrorHandler
 
Nested classes/interfaces inherited from interface com.vaadin.terminal.VariableOwner
VariableOwner.ErrorEvent
 
Nested classes/interfaces inherited from interface com.vaadin.ui.Component
Component.ErrorEvent, Component.ErrorListener, Component.Event, Component.Focusable, Component.Listener
 
Nested classes/interfaces inherited from interface com.vaadin.terminal.Sizeable
Sizeable.Unit
 
Nested classes/interfaces inherited from interface com.vaadin.ui.Field
Field.ValueChangeEvent
 
Nested classes/interfaces inherited from interface com.vaadin.data.Buffered
Buffered.SourceException
 
Nested classes/interfaces inherited from interface com.vaadin.data.Property
Property.Editor, Property.ReadOnlyException, Property.ReadOnlyStatusChangeListener, Property.ReadOnlyStatusChangeNotifier, Property.Transactional<T>, Property.ValueChangeListener, Property.ValueChangeNotifier, Property.Viewer
 
Field Summary
static DateField.Resolution RESOLUTION_DAY
          Deprecated. Use DateField.Resolution.DAY
static DateField.Resolution RESOLUTION_HOUR
          Deprecated. Use DateField.Resolution.HOUR
static DateField.Resolution RESOLUTION_MIN
          Deprecated. Use DateField.Resolution.MINUTE
static DateField.Resolution RESOLUTION_MONTH
          Deprecated. Use DateField.Resolution.MONTH
static DateField.Resolution RESOLUTION_SEC
          Deprecated. Use DateField.Resolution.SECOND
static DateField.Resolution RESOLUTION_YEAR
          Deprecated. Use DateField.Resolution.YEAR
 
Fields inherited from interface com.vaadin.terminal.Sizeable
SIZE_UNDEFINED, UNITS_CM, UNITS_EM, UNITS_EX, UNITS_INCH, UNITS_MM, UNITS_PERCENTAGE, UNITS_PICAS, UNITS_PIXELS, UNITS_POINTS
 
Constructor Summary
DateField()
          Constructs an empty DateField with no caption.
DateField(Property dataSource)
          Constructs a new DateField that's bound to the specified Property and has no caption.
DateField(String caption)
          Constructs an empty DateField with caption.
DateField(String caption, Date value)
          Constructs a new DateField with the given caption and initial text contents.
DateField(String caption, Property dataSource)
          Constructs a new DateField that's bound to the specified Property and has the given caption String.
 
Method Summary
 void addListener(FieldEvents.BlurListener listener)
          Adds a BlurListener to the Component which gets fired when a Field loses keyboard focus.
 void addListener(FieldEvents.FocusListener listener)
          Adds a FocusListener to the Component which gets fired when a Field receives keyboard focus.
 void changeVariables(Object source, Map<String,Object> variables)
          Called when one or more variables handled by the implementing class are changed.
 String getDateFormat()
          Returns a format string used to format date value on client side or null if default formatting from Component.getLocale() is used.
 String getParseErrorMessage()
          Return the error message that is shown if the user inputted value can't be parsed into a Date object.
 DateField.Resolution getResolution()
          Gets the resolution.
 TimeZone getTimeZone()
          Gets the time zone used by this field.
 Class<Date> getType()
          Returns the type of the Field.
protected  Date handleUnparsableDateString(String dateString)
          This method is called to handle a non-empty date string from the client if the client could not parse it as a Date.
 boolean isLenient()
          Returns whether date/time interpretation is to be lenient.
 boolean isShowISOWeekNumbers()
          Checks whether ISO 8601 week numbers are shown in the date selector.
 void paintContent(PaintTarget target)
           Paints the Paintable into a UIDL stream.
 void removeListener(FieldEvents.BlurListener listener)
          Removes a BlurListener from the Component.
 void removeListener(FieldEvents.FocusListener listener)
          Removes a FocusListener from the Component.
 void setDateFormat(String dateFormat)
          Sets formatting used by some component implementations.
protected  void setInternalValue(Date newValue)
          Sets the internal field value.
 void setLenient(boolean lenient)
          Specifies whether or not date/time interpretation in component is to be lenient.
 void setParseErrorMessage(String parsingErrorMessage)
          Sets the default error message used if the DateField cannot parse the text input by user to a Date field.
 void setResolution(DateField.Resolution resolution)
          Sets the resolution of the DateField.
 void setShowISOWeekNumbers(boolean showWeekNumbers)
          Sets the visibility of ISO 8601 week numbers in the date selector.
 void setTimeZone(TimeZone timeZone)
          Sets the time zone used by this date field.
protected  void setValue(Date newValue, boolean repaintIsNotNeeded)
          Sets the value of the field.
protected  boolean shouldHideErrors()
          Returns true if the error indicator be hidden when painting the component even when there are errors.
 void validate()
          Validates the current value against registered validators if the field is not empty.
 
Methods inherited from class com.vaadin.ui.AbstractField
addListener, addListener, addValidator, attach, commit, detach, discard, fireReadOnlyStatusChange, fireValueChange, focus, getConversionError, getConversionError, getConvertedValue, getConverter, getCurrentBufferedSourceException, getErrorMessage, getInternalValue, getPropertyDataSource, getRequiredError, getState, getTabIndex, getValidators, getValue, isBuffered, isEmpty, isInvalidAllowed, isInvalidCommitted, isModified, isReadOnly, isReadThrough, isRequired, isValid, isValidationVisible, isWriteThrough, readOnlyStatusChange, removeAllValidators, removeListener, removeListener, removeValidator, setBuffered, setConversionError, setConvertedValue, setConverter, setConverter, setCurrentBufferedSourceException, setInvalidAllowed, setInvalidCommitted, setPropertyDataSource, setReadOnly, setReadThrough, setRequired, setRequiredError, setTabIndex, setValidationVisible, setValue, setWriteThrough, toString, updateState, validate, valueChange
 
Methods inherited from class com.vaadin.ui.AbstractComponent
addListener, addListener, addListener, addListener, addShortcutListener, addStyleName, findAncestor, fireComponentErrorEvent, fireComponentEvent, fireEvent, getActionManager, getApplication, getCaption, getComponentError, getData, getDebugId, getDescription, getErrorHandler, getHeight, getHeightUnits, getIcon, getListeners, getLocale, getParent, getRoot, getStyle, getStyleName, getWidth, getWidthUnits, handleError, hasListeners, isConnectorEnabled, isEnabled, isImmediate, isVisible, removeListener, removeListener, removeListener, removeListener, removeListener, removeShortcutListener, removeStyleName, requestRepaint, setCaption, setComponentError, setData, setDebugId, setDescription, setEnabled, setErrorHandler, setHeight, setHeight, setIcon, setImmediate, setLocale, setParent, setSizeFull, setSizeUndefined, setStyle, setStyleName, setVisible, setWidth, setWidth
 
Methods inherited from class com.vaadin.terminal.AbstractClientConnector
addExtension, addMethodInvocationToQueue, createState, getAllChildrenIterable, getConnectorId, getExtensions, getRpcManager, getRpcProxy, getStateType, registerRpc, registerRpc, removeExtension, requestRepaintAll, retrievePendingRpcCalls
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface com.vaadin.terminal.VariableOwner
isEnabled, isImmediate
 
Methods inherited from interface com.vaadin.ui.Component
addListener, addStyleName, attach, getApplication, getCaption, getDebugId, getIcon, getLocale, getParent, getRoot, getState, getStyleName, isEnabled, isReadOnly, isVisible, removeListener, removeStyleName, setCaption, setDebugId, setEnabled, setIcon, setReadOnly, setStyleName, setVisible, updateState
 
Methods inherited from interface com.vaadin.terminal.gwt.server.ClientConnector
detach, getExtensions, getStateType, isConnectorEnabled, removeExtension, requestRepaint, requestRepaintAll, retrievePendingRpcCalls, setParent
 
Methods inherited from interface com.vaadin.terminal.gwt.client.Connector
getConnectorId
 
Methods inherited from interface com.vaadin.terminal.gwt.server.RpcTarget
getRpcManager
 
Methods inherited from interface com.vaadin.terminal.Sizeable
getHeight, getHeightUnits, getWidth, getWidthUnits, setHeight, setHeight, setSizeFull, setSizeUndefined, setWidth, setWidth
 
Methods inherited from interface com.vaadin.event.Action.ShortcutNotifier
addShortcutListener, removeShortcutListener
 

Field Detail

RESOLUTION_SEC

@Deprecated
public static final DateField.Resolution RESOLUTION_SEC
Deprecated. Use DateField.Resolution.SECOND
Resolution identifier: seconds.


RESOLUTION_MIN

@Deprecated
public static final DateField.Resolution RESOLUTION_MIN
Deprecated. Use DateField.Resolution.MINUTE
Resolution identifier: minutes.


RESOLUTION_HOUR

@Deprecated
public static final DateField.Resolution RESOLUTION_HOUR
Deprecated. Use DateField.Resolution.HOUR
Resolution identifier: hours.


RESOLUTION_DAY

@Deprecated
public static final DateField.Resolution RESOLUTION_DAY
Deprecated. Use DateField.Resolution.DAY
Resolution identifier: days.


RESOLUTION_MONTH

@Deprecated
public static final DateField.Resolution RESOLUTION_MONTH
Deprecated. Use DateField.Resolution.MONTH
Resolution identifier: months.


RESOLUTION_YEAR

@Deprecated
public static final DateField.Resolution RESOLUTION_YEAR
Deprecated. Use DateField.Resolution.YEAR
Resolution identifier: years.

Constructor Detail

DateField

public DateField()
Constructs an empty DateField with no caption.


DateField

public DateField(String caption)
Constructs an empty DateField with caption.

Parameters:
caption - the caption of the datefield.

DateField

public DateField(String caption,
                 Property dataSource)
Constructs a new DateField that's bound to the specified Property and has the given caption String.

Parameters:
caption - the caption String for the editor.
dataSource - the Property to be edited with this editor.

DateField

public DateField(Property dataSource)
          throws IllegalArgumentException
Constructs a new DateField that's bound to the specified Property and has no caption.

Parameters:
dataSource - the Property to be edited with this editor.
Throws:
IllegalArgumentException

DateField

public DateField(String caption,
                 Date value)
Constructs a new DateField with the given caption and initial text contents. The editor constructed this way will not be bound to a Property unless Property.Viewer.setPropertyDataSource(Property) is called to bind it.

Parameters:
caption - the caption String for the editor.
value - the Date value.
Method Detail

paintContent

public void paintContent(PaintTarget target)
                  throws PaintException
Description copied from interface: Vaadin6Component

Paints the Paintable into a UIDL stream. This method creates the UIDL sequence describing it and outputs it to the given UIDL stream.

It is called when the contents of the component should be painted in response to the component first being shown or having been altered so that its visual representation is changed.

Specified by:
paintContent in interface Vaadin6Component
Parameters:
target - the target UIDL stream where the component should paint itself to.
Throws:
PaintException - if the paint operation failed.

shouldHideErrors

protected boolean shouldHideErrors()
Description copied from class: AbstractField
Returns true if the error indicator be hidden when painting the component even when there are errors. This is a mostly internal method, but can be overridden in subclasses e.g. if the error indicator should also be shown for empty fields in some cases.

Overrides:
shouldHideErrors in class AbstractField<Date>
Returns:
true to hide the error indicator, false to use the normal logic to show it when there are errors

changeVariables

public void changeVariables(Object source,
                            Map<String,Object> variables)
Description copied from interface: VariableOwner
Called when one or more variables handled by the implementing class are changed.

Specified by:
changeVariables in interface VariableOwner
Parameters:
source - the Source of the variable change. This is the origin of the event. For example in Web Adapter this is the request.
variables - the Mapping from variable names to new variable values.

handleUnparsableDateString

protected Date handleUnparsableDateString(String dateString)
                                   throws Converter.ConversionException
This method is called to handle a non-empty date string from the client if the client could not parse it as a Date. By default, a Converter.ConversionException is thrown, and the current value is not modified. This can be overridden to handle conversions, to return null (equivalent to empty input), to throw an exception or to fire an event.

Parameters:
dateString -
Returns:
parsed Date
Throws:
Converter.ConversionException - to keep the old value and indicate an error

getType

public Class<Date> getType()
Description copied from class: AbstractField
Returns the type of the Field. The methods getValue and setValue must be compatible with this type: one must be able to safely cast the value returned from getValue to the given type and pass any variable assignable to this type as an argument to setValue.

Specified by:
getType in interface Property<Date>
Specified by:
getType in class AbstractField<Date>
Returns:
the type of the Field

setValue

protected void setValue(Date newValue,
                        boolean repaintIsNotNeeded)
                 throws Property.ReadOnlyException
Description copied from class: AbstractField
Sets the value of the field.

Overrides:
setValue in class AbstractField<Date>
Parameters:
newValue - the New value of the field.
repaintIsNotNeeded - True iff caller is sure that repaint is not needed.
Throws:
Property.ReadOnlyException

setInternalValue

protected void setInternalValue(Date newValue)
Description copied from class: AbstractField
Sets the internal field value. This is purely used by AbstractField to change the internal Field value. It does not trigger valuechange events. It can be overridden by the inheriting classes to update all dependent variables. Subclasses can also override AbstractField.getInternalValue() if necessary.

Overrides:
setInternalValue in class AbstractField<Date>
Parameters:
newValue - the new value to be set.

getResolution

public DateField.Resolution getResolution()
Gets the resolution.

Returns:
int

setResolution

public void setResolution(DateField.Resolution resolution)
Sets the resolution of the DateField. The default resolution is DateField.Resolution.DAY since Vaadin 7.0.

Parameters:
resolution - the resolution to set.

setDateFormat

public void setDateFormat(String dateFormat)
Sets formatting used by some component implementations. See SimpleDateFormat for format details. By default it is encouraged to used default formatting defined by Locale, but due some JVM bugs it is sometimes necessary to use this method to override formatting. See Vaadin issue #2200.

Parameters:
dateFormat - the dateFormat to set
See Also:
com.vaadin.ui.AbstractComponent#setLocale(Locale))

getDateFormat

public String getDateFormat()
Returns a format string used to format date value on client side or null if default formatting from Component.getLocale() is used.

Returns:
the dateFormat

setLenient

public void setLenient(boolean lenient)
Specifies whether or not date/time interpretation in component is to be lenient.

Parameters:
lenient - true if the lenient mode is to be turned on; false if it is to be turned off.
See Also:
Calendar.setLenient(boolean), isLenient()

isLenient

public boolean isLenient()
Returns whether date/time interpretation is to be lenient.

Returns:
true if the interpretation mode of this calendar is lenient; false otherwise.
See Also:
setLenient(boolean)

addListener

public void addListener(FieldEvents.FocusListener listener)
Description copied from interface: FieldEvents.FocusNotifier
Adds a FocusListener to the Component which gets fired when a Field receives keyboard focus.

Specified by:
addListener in interface FieldEvents.FocusNotifier
See Also:
FieldEvents.FocusListener

removeListener

public void removeListener(FieldEvents.FocusListener listener)
Description copied from interface: FieldEvents.FocusNotifier
Removes a FocusListener from the Component.

Specified by:
removeListener in interface FieldEvents.FocusNotifier
See Also:
FieldEvents.FocusListener

addListener

public void addListener(FieldEvents.BlurListener listener)
Description copied from interface: FieldEvents.BlurNotifier
Adds a BlurListener to the Component which gets fired when a Field loses keyboard focus.

Specified by:
addListener in interface FieldEvents.BlurNotifier
See Also:
FieldEvents.BlurListener

removeListener

public void removeListener(FieldEvents.BlurListener listener)
Description copied from interface: FieldEvents.BlurNotifier
Removes a BlurListener from the Component.

Specified by:
removeListener in interface FieldEvents.BlurNotifier
See Also:
FieldEvents.BlurListener

isShowISOWeekNumbers

public boolean isShowISOWeekNumbers()
Checks whether ISO 8601 week numbers are shown in the date selector.

Returns:
true if week numbers are shown, false otherwise.

setShowISOWeekNumbers

public void setShowISOWeekNumbers(boolean showWeekNumbers)
Sets the visibility of ISO 8601 week numbers in the date selector. ISO 8601 defines that a week always starts with a Monday so the week numbers are only shown if this is the case.

Parameters:
showWeekNumbers - true if week numbers should be shown, false otherwise.

validate

public void validate()
              throws Validator.InvalidValueException
Validates the current value against registered validators if the field is not empty. Note that DateField is considered empty (value == null) and invalid if it contains text typed in by the user that couldn't be parsed into a Date value.

Specified by:
validate in interface Validatable
Overrides:
validate in class AbstractField<Date>
Throws:
Validator.InvalidValueException - if the value is not valid
See Also:
AbstractField.validate()

getParseErrorMessage

public String getParseErrorMessage()
Return the error message that is shown if the user inputted value can't be parsed into a Date object. If handleUnparsableDateString(String) is overridden and it throws a custom exception, the message returned by Throwable.getLocalizedMessage() will be used instead of the value returned by this method.

Returns:
the error message that the DateField uses when it can't parse the textual input from user to a Date object
See Also:
setParseErrorMessage(String)

setParseErrorMessage

public void setParseErrorMessage(String parsingErrorMessage)
Sets the default error message used if the DateField cannot parse the text input by user to a Date field. Note that if the handleUnparsableDateString(String) method is overridden, the localized message from its exception is used.

Parameters:
parsingErrorMessage -
See Also:
getParseErrorMessage(), handleUnparsableDateString(String)

setTimeZone

public void setTimeZone(TimeZone timeZone)
Sets the time zone used by this date field. The time zone is used to convert the absolute time in a Date object to a logical time displayed in the selector and to convert the select time back to a Date object. If no time zone has been set, the current default time zone returned by TimeZone.getDefault() is used.

Parameters:
timeZone - the time zone to use for time calculations.
See Also:
getTimeZone()

getTimeZone

public TimeZone getTimeZone()
Gets the time zone used by this field. The time zone is used to convert the absolute time in a Date object to a logical time displayed in the selector and to convert the select time back to a Date object. If null is returned, the current default time zone returned by TimeZone.getDefault() is used.

Returns:
the current time zone


Copyright © 2000-2011 Vaadin Ltd. All Rights Reserved.