Class DatePicker
- All Implemented Interfaces:
AttachNotifier
,BlurNotifier<DatePicker>
,DetachNotifier
,Focusable<DatePicker>
,FocusNotifier<DatePicker>
,HasElement
,HasEnabled
,HasHelper
,HasLabel
,HasSize
,HasStyle
,HasTheme
,HasValidation
,HasValue<AbstractField.ComponentValueChangeEvent<DatePicker,
,LocalDate>, LocalDate> HasValueAndElement<AbstractField.ComponentValueChangeEvent<DatePicker,
,LocalDate>, LocalDate> HasAllowedCharPattern
,HasAutoOpen
,HasClearButton
,HasClientValidation
,HasOverlayClassName
,HasPrefix
,HasThemeVariant<DatePickerVariant>
,HasTooltip
,HasValidationProperties
,HasValidator<LocalDate>
,Serializable
DatePicker allows setting and getting LocalDate
objects, setting
minimum and maximum date ranges and has internationalization support by using
the DatePicker.DatePickerI18n
object.
This component allows the date to be entered directly using the keyboard in the format of the current locale or through the date picker overlay. The overlay opens when the field is clicked and/or any input is entered when the field is focused.
- Author:
- Vaadin Ltd
- See Also:
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic class
The internationalization properties forDatePicker
.static class
invalid-changed
event is sent when the invalid state changes.static class
opened-changed
event is sent when the overlay opened state changes.Nested classes/interfaces inherited from class com.vaadin.flow.component.AbstractField
AbstractField.ComponentValueChangeEvent<C extends Component,
V> Nested classes/interfaces inherited from interface com.vaadin.flow.component.BlurNotifier
BlurNotifier.BlurEvent<C extends Component>
Nested classes/interfaces inherited from interface com.vaadin.flow.component.FocusNotifier
FocusNotifier.FocusEvent<C extends Component>
Nested classes/interfaces inherited from interface com.vaadin.flow.component.shared.HasClientValidation
HasClientValidation.ClientValidatedEvent
Nested classes/interfaces inherited from interface com.vaadin.flow.component.HasValue
HasValue.ValueChangeEvent<V>, HasValue.ValueChangeListener<E extends HasValue.ValueChangeEvent<?>>
-
Constructor Summary
ConstructorDescriptionDefault constructor.DatePicker
(HasValue.ValueChangeListener<AbstractField.ComponentValueChangeEvent<DatePicker, LocalDate>> listener) Convenience constructor to create a date picker with aHasValue.ValueChangeListener
.DatePicker
(String label) Convenience constructor to create a date picker with a label.DatePicker
(String label, HasValue.ValueChangeListener<AbstractField.ComponentValueChangeEvent<DatePicker, LocalDate>> listener) Convenience constructor to create a date picker with aHasValue.ValueChangeListener
and a label.DatePicker
(String label, LocalDate initialDate) Convenience constructor to create a date picker with a pre-selected date in current UI locale format and a label.DatePicker
(String label, LocalDate initialDate, HasValue.ValueChangeListener<AbstractField.ComponentValueChangeEvent<DatePicker, LocalDate>> listener) Convenience constructor to create a date picker with a pre-selected date in current UI locale format, aHasValue.ValueChangeListener
and a label.DatePicker
(LocalDate initialDate) Convenience constructor to create a date picker with a pre-selected date in current UI locale format.DatePicker
(LocalDate initialDate, HasValue.ValueChangeListener<AbstractField.ComponentValueChangeEvent<DatePicker, LocalDate>> listener) Convenience constructor to create a date picker with a pre-selected date in current UI locale format and aHasValue.ValueChangeListener
.DatePicker
(LocalDate initialDate, Locale locale) Convenience Constructor to create a date picker with pre-selected date and locale setup. -
Method Summary
Modifier and TypeMethodDescriptionAdds a listener forinvalid-changed
events fired by the webcomponent.Adds a listener foropened-changed
events fired by the webcomponent.Enables the implementing components to notify changes in their validation status to the observers.protected void
close()
Closes the datepicker overlay.Returns a validator that checks the state of the Value.getI18n()
Gets the internationalization object previously set for this component.Get the visible date when there is no value selected.getLabel()
Gets the label of the datepicker.Gets the Locale for this date pickergetMax()
Gets the maximum date in the date picker.getMin()
Gets the minimum date in the date picker.getName()
Gets the name of the DatePicker.The placeholder text that should be displayed in the input element, when the user has not entered a value.protected boolean
Returns whether the input element has a value or not.boolean
isOpened()
Gets the states of the drop-down for the datepickerboolean
Determines whether the datepicker is marked as input required.boolean
Get the state ofshowWeekNumbers
property of the datepickerprotected void
onAttach
(AttachEvent attachEvent) Called when the component is attached to a UI.void
open()
Opens the datepicker overlay.void
Sets the internationalization properties for this component.void
setInitialPosition
(LocalDate initialPosition) Date which should be visible when there is no value selected.void
Sets the label for the datepicker.void
Set the Locale for the Date Picker.void
Sets the maximum date in the date picker.void
Sets the minimum date in the date picker.void
Sets the name of the DatePicker.void
setOpened
(boolean opened) Sets the opened property of the datepicker to open or close its overlay.void
setPlaceholder
(String placeholder) Sets the placeholder text that should be displayed in the input element, when the user has not entered a value.void
setRequired
(boolean required) Sets whether the date picker is marked as input required.void
setRequiredIndicatorVisible
(boolean required) Sets the required indicator visible or not.void
Sets the value of this object.void
setWeekNumbersVisible
(boolean weekNumbersVisible) Set the week number visible in the DatePicker.protected void
validate()
Performs server-side validation of the current value.Methods inherited from class com.vaadin.flow.component.AbstractSinglePropertyField
getSynchronizationRegistration, hasValidValue, setPresentationValue, setSynchronizedEvent
Methods inherited from class com.vaadin.flow.component.AbstractField
addValueChangeListener, getEmptyValue, getValue, isEmpty, setModelValue, valueEquals
Methods inherited from class com.vaadin.flow.component.Component
addListener, findAncestor, fireEvent, from, get, getChildren, getElement, getEventBus, getId, getListeners, getParent, getTranslation, getTranslation, getTranslation, getTranslation, getTranslation, getTranslation, getUI, hasListener, isAttached, isTemplateMapped, isVisible, onDetach, onEnabledStateChanged, removeFromParent, scrollIntoView, scrollIntoView, set, setElement, setId, setVisible
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface com.vaadin.flow.component.AttachNotifier
addAttachListener
Methods inherited from interface com.vaadin.flow.component.BlurNotifier
addBlurListener
Methods inherited from interface com.vaadin.flow.component.DetachNotifier
addDetachListener
Methods inherited from interface com.vaadin.flow.component.Focusable
addFocusShortcut, blur, focus, getTabIndex, setTabIndex
Methods inherited from interface com.vaadin.flow.component.FocusNotifier
addFocusListener
Methods inherited from interface com.vaadin.flow.component.shared.HasAllowedCharPattern
getAllowedCharPattern, setAllowedCharPattern
Methods inherited from interface com.vaadin.flow.component.shared.HasAutoOpen
isAutoOpen, setAutoOpen
Methods inherited from interface com.vaadin.flow.component.shared.HasClearButton
isClearButtonVisible, setClearButtonVisible
Methods inherited from interface com.vaadin.flow.component.shared.HasClientValidation
addClientValidatedEventListener
Methods inherited from interface com.vaadin.flow.component.HasElement
getElement
Methods inherited from interface com.vaadin.flow.component.HasEnabled
isEnabled, setEnabled
Methods inherited from interface com.vaadin.flow.component.HasHelper
getHelperComponent, getHelperText, setHelperComponent, setHelperText
Methods inherited from interface com.vaadin.flow.component.shared.HasOverlayClassName
getOverlayClassName, setOverlayClassName
Methods inherited from interface com.vaadin.flow.component.shared.HasPrefix
getPrefixComponent, setPrefixComponent
Methods inherited from interface com.vaadin.flow.component.HasSize
getHeight, getHeightUnit, getMaxHeight, getMaxWidth, getMinHeight, getMinWidth, getWidth, getWidthUnit, setHeight, setHeight, setHeightFull, setMaxHeight, setMaxHeight, setMaxWidth, setMaxWidth, setMinHeight, setMinHeight, setMinWidth, setMinWidth, setSizeFull, setSizeUndefined, setWidth, setWidth, setWidthFull
Methods inherited from interface com.vaadin.flow.component.HasStyle
addClassName, addClassNames, getClassName, getClassNames, getStyle, hasClassName, removeClassName, removeClassNames, setClassName, setClassName
Methods inherited from interface com.vaadin.flow.component.HasTheme
addThemeName, addThemeNames, getThemeName, getThemeNames, hasThemeName, removeThemeName, removeThemeNames, setThemeName, setThemeName
Methods inherited from interface com.vaadin.flow.component.shared.HasThemeVariant
addThemeVariants, removeThemeVariants
Methods inherited from interface com.vaadin.flow.component.shared.HasTooltip
getTooltip, setTooltipText
Methods inherited from interface com.vaadin.flow.component.shared.HasValidationProperties
getErrorMessage, isInvalid, setErrorMessage, setInvalid
Methods inherited from interface com.vaadin.flow.component.HasValue
clear, getOptionalValue
Methods inherited from interface com.vaadin.flow.component.HasValueAndElement
isReadOnly, isRequiredIndicatorVisible, setReadOnly
-
Constructor Details
-
DatePicker
public DatePicker()Default constructor. -
DatePicker
Convenience constructor to create a date picker with a pre-selected date in current UI locale format.- Parameters:
initialDate
- the pre-selected date in the picker- See Also:
-
DatePicker
Convenience constructor to create a date picker with a label.- Parameters:
label
- the label describing the date picker- See Also:
-
DatePicker
Convenience constructor to create a date picker with a pre-selected date in current UI locale format and a label.- Parameters:
label
- the label describing the date pickerinitialDate
- the pre-selected date in the picker- See Also:
-
DatePicker
public DatePicker(HasValue.ValueChangeListener<AbstractField.ComponentValueChangeEvent<DatePicker, LocalDate>> listener) Convenience constructor to create a date picker with aHasValue.ValueChangeListener
.- Parameters:
listener
- the listener to receive value change events- See Also:
-
DatePicker
public DatePicker(String label, HasValue.ValueChangeListener<AbstractField.ComponentValueChangeEvent<DatePicker, LocalDate>> listener) Convenience constructor to create a date picker with aHasValue.ValueChangeListener
and a label.- Parameters:
label
- the label describing the date pickerlistener
- the listener to receive value change events- See Also:
-
DatePicker
public DatePicker(LocalDate initialDate, HasValue.ValueChangeListener<AbstractField.ComponentValueChangeEvent<DatePicker, LocalDate>> listener) Convenience constructor to create a date picker with a pre-selected date in current UI locale format and aHasValue.ValueChangeListener
.- Parameters:
initialDate
- the pre-selected date in the pickerlistener
- the listener to receive value change events- See Also:
-
DatePicker
public DatePicker(String label, LocalDate initialDate, HasValue.ValueChangeListener<AbstractField.ComponentValueChangeEvent<DatePicker, LocalDate>> listener) Convenience constructor to create a date picker with a pre-selected date in current UI locale format, aHasValue.ValueChangeListener
and a label.- Parameters:
label
- the label describing the date pickerinitialDate
- the pre-selected date in the pickerlistener
- the listener to receive value change events- See Also:
-
DatePicker
Convenience Constructor to create a date picker with pre-selected date and locale setup.- Parameters:
initialDate
- the pre-selected date in the pickerlocale
- the locale for the date picker
-
-
Method Details
-
setMin
Sets the minimum date in the date picker. Dates before that will be disabled in the popup.- Parameters:
min
- the minimum date that is allowed to be selected, ornull
to remove any minimum constraints
-
getMin
Gets the minimum date in the date picker. Dates before that will be disabled in the popup.- Returns:
- the minimum date that is allowed to be selected, or
null
if there's no minimum
-
setMax
Sets the maximum date in the date picker. Dates after that will be disabled in the popup.- Parameters:
max
- the maximum date that is allowed to be selected, ornull
to remove any maximum constraints
-
getMax
Gets the maximum date in the date picker. Dates after that will be disabled in the popup.- Returns:
- the maximum date that is allowed to be selected, or
null
if there's no maximum
-
setLocale
Set the Locale for the Date Picker. The displayed date will be matched to the format used in that locale.NOTE:Supported formats are MM/DD/YYYY, DD/MM/YYYY and YYYY/MM/DD. Browser compatibility can be different based on the browser and mobile devices, you can check here for more details: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toLocaleDateString
When using custom date formats through
setI18n(DatePickerI18n)
, setting a locale has no effect, and dates will always be parsed and displayed using the custom date format.- Parameters:
locale
- the locale set to the date picker, cannot be null
-
getLocale
Gets the Locale for this date picker -
onAttach
Description copied from class:Component
Called when the component is attached to a UI.The default implementation does nothing.
This method is invoked before the
AttachEvent
is fired for the component. -
getI18n
Gets the internationalization object previously set for this component.Note: updating the object content that is gotten from this method will not update the lang on the component if not set back using
setI18n(DatePickerI18n)
- Returns:
- the i18n object. It will be
null
, If the i18n properties weren't set.
-
setI18n
Sets the internationalization properties for this component.- Parameters:
i18n
- the internationalized properties, notnull
-
getDefaultValidator
Description copied from interface:HasValidator
Returns a validator that checks the state of the Value. This should be overridden for components with internal value conversion or validation, e.g. when the user is providing a string that has to be parsed into a date. An invalid input from user will be exposed to aBinder
and can be seen as a validation failure.- Specified by:
getDefaultValidator
in interfaceHasValidator<LocalDate>
- Returns:
- state validator
-
addValidationStatusChangeListener
public Registration addValidationStatusChangeListener(ValidationStatusChangeListener<LocalDate> listener) Description copied from interface:HasValidator
Enables the implementing components to notify changes in their validation status to the observers.Note: This method can be overridden by the implementing classes e.g. components, to enable the associated
Binder.Binding
instance subscribing for their validation change events and revalidate itself.This method primarily designed for notifying the Binding about the validation status changes of a bound component at the client-side. WebComponents such as
<vaadin-date-picker>
or any other component that accept a formatted text as input should be able to communicate their invalid status to their server-side instance, and a bound server-side component instance must notify its binding about this validation status change as well. When the binding instance revalidates, a chain of validators and convertors get executed one of which is the default validator provided byHasValidator.getDefaultValidator()
. Thus, In order for the binding to be able to show/clear errors for its associated bound field, it is important that implementing components take that validation status into account while implementing any validator and converter includingHasValidator.getDefaultValidator()
. Here is an example:@Tag("date-picker-demo") public class DatePickerDemo implements HasValidator<LocalDate> { // Each web component has a way to communicate its validation status // to its server-side component instance. The following clientSideValid // state is introduced here just for the sake of simplicity of this code // snippet: boolean clientSideValid = true; /** * Note how
clientSideValid
engaged in the definition * of this method. It is important to reflect this status either * in the returning validation result of this method or any other * validation that is associated with this component. */ @Override public Validator getDefaultValidator() { return (value, valueContext) -> clientSideValid ? ValidationResult.ok() : ValidationResult.error("Invalid date format"); } private final Collection<ValidationStatusChangeListener<LocalDate>> validationStatusListeners = new ArrayList<>(); /** * This enables the binding to subscribe for the validation status * change events that are fired by this component and revalidate * itself respectively. */ @Override public Registration addValidationStatusChangeListener( ValidationStatusChangeListener<LocalDate> listener) { validationStatusListeners.add(listener); return () -> validationStatusListeners.remove(listener); } private void fireValidationStatusChangeEvent( boolean newValidationStatus) { if (this.clientSideValid != newValidationStatus) { this.clientSideValid = newValidationStatus; var event = new ValidationStatusChangeEvent<>(this, newValidationStatus); validationStatusListeners.forEach( listener -> listener.validationStatusChanged(event)); } } }- Specified by:
addValidationStatusChangeListener
in interfaceHasValidator<LocalDate>
- Returns:
- Registration of the added listener.
- See Also:
-
isInputValuePresent
@Synchronize(property="_hasInputValue", value="has-input-value-changed") protected boolean isInputValuePresent()Returns whether the input element has a value or not.- Returns:
true
if the input element's value is populated,false
otherwise
-
setValue
Description copied from interface:HasValue
Sets the value of this object. If the new value is not equal togetValue()
, fires a value change event. May throwIllegalArgumentException
if the value is not acceptable.Implementation note: the implementing class should document whether null values are accepted or not, and override
HasValue.getEmptyValue()
if the empty value is notnull
.- Specified by:
setValue
in interfaceHasValue<AbstractField.ComponentValueChangeEvent<DatePicker,
LocalDate>, LocalDate> - Overrides:
setValue
in classAbstractField<DatePicker,
LocalDate> - Parameters:
value
- the new value
-
setLabel
Sets the label for the datepicker. -
getLabel
Gets the label of the datepicker. -
setPlaceholder
Sets the placeholder text that should be displayed in the input element, when the user has not entered a value.- Parameters:
placeholder
- the placeholder text
-
getPlaceholder
The placeholder text that should be displayed in the input element, when the user has not entered a value.- Returns:
- the
placeholder
property of the datepicker
-
setInitialPosition
Date which should be visible when there is no value selected.The same date formats as for the
value
property are supported.- Parameters:
initialPosition
- the LocalDate value to set
-
getInitialPosition
Get the visible date when there is no value selected.The same date formats as for the
value
property are supported.This property is not synchronized automatically from the client side, so the returned value may not be the same as in client side.
- Returns:
- the
initialPosition
property from the datepicker
-
setRequired
public void setRequired(boolean required) Sets whether the date picker is marked as input required.- Parameters:
required
- the boolean value to set
-
setRequiredIndicatorVisible
public void setRequiredIndicatorVisible(boolean required) Description copied from interface:HasValue
Sets the required indicator visible or not.If set visible, it is visually indicated in the user interface.
The method is intended to be used with
Binder
which does server-side validation. In case HTML element has its own (client-side) validation it should be disabled whensetRequiredIndicatorVisible(true)
is called and re-enabled back onsetRequiredIndicatorVisible(false)
. It's responsibility of each component implementation to follow the contract so that the method call doesn't do anything else than show/hide the "required" indication. Usually components provide their ownsetRequired
method which should be called in case the client-side validation is required.- Specified by:
setRequiredIndicatorVisible
in interfaceHasValue<AbstractField.ComponentValueChangeEvent<DatePicker,
LocalDate>, LocalDate> - Specified by:
setRequiredIndicatorVisible
in interfaceHasValueAndElement<AbstractField.ComponentValueChangeEvent<DatePicker,
LocalDate>, LocalDate> - Parameters:
required
-true
to make the required indicator visible,false
if not
-
isRequired
public boolean isRequired()Determines whether the datepicker is marked as input required.This property is not synchronized automatically from the client side, so the returned value may not be the same as in client side.
- Returns:
true
if the input is required,false
otherwise
-
setWeekNumbersVisible
public void setWeekNumbersVisible(boolean weekNumbersVisible) Set the week number visible in the DatePicker.Set true to display ISO-8601 week numbers in the calendar.
Notice that displaying week numbers is only supported when i18n.firstDayOfWeek is 1 (Monday).
- Parameters:
weekNumbersVisible
- the boolean value to set
-
isWeekNumbersVisible
public boolean isWeekNumbersVisible()Get the state ofshowWeekNumbers
property of the datepickerThis property is not synchronized automatically from the client side, so the returned value may not be the same as in client side.
- Returns:
- the
showWeekNumbers
property from the datepicker
-
setOpened
public void setOpened(boolean opened) Sets the opened property of the datepicker to open or close its overlay.- Parameters:
opened
-true
to open the datepicker overlay,false
to close it
-
open
public void open()Opens the datepicker overlay. -
close
protected void close()Closes the datepicker overlay. -
isOpened
public boolean isOpened()Gets the states of the drop-down for the datepicker- Returns:
true
if the drop-down is opened,false
otherwise
-
setName
Sets the name of the DatePicker.- Parameters:
name
- the string value to set
-
getName
Gets the name of the DatePicker.- Returns:
- the
name
property from the DatePicker
-
validate
protected void validate()Performs server-side validation of the current value. This is needed because it is possible to circumvent the client-side validation constraints using browser development tools. -
addOpenedChangeListener
public Registration addOpenedChangeListener(ComponentEventListener<DatePicker.OpenedChangeEvent> listener) Adds a listener foropened-changed
events fired by the webcomponent.- Parameters:
listener
- the listener- Returns:
- a
Registration
for removing the event listener
-
addInvalidChangeListener
public Registration addInvalidChangeListener(ComponentEventListener<DatePicker.InvalidChangeEvent> listener) Adds a listener forinvalid-changed
events fired by the webcomponent.- Parameters:
listener
- the listener- Returns:
- a
Registration
for removing the event listener
-