Package com.iizix.prop.ui.datetime

Class UIDateTime

java.lang.Object
com.iizix.prop.GProp<GProp<?>[]>
com.iizix.prop.PropCnr
com.iizix.prop.ui.UIComp
com.iizix.prop.ui.datetime.UIDateTime
All Implemented Interfaces:
EventListener, IFocusComp, IMessageBox, IComponent, ICustomDataProvider, IGProp<GProp<?>[]>, IPropCnr, IUIDateTime, IUIComp, IUICompRelativeTarget, IUIFocusComp, IUIHint, IUILabelForTarget, IUIDateTimeComponent, IUINullableValueComponent, IUIValueComponent, IVSComponentListener, IVSComponentState, IVSFieldListener, Cloneable
Direct Known Subclasses:
EUIDateTime
public class UIDateTime extends UIComp implements IUIDateTime, IUIHint, IUILabelForTarget, IUIFocusComp, IUIDateTimeComponent, IUINullableValueComponent
Date/Time UI Component.
Author:
Christopher Mindus

  • Constructor Details

    • UIDateTime

      public UIDateTime()
      Creates the component without a name. The name must be set in all cases using the setPropertyAtom call.

    • UIDateTime

      public UIDateTime(Atom propertyAtom)
      Creates the component with the specified name. All system-reserved names for components begins with "$".
      Parameters:
      propertyAtom - the name of the component, unique within it's parent.

    • UIDateTime

      public UIDateTime(Atom propertyAtom, GProp<?>[] newValue) throws PropException
      Creates the component with the specified name, initialized to contain the GProp items. All system-reserved names for components begins with "$".
      Parameters:
      propertyAtom - The name of the component, unique within it's parent.
      newValue - The array of all properties the component should have.
      Throws:
      PropException - when at least one of the properties to initialize the component with is invalid.

  • Method Details

    • getDeviceType

      public int getDeviceType()
      Support for both mobile and desktop.
      Specified by:
      getDeviceType in interface IUIComp
      Returns:
      0=both.

    • getUIDateTimeType

      public UIDateTimeType getUIDateTimeType()
      Returns the date-time type for this component.
      Specified by:
      getUIDateTimeType in interface IUIDateTime
      Returns:
      Enum value as Time, Date, DateTime or ZoneId.

    • getDataType

      public UIDateTimeDataType getDataType()
      Returns the date-time datatype for this component.
      Specified by:
      getDataType in interface IUIDateTime
      Returns:
      Enum value as Time, Date, DateTime or ZoneId.

    • getGDateTimeType

      public GDateTime.Type getGDateTimeType()
      Returns the GDateTime datatype for this component.
      Specified by:
      getGDateTimeType in interface IUIDateTime
      Returns:
      Enum value as LocalTime, OffsetTime, LocalDate, LocalDateTime, OffsetDateTime or ZonedDateTime.

    • isDataTypeEnforced

      public boolean isDataTypeEnforced()
      Returns if the enforcement of the datatype is set.
      Specified by:
      isDataTypeEnforced in interface IUIDateTime
      Returns:
      true if the datatype when setting the value MUST be exactly the same datatype, or false (default) to allow conversion to the internal configured datatype. In the Designer, this value is called "Allow data conversion", and is default true.

    • setType

      public boolean setType(UIDateTimeType type, UIDateTimeDataType dataType, boolean doEnforceDataType)
      Sets the date-time type, its datatype and the enforcement flag of the datatype.

      Note 1: This method DOES NOT change the value, so the value may end up in the wrong datatype, and you should ensure that this does not occur.

      Note 2: The doEnforceDataType is always true for ZoneId type.

      Specified by:
      setType in interface IUIDateTime
      Parameters:
      type - The type.
      dataType - The datatype.
      doEnforceDataType - The enforcement flag: when true the datatype must match precisely, when false, data conversion is done internally to retrieve the datatype based on the current user's (or system) locale information.
      Returns:
      true if a change of type, datatype or enforcement occurred, false for no change.
      Throws:
      IllegalArgumentException - If the type does not support the dataType.

    • onEventSelf

      public void onEventSelf(GEvent event)
      Processes events.
      Specified by:
      onEventSelf in interface IGProp<GProp<?>[]>
      Overrides:
      onEventSelf in class UIComp
      Parameters:
      event - The property event.

    • setComponentToVSField

      public int setComponentToVSField()
      Sets the value from component to its VirtualSpace field, if any.
      Specified by:
      setComponentToVSField in interface IUIComp
      Overrides:
      setComponentToVSField in class UIComp
      Returns:
      1 for update completed, 0 for nothing done and -1 for error occurred.

    • setComponentToVSField

      public static int setComponentToVSField(UIComp dateTimeComp, VSField field)
      Sets the value from component to its VirtualSpace field, if any.
      Parameters:
      dateTimeComp - The date/time component.
      field - The field.
      Returns:
      1 for update completed, 0 for nothing done and -1 for error occurred.

    • onValueChanged

      public void onValueChanged(VSField field, Value value, GProp<?> trigger, IPostEventProcessing postProcessing)
      Called when the field value is set.

      Components must override to provide the implementation when they are not implementing IPlainTextComponent, in this case the default implementation transports the field string value to this text components plain text.

      Specified by:
      onValueChanged in interface IVSFieldListener
      Overrides:
      onValueChanged in class UIComp
      Parameters:
      field - The VS field.
      value - The value, never null, but value.isNull() could be true.
      trigger - The trigger property that may be null.
      postProcessing - Post-processing instance.

    • isNullAllowed

      public boolean isNullAllowed()
      Returns if a null value is allowed, i.e. no date/time value is set and the UI component is blank.
      Specified by:
      isNullAllowed in interface IUIDateTime
      Specified by:
      isNullAllowed in interface IUINullableValueComponent
      Returns:
      true if null is allowed, or false (default) if not allowed.

    • setNullAllowed

      public boolean setNullAllowed(boolean isNullAllowed)
      Sets the null value allowed flag, i.e. allows no date/time value to be set and the UI component is blank.

      Setting this parameter isNullAllowed to false when the value already is null will not affect the value.

      Specified by:
      setNullAllowed in interface IUIDateTime
      Specified by:
      setNullAllowed in interface IUINullableValueComponent
      Parameters:
      isNullAllowed - Flag for null allowed.
      Returns:
      true if the setting changed, false for no change.

    • setValueToNull

      public boolean setValueToNull()
      Sets the value to null.
      Specified by:
      setValueToNull in interface IUIDateTime
      Specified by:
      setValueToNull in interface IUINullableValueComponent
      Returns:
      true for value changed, false for no change.
      Throws:
      IllegalStateException - If the flag isNullAllowed() is false.

    • setValue

      public boolean setValue(GDateTime value)
      Sets the date-time value with the locale information of the current user session (or system default) in case value conversion is required.
      Specified by:
      setValue in interface IUIDateTime
      Specified by:
      setValue in interface IUIDateTimeComponent
      Parameters:
      value - The value to set, null may be allowed depending on the flag returned by isNullAllowed().
      Returns:
      true for value changed, false for no change to the value.
      Throws:
      IllegalArgumentException - If the date/time type is enforced and not matching.
      IllegalStateException - If the date/time conversion cannot possibly take place due to type mismatch.
      NullPointerException - If the value is null and allow null is not enabled.

    • setValue

      public boolean setValue(GDateTime value, LocaleInfo localeInfo)
      Sets the date-time value.
      Specified by:
      setValue in interface IUIDateTime
      Parameters:
      value - The value to set, null may be allowed depending on the flag returned by isNullAllowed().
      localeInfo - The locale information to use, or null to use the current user's or system default.
      Returns:
      true for value changed, false for no change to the value.
      Throws:
      IllegalArgumentException - If the date/time type is enforced and not matching.
      IllegalStateException - If the date/time conversion cannot possibly take place due to type mismatch.
      NullPointerException - If the value is null and allow null is not enabled.

    • getValue

      public GDateTime getValue()
      Gets the current date-time value.
      Specified by:
      getValue in interface IUIDateTime
      Specified by:
      getValue in interface IUIDateTimeComponent
      Returns:
      The current value as configured with its datatype's corresponding GDateTime value, or null if the value is null and the flag isNullAllowed() is set. The value may still be null if the "null-allowed" flag has been toggled recently programmatically to false but the value has not been assigned yet.

    • getDefaultValue

      public GDateTime getDefaultValue()
      Gets the default value of the component as a GDateTime.
      Specified by:
      getDefaultValue in interface IUIDateTime
      Specified by:
      getDefaultValue in interface IUIDateTimeComponent
      Returns:
      The default value depends on the date/time type, i.e. the time as midnight as a LocalTime (00:00:00 for type Time), the epoch date as a LocalDate (1st of January 1970 for type Date), the combination of the two above for type DateTime, and the current Zone ID of the user's session (or system default) for ZoneId.

    • isTimeValueSupported

      public boolean isTimeValueSupported()
      Returns if the implementation supports time.
      Specified by:
      isTimeValueSupported in interface IUIDateTime
      Specified by:
      isTimeValueSupported in interface IUIDateTimeComponent
      Returns:
      false when time is not supported, true when setting a value requires a time part.

    • isTimeValueRequired

      public boolean isTimeValueRequired()
      Returns if the implementation requires a time in the value component.
      Specified by:
      isTimeValueRequired in interface IUIDateTime
      Specified by:
      isTimeValueRequired in interface IUIDateTimeComponent
      Returns:
      true when time is required in the component, and null is not allowed.

    • isDateValueSupported

      public boolean isDateValueSupported()
      Returns if the implementation supports date.
      Specified by:
      isDateValueSupported in interface IUIDateTime
      Specified by:
      isDateValueSupported in interface IUIDateTimeComponent
      Returns:
      false when date is not supported, true when setting a value requires a date part.

    • isDateValueRequired

      public boolean isDateValueRequired()
      Returns if the implementation requires a date in the value component.
      Specified by:
      isDateValueRequired in interface IUIDateTime
      Specified by:
      isDateValueRequired in interface IUIDateTimeComponent
      Returns:
      true when date is required in the component, and null is not allowed.

    • getLocalDate

      public LocalDate getLocalDate()
      Gets the local date part of the value.
      Specified by:
      getLocalDate in interface IUIDateTime
      Returns:
      Only the date part of the value, or null if the value is null.
      Throws:
      IllegalStateException - If the value doesn't contain a date part, i.e. it's the wrong datatype.

    • setDate

      public boolean setDate(LocalDate localDate)
      Sets the value as a local date with the locale information of the current user session (or system default) in case value conversion is required.

      If the component is configured for the UIDateTimeType.DateTime, this will change only the date part of the value and keep offset, zone and/or date parts. To set the entire value, use setValue(GDateTime) or setValue(GDateTime, LocaleInfo).

      Specified by:
      setDate in interface IUIDateTime
      Parameters:
      localDate - The local date to set, null is not allowed.
      Throws:
      IllegalArgumentException - If the date/time type is enforced and not matching, or in case the datatype is UIDateTimeType.Time.
      NullPointerException - If localDate is null or in case the CURRENT value is null and the datatype is UIDateTimeType.DateTime.

    • setDate

      public boolean setDate(LocalDate localDate, LocaleInfo localeInfo)
      Sets the value as a local date.

      If the component is configured for the UIDateTimeType.DateTime, this will change only the date part of the value and keep offset, zone and/or date parts. To set the entire value, use setValue(GDateTime) or setValue(GDateTime, LocaleInfo).

      Specified by:
      setDate in interface IUIDateTime
      Parameters:
      localDate - The local date to set, null is not allowed.
      localeInfo - The locale information to use, or null to use the current user's or system default.
      Throws:
      IllegalArgumentException - If the date/time type is enforced and not matching, or in case the datatype is UIDateTimeType.Time or UIDateTimeType.ZoneId.
      NullPointerException - If localDate is null or in case the CURRENT value is null and the datatype is UIDateTimeType.DateTime.

    • getZoneId

      public ZoneId getZoneId()
      Gets the zone of the value.
      Specified by:
      getZoneId in interface IUIDateTime
      Returns:
      Only the zone part of the value, or null if the value is null or doesn't have a zone. It is non-null only when the value is non-null and datatype is one of OffsetTime, OffsetDateTime, ZonedDateTime or ZoneId.

    • setZoneId

      public boolean setZoneId(ZoneId zone)
      Sets the zone value.

      If the component is configured for the UIDateTimeType.DateTime, this will change only the zone part of the value.

      Specified by:
      setZoneId in interface IUIDateTime
      Parameters:
      zone - The local date to set, null is not allowed.
      Throws:
      IllegalArgumentException - If the date/time type is enforced and not matching, or in case the datatype is UIDateTimeType.ZoneId.
      NullPointerException - If zone is null or in case the CURRENT value is null and the datatype is UIDateTimeType.DateTime.

    • getFormat

      public int getFormat()
      Gets the format used.
      Specified by:
      getFormat in interface IUIDateTime
      Returns:
      The format as 0=short, 1=normal, 2=long or 3=full (default).

    • setFormat

      public boolean setFormat(int format)
      Sets the format.
      Specified by:
      setFormat in interface IUIDateTime
      Parameters:
      format - The format as 0=short, 1=normal, 2=long or 3=full (default).
      Returns:
      true for changes, false for no change.
      Throws:
      IllegalArgumentException - If the format is not 0-3.

    • getMinimumYear

      public int getMinimumYear()
      Gets the minimum year for the mobile spinner.
      Specified by:
      getMinimumYear in interface IUIDateTime
      Returns:
      The minimum year, or -1 if undefined.

    • getMaximumYear

      public int getMaximumYear()
      Gets the maximum year for the mobile spinner.
      Specified by:
      getMaximumYear in interface IUIDateTime
      Returns:
      The minimum year, or -1 if undefined.

    • setYearRange

      public boolean setYearRange(int min, int max)
      Sets the minimum and maximum year for the mobile spinner.
      Specified by:
      setYearRange in interface IUIDateTime
      Parameters:
      min - The minimum year, or -1 for no minimum, i.e. current year minus 20.
      max - The maximum year, or -1 for no maximum, i.e. current year plus 20.
      Returns:
      true for changed, false for no change.
      Throws:
      IllegalArgumentException - If the min is larger than max or if either min or max is not in the range of 0-10_000.

    • isZoneUsed

      public boolean isZoneUsed()
      Returns whether the zone should be used for a ZonedTimeDate type.
      Specified by:
      isZoneUsed in interface IUIDateTime
      Returns:
      true to use the zone or false (default) not to use the zone.

    • setUseZone

      public boolean setUseZone(boolean on)
      Sets whether the zone should be used for a ZonedTimeDate type.
      Specified by:
      setUseZone in interface IUIDateTime
      Parameters:
      on - The flag.
      Returns:
      true for changes, false for no change.

    • isCalendarUsed

      public boolean isCalendarUsed()
      Returns whether a calendar should be used for date input (mobile only).
      Specified by:
      isCalendarUsed in interface IUIDateTime
      Returns:
      true to use the calendar or false (default) to use spinners.

    • setUseCalendar

      public boolean setUseCalendar(boolean on)
      Sets whether a calendar should be used for date input (mobile only).
      Specified by:
      setUseCalendar in interface IUIDateTime
      Parameters:
      on - The flag.
      Returns:
      true for changes, false for no change.

    • hasCalendarButton

      public boolean hasCalendarButton()
      Returns whether a button to show calendar should be present for date input (mobile only).
      Specified by:
      hasCalendarButton in interface IUIDateTime
      Returns:
      true to use the calendar or false (default) to use spinners.

    • setUseCalendarButton

      public boolean setUseCalendarButton(boolean on)
      Sets whether a calendar button should be shown for date input (mobile only).
      Specified by:
      setUseCalendarButton in interface IUIDateTime
      Parameters:
      on - The flag.
      Returns:
      true for changes, false for no change.

    • isMillisecondsUsed

      public boolean isMillisecondsUsed()
      Returns whether the time value should use milliseconds in time formats using seconds.
      Specified by:
      isMillisecondsUsed in interface IUIDateTime
      Returns:
      true to use the zone or false (default) not to use the zone.

    • setUseMilliseconds

      public boolean setUseMilliseconds(boolean on)
      Sets whether the time value should use milliseconds in time formats using seconds.
      Specified by:
      setUseMilliseconds in interface IUIDateTime
      Parameters:
      on - The flag.
      Returns:
      true for changes, false for no change.

    • isDayMonthCombined

      public boolean isDayMonthCombined()
      Returns whether to combine day and month in a single spinner (mobile).
      Specified by:
      isDayMonthCombined in interface IUIDateTime
      Returns:
      The flag, default false.

    • setCombineDayMonth

      public boolean setCombineDayMonth(boolean on)
      Sets whether to combine day and month in a single spinner (mobile).
      Specified by:
      setCombineDayMonth in interface IUIDateTime
      Parameters:
      on - The flag.
      Returns:
      true for changes, false for no change.

    • getVisualLength

      public int getVisualLength()
      Returns the visual length of the entry field.
      Returns:
      The visual length or 15 by default.

    • getApproximateSize

      public Size getApproximateSize()
      Returns the size of the component in pixels. The size is a calculation and does not exactly reflect the real size that may be different due to additional styles not taken into account by this method. The size is calculated from the font of the component and default or defined values (such as character length or number of lines for text area).
      Specified by:
      getApproximateSize in class UIComp
      Returns:
      The size of the component.