Package org.zkoss.stateless.sul

Interface IDaterangebox

    • Field Detail

      • DEFAULT

        static final IDaterangebox DEFAULT
        Constant for default attributes of this immutable component.

    • Method Detail

      • getWidgetClass

        default java.lang.String getWidgetClass()
        Returns the client widget class.

        Default: "zkmax.db.Daterangebox"

        Specified by:
        getWidgetClass in interface IComponent<IDaterangebox>

      • getValue

        @Nullable
org.zkoss.zul.DateRange getValue()
        Returns the current range, or null if unset. Either end of a non-null range may itself be null (an open-ended range).

        This is the one stored endpoint attribute; getBeginValue() and getEndValue() are derived from it. DateRange copies both ends on the way in and on the way out, so a caller that keeps a reference to the Date it passed cannot mutate this component afterwards.

        Default: null

      • withValue

        IDaterangebox withValue​(@Nullable
                        org.zkoss.zul.DateRange value)
        Returns a copy of this immutable component with the specified value.

        Sets both endpoints at once.

        Note: UiAgent.smartUpdate(Locator, SmartUpdater) is not supported for this property — IDaterangebox.Updater ships the raw attribute while the initial render ships the epoch millis the client widget parses. Push a whole component with UiAgent.replaceWith(Locator, IComponent) instead.

        Parameters:
        value - The range; null clears both ends.
        Returns:
        A modified copy of the this object

      • getBeginValue

        @Nullable
@Derived
default java.util.Date getBeginValue()
        Returns the begin endpoint, or null if unset.

        A derived snapshot of getValue(); mutating the returned Date is not supported, call getValue() for a fresh copy.

        Default: null

      • withBeginValue

        default IDaterangebox withBeginValue​(@Nullable
                                     java.util.Date beginValue)
        Returns a copy of this immutable component with the specified beginValue, keeping the current end endpoint.

        Sets the begin endpoint. See withValue(DateRange) for the smartUpdate restriction.

        Parameters:
        beginValue - The begin date; null clears the begin endpoint.

        Default: null.

        Returns:
        A modified copy of the this object

      • getEndValue

        @Nullable
@Derived
default java.util.Date getEndValue()
        Returns the end endpoint, or null if unset.

        A derived snapshot of getValue(); mutating the returned Date is not supported, call getValue() for a fresh copy.

        Default: null

      • withEndValue

        default IDaterangebox withEndValue​(@Nullable
                                   java.util.Date endValue)
        Returns a copy of this immutable component with the specified endValue, keeping the current begin endpoint.

        Sets the end endpoint. See withValue(DateRange) for the smartUpdate restriction.

        Parameters:
        endValue - The end date; null clears the end endpoint.

        Default: null.

        Returns:
        A modified copy of the this object

      • withBeginValueInLocalDate

        default IDaterangebox withBeginValueInLocalDate​(@Nullable
                                                java.time.LocalDate beginValue)
        Returns a copy of this immutable component with the specified beginValue taken at start of day in getTimeZone().
        Parameters:
        beginValue - The begin date; null clears the begin endpoint.
        Returns:
        A modified copy of the this object

      • withEndValueInLocalDate

        default IDaterangebox withEndValueInLocalDate​(@Nullable
                                              java.time.LocalDate endValue)
        Returns a copy of this immutable component with the specified endValue taken at start of day in getTimeZone().
        Parameters:
        endValue - The end date; null clears the end endpoint.
        Returns:
        A modified copy of the this object

      • withValueInLocalDate

        default IDaterangebox withValueInLocalDate​(@Nullable
                                           org.zkoss.zul.LocalDateRange value)
        Returns a copy of this immutable component with the specified value, each end taken at start of day in getTimeZone().
        Parameters:
        value - The range; null clears both ends.
        Returns:
        A modified copy of the this object

      • withBeginValueInLocalDateTime

        default IDaterangebox withBeginValueInLocalDateTime​(@Nullable
                                                    java.time.LocalDateTime beginValue)
        Returns a copy of this immutable component with the specified beginValue, interpreted in getTimeZone().
        Parameters:
        beginValue - The begin date-time; null clears the begin endpoint.
        Returns:
        A modified copy of the this object

      • withEndValueInLocalDateTime

        default IDaterangebox withEndValueInLocalDateTime​(@Nullable
                                                  java.time.LocalDateTime endValue)
        Returns a copy of this immutable component with the specified endValue, interpreted in getTimeZone().
        Parameters:
        endValue - The end date-time; null clears the end endpoint.
        Returns:
        A modified copy of the this object

      • withValueInLocalDateTime

        default IDaterangebox withValueInLocalDateTime​(@Nullable
                                               org.zkoss.zul.LocalDateTimeRange value)
        Returns a copy of this immutable component with the specified value, each end interpreted in getTimeZone().
        Parameters:
        value - The range; null clears both ends.
        Returns:
        A modified copy of the this object

      • withBeginValueInZonedDateTime

        default IDaterangebox withBeginValueInZonedDateTime​(@Nullable
                                                    java.time.ZonedDateTime beginValue)
        Returns a copy of this immutable component with the specified beginValue (its instant is used).
        Parameters:
        beginValue - The begin date-time; null clears the begin endpoint.
        Returns:
        A modified copy of the this object

      • withEndValueInZonedDateTime

        default IDaterangebox withEndValueInZonedDateTime​(@Nullable
                                                  java.time.ZonedDateTime endValue)
        Returns a copy of this immutable component with the specified endValue (its instant is used).
        Parameters:
        endValue - The end date-time; null clears the end endpoint.
        Returns:
        A modified copy of the this object

      • withValueInZonedDateTime

        default IDaterangebox withValueInZonedDateTime​(@Nullable
                                               org.zkoss.zul.ZonedDateTimeRange value)
        Returns a copy of this immutable component with the specified value (each end's instant is used).
        Parameters:
        value - The range; null clears both ends.
        Returns:
        A modified copy of the this object

      • getFormat

        @Nullable
java.lang.String getFormat()
        Returns the raw date format pattern, or null if none was set (in which case getRealFormat() supplies the locale-derived fallback).

        Default: null

      • withFormat

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

        Sets the date format pattern applied to both input fields, using java.text.SimpleDateFormat letters (e.g. yyyy/MM/dd). null or "" resets to the locale-aware MEDIUM fallback.

        Note: UiAgent.smartUpdate(Locator, SmartUpdater) is not supported for this property — IDaterangebox.Updater ships the raw attribute while the initial render ships getRealFormat(). Push a whole component with UiAgent.replaceWith(Locator, IComponent) instead.

        Parameters:
        format - The format pattern, or null/"" for the default.

        Default: null.

        Returns:
        A modified copy of the this object

      • getLocale

        @Nullable
java.util.Locale getLocale()
        Returns the locale used for month/weekday labels and the first-day-of-week, or null (the page/current locale) if unset.

        Default: null

      • withLocale

        IDaterangebox withLocale​(@Nullable
                         java.util.Locale locale)
        Returns a copy of this immutable component with the specified locale.

        Sets the locale used for month/weekday labels and the first-day-of-week.

        Note: UiAgent.smartUpdate(Locator, SmartUpdater) is not supported for this property — IDaterangebox.Updater ships the raw attribute while the initial render ships locale.toString() plus the localized symbols. Push a whole component with UiAgent.replaceWith(Locator, IComponent) instead.

        Parameters:
        locale - The preferred locale, or null to use the current locale.

        Default: null.

        Returns:
        A modified copy of the this object

      • withLocale

        default IDaterangebox withLocale​(@Nullable
                                 java.lang.String locale)
        Returns a copy of this immutable component with the specified locale.

        Sets the locale from its string code (e.g. "zh_TW").

        Parameters:
        locale - The locale code, or null/"" to clear.

        Default: null.

        Returns:
        A modified copy of the this object

      • getTimeZone

        @Nullable
java.util.TimeZone getTimeZone()
        Returns the time zone used for calendar-day boundary decisions and constraint-bound parsing, or null (the current time zone) if unset.

        Default: null

      • withTimeZone

        IDaterangebox withTimeZone​(@Nullable
                           java.util.TimeZone timeZone)
        Returns a copy of this immutable component with the specified timeZone.

        Sets the time zone used for calendar-day boundary decisions and for SimpleDateConstraint bound parsing.

        Note: UiAgent.smartUpdate(Locator, SmartUpdater) is not supported for this property — IDaterangebox.Updater ships the raw attribute while the initial render ships DateTimeFormatInputElement.getFormattedTimeZone(timeZone). Push a whole component with UiAgent.replaceWith(Locator, IComponent) instead.

        Parameters:
        timeZone - The preferred time zone, or null to use the current one.

        Default: null.

        Returns:
        A modified copy of the this object

      • withTimeZone

        default IDaterangebox withTimeZone​(@Nullable
                                   java.lang.String timeZone)
        Returns a copy of this immutable component with the specified timeZone.

        Sets the time zone from its ID (e.g. "Asia/Tokyo").

        Parameters:
        timeZone - The time zone ID, or null/"" to clear.

        Default: null.

        Returns:
        A modified copy of the this object
        Throws:
        org.zkoss.zk.ui.WrongValueException - if timeZone is not a recognized time zone ID.

      • getConstraint

        @Nullable
java.lang.String getConstraint()
        Returns the SimpleDateConstraint expression applied to both endpoints, or null if none.

        Default: null

      • withConstraint

        IDaterangebox withConstraint​(@Nullable
                             java.lang.String constraint)
        Returns a copy of this immutable component with the specified constraint.

        Sets the constraint from a SimpleDateConstraint expression (e.g. "between 20240101 and 20241231", "no past"), which is applied to both the begin and end values.

        Parameters:
        constraint - The constraint expression, or null to clear.

        Default: null.

        Returns:
        A modified copy of the this object

      • getNumberOfMonths

        default int getNumberOfMonths()
        Returns the number of side-by-side calendar panels shown in the popup.

        Default: the library property org.zkoss.zul.daterangebox.numberOfMonths (2 if unset).

      • withNumberOfMonths

        IDaterangebox withNumberOfMonths​(int numberOfMonths)
        Returns a copy of this immutable component with the specified numberOfMonths.

        Sets the number of side-by-side calendar panels shown in the popup.

        Parameters:
        numberOfMonths - The panel count; must be between 1 and the configured maximum (library property org.zkoss.zul.daterangebox.numberOfMonths.max, default 12).
        Returns:
        A modified copy of the this object
        Throws:
        org.zkoss.zk.ui.WrongValueException - if it is outside that range.

      • getAllowEmpty

        @Nullable
default java.lang.String getAllowEmpty()
        Returns which endpoints may be left empty: one of "none", "begin", "end" or "both".

        Default: "both"

      • withAllowEmpty

        IDaterangebox withAllowEmpty​(@Nullable
                             java.lang.String allowEmpty)
        Returns a copy of this immutable component with the specified allowEmpty.

        Sets which endpoints may be left empty.

        Parameters:
        allowEmpty - one of none, begin, end or both.

        Default: "both".

        Returns:
        A modified copy of the this object
        Throws:
        org.zkoss.zk.ui.WrongValueException - if it is not one of the accepted tokens.

      • isShowTime

        @Nullable
default java.lang.Boolean isShowTime()
        Returns whether the popup shows a time picker and the inputs display the time component, or null when it was never set.

        Default: null (unset)

        Tri-state, mirroring Daterangebox's Boolean _showTime: null leaves the decision to the client, which auto-detects a time token in the format; an explicit false suppresses that auto-detection. Only a non-null value reaches the wire, so the three states stay distinguishable.

      • withShowTime

        IDaterangebox withShowTime​(@Nullable
                           java.lang.Boolean showTime)
        Returns a copy of this immutable component with the specified showTime.

        Sets whether the popup shows a time picker. When turned on without an explicit format, " HH:mm" is appended to the effective format (see getRealFormat()).

        Parameters:
        showTime - true to show the time picker, false to suppress it even for a time-bearing format, or null to let the client decide from the format.

        Default: null.

        Returns:
        A modified copy of the this object

      • getMinNights

        default int getMinNights()
        Returns the minimum number of nights required between begin and end. 0 means no minimum.

        Default: 0

      • withMinNights

        IDaterangebox withMinNights​(int minNights)
        Returns a copy of this immutable component with the specified minNights.

        Sets the minimum number of nights required between begin and end.

        Parameters:
        minNights - The minimum nights; must be >= 0 and not exceed a non-zero getMaxNights().

        Default: 0.

        Returns:
        A modified copy of the this object
        Throws:
        org.zkoss.zk.ui.WrongValueException - if it is negative, or greater than a configured non-zero maxNights.

      • getMaxNights

        default int getMaxNights()
        Returns the maximum number of nights allowed between begin and end. 0 means unbounded.

        Default: 0

      • withMaxNights

        IDaterangebox withMaxNights​(int maxNights)
        Returns a copy of this immutable component with the specified maxNights.

        Sets the maximum number of nights allowed between begin and end.

        Parameters:
        maxNights - The maximum nights; must be >= 0 and not less than a non-zero getMinNights().

        Default: 0.

        Returns:
        A modified copy of the this object
        Throws:
        org.zkoss.zk.ui.WrongValueException - if it is negative, or less than a configured non-zero minNights.

      • getPosition

        @Nullable
default java.lang.String getPosition()
        Returns the popup anchor position token.

        Default: "after_start"

      • withPosition

        IDaterangebox withPosition​(@Nullable
                           java.lang.String position)
        Returns a copy of this immutable component with the specified position.

        Position the calendar popup to the specified location.

        Parameters:
        position - Where to position. Default: after_start. It accepts the same tokens as IPopupBase.Position.
        Returns:
        A modified copy of the this object

      • withPosition

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

        Position the calendar popup to the specified location.

        Parameters:
        position - Where to position. Default: IPopupBase.Position.AFTER_START
        Returns:
        A modified copy of the this object

      • isButtonVisible

        default boolean isButtonVisible()
        Returns whether the calendar drop-down button is shown to the right of the inputs.

        Default: true

      • withButtonVisible

        IDaterangebox withButtonVisible​(boolean buttonVisible)
        Returns a copy of this immutable component with the specified buttonVisible.

        Sets whether the calendar drop-down button is shown.

        Parameters:
        buttonVisible - false to hide the button.

        Default: true.

        Returns:
        A modified copy of the this object

      • isWeekOfYear

        default boolean isWeekOfYear()
        Returns whether the week-of-year column is shown in the calendar panels.

        Default: false

      • withWeekOfYear

        IDaterangebox withWeekOfYear​(boolean weekOfYear)
        Returns a copy of this immutable component with the specified weekOfYear.

        Sets whether the week-of-year column is shown in the calendar panels.

        Parameters:
        weekOfYear - true to show the week-of-year column.

        Default: false.

        Returns:
        A modified copy of the this object

      • isShowTodayLink

        default boolean isShowTodayLink()
        Returns whether the "Today" shortcut link is shown in the day view.

        Default: false

      • withShowTodayLink

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

        Sets whether the "Today" shortcut link is shown in the day view.

        Parameters:
        showTodayLink - true to show the "Today" link.

        Default: false.

        Returns:
        A modified copy of the this object

      • getTodayLinkLabel

        @Nullable
default java.lang.String getTodayLinkLabel()
        Returns the label of the "Today" shortcut shown in the popup footer.

        Default: the localized MZul.CALENDAR_TODAY ("Today" in English)

      • withTodayLinkLabel

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

        Sets the label of the "Today" shortcut shown in the popup footer.

        Parameters:
        todayLinkLabel - The label of the link to jump to today, or null — Daterangebox.setTodayLinkLabel(String) accepts a null and the C2I conversion has to be able to carry it back.

        Default: "Today".

        Returns:
        A modified copy of the this object

      • getAutocomplete

        default java.lang.String getAutocomplete()
        Returns the HTML autocomplete token applied to both range inputs.

        Default: "off"

      • withAutocomplete

        IDaterangebox withAutocomplete​(java.lang.String autocomplete)
        Returns a copy of this immutable component with the specified autocomplete.

        Sets the HTML autocomplete token applied to both range inputs. Required for WCAG 1.3.5 (Identify Input Purpose) when the inputs collect information about the user — e.g. "bday".

        Parameters:
        autocomplete - The autofill detail token.

        Default: "off".

        Returns:
        A modified copy of the this object

      • isLenient

        default boolean isLenient()
        Returns whether date parsing is lenient. With lenient parsing, inputs that do not exactly match the format may be interpreted heuristically.

        Default: true

      • withLenient

        IDaterangebox withLenient​(boolean lenient)
        Returns a copy of this immutable component with the specified lenient.

        Sets whether date parsing is lenient.

        Parameters:
        lenient - false to require inputs to match the format exactly.

        Default: true.

        Returns:
        A modified copy of the this object

      • isStrictDate

        default boolean isStrictDate()
        Returns whether strict date validation is enabled, rejecting impossible dates such as "Nov 31".

        Default: false

      • withStrictDate

        IDaterangebox withStrictDate​(boolean strictDate)
        Returns a copy of this immutable component with the specified strictDate.

        Sets whether strict date validation is enabled.

        Parameters:
        strictDate - true to refuse dates like "Jan 0".

        Default: false.

        Returns:
        A modified copy of the this object

      • getSeparator

        default java.lang.String getSeparator()
        Returns the separator rendered between the two date inputs.

        Default: the library property org.zkoss.zul.daterangebox.separator ("~" if unset)

      • withSeparator

        IDaterangebox withSeparator​(java.lang.String separator)
        Returns a copy of this immutable component with the specified separator.

        Sets the separator string rendered between the two date inputs.

        Note: unlike Daterangebox.setSeparator(String), null is not accepted here. To fall back to getSeparator()'s default chain, build a fresh instance without setting a separator.

        Parameters:
        separator - The separator string.

        Default: "~".

        Returns:
        A modified copy of the this object

      • getPlaceholder

        @Nullable
java.lang.String getPlaceholder()
        Returns the placeholder applied to both inputs when no per-input placeholder is set, or null if none.

        Default: null

      • withPlaceholder

        IDaterangebox withPlaceholder​(@Nullable
                              java.lang.String placeholder)
        Returns a copy of this immutable component with the specified placeholder.

        Sets the placeholder shown in both inputs when empty.

        Parameters:
        placeholder - The placeholder text, or null to clear.

        Default: null.

        Returns:
        A modified copy of the this object

      • getBeginPlaceholder

        @Nullable
java.lang.String getBeginPlaceholder()
        Returns the placeholder for the begin input, or null if none.

        Default: null

      • withBeginPlaceholder

        IDaterangebox withBeginPlaceholder​(@Nullable
                                   java.lang.String beginPlaceholder)
        Returns a copy of this immutable component with the specified beginPlaceholder.

        Sets the placeholder shown in the begin input when empty.

        Parameters:
        beginPlaceholder - The placeholder text, or null to clear.

        Default: null.

        Returns:
        A modified copy of the this object

      • getEndPlaceholder

        @Nullable
java.lang.String getEndPlaceholder()
        Returns the placeholder for the end input, or null if none.

        Default: null

      • withEndPlaceholder

        IDaterangebox withEndPlaceholder​(@Nullable
                                 java.lang.String endPlaceholder)
        Returns a copy of this immutable component with the specified endPlaceholder.

        Sets the placeholder shown in the end input when empty.

        Parameters:
        endPlaceholder - The placeholder text, or null to clear.

        Default: null.

        Returns:
        A modified copy of the this object

      • isHoverPreview

        default boolean isHoverPreview()
        Returns whether hovering a candidate end date previews the range in the calendar.

        Default: the library property org.zkoss.zul.daterangebox.hoverPreview (true if unset)

      • withHoverPreview

        IDaterangebox withHoverPreview​(boolean hoverPreview)
        Returns a copy of this immutable component with the specified hoverPreview.

        Sets whether hovering a candidate end date previews the range.

        Parameters:
        hoverPreview - false to disable the hover preview.

        Default: true.

        Returns:
        A modified copy of the this object

      • of

        static IDaterangebox of​(org.zkoss.zul.DateRange value)
        Returns the instance with the given range.
        Parameters:
        value - The initial range

      • of

        static IDaterangebox of​(@Nullable
                        java.util.Date beginValue,
                        @Nullable
                        java.util.Date endValue)
        Returns the instance with the given endpoints.
        Parameters:
        beginValue - The begin date, or null
        endValue - The end date, or null

      • ofFormat

        static IDaterangebox ofFormat​(java.lang.String format)
        Returns the instance with the given format.
        Parameters:
        format - The daterangebox format

      • ofConstraint

        static IDaterangebox ofConstraint​(java.lang.String constraint)
        Returns the instance with the given constraint.
        Parameters:
        constraint - The daterangebox constraint

      • ofId

        static IDaterangebox ofId​(java.lang.String id)
        Returns the instance with the given id.
        Parameters:
        id - The id to identify this component