Package 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.impl.DateTimeFormatInputElement
org.zkoss.zul.Datebox
All Implemented Interfaces:
Serializable, Cloneable, org.zkoss.zk.ui.Component, org.zkoss.zk.ui.ext.Disable, org.zkoss.zk.ui.ext.Readonly, org.zkoss.zk.ui.ext.Scope, org.zkoss.zk.ui.sys.ComponentCtrl, Constrainted
public class Datebox extends DateTimeFormatInputElement
An edit box for holding a date.

The default format (FormatInputElement.getFormat()) depends on DateFormats.getDateFormat(int, Locale, String) and the current user's locale (unless DateTimeFormatInputElement.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:

  • Field Details

  • Constructor Details

    • Datebox

      public Datebox()

    • Datebox

      public Datebox(Date date) throws org.zkoss.zk.ui.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:
      org.zkoss.zk.ui.WrongValueException

    • Datebox

      public Datebox(ZonedDateTime value) throws org.zkoss.zk.ui.WrongValueException
      Constructor with a given date.
      Parameters:
      value - 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:
      org.zkoss.zk.ui.WrongValueException
      Since:
      9.0.0

    • Datebox

      public Datebox(LocalDateTime value) throws org.zkoss.zk.ui.WrongValueException
      Constructor with a given date.
      Parameters:
      value - 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:
      org.zkoss.zk.ui.WrongValueException
      Since:
      9.0.0

    • Datebox

      public Datebox(LocalDate value) throws org.zkoss.zk.ui.WrongValueException
      Constructor with a given date.
      Parameters:
      value - 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:
      org.zkoss.zk.ui.WrongValueException
      Since:
      9.0.0

    • Datebox

      public Datebox(LocalTime value) throws org.zkoss.zk.ui.WrongValueException
      Constructor with a given date.
      Parameters:
      value - 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:
      org.zkoss.zk.ui.WrongValueException
      Since:
      9.0.0

  • Method Details

    • 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

    • setStrictDate

      public void setStrictDate(boolean strictDate)
      Sets whether or not date/time should be strict. 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.
      Since:
      8.6.0

    • isStrictDate

      public boolean isStrictDate()
      Returns whether date/time should be strict or not.

      Default: false.

      Since:
      8.6.0

    • getDefaultFormat

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

    • setLenient

      public void setLenient(boolean lenient)
      Sets whether date/time parsing is to be lenient or not.

      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.

    • 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

    • getPosition

      public String getPosition()
      Returns:
      the datebox popup position
      Since:
      8.0.3

    • setPosition

      public void setPosition(String position)
      Position the popup datebox to the specified location.
      Parameters:
      position - where to position. Default: after_start Allowed values:
      • before_start
        the element appears above the anchor, aligned to the left.
      • before_center
        the element appears above the anchor, aligned to the center.
      • before_end
        the element appears above the anchor, aligned to the right.
      • after_start
        the element appears below the anchor, aligned to the left.
      • after_center
        the element appears below the anchor, aligned to the center.
      • after_end
        the element appears below the anchor, aligned to the right.
      • start_before
        the element appears to the left of the anchor, aligned to the top.
      • start_center
        the element appears to the left of the anchor, aligned to the middle.
      • start_after
        the element appears to the left of the anchor, aligned to the bottom.
      • end_before
        the element appears to the right of the anchor, aligned to the top.
      • end_center
        the element appears to the right of the anchor, aligned to the middle.
      • end_after
        the element appears to the right of the anchor, aligned to the bottom.
      • overlap/top_left
        the element overlaps the anchor, with anchor and element aligned at top-left.
      • top_center
        the element overlaps the anchor, with anchor and element aligned at top-center.
      • overlap_end/top_right
        the element overlaps the anchor, with anchor and element aligned at top-right.
      • middle_left
        the element overlaps the anchor, with anchor and element aligned at middle-left.
      • middle_center
        the element overlaps the anchor, with anchor and element aligned at middle-center.
      • middle_right
        the element overlaps the anchor, with anchor and element aligned at middle-right.
      • overlap_before/bottom_left
        the element overlaps the anchor, with anchor and element aligned at bottom-left.
      • bottom_center
        the element overlaps the anchor, with anchor and element aligned at bottom-center.
      • overlap_after/bottom_right
        the element overlaps the anchor, with anchor and element aligned at bottom-right.
      • at_pointer
        the element appears with the upper-left aligned with the mouse cursor.
      • after_pointer
        the element appears with the top aligned with the bottom of the mouse cursor, with the left side of the element at the horizontal position of the mouse cursor.
      Since:
      8.0.3

    • setFormat

      public void setFormat(String format) throws org.zkoss.zk.ui.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:
      org.zkoss.zk.ui.WrongValueException

    • toStyle

      public static int toStyle(String format)
      Returns the styling index, or -111 if not matched.

    • getRealFormat

      public 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

    • setTimeZone

      public void setTimeZone(TimeZone tzone)
      Sets the time zone that this component 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.

      Overrides:
      setTimeZone in class DateTimeFormatInputElement

    • getDisplayedTimeZones

      public List<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(List<TimeZone> dtzones)
      Sets a list of the time zones that will be displayed at the client and allow user to select.

      If the DateTimeFormatInputElement.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(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:

    • 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

    • getRealSymbols

      public static Object[] getRealSymbols(Locale locale, org.zkoss.zk.ui.Component comp)
      Returns the localized client date symbols payload for a component locale.
      Parameters:
      locale - the component locale, or null for the page locale
      comp - the component requesting the symbols
      Returns:
      the client payload, or null if no component locale is set
      Since:
      11.0.0

    • 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

      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(org.zkoss.zk.au.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 org.zkoss.zk.ui.sys.ComponentCtrl
      Overrides:
      service in class InputElement
      Since:
      5.0.0

    • getExtraCtrl

      public Object getExtraCtrl()
      Specified by:
      getExtraCtrl in interface org.zkoss.zk.ui.sys.ComponentCtrl
      Overrides:
      getExtraCtrl in class org.zkoss.zk.ui.HtmlBasedComponent

    • setConstraint

      public void setConstraint(String constr)
      Overrides:
      setConstraint in class InputElement
      Parameters:
      constr - a list of constraints separated by comma. Example: "between 20071012 and 20071223", "before 20080103"

    • coerceFromString

      protected Object coerceFromString(String value) throws org.zkoss.zk.ui.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:
      org.zkoss.zk.ui.WrongValueException

    • coerceToString

      protected String coerceToString(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 DateFormat getDateFormat(String fmt)
      Returns the date format of the specified format

      Default: it uses SimpleDateFormat to format the date.

      Parameters:
      fmt - the pattern.

    • getZclass

      public String getZclass()
      Overrides:
      getZclass in class org.zkoss.zk.ui.HtmlBasedComponent

    • 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

    • getTodayLinkLabel

      public String getTodayLinkLabel()
      Returns the label of the link that jump to today in day view

      Default: Today

      Returns:
      String
      Since:
      8.0.4

    • setTodayLinkLabel

      public void setTodayLinkLabel(String todayLinkLabel)
      Sets the label of the link that jump to today in day view
      Parameters:
      todayLinkLabel - today link label
      Since:
      8.0.4

    • getDefaultDateTime

      public LocalDateTime getDefaultDateTime()
      Returns the default datetime if the value is empty.

      Default: null (means current datetime)

      Since:
      9.0.0

    • setDefaultDateTime

      public void setDefaultDateTime(LocalDateTime defaultDateTime)
      Sets the default datetime if the value is empty.
      Parameters:
      defaultDateTime - Default datetime. null means current datetime.
      Since:
      9.0.0

    • getSelectLevel

      public String getSelectLevel()
      Returns the level that a user can select.

      Default: "day"

      Returns:
      the level that a user can select
      Since:
      9.5.1

    • setSelectLevel

      public void setSelectLevel(String selectLevel)
      Sets the level that a user can select. The valid options are "day", "month", and "year".
      Parameters:
      selectLevel - the level that a user can select
      Since:
      9.5.1

    • getClosePopupOnTimezoneChange

      public boolean getClosePopupOnTimezoneChange()
      Returns whether to auto close the datebox popup after changing the timezone.

      Default: true

      Returns:
      boolean
      Since:
      9.6.0

    • setClosePopupOnTimezoneChange

      public void setClosePopupOnTimezoneChange(boolean closePopupOnTimezoneChange)
      Sets whether to auto close the datebox popup after changing the timezone.
      Parameters:
      closePopupOnTimezoneChange - shall close the datebox popup or not
      Since:
      9.6.0

    • getPropertyAccess

      public org.zkoss.zk.ui.sys.PropertyAccess getPropertyAccess(String prop)
      Specified by:
      getPropertyAccess in interface org.zkoss.zk.ui.sys.ComponentCtrl
      Overrides:
      getPropertyAccess in class DateTimeFormatInputElement

    • renderProperties

      protected void renderProperties(org.zkoss.zk.ui.sys.ContentRenderer renderer) throws IOException
      Overrides:
      renderProperties in class DateTimeFormatInputElement
      Throws:
      IOException