Package org.zkoss.zkmax.zul

Class Daterangebox

java.lang.Object
org.zkoss.zk.ui.AbstractComponent
org.zkoss.zk.ui.HtmlBasedComponent
org.zkoss.zul.impl.XulElement
org.zkoss.zkmax.zul.Daterangebox
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, org.zkoss.zul.ext.Constrainted
public class Daterangebox extends org.zkoss.zul.impl.XulElement implements org.zkoss.zk.ui.ext.Disable, org.zkoss.zk.ui.ext.Readonly, org.zkoss.zul.ext.Constrainted
A date range picker. Allows users to select a contiguous range of dates (optionally including time) via a popup with one or more side-by-side calendar panels and an optional minimum / maximum length constraint.

Value is a DateRange composed of a begin date and an end date. Either end may be null when setAllowEmpty(String) permits.

Reuses SimpleDateConstraint for validation: "between A and B", "before X", "after X", "no past", "no future", etc. apply to both the begin and end values.

Server / client globally configurable defaults (zk.xml library properties)

  • org.zkoss.zul.daterangebox.numberOfMonths (default 2)
  • org.zkoss.zul.daterangebox.hoverPreview (default true)
  • org.zkoss.zul.daterangebox.separator (default "~")

Events

onChange and onChanging deliver a Daterangebox.RangeChangeEvent (which extends Event), not an InputEvent — a two-ended range cannot be carried by the single value of an InputEvent. A server-side listener must declare its parameter as Daterangebox.RangeChangeEvent and read Daterangebox.RangeChangeEvent.getRange(), Daterangebox.RangeChangeEvent.getBegin() or Daterangebox.RangeChangeEvent.getEnd(); a handler typed onChange(InputEvent), or a ZUL EL expression reading event.value, will not match. Data binding is unaffected: @bind/@save persist through the value / beginValue / endValue properties rather than the event object.

Since:
11.0.0
Author:
peaker
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    protected class 
    Daterangebox.ExtraCtrl
    A utility class to implement HtmlBasedComponent.getExtraCtrl().
    static class 
    Daterangebox.RangeChangeEvent
    Event fired when the begin or end value changes (carried by onChange and onChanging).

    Nested classes/interfaces inherited from class org.zkoss.zk.ui.AbstractComponent

    org.zkoss.zk.ui.AbstractComponent.Children, org.zkoss.zk.ui.AbstractComponent.ForwardInfo, org.zkoss.zk.ui.AbstractComponent.TargetInfo

  • Field Summary

    Fields inherited from class org.zkoss.zk.ui.HtmlBasedComponent

    _zclass

    Fields inherited from interface org.zkoss.zk.ui.Component

    APPLICATION_SCOPE, COMPONENT_SCOPE, DESKTOP_SCOPE, PAGE_SCOPE, REQUEST_SCOPE, SESSION_SCOPE, SPACE_SCOPE

    Fields inherited from interface org.zkoss.zk.ui.sys.ComponentCtrl

    AFTER_CHILD_ADDED, AFTER_CHILD_REMOVED, AFTER_CLONED, AFTER_PAGE_ATTACHED, AFTER_PAGE_DETACHED, AFTER_PARENT_CHANGED, CE_BUSY_IGNORE, CE_DUPLICATE_IGNORE, CE_IMPORTANT, CE_NON_DEFERRABLE, CE_REPEAT_IGNORE

  • Constructor Summary

    Constructors
    Constructor
    Description
    Daterangebox()
    Constructs an empty date range picker.
    Daterangebox(org.zkoss.zul.DateRange range)
    Constructs a date range picker with the given initial range.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    beforeChildAdded(org.zkoss.zk.ui.Component child, org.zkoss.zk.ui.Component refChild)
    Rejects ZUL child nodes.
    void
    clearErrorMessage()
    Clears the error message.
    String
    getAllowEmpty()
    Returns which endpoints may be left empty: one of "none", "begin", "end" or "both".
    String
    getBeginPlaceholder()
    Returns the placeholder for the begin input, or null if none.
    Date
    getBeginValue()
    Returns a defensive copy of the begin endpoint, or null if unset.
    LocalDate
    getBeginValueInLocalDate()
    Returns the begin endpoint as a LocalDate in the component's time zone, or null if unset.
    LocalDateTime
    getBeginValueInLocalDateTime()
    Returns the begin endpoint as a LocalDateTime in the component's time zone, or null if unset.
    ZonedDateTime
    getBeginValueInZonedDateTime()
    Returns the begin endpoint as a ZonedDateTime in the component's time zone, or null if unset.
    org.zkoss.zul.Constraint
    getConstraint()
    Returns the active Constraint, or null if none is set.
    String
    getConstraintString()
    Returns the raw constraint string of the active Constraint if it is a SimpleConstraint, or null otherwise, matching InputElement.getConstraintString().
    String
    getEndPlaceholder()
    Returns the placeholder for the end input, or null if none.
    Date
    getEndValue()
    Returns a defensive copy of the end endpoint, or null if unset.
    LocalDate
    getEndValueInLocalDate()
    Returns the end endpoint as a LocalDate in the component's time zone, or null if unset.
    LocalDateTime
    getEndValueInLocalDateTime()
    Returns the end endpoint as a LocalDateTime in the component's time zone, or null if unset.
    ZonedDateTime
    getEndValueInZonedDateTime()
    Returns the end endpoint as a ZonedDateTime in the component's time zone, or null if unset.
    String
    getErrorMessage()
    Returns the error message that is caused when user entered invalid value, or null if no error at all.
    Object
    getExtraCtrl()
     
    String
    getFormat()
    Returns the raw date format pattern, or null if none was set (in which case getRealFormat() supplies the locale-derived fallback).
    Map<String,String>
    getInputAttributes()
    Returns the additional attributes which is set by setInputAttributes(Map<String, String> inputAttributes).
    Locale
    getLocale()
    Returns the locale used for month/weekday labels and the first-day-of-week, or null (the page/current locale) if unset.
    int
    getMaxNights()
    Returns the maximum number of nights (difference in calendar days) allowed between begin and end.
    int
    getMinNights()
    Returns the minimum number of nights (difference in calendar days) required between begin and end.
    int
    getNumberOfMonths()
    Returns the number of side-by-side calendar panels shown in the popup.
    String
    getPlaceholder()
    Returns the placeholder applied to both inputs when no per-input placeholder is set, or null if none.
    String
    getPosition()
    Returns the popup anchor position token.
    String
    getRealFormat()
    Returns the format actually used.
    String
    getSeparator()
    Returns the explicit separator if set, otherwise the library-property default (or "~" as the final fallback).
    TimeZone
    getTimeZone()
    Returns the time zone used for calendar-day boundary decisions and constraint-bound parsing, or null (the current time zone) if unset.
    String
    getTodayLinkLabel()
    Returns the label of the "Today" shortcut shown in the popup footer when isShowTodayLink() is on.
    org.zkoss.zul.DateRange
    getValue()
    Returns the current range as a DateRange.
    org.zkoss.zul.LocalDateRange
    getValueInLocalDate()
    Returns the range as a LocalDateRange in the component's time zone.
    org.zkoss.zul.LocalDateTimeRange
    getValueInLocalDateTime()
    Returns the range as a LocalDateTimeRange in the component's time zone.
    org.zkoss.zul.ZonedDateTimeRange
    getValueInZonedDateTime()
    Returns the range as a ZonedDateTimeRange in the component's time zone.
    String
    getZclass()
     
    boolean
    isButtonVisible()
    Returns whether the calendar drop-down button is shown to the right of the inputs.
    boolean
    isDisabled()
    Returns whether the component is disabled (no user interaction).
    boolean
    isHoverPreview()
    Returns whether hovering a candidate end date previews the range in the calendar.
    boolean
    isLenient()
    Returns whether date parsing is lenient.
    boolean
    isOpen()
    Returns whether the calendar popup is currently open.
    boolean
    isReadonly()
    Returns whether the component is read-only (value shown but not editable).
    boolean
    isShowTime()
    Returns whether the time picker is shown.
    boolean
    isShowTodayLink()
    Returns whether the "Today" shortcut link is shown in the day view.
    boolean
    isStrictDate()
    Returns whether strict date validation is enabled, rejecting impossible dates such as "Nov 31".
    boolean
    isWeekOfYear()
    Returns whether the week-of-year column is shown in the calendar panels.
    org.zkoss.zk.ui.WrongValueException
    onWrongValue(org.zkoss.zk.ui.WrongValueException ex)
     
    protected void
    renderProperties(org.zkoss.zk.ui.sys.ContentRenderer renderer)
     
    void
    service(org.zkoss.zk.au.AuRequest request, boolean everError)
     
    void
    setAllowEmpty(String which)
    Sets which endpoints may be left empty and pushes it to the client via smartUpdate.
    void
    setBeginPlaceholder(String s)
    Sets the placeholder shown in the begin input when empty and pushes it via smartUpdate.
    void
    setBeginValue(Date d)
    Sets the begin endpoint.
    void
    setBeginValueInLocalDate(LocalDate d)
    Sets the begin endpoint from a LocalDate, taken at start of day in the component's time zone.
    void
    setBeginValueInLocalDateTime(LocalDateTime d)
    Sets the begin endpoint from a LocalDateTime, interpreted in the component's time zone.
    void
    setBeginValueInZonedDateTime(ZonedDateTime d)
    Sets the begin endpoint from a ZonedDateTime (its instant is used).
    void
    setButtonVisible(boolean b)
    Sets whether the calendar drop-down button is shown and pushes it via smartUpdate.
    void
    setConstraint(String constr)
    Sets the constraint from a SimpleDateConstraint expression (e.g.
    void
    setConstraint(org.zkoss.zul.Constraint constr)
    Sets the active Constraint instance applied to both endpoints.
    void
    setDisabled(boolean b)
    Sets whether the component is disabled and pushes it via smartUpdate.
    void
    setEndPlaceholder(String s)
    Sets the placeholder shown in the end input when empty and pushes it via smartUpdate.
    void
    setEndValue(Date d)
    Sets the end endpoint.
    void
    setEndValueInLocalDate(LocalDate d)
    Sets the end endpoint from a LocalDate, taken at start of day in the component's time zone.
    void
    setEndValueInLocalDateTime(LocalDateTime d)
    Sets the end endpoint from a LocalDateTime, interpreted in the component's time zone.
    void
    setEndValueInZonedDateTime(ZonedDateTime d)
    Sets the end endpoint from a ZonedDateTime (its instant is used).
    void
    setErrorMessage(String errmsg)
    Associates an error message to this component.
    void
    setFormat(String format)
    Sets the date format pattern applied to both input fields, using java.text.SimpleDateFormat letters (e.g.
    void
    setHoverPreview(boolean b)
    Sets whether hovering a candidate end date previews the range in the calendar and pushes it via smartUpdate.
    void
    setInputAttributes(String inputAttributes)
    Sets some additional attributes to both range input html tags in the component.
    void
    setInputAttributes(Map<String,String> inputAttributes)
    Sets some additional attributes to both range input html tags in the component.
    void
    setLenient(boolean b)
    Sets whether date parsing is lenient and pushes it via smartUpdate.
    void
    setLocale(String localeCode)
    Sets the locale from its string code (e.g.
    void
    setLocale(Locale locale)
    Sets the locale used for month/weekday labels and the first-day-of-week.
    void
    setMaxNights(int n)
    Sets the maximum number of nights (difference in calendar days) allowed between begin and end and pushes it via smartUpdate.
    void
    setMinNights(int n)
    Sets the minimum number of nights (difference in calendar days) required between begin and end and pushes it via smartUpdate.
    void
    setNumberOfMonths(int n)
    Sets the number of side-by-side calendar panels shown in the popup and pushes it to the client via smartUpdate.
    void
    setOpen(boolean open)
    Opens or closes the calendar popup by dispatching an AuInvoke to the client widget.
    void
    setPlaceholder(String s)
    Sets the placeholder shown in both inputs when empty and pushes it via smartUpdate.
    void
    setPosition(String pos)
    Sets where the calendar popup is anchored relative to the input box.
    void
    setReadonly(boolean b)
    Sets whether the component is read-only and pushes it via smartUpdate.
    void
    setSeparator(String s)
    Sets the separator string rendered between the two date inputs.
    void
    setShowTime(boolean b)
    Sets whether the popup shows a time picker and the inputs display the time component.
    void
    setShowTodayLink(boolean b)
    Sets whether the "Today" shortcut link is shown in the day view and pushes it via smartUpdate.
    void
    setStrictDate(boolean b)
    Sets whether strict date validation is enabled and pushes it via smartUpdate.
    void
    setTimeZone(String tzId)
    Sets the time zone from its ID (e.g.
    void
    setTimeZone(TimeZone tz)
    Sets the time zone used for calendar-day boundary decisions and for SimpleDateConstraint bound parsing.
    void
    setTodayLinkLabel(String todayLinkLabel)
    Sets the label of the "Today" shortcut shown in the popup footer (gated by setShowTodayLink(boolean)) and pushes it via smartUpdate.
    void
    setValue(org.zkoss.zul.DateRange range)
    Sets the range.
    void
    setValueInLocalDate(org.zkoss.zul.LocalDateRange r)
    Sets the range from a LocalDateRange, each end taken at start of day in the component's time zone.
    void
    setValueInLocalDateTime(org.zkoss.zul.LocalDateTimeRange r)
    Sets the range from a LocalDateTimeRange, each end interpreted in the component's time zone.
    void
    setValueInZonedDateTime(org.zkoss.zul.ZonedDateTimeRange r)
    Sets the range from a ZonedDateTimeRange (each end's instant is used).
    boolean
    setVisible(boolean visible)
     
    void
    setWeekOfYear(boolean b)
    Sets whether the week-of-year column is shown in the calendar panels and pushes it via smartUpdate.

    Methods inherited from class org.zkoss.zul.impl.XulElement

    clone, getContext, getCtrlKeys, getPopup, getPropertyAccess, getTooltip, setContext, setContext, setContextAttributes, setCtrlKeys, setPopup, setPopup, setPopupAttributes, setTooltip, setTooltip, setTooltipAttributes

    Methods inherited from class org.zkoss.zk.ui.HtmlBasedComponent

    addSclass, evalCSSFlex, focus, getAction, getClientAction, getDraggable, getDroppable, getHeight, getHflex, getLeft, getRenderdefer, getSclass, getSkeleton, getStyle, getTabindex, getTabindexInteger, getTooltiptext, getTop, getVflex, getWidth, getZindex, getZIndex, removeSclass, removeSclass, setAction, setClass, setClientAction, setDraggable, setDroppable, setFocus, setHeight, setHeight0, setHeightDirectly, setHflex, setHflex0, setHflexDirectly, setLeft, setLeftDirectly, setRenderdefer, setSclass, setSkeleton, setStyle, setTabindex, setTabindex, setTooltiptext, setTop, setTopDirectly, setVflex, setVflex0, setVflexDirectly, setWidth, setWidth0, setWidthDirectly, setZclass, setZindex, setZIndex, setZIndexDirectly

    Methods inherited from class org.zkoss.zk.ui.AbstractComponent

    addAnnotation, addCallback, addClientEvent, addEventHandler, addEventListener, addEventListener, addForward, addForward, addForward, addForward, addMoved, addRedrawCallback, addScopeListener, addShadowRoot, addShadowRootBefore, addSharedEventHandlerMap, appendChild, applyProperties, beforeChildRemoved, beforeParentChanged, destroyIndexCacheMap, detach, didActivate, didActivate, didDeserialize, didDeserialize, disableBindingAnnotation, disableClientUpdate, disableHostChanged, enableBindingAnnotation, enableHostChanged, getAnnotatedProperties, getAnnotatedPropertiesBy, getAnnotation, getAnnotations, getAnnotations, getAttribute, getAttribute, getAttribute, getAttributeOrFellow, getAttributes, getAttributes, getAuService, getAutag, getCallback, getChildren, getClientAttribute, getClientDataAttribute, getClientEvents, getDefaultMold, getDefinition, getDesktop, getEventHandler, getEventHandlerNames, getEventListenerMap, getEventListeners, getFellow, getFellow, getFellowIfAny, getFellowIfAny, getFellows, getFirstChild, getForwards, getId, getIndexCacheMap, getLastChild, getMold, getNextSibling, getPage, getParent, getPreviousSibling, getRedrawCallback, getRoot, getShadowFellowIfAny, getShadowRoots, getShadowVariable, getShadowVariable, getShadowVariable0, getSpaceOwner, getSpecialRendererOutput, getStubonly, getSubBindingAnnotationCount, getTemplate, getTemplateNames, getUuid, getWidgetAttributeNames, getWidgetClass, getWidgetListener, getWidgetListenerNames, getWidgetOverride, getWidgetOverrideNames, hasAttribute, hasAttribute, hasAttribute, hasAttributeOrFellow, hasBindingAnnotation, hasFellow, hasFellow, hasSubBindingAnnotation, initIndexCacheMap, insertBefore, invalidate, isChildable, isDisabledHostChanged, isInitialized, isInvalidated, isListenerAvailable, isVisible, onChildAdded, onChildRemoved, onPageAttached, onPageDetached, onParentChanged, query, queryAll, redraw, redrawChildren, removeAttribute, removeAttribute, removeAttribute, removeCallback, removeChild, removeEventListener, removeForward, removeForward, removeRedrawCallback, removeScopeListener, removeShadowRoot, render, render, render, renderPropertiesOnly, replace, response, response, response, service, sessionDidActivate, sessionWillPassivate, setAttribute, setAttribute, setAttribute, setAuService, setAutag, setClientAttribute, setClientDataAttribute, setDefinition, setDefinition, setId, setMold, setPage, setPageBefore, setParent, setStubonly, setStubonly, setSubBindingAnnotationCount, setTemplate, setVisibleDirectly, setWidgetClass, setWidgetListener, setWidgetOverride, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdate, smartUpdateWidgetListener, smartUpdateWidgetOverride, toString, updateByClient, updateSubBindingAnnotationCount, willPassivate, willPassivate, willSerialize, willSerialize

    Methods inherited from class java.lang.Object

    equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Constructor Details

    • Daterangebox

      public Daterangebox()
      Constructs an empty date range picker. Both ends start null and numberOfMonths is resolved lazily from the library default (see getNumberOfMonths()) the first time it is read.
      Since:
      11.0.0

    • Daterangebox

      public Daterangebox(org.zkoss.zul.DateRange range)
      Constructs a date range picker with the given initial range.
      Parameters:
      range - the initial begin/end range; null leaves both ends empty.
      Throws:
      org.zkoss.zk.ui.WrongValueException - if the range violates the active constraint, the allowEmpty rule, the begin-after-end rule or the minNights/maxNights bounds.
      Since:
      11.0.0

  • Method Details

    • getValue

      public org.zkoss.zul.DateRange getValue()
      Returns the current range as a DateRange. Always non-null; either or both ends may be null.
      Since:
      11.0.0

    • setValue

      public void setValue(org.zkoss.zul.DateRange range)
      Sets the range. null clears both ends.

      If an error message is pending (getErrorMessage()), the range is validated and sent to the client even when it equals the current one, and the error message is cleared.

      Parameters:
      range - may be null
      Throws:
      org.zkoss.zk.ui.WrongValueException - if the new range violates the active constraint, the allowEmpty rule, the begin-after-end rule or the minNights/maxNights bounds.
      Since:
      11.0.0

    • getBeginValue

      public Date getBeginValue()
      Returns a defensive copy of the begin endpoint, or null if unset.
      Since:
      11.0.0
      See Also:

    • setBeginValue

      public void setBeginValue(Date d)
      Sets the begin endpoint. In date-only mode (isShowTime() is false) the time-of-day component is ignored when checking the range order, so a same-calendar-day pair whose begin time is later than the end time (e.g. Jan 1 23:00 / Jan 1 09:00) is accepted as a zero-night stay rather than rejected as inverted. Note that DateRange.getDays() compares wall-clock instants, so it can still report a negative count for such a pair — validation and getDays() intentionally use different granularities.
      Parameters:
      d - the new begin date; null clears the begin endpoint.
      Throws:
      org.zkoss.zk.ui.WrongValueException - if the resulting range violates the active constraint, the allowEmpty rule, the begin-after-end rule or the minNights/maxNights bounds.
      Since:
      11.0.0

    • getEndValue

      public Date getEndValue()
      Returns a defensive copy of the end endpoint, or null if unset.
      Since:
      11.0.0
      See Also:

    • setEndValue

      public void setEndValue(Date d)
      Sets the end endpoint. See setBeginValue(Date) for the date-only range-order semantics and how they relate to DateRange.getDays().
      Parameters:
      d - the new end date; null clears the end endpoint.
      Throws:
      org.zkoss.zk.ui.WrongValueException - if the resulting range violates the active constraint, the allowEmpty rule, the begin-after-end rule or the minNights/maxNights bounds.
      Since:
      11.0.0

    • getErrorMessage

      public String getErrorMessage()
      Returns the error message that is caused when user entered invalid value, or null if no error at all.
      Since:
      11.0.0

    • setErrorMessage

      public void setErrorMessage(String errmsg)
      Associates an error message to this component. It will cause the given error message to be shown at the client.

      Notice that the application rarely invokes this method. Rather, throw WrongValueException instead.

      Parameters:
      errmsg - the error message; null or empty clears it.
      Since:
      11.0.0

    • clearErrorMessage

      public void clearErrorMessage()
      Clears the error message.

      The error message is cleared automatically, so you rarely need to call this method. However, if the error can be corrected by changing only one end with setBeginValue(Date) or setEndValue(Date), you may have to clear the error message manually by invoking this method, since this component cannot tell whether the end left alone is still in error. setValue(DateRange) sets both ends and clears it.

      Since:
      11.0.0

    • getBeginValueInLocalDate

      public LocalDate getBeginValueInLocalDate()
      Returns the begin endpoint as a LocalDate in the component's time zone, or null if unset.
      Since:
      11.0.0
      See Also:

    • setBeginValueInLocalDate

      public void setBeginValueInLocalDate(LocalDate d)
      Sets the begin endpoint from a LocalDate, taken at start of day in the component's time zone. Equivalent to setBeginValue(Date).
      Parameters:
      d - the new begin date; null clears the begin endpoint.
      Since:
      11.0.0

    • getEndValueInLocalDate

      public LocalDate getEndValueInLocalDate()
      Returns the end endpoint as a LocalDate in the component's time zone, or null if unset.
      Since:
      11.0.0
      See Also:

    • setEndValueInLocalDate

      public void setEndValueInLocalDate(LocalDate d)
      Sets the end endpoint from a LocalDate, taken at start of day in the component's time zone. Equivalent to setEndValue(Date).
      Parameters:
      d - the new end date; null clears the end endpoint.
      Since:
      11.0.0

    • getValueInLocalDate

      public org.zkoss.zul.LocalDateRange getValueInLocalDate()
      Returns the range as a LocalDateRange in the component's time zone.
      Since:
      11.0.0
      See Also:

    • setValueInLocalDate

      public void setValueInLocalDate(org.zkoss.zul.LocalDateRange r)
      Sets the range from a LocalDateRange, each end taken at start of day in the component's time zone. Equivalent to setValue(DateRange).
      Parameters:
      r - the new range; null clears both ends.
      Since:
      11.0.0

    • getBeginValueInLocalDateTime

      public LocalDateTime getBeginValueInLocalDateTime()
      Returns the begin endpoint as a LocalDateTime in the component's time zone, or null if unset.
      Since:
      11.0.0
      See Also:

    • setBeginValueInLocalDateTime

      public void setBeginValueInLocalDateTime(LocalDateTime d)
      Sets the begin endpoint from a LocalDateTime, interpreted in the component's time zone. Equivalent to setBeginValue(Date).
      Parameters:
      d - the new begin date-time; null clears the begin endpoint.
      Since:
      11.0.0

    • getEndValueInLocalDateTime

      public LocalDateTime getEndValueInLocalDateTime()
      Returns the end endpoint as a LocalDateTime in the component's time zone, or null if unset.
      Since:
      11.0.0
      See Also:

    • setEndValueInLocalDateTime

      public void setEndValueInLocalDateTime(LocalDateTime d)
      Sets the end endpoint from a LocalDateTime, interpreted in the component's time zone. Equivalent to setEndValue(Date).
      Parameters:
      d - the new end date-time; null clears the end endpoint.
      Since:
      11.0.0

    • getValueInLocalDateTime

      public org.zkoss.zul.LocalDateTimeRange getValueInLocalDateTime()
      Returns the range as a LocalDateTimeRange in the component's time zone.
      Since:
      11.0.0
      See Also:

    • setValueInLocalDateTime

      public void setValueInLocalDateTime(org.zkoss.zul.LocalDateTimeRange r)
      Sets the range from a LocalDateTimeRange, each end interpreted in the component's time zone. Equivalent to setValue(DateRange).
      Parameters:
      r - the new range; null clears both ends.
      Since:
      11.0.0

    • getBeginValueInZonedDateTime

      public ZonedDateTime getBeginValueInZonedDateTime()
      Returns the begin endpoint as a ZonedDateTime in the component's time zone, or null if unset.
      Since:
      11.0.0
      See Also:

    • setBeginValueInZonedDateTime

      public void setBeginValueInZonedDateTime(ZonedDateTime d)
      Sets the begin endpoint from a ZonedDateTime (its instant is used). Equivalent to setBeginValue(Date).
      Parameters:
      d - the new begin date-time; null clears the begin endpoint.
      Since:
      11.0.0

    • getEndValueInZonedDateTime

      public ZonedDateTime getEndValueInZonedDateTime()
      Returns the end endpoint as a ZonedDateTime in the component's time zone, or null if unset.
      Since:
      11.0.0
      See Also:

    • setEndValueInZonedDateTime

      public void setEndValueInZonedDateTime(ZonedDateTime d)
      Sets the end endpoint from a ZonedDateTime (its instant is used). Equivalent to setEndValue(Date).
      Parameters:
      d - the new end date-time; null clears the end endpoint.
      Since:
      11.0.0

    • getValueInZonedDateTime

      public org.zkoss.zul.ZonedDateTimeRange getValueInZonedDateTime()
      Returns the range as a ZonedDateTimeRange in the component's time zone.
      Since:
      11.0.0
      See Also:

    • setValueInZonedDateTime

      public void setValueInZonedDateTime(org.zkoss.zul.ZonedDateTimeRange r)
      Sets the range from a ZonedDateTimeRange (each end's instant is used). Equivalent to setValue(DateRange).
      Parameters:
      r - the new range; null clears both ends.
      Since:
      11.0.0

    • getFormat

      public 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.
      Since:
      11.0.0
      See Also:

    • setFormat

      public void setFormat(String format)
      Sets the date format pattern applied to both input fields, using java.text.SimpleDateFormat letters (e.g. yyyy/MM/dd). Passing null or "" resets to the locale-aware MEDIUM fallback. The resolved pattern (see getRealFormat(), which also appends " HH:mm" when isShowTime() is on) is pushed to the client via smartUpdate.
      Parameters:
      format - the format pattern, or null/"" for the default.
      Since:
      11.0.0

    • getRealFormat

      public String getRealFormat()
      Returns the format actually used. When format has not been explicitly set, falls back to the locale-aware MEDIUM pattern. If showTime is explicitly true and no explicit format has been set, " HH:mm" is appended so the input field shows the time the user picks in the popup — without this, a showTime component would let the user pick a time that the date-only input never displays.
      Returns:
      the effective, never-null format pattern.
      Since:
      11.0.0

    • getLocale

      public 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.
      Since:
      11.0.0
      See Also:

    • setLocale

      public void setLocale(Locale locale)
      Sets the locale used for month/weekday labels and the first-day-of-week.

      Client-side date parsing and formatting via zk.fmt.Calendar use the localized symbols pushed for this property.

      Parameters:
      locale - the locale, or null to use the current/page locale.
      Since:
      11.0.0

    • setLocale

      public void setLocale(String localeCode)
      Sets the locale from its string code (e.g. "zh_TW"), delegating to setLocale(Locale). Passing null or "" clears the locale.
      Parameters:
      localeCode - the locale code, or null/"" to clear.
      Since:
      11.0.0

    • getTimeZone

      public 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.
      Since:
      11.0.0
      See Also:

    • setTimeZone

      public void setTimeZone(TimeZone tz)
      Sets the time zone used for calendar-day boundary decisions and for SimpleDateConstraint bound parsing. The popup's "Today" button, client-side typed input parsing, server-side constraint parsing, and the valueIn* java.time getters all honor this property.

      Note: an already-set AbstractSimpleDateTimeConstraint is re-anchored to the new zone in place, so an instance shared with another component follows this zone too — see setConstraint(Constraint).

      Parameters:
      tz - the time zone, or null to use the current time zone.
      Since:
      11.0.0

    • setTimeZone

      public void setTimeZone(String tzId)
      Sets the time zone from its ID (e.g. "Asia/Tokyo"), delegating to setTimeZone(TimeZone). Passing null or "" clears the time zone. Because TimeZone.getTimeZone silently returns GMT for an unrecognized ID, an unknown non-GMT/UTC ID (e.g. a typo) is rejected rather than silently resolving to GMT.
      Parameters:
      tzId - the time zone ID, or null/"" to clear.
      Throws:
      org.zkoss.zk.ui.WrongValueException - if tzId is not a recognized time zone ID.
      Since:
      11.0.0

    • getConstraint

      public org.zkoss.zul.Constraint getConstraint()
      Returns the active Constraint, or null if none is set. Default: null.
      Specified by:
      getConstraint in interface org.zkoss.zul.ext.Constrainted
      Since:
      11.0.0
      See Also:

    • getConstraintString

      public String getConstraintString()
      Returns the raw constraint string of the active Constraint if it is a SimpleConstraint, or null otherwise, matching InputElement.getConstraintString(). Custom Constraint implementations have no canonical string form, so we surface null rather than fabricate one — callers that need to display the active constraint should fall back to getConstraint().
      Returns:
      the raw constraint string, or null.
      Since:
      11.0.0

    • setConstraint

      public void setConstraint(String constr)
      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. Passing null or "" clears the constraint. The bounds are parsed in the current getTimeZone().
      Parameters:
      constr - the constraint expression, or null/"" to clear.
      Since:
      11.0.0

    • setConstraint

      public void setConstraint(org.zkoss.zul.Constraint constr)
      Sets the active Constraint instance applied to both endpoints. A SimpleDateConstraint validates the pair as a range; any other Constraint is invoked per endpoint. Passing null clears the constraint.

      Note: an AbstractSimpleDateTimeConstraint is re-anchored to this component's getTimeZone() in place, as DateTimeFormatInputElement.setConstraint(org.zkoss.zul.Constraint) does, so an instance shared with another component follows this zone too.

      Specified by:
      setConstraint in interface org.zkoss.zul.ext.Constrainted
      Parameters:
      constr - the constraint, or null to clear.
      Since:
      11.0.0

    • getNumberOfMonths

      public int getNumberOfMonths()
      Returns the number of side-by-side calendar panels shown in the popup. When not explicitly set, resolves the library default (org.zkoss.zul.daterangebox.numberOfMonths, default 2).
      Since:
      11.0.0
      See Also:

    • setNumberOfMonths

      public void setNumberOfMonths(int n)
      Sets the number of side-by-side calendar panels shown in the popup and pushes it to the client via smartUpdate. The accepted range is 1 to the configured maximum (library property org.zkoss.zul.daterangebox.numberOfMonths.max, default 12).
      Parameters:
      n - the panel count; must be between 1 and the configured maximum.
      Throws:
      org.zkoss.zk.ui.WrongValueException - if n is outside that range.
      Since:
      11.0.0

    • getAllowEmpty

      public String getAllowEmpty()
      Returns which endpoints may be left empty: one of "none", "begin", "end" or "both". Default: "both".
      Since:
      11.0.0
      See Also:

    • setAllowEmpty

      public void setAllowEmpty(String which)
      Sets which endpoints may be left empty and pushes it to the client via smartUpdate. Accepted tokens: "none" (both required), "begin", "end" and "both" (both optional). Passing null resets to "both".
      Parameters:
      which - one of none, begin, end, both, or null to reset to both.
      Throws:
      org.zkoss.zk.ui.WrongValueException - if which is not one of the accepted tokens.
      Since:
      11.0.0

    • isShowTime

      public boolean isShowTime()
      Returns whether the time picker is shown. If never explicitly set, auto-detected from getRealFormat().
      Since:
      11.0.0
      See Also:

    • setShowTime

      public void setShowTime(boolean b)
      Sets whether the popup shows a time picker and the inputs display the time component. When turned on without an explicit format, " HH:mm" is appended to the effective format (see getRealFormat()). The new state, and any re-resolved format, are pushed via smartUpdate. Default: unset (auto-detected from the format).
      Parameters:
      b - true to show the time picker.
      Since:
      11.0.0

    • getMinNights

      public int getMinNights()
      Returns the minimum number of nights (difference in calendar days) required between begin and end. 0 means no minimum. Default: 0.
      Since:
      11.0.0
      See Also:

    • setMinNights

      public void setMinNights(int n)
      Sets the minimum number of nights (difference in calendar days) required between begin and end and pushes it via smartUpdate. 0 disables the minimum.
      Parameters:
      n - the minimum nights; must be >= 0 and not exceed a non-zero getMaxNights().
      Throws:
      org.zkoss.zk.ui.WrongValueException - if n is negative, or greater than a configured non-zero maxNights.
      Since:
      11.0.0

    • getMaxNights

      public int getMaxNights()
      Returns the maximum number of nights (difference in calendar days) allowed between begin and end. 0 means unbounded. Default: 0.
      Since:
      11.0.0
      See Also:

    • setMaxNights

      public void setMaxNights(int n)
      Sets the maximum number of nights (difference in calendar days) allowed between begin and end and pushes it via smartUpdate. 0 leaves the range unbounded.
      Parameters:
      n - the maximum nights; must be >= 0 and not less than a non-zero getMinNights().
      Throws:
      org.zkoss.zk.ui.WrongValueException - if n is negative, or less than a configured non-zero minNights.
      Since:
      11.0.0

    • getPosition

      public String getPosition()
      Returns the popup anchor position token. Default: "after_start".
      Since:
      11.0.0
      See Also:

    • setPosition

      public void setPosition(String pos)
      Sets where the calendar popup is anchored relative to the input box. Default: after_start (the popup drops below the box, aligned to its left edge). Accepts the same position tokens as Popup.open(org.zkoss.zk.ui.Component, String) — e.g. before_start, after_end, start_center, end_after, overlap or at_pointer. The value is pushed to the client and applied the next time the popup opens.
      Parameters:
      pos - the popup position token
      Since:
      11.0.0

    • isButtonVisible

      public boolean isButtonVisible()
      Returns whether the calendar drop-down button is shown to the right of the inputs. Default: true.
      Since:
      11.0.0
      See Also:

    • setButtonVisible

      public void setButtonVisible(boolean b)
      Sets whether the calendar drop-down button is shown and pushes it via smartUpdate.
      Parameters:
      b - true to show the button.
      Since:
      11.0.0

    • isWeekOfYear

      public boolean isWeekOfYear()
      Returns whether the week-of-year column is shown in the calendar panels. Default: false.
      Since:
      11.0.0
      See Also:

    • setWeekOfYear

      public void setWeekOfYear(boolean b)
      Sets whether the week-of-year column is shown in the calendar panels and pushes it via smartUpdate.
      Parameters:
      b - true to show the week-of-year column.
      Since:
      11.0.0

    • isShowTodayLink

      public boolean isShowTodayLink()
      Returns whether the "Today" shortcut link is shown in the day view. Default: false.
      Since:
      11.0.0
      See Also:

    • setShowTodayLink

      public void setShowTodayLink(boolean b)
      Sets whether the "Today" shortcut link is shown in the day view and pushes it via smartUpdate.
      Parameters:
      b - true to show the "Today" link.
      Since:
      11.0.0

    • getTodayLinkLabel

      public String getTodayLinkLabel()
      Returns the label of the "Today" shortcut shown in the popup footer when isShowTodayLink() is on.

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

      Since:
      11.0.0
      See Also:

    • setTodayLinkLabel

      public void setTodayLinkLabel(String todayLinkLabel)
      Sets the label of the "Today" shortcut shown in the popup footer (gated by setShowTodayLink(boolean)) and pushes it via smartUpdate. Mirrors Datebox.setTodayLinkLabel(String) so the label is owned per-component rather than read from a global locale bundle.
      Parameters:
      todayLinkLabel - the label; null is accepted and shipped as-is.
      Since:
      11.0.0

    • getInputAttributes

      public Map<String,String> getInputAttributes()
      Returns the additional attributes which is set by setInputAttributes(Map<String, String> inputAttributes).

      The attributes are rendered on both range input html tags of this component.

      Returns:
      inputAttributes a Map with attribute names as the keys, or null if not set.
      Since:
      11.0.0

    • setInputAttributes

      public void setInputAttributes(Map<String,String> inputAttributes)
      Sets some additional attributes to both range input html tags in the component. This will only reset the additional attributes that are set by this method.

      It is also how to specify the HTML autocomplete attribute required by WCAG 1.3.5 (Identify Input Purpose) when this component collects information about the user, for example autocomplete=bday.

      Parameters:
      inputAttributes - a Map with attribute names as the keys.
      Since:
      11.0.0

    • setInputAttributes

      public void setInputAttributes(String inputAttributes)
      Sets some additional attributes to both range input html tags in the component. This will only reset the additional attributes that are set by this method.
      Parameters:
      inputAttributes - a String of attributes separated by ";" and follow name=value rule. for example: "autocomplete=bday"
      Since:
      11.0.0

    • isOpen

      public boolean isOpen()
      Returns whether the calendar popup is currently open. Default: false.
      Since:
      11.0.0
      See Also:

    • setOpen

      public void setOpen(boolean open)
      Opens or closes the calendar popup by dispatching an AuInvoke to the client widget. Only works while visible, as Combobox.setOpen(boolean): the request is ignored while the component is invisible, and an open is ignored while disabled.
      Parameters:
      open - true to open the popup, false to close it.
      Since:
      11.0.0

    • setVisible

      public boolean setVisible(boolean visible)
      Specified by:
      setVisible in interface org.zkoss.zk.ui.Component
      Overrides:
      setVisible in class org.zkoss.zk.ui.AbstractComponent

    • isLenient

      public 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.
      Since:
      11.0.0
      See Also:

    • setLenient

      public void setLenient(boolean b)
      Sets whether date parsing is lenient and pushes it via smartUpdate. With strict parsing (false), inputs must match the format exactly.
      Parameters:
      b - true for lenient parsing.
      Since:
      11.0.0

    • isStrictDate

      public boolean isStrictDate()
      Returns whether strict date validation is enabled, rejecting impossible dates such as "Nov 31". Default: false.
      Since:
      11.0.0
      See Also:

    • setStrictDate

      public void setStrictDate(boolean b)
      Sets whether strict date validation is enabled and pushes it via smartUpdate. When true, impossible dates like "Jan 0" or "Nov 31" are refused.
      Parameters:
      b - true to enable strict date validation.
      Since:
      11.0.0

    • getSeparator

      public String getSeparator()
      Returns the explicit separator if set, otherwise the library-property default (or "~" as the final fallback).
      Returns:
      the resolved separator string; never null.
      Since:
      11.0.0

    • setSeparator

      public void setSeparator(String s)
      Sets the separator string rendered between the two date inputs.

      Reset semantics: passing null clears the explicit value and the next render falls back to getSeparator()'s default chain (library property "org.zkoss.zul.daterangebox.separator" → "~"). The smartUpdate pushes the resolved default so the client immediately mirrors the reset rather than carrying the previous string forward. Unique to this setter — the other String setters preserve the raw value on the wire because they have no library-property fallback.

      Parameters:
      s - the separator string, or null to reset to the default.
      Since:
      11.0.0

    • getPlaceholder

      public String getPlaceholder()
      Returns the placeholder applied to both inputs when no per-input placeholder is set, or null if none. Default: null.
      Since:
      11.0.0
      See Also:

    • setPlaceholder

      public void setPlaceholder(String s)
      Sets the placeholder shown in both inputs when empty and pushes it via smartUpdate.
      Parameters:
      s - the placeholder text, or null to clear.
      Since:
      11.0.0

    • getBeginPlaceholder

      public String getBeginPlaceholder()
      Returns the placeholder for the begin input, or null if none. Default: null.
      Since:
      11.0.0
      See Also:

    • setBeginPlaceholder

      public void setBeginPlaceholder(String s)
      Sets the placeholder shown in the begin input when empty and pushes it via smartUpdate.
      Parameters:
      s - the placeholder text, or null to clear.
      Since:
      11.0.0

    • getEndPlaceholder

      public String getEndPlaceholder()
      Returns the placeholder for the end input, or null if none. Default: null.
      Since:
      11.0.0
      See Also:

    • setEndPlaceholder

      public void setEndPlaceholder(String s)
      Sets the placeholder shown in the end input when empty and pushes it via smartUpdate.
      Parameters:
      s - the placeholder text, or null to clear.
      Since:
      11.0.0

    • isHoverPreview

      public boolean isHoverPreview()
      Returns whether hovering a candidate end date previews the range in the calendar. When not explicitly set, resolves the library default (org.zkoss.zul.daterangebox.hoverPreview, default true).
      Since:
      11.0.0
      See Also:

    • setHoverPreview

      public void setHoverPreview(boolean b)
      Sets whether hovering a candidate end date previews the range in the calendar and pushes it via smartUpdate.
      Parameters:
      b - true to enable the hover preview.
      Since:
      11.0.0

    • isDisabled

      public boolean isDisabled()
      Returns whether the component is disabled (no user interaction). Default: false.
      Specified by:
      isDisabled in interface org.zkoss.zk.ui.ext.Disable
      Since:
      11.0.0
      See Also:

    • setDisabled

      public void setDisabled(boolean b)
      Sets whether the component is disabled and pushes it via smartUpdate. A disabled component ignores open requests.
      Specified by:
      setDisabled in interface org.zkoss.zk.ui.ext.Disable
      Parameters:
      b - true to disable the component.
      Since:
      11.0.0

    • isReadonly

      public boolean isReadonly()
      Returns whether the component is read-only (value shown but not editable). Default: false.
      Specified by:
      isReadonly in interface org.zkoss.zk.ui.ext.Readonly
      Since:
      11.0.0
      See Also:

    • setReadonly

      public void setReadonly(boolean b)
      Sets whether the component is read-only and pushes it via smartUpdate. Read-only blocks typing only: the popup still opens and a pick still commits, the same contract as Combobox and Datebox.
      Specified by:
      setReadonly in interface org.zkoss.zk.ui.ext.Readonly
      Parameters:
      b - true to make the component read-only.
      Since:
      11.0.0

    • service

      public void service(org.zkoss.zk.au.AuRequest request, boolean everError)
      Specified by:
      service in interface org.zkoss.zk.ui.sys.ComponentCtrl
      Overrides:
      service in class org.zkoss.zk.ui.HtmlBasedComponent

    • onWrongValue

      public org.zkoss.zk.ui.WrongValueException onWrongValue(org.zkoss.zk.ui.WrongValueException ex)
      Specified by:
      onWrongValue in interface org.zkoss.zk.ui.sys.ComponentCtrl
      Overrides:
      onWrongValue in class org.zkoss.zk.ui.AbstractComponent

    • getExtraCtrl

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

    • renderProperties

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

    • getZclass

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

    • beforeChildAdded

      public void beforeChildAdded(org.zkoss.zk.ui.Component child, org.zkoss.zk.ui.Component refChild)
      Rejects ZUL child nodes. The two input fields, the calendar panels and the Timeboxes inside the popup are owned by Daterangebox / DaterangePopup and constructed dynamically — letting the application drop arbitrary children into the component would either be ignored at render time or collide with the internally-managed sub-tree.
      Specified by:
      beforeChildAdded in interface org.zkoss.zk.ui.sys.ComponentCtrl
      Overrides:
      beforeChildAdded in class org.zkoss.zk.ui.AbstractComponent