Package com.iizix.prop.ui.datetime

Class UIDateTime

    • Constructor Detail

      • 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 Detail

      • 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:
        java.lang.IllegalArgumentException - If the type does not support the dataType.

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

      • 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:
        java.lang.IllegalArgumentException - If the date/time type is enforced and not matching.
        java.lang.IllegalStateException - If the date/time conversion cannot possibly take place due to type mismatch.
        java.lang.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:
        java.lang.IllegalArgumentException - If the date/time type is enforced and not matching.
        java.lang.IllegalStateException - If the date/time conversion cannot possibly take place due to type mismatch.
        java.lang.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.

      • getLocalDate

        public java.time.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:
        java.lang.IllegalStateException - If the value doesn't contain a date part, i.e. it's the wrong datatype.

      • setDate

        public boolean setDate​(java.time.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:
        java.lang.IllegalArgumentException - If the date/time type is enforced and not matching, or in case the datatype is UIDateTimeType.Time.
        java.lang.NullPointerException - If localDate is null or in case the CURRENT value is null and the datatype is UIDateTimeType.DateTime.

      • setDate

        public boolean setDate​(java.time.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:
        java.lang.IllegalArgumentException - If the date/time type is enforced and not matching, or in case the datatype is UIDateTimeType.Time or UIDateTimeType.ZoneId.
        java.lang.NullPointerException - If localDate is null or in case the CURRENT value is null and the datatype is UIDateTimeType.DateTime.

      • getZoneId

        public java.time.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​(java.time.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:
        java.lang.IllegalArgumentException - If the date/time type is enforced and not matching, or in case the datatype is UIDateTimeType.ZoneId.
        java.lang.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:
        java.lang.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:
        java.lang.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.