Package org.zkoss.stateless.sul

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>
    Immutable Datebox component

    An edit box for holding a date.

    The default format (IFormatInputElement.getFormat()) depends on DateFormats.getDateFormat(int, Locale, String) and the current user's locale (unless IDateTimeFormatInputElement.withLocale(Locale) is assigned. Please refer to withFormat(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 of no empty, no future, no past, and no 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 the locale. 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 format yyyy/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 as short, medium, long, and full.

    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 to IPopupBase.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 the Calendar). 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

    • 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 interface IComponent<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 of this immutable component with the specified displayedTimeZones.

        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 of this immutable component with the specified displayedTimeZones.

        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 of this immutable component with the specified displayedTimeZones.

        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 of this immutable component with the specified displayedTimeZones.

        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 of this immutable component with the specified defaultDateTime.

        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 of this immutable component with the specified buttonVisible.

        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 of this immutable component with the specified lenient.

        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 of this immutable component with the specified timeZonesReadonly.

        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 of this immutable component with the specified weekOfYear.

        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 of this immutable component with the specified position.

        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.
        Returns:
        A modified copy of the this object

      • withPosition

        default IDatebox withPosition​(IPopupBase.Position position)
        Returns a copy of this immutable component with the specified position.

        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 of this immutable component with the specified strictDate.

        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 view

        Default: false

      • withShowTodayLink

        IDatebox withShowTodayLink​(boolean showTodayLink)
        Returns a copy of this immutable component with the specified showTodayLink.

        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 view

        Default: "Today"

      • withTodayLinkLabel

        IDatebox withTodayLinkLabel​(java.lang.String todayLinkLabel)
        Returns a copy of this immutable component with the specified todayLinkLabel.

        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 of this immutable component with the specified selectLevel.

        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 of this immutable component with the specified closePopupOnTimezoneChange.

        Sets whether to auto close the datebox popup after changing the timezone.

        Parameters:
        closePopupOnTimezoneChange - Whether to auto close the datebox popup after changing the timezone

        Default: 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 interface IInputElement<IDatebox,​java.util.Date>

      • withFormat

        IDatebox withFormat​(@Nullable
                    java.lang.String format)
        Returns a copy of this immutable component with the specified format.

        Sets the date format.

        You could specify one of the following reserved words, and DateFormats.getDateFormat(int, Locale, String) or DateFormats.getDateTimeFormat(int, int, java.util.Locale, java.lang.String) will be used to retrieve the real format.

        short DateFormats.getDateFormat(int, Locale, String) with DateFormat.SHORT
        medium DateFormats.getDateFormat(int, Locale, String) with DateFormat.MEDIUM
        long DateFormats.getDateFormat(int, Locale, String) with DateFormat.LONG
        full DateFormats.getDateFormat(int, Locale, 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
        Specified by:
        withFormat in interface IFormatInputElement<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 datebox
        date - 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 datebox
        date - 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