Interface IDatebox
-
- All Superinterfaces:
IAnyGroup<IDatebox>
,IChildrenOfInputgroup<IDatebox>
,IComponent<IDatebox>
,IDateTimeFormatInputElement<IDatebox>
,IFormatInputElement<IDatebox,java.util.Date>
,IHtmlBasedComponent<IDatebox>
,IInputElement<IDatebox,java.util.Date>
,IReadonly<IDatebox>
,IXulElement<IDatebox>
public interface IDatebox extends IDateTimeFormatInputElement<IDatebox>, IAnyGroup<IDatebox>
ImmutableDatebox
componentAn edit box for holding a date.
The default format (
IFormatInputElement.getFormat()
) depends onDateFormats.getDateFormat(int, Locale, String)
and the current user's locale (unlessIDateTimeFormatInputElement.withLocale(Locale)
is assigned. Please refer towithFormat(String)
for more details.Support @Action
Name Action Type onTimeZoneChange Denotes the time zone of the component is changed by user. Mouseless Entry
- Alt+DOWN to pop up the
calendar
. - LEFT, RIGHT, UP and DOWN to change the selected day from the
calendar
. - ENTER to activate the selection by copying the selected day to the
datebox
control. - Alt+UP or ESC to give up the selection and close the
calendar
.
Constraint
You could specify what value to accept for input controls by use of the
constraint
attribute. It could be a combination ofno empty
,no future
,no past
, andno today
.It also supports an interval of dates. For example,
IDatebox.ofConstraint("between 20071225 and 20071203"); IDatebox.ofConstraint("before 20071225"); IDatebox.ofConstraint("after 20071225");
Notices: The format of the date in the constraint must be
yyyMMdd
. It is independent of thelocale
. The date specified in the above constraints (before/after/between
) is included. For example,"before 20071225"
includes December 25, 2007 and any day before it, and"after 20110305"
includes March 5, 2011 and any day after it.Displayed Time Zones
The image below shows the new Datebox functionality which allows the user to change the time zone to other predefined time zones.
IDatebox.ofFormat("M/d/yy KK:mm:ss a").withWidth("150px") .withDisplayedTimeZones("GMT+12", "GMT+8").withTimeZone("GMT+8") .withTimeZonesReadonly(false)
Format
You are able to format the field by providing specifying the attribute with a formatting string. The default value is
null
. When the formatting of the datebox is null, it means the date will be outputted using the formatyyyy/MM/dd
.IDatebox.ofFormat("MM/dd/yyyy");
Length Option
In addition to specifying the format explicitly, you could specify the length option. It supports four different length options mentioned at
DateFormat
, such asshort
,medium
,long
, andfull
.In addition, you could specify the format for both date and time by using the syntax:
withFormat("option_for_date+option_for_time")
For example,IDatebox.ofFormat("medium+full")
Multiple-Eras Calendar
Datebox can display some multiple-eras calendar systems including:
- ROC (Taiwan):
withLocale("zh-TW-u-ca-roc");
- Japan:
withLocale("ja-JP-u-ca-japanese");
- Buddhist:
withLocale("th-TH-u-ca-buddhist");
Position
By default, the popup position is set to
after_start
, for other possible popup positions please refer toIPopupBase.Position
The First Day of the Week
The first day of the week is decided by the locale (actually the return value of the
getFirstDayOfWeek
method in theCalendar
). You can also control the first day of the week by the use of the session attribute and the library property. Please refer to The First Day of the Week for details.2DigitYearStart
You can control the 2DigitYearStart by the use of the library property, for example,
<
library-property>
<
name>
org.zkoss.web.preferred.2DigitYearStart<
/name>
<
value>
1950<
/value>
<
/library-property>
- Author:
- katherine
- See Also:
Datebox
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static class
IDatebox.Builder
Builds instances of typeIDatebox
.static class
IDatebox.Updater
Builds an updater of typeIDatebox
forUiAgent.smartUpdate(Locator, SmartUpdater)
.
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description default boolean
getClosePopupOnTimezoneChange()
Returns whether to auto close the datebox popup after changing the timezone.default int
getCols()
Returns the cols which determines the visible width, in characters.java.time.LocalDateTime
getDefaultDateTime()
Returns the default datetime if the value is empty.default 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 java.lang.String
getPosition()
default java.lang.String
getSelectLevel()
Returns the level that a user can select.default boolean
getShowTodayLink()
Returns whether enable to show the link that jump to today in day viewdefault java.lang.String
getTodayLinkLabel()
Returns the label of the link that jump to today in day viewdefault java.lang.String
getWidgetClass()
Returns the client widget class.default boolean
isButtonVisible()
Returns whether the button (on the right of the timebox) is visible.default boolean
isLenient()
Returns whether date/time parsing is to be lenient or not.default boolean
isStrictDate()
Returns whether date/time should be strict or not.default boolean
isTimeZonesReadonly()
Returns whether the list of the time zones to display is readonly.default boolean
isWeekOfYear()
Returns whether enable to show the week number in the current calendar or not.static IDatebox
of(java.lang.String format, java.time.temporal.Temporal date)
Return the instance of the given format and date.static IDatebox
of(java.lang.String format, java.util.Date date)
Return the instance of the given format and date.static IDatebox
of(java.time.temporal.Temporal date)
Return the instance of the given date.static IDatebox
of(java.util.Date date)
Return the instance of the given date.static ITimebox
ofCols(int cols)
Returns the instance with the given cols.static IDatebox
ofConstraint(java.lang.String constraint)
Returns the instance with the given constraint.static IDatebox
ofFormat(java.lang.String format)
Returns the instance with the given format.static IDatebox
ofId(java.lang.String id)
Returns the instance with the given id.static IDatebox
ofLocale(java.lang.String locale)
Returns the instance with the given locale.static IDatebox
ofLocale(java.util.Locale locale)
Returns the instance with the given locale.IDatebox
withButtonVisible(boolean buttonVisible)
Returns a copy ofthis
immutable component with the specifiedbuttonVisible
.IDatebox
withClosePopupOnTimezoneChange(boolean closePopupOnTimezoneChange)
Returns a copy ofthis
immutable component with the specifiedclosePopupOnTimezoneChange
.IDatebox
withDefaultDateTime(java.time.LocalDateTime defaultDateTime)
Returns a copy ofthis
immutable component with the specifieddefaultDateTime
.IDatebox
withDisplayedTimeZones(java.lang.Iterable<? extends java.util.TimeZone> displayedTimeZones)
Returns a copy ofthis
immutable component with the specifieddisplayedTimeZones
.default IDatebox
withDisplayedTimeZones(java.lang.String displayedTimeZones)
Returns a copy ofthis
immutable component with the specifieddisplayedTimeZones
.default IDatebox
withDisplayedTimeZones(java.lang.String... displayedTimeZones)
Returns a copy ofthis
immutable component with the specifieddisplayedTimeZones
.default IDatebox
withDisplayedTimeZones(java.util.TimeZone... displayedTimeZones)
Returns a copy ofthis
immutable component with the specifieddisplayedTimeZones
.IDatebox
withFormat(java.lang.String format)
Returns a copy ofthis
immutable component with the specifiedformat
.IDatebox
withLenient(boolean lenient)
Returns a copy ofthis
immutable component with the specifiedlenient
.IDatebox
withPosition(java.lang.String position)
Returns a copy ofthis
immutable component with the specifiedposition
.default IDatebox
withPosition(IPopupBase.Position position)
Returns a copy ofthis
immutable component with the specifiedposition
.IDatebox
withSelectLevel(java.lang.String selectLevel)
Returns a copy ofthis
immutable component with the specifiedselectLevel
.IDatebox
withShowTodayLink(boolean showTodayLink)
Returns a copy ofthis
immutable component with the specifiedshowTodayLink
.IDatebox
withStrictDate(boolean strictDate)
Returns a copy ofthis
immutable component with the specifiedstrictDate
.IDatebox
withTimeZonesReadonly(boolean timeZonesReadonly)
Returns a copy ofthis
immutable component with the specifiedtimeZonesReadonly
.IDatebox
withTodayLinkLabel(java.lang.String todayLinkLabel)
Returns a copy ofthis
immutable component with the specifiedtodayLinkLabel
.IDatebox
withWeekOfYear(boolean weekOfYear)
Returns a copy ofthis
immutable component with the specifiedweekOfYear
.-
Methods inherited from interface org.zkoss.stateless.sul.IComponent
getAction, getActions, getClientAttributes, getId, getMold, getWidgetListeners, getWidgetOverrides, isVisible, withAction, withAction, withAction, withAction, withAction, withAction, withAction, withAction, withAction, withAction, withAction, withActions, withActions, withClientAttribute, withClientAttributes, withId, withMold, withVisible, withWidgetClass, withWidgetListener, withWidgetListeners, withWidgetOverride, withWidgetOverrides
-
Methods inherited from interface org.zkoss.stateless.sul.IDateTimeFormatInputElement
getLocale, getTimeZone, getValueInLocalDate, getValueInLocalDateTime, getValueInLocalTime, getValueInZonedDateTime, withLocale, withLocale, withTimeZone, withTimeZone, withValue, withValueInLocalDate, withValueInLocalDateTime, withValueInLocalTime, withValueInZonedDateTime
-
Methods inherited from interface org.zkoss.stateless.sul.IFormatInputElement
getFormat
-
Methods inherited from interface org.zkoss.stateless.sul.IHtmlBasedComponent
getClientAction, getDraggable, getDroppable, getHeight, getHflex, getLeft, getRenderdefer, getSclass, getStyle, getTabindex, getTooltiptext, getTop, getVflex, getWidth, getZclass, getZIndex, isFocus, withClientAction, withDraggable, withDroppable, withFocus, withHeight, withHflex, withLeft, withRenderdefer, withSclass, withStyle, withTabindex, withTabindex, withTooltiptext, withTop, withVflex, withWidth, withZclass, withZIndex
-
Methods inherited from interface org.zkoss.stateless.sul.IInputElement
getConstraint, getErrorboxIconSclass, getErrorboxSclass, getErrorMessage, getInputAttributes, getInstant, getMaxlength, getName, getPlaceholder, getValue, isDisabled, isInplace, withCols, withConstraint, withDisabled, withErrorboxIconSclass, withErrorboxSclass, withErrorMessage, withInplace, withInputAttributes, withInstant, withMaxlength, withName, withPlaceholder
-
Methods inherited from interface org.zkoss.stateless.sul.IReadonly
isReadonly, withReadonly
-
Methods inherited from interface org.zkoss.stateless.sul.IXulElement
getContext, getCtrlKeys, getPopup, getTooltip, withContext, withCtrlKeys, withPopup, withTooltip
-
-
-
-
Field Detail
-
DEFAULT
static final IDatebox DEFAULT
Constant for default attributes of this immutable component.
-
-
Method Detail
-
getWidgetClass
default java.lang.String getWidgetClass()
Returns the client widget class.Default:
"zul.db.Datebox"
- Specified by:
getWidgetClass
in interfaceIComponent<IDatebox>
-
getDisplayedTimeZones
@Nullable default 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
-
withDisplayedTimeZones
IDatebox withDisplayedTimeZones(@Nullable java.lang.Iterable<? extends java.util.TimeZone> displayedTimeZones)
Returns a copy ofthis
immutable component with the specifieddisplayedTimeZones
.Sets a list of the time zones that will be displayed at the client and allow user to select.
If the
IDateTimeFormatInputElement.getTimeZone()
is null, the first time zone in the list is assumed.- Parameters:
displayedTimeZones
- A list of the time zones to display.Default:
null
.- Returns:
- A modified copy of the
this
object
-
withDisplayedTimeZones
default IDatebox withDisplayedTimeZones(java.util.TimeZone... displayedTimeZones)
Returns a copy ofthis
immutable component with the specifieddisplayedTimeZones
.Sets a list of the time zones that will be displayed at the client and allow user to select.
If the
IDateTimeFormatInputElement.getTimeZone()
is null, the first time zone in the list is assumed.- Parameters:
displayedTimeZones
- A list of the time zones to display.Default:
null
.- Returns:
- A modified copy of the
this
object
-
withDisplayedTimeZones
default IDatebox withDisplayedTimeZones(java.lang.String displayedTimeZones)
Returns a copy ofthis
immutable component with the specifieddisplayedTimeZones
.Sets a list of the time zones that will be displayed at the client and allow user to select.
If the
IDateTimeFormatInputElement.getTimeZone()
is null, the first time zone in the list is assumed.- Parameters:
displayedTimeZones
- A list of the time zones to display.Default:
null
.- Returns:
- A modified copy of the
this
object
-
withDisplayedTimeZones
default IDatebox withDisplayedTimeZones(java.lang.String... displayedTimeZones)
Returns a copy ofthis
immutable component with the specifieddisplayedTimeZones
.Sets a list of the time zones that will be displayed at the client and allow user to select.
If the
IDateTimeFormatInputElement.getTimeZone()
is null, the first time zone in the list is assumed.- Parameters:
displayedTimeZones
- A list of the time zones to display.Default:
null
.- Returns:
- A modified copy of the
this
object
-
getDefaultDateTime
@Nullable java.time.LocalDateTime getDefaultDateTime()
Returns the default datetime if the value is empty.Default:
null
(means current datetime)
-
withDefaultDateTime
IDatebox withDefaultDateTime(@Nullable java.time.LocalDateTime defaultDateTime)
Returns a copy ofthis
immutable component with the specifieddefaultDateTime
.Sets the default datetime if the value is empty.
- Parameters:
defaultDateTime
- Default datetime. null means current datetime.Default:
null
.- Returns:
- A modified copy of the
this
object
-
isButtonVisible
default boolean isButtonVisible()
Returns whether the button (on the right of the timebox) is visible.Default:
true
.
-
withButtonVisible
IDatebox withButtonVisible(boolean buttonVisible)
Returns a copy ofthis
immutable component with the specifiedbuttonVisible
.Sets whether the button (on the right of the timebox) is visible.
- Parameters:
buttonVisible
-false
to disable the button visibility.Default:
true
.- Returns:
- A modified copy of the
this
object
-
isLenient
default boolean isLenient()
Returns whether date/time parsing is to be lenient or not.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.
Default:
true
-
withLenient
IDatebox withLenient(boolean lenient)
Returns a copy ofthis
immutable component with the specifiedlenient
.Sets whether date/time parsing is to be lenient or not.
- Parameters:
lenient
-false
to disable date/time parsing is to be lenient.Default:
true
.- Returns:
- A modified copy of the
this
object
-
isTimeZonesReadonly
default 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.Default:
false
-
withTimeZonesReadonly
IDatebox withTimeZonesReadonly(boolean timeZonesReadonly)
Returns a copy ofthis
immutable component with the specifiedtimeZonesReadonly
.Sets whether the list of the time zones to display is readonly. If readonly, the user cannot change the time zone at the client.
- Parameters:
timeZonesReadonly
-true
to make time zones options display as readonly.Default:
false
.- Returns:
- A modified copy of the
this
object
-
isWeekOfYear
default boolean isWeekOfYear()
Returns whether enable to show the week number in the current calendar or not.Default:
false
-
withWeekOfYear
IDatebox withWeekOfYear(boolean weekOfYear)
Returns a copy ofthis
immutable component with the specifiedweekOfYear
.Sets whether enable to show the week number in the current calendar or not. (ZK EE only)
- Parameters:
weekOfYear
-true
to show the week number in the current calendar.Default:
false
.- Returns:
- A modified copy of the
this
object
-
getPosition
default java.lang.String getPosition()
- Returns:
- the datebox popup position
-
withPosition
IDatebox withPosition(java.lang.String position)
Returns a copy ofthis
immutable component with the specifiedposition
.Position the popup datebox to the specified location.
- Parameters:
position
- Where to position. Default:after_start
Allowed values:- before_start
the component appears above the anchor, aligned to the left. - before_center
the component appears above the anchor, aligned to the center. - before_end
the component appears above the anchor, aligned to the right. - after_start
the component appears below the anchor, aligned to the left. - after_center
the component appears below the anchor, aligned to the center. - after_end
the component appears below the anchor, aligned to the right. - start_before
the component appears to the left of the anchor, aligned to the top. - start_center
the component appears to the left of the anchor, aligned to the middle. - start_after
the component appears to the left of the anchor, aligned to the bottom. - end_before
the component appears to the right of the anchor, aligned to the top. - end_center
the component appears to the right of the anchor, aligned to the middle. - end_after
the component appears to the right of the anchor, aligned to the bottom. - overlap/top_left
the component overlaps the anchor, with anchor and element aligned at top-left. - top_center
the component overlaps the anchor, with anchor and element aligned at top-center. - overlap_end/top_right
the component overlaps the anchor, with anchor and element aligned at top-right. - middle_left
the component overlaps the anchor, with anchor and element aligned at middle-left. - middle_center
the component overlaps the anchor, with anchor and element aligned at middle-center. - middle_right
the component overlaps the anchor, with anchor and element aligned at middle-right. - overlap_before/bottom_left
the component overlaps the anchor, with anchor and element aligned at bottom-left. - bottom_center
the component overlaps the anchor, with anchor and element aligned at bottom-center. - overlap_after/bottom_right
the component overlaps the anchor, with anchor and element aligned at bottom-right. - at_pointer
the component appears with the upper-left aligned with the mouse cursor. - after_pointer
the component appears with the top aligned with the bottom of the mouse cursor, with the left side of the component at the horizontal position of the mouse cursor.
- before_start
- Returns:
- A modified copy of the
this
object
-
withPosition
default IDatebox withPosition(IPopupBase.Position position)
Returns a copy ofthis
immutable component with the specifiedposition
.Position the popup datebox to the specified location.
- Parameters:
position
- Where to position. Default:IPopupBase.Position.AFTER_START
- Returns:
- A modified copy of the
this
object
-
isStrictDate
default boolean isStrictDate()
Returns whether date/time should be strict or not.Default:
false
.
-
withStrictDate
IDatebox withStrictDate(boolean strictDate)
Returns a copy ofthis
immutable component with the specifiedstrictDate
.Sets whether date/time should be strict or not.
If true, any invalid input like "Jan 0" or "Nov 31" would be refused.
If false, it won't be checked and let lenient parsing decide.
- Parameters:
strictDate
-true
to make date/time be strict.Default:
false
.- Returns:
- A modified copy of the
this
object
-
getShowTodayLink
default boolean getShowTodayLink()
Returns whether enable to show the link that jump to today in day viewDefault:
false
-
withShowTodayLink
IDatebox withShowTodayLink(boolean showTodayLink)
Returns a copy ofthis
immutable component with the specifiedshowTodayLink
.Sets whether enable to show the link that jump to today in day view
- Parameters:
showTodayLink
-true
to show a link to jump to today.Default:
false
.- Returns:
- A modified copy of the
this
object
-
getTodayLinkLabel
default java.lang.String getTodayLinkLabel()
Returns the label of the link that jump to today in day viewDefault:
"Today"
-
withTodayLinkLabel
IDatebox withTodayLinkLabel(java.lang.String todayLinkLabel)
Returns a copy ofthis
immutable component with the specifiedtodayLinkLabel
.Sets the label of the link that jump to today in day view.
- Parameters:
todayLinkLabel
- The label of the link to jump to today.Default:
"Today"
.- Returns:
- A modified copy of the
this
object
-
getSelectLevel
default java.lang.String getSelectLevel()
Returns the level that a user can select.Default:
"day"
-
withSelectLevel
IDatebox withSelectLevel(java.lang.String selectLevel)
Returns a copy ofthis
immutable component with the specifiedselectLevel
.Sets the level that a user can select.
- Parameters:
selectLevel
- The level that a user can select.Default:
"day"
.- Returns:
- A modified copy of the
this
object
-
getClosePopupOnTimezoneChange
default boolean getClosePopupOnTimezoneChange()
Returns whether to auto close the datebox popup after changing the timezone.Default:
true
-
withClosePopupOnTimezoneChange
IDatebox withClosePopupOnTimezoneChange(boolean closePopupOnTimezoneChange)
Returns a copy ofthis
immutable component with the specifiedclosePopupOnTimezoneChange
.Sets whether to auto close the datebox popup after changing the timezone.
- Parameters:
closePopupOnTimezoneChange
- Whether to auto close the datebox popup after changing the timezoneDefault:
true
.- Returns:
- A modified copy of the
this
object
-
getCols
default int getCols()
Returns the cols which determines the visible width, in characters.Default:
11
(non-positive means the same as browser's default).- Specified by:
getCols
in interfaceIInputElement<IDatebox,java.util.Date>
-
withFormat
IDatebox withFormat(@Nullable java.lang.String format)
Returns a copy ofthis
immutable component with the specifiedformat
.Sets the date format.
You could specify one of the following reserved words, and
DateFormats.getDateFormat(int, Locale, String)
orDateFormats.getDateTimeFormat(int, int, java.util.Locale, java.lang.String)
will be used to retrieve the real format.short DateFormats.getDateFormat(int, Locale, String)
withDateFormat.SHORT
medium DateFormats.getDateFormat(int, Locale, String)
withDateFormat.MEDIUM
long DateFormats.getDateFormat(int, Locale, String)
withDateFormat.LONG
full DateFormats.getDateFormat(int, Locale, String)
withDateFormat.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
- Specified by:
withFormat
in interfaceIFormatInputElement<IDatebox,java.util.Date>
- Parameters:
format
- The format of the datebox.Default:
Datebox.DEFAULT_FORMAT
.- Returns:
- A modified copy of the
this
object
-
of
static IDatebox of(java.util.Date date)
Return the instance of the given date.- Parameters:
date
- The date to indicate the value for datebox.
-
of
static IDatebox of(java.time.temporal.Temporal date)
Return the instance of the given date.- Parameters:
date
- The date to indicate the value for datebox.
-
of
static IDatebox of(java.lang.String format, java.util.Date date)
Return the instance of the given format and date.- Parameters:
format
- The format of the dateboxdate
- The date to indicate the value for datebox.
-
of
static IDatebox of(java.lang.String format, java.time.temporal.Temporal date)
Return the instance of the given format and date.- Parameters:
format
- The format of the dateboxdate
- The date to indicate the value for datebox.
-
ofLocale
static IDatebox ofLocale(java.lang.String locale)
Returns the instance with the given locale.- Parameters:
locale
- The datebox locale
-
ofLocale
static IDatebox ofLocale(java.util.Locale locale)
Returns the instance with the given locale.- Parameters:
locale
- The datebox locale
-
ofCols
static ITimebox ofCols(int cols)
Returns the instance with the given cols.- Parameters:
cols
- The cols which determines the visible width
-
ofConstraint
static IDatebox ofConstraint(java.lang.String constraint)
Returns the instance with the given constraint.- Parameters:
constraint
- The datebox constraint
-
ofFormat
static IDatebox ofFormat(java.lang.String format)
Returns the instance with the given format.- Parameters:
format
- The datebox format
-
ofId
static IDatebox ofId(java.lang.String id)
Returns the instance with the given id.- Parameters:
id
- The id to identify this component
-
-