Developer

API Reference

AEECLSID_JulianDateWidget

Brew Release
Brew MP 1.0.2
See Also
AEEDateTime AEECLSID_JulianTimeWidget Border Events Events IDateCtl ISHELL_CreateInstance IWidget_SetFlags Model Events
Description

This topic describes two similar widgets, a date widget and a time widget, each of which is used to display and set a date/time variable. These widgets share common behaviors, such as how they handle events or interact with their attached model; but they differ in what fields they contain and what data they expose from their model.
NOTES: The AEECLSID_JulianDateWidget and AEECLSID_JulianTimeWidget classes replace the IDateCtl interface, which has been deprecated. The Date and Time widgets are deprecated and should no longer be used. Instead use the AEECLSID_JulianDateWidget and AEECLSID_JulianTimeWidget classes, which are similar.
Features common to both the date and time widgets: - Automatic field verification and date/time validation.
- Field order that is configurable.
- Fields that are specified by a format pattern string or ILocale object.
- Field delimiter that are specified by a string or ILocale object.
- Value model updating and notification that is performed in two different
configurable modes, upon field change or upon focus change. - Fields that are auto-incremented and decremented with the up/down arrow keys.

View Model Notifications:
The date and time widgets will send event notifications through their view model for the widget events described below.
   
Event                   Description
-----                   -----------------------------------------------------------
EVT_MDL_FIELDCHANGE:    The date and time widgets send this notification when the current
                        field selection has been changed by user navigation.  The 
                        dwParam value of the ModelEvent struct contains a composite 
                        value.  The high-order word contains the zero-based index of the 
                        new field.  The low-order word contains a boolean value that signifies 
                        the direction of movement.  
                        
                        HIWORD(dwParam) (dwParam >> 16)  --  (uint16) new field index.
                        LOWORD(dwParam) (dwParam & 0xFF) --  (boolean) direction of movement.
                                                             TRUE means forward (right) movement.
                                                             FALSE means backward (left) movement.
                        
                        For example, when moving from field 1 to field 2, the widget will 
                        send an EVT_MDL_FIELDCHANGE notification with the high-order word of 
                        the dwParam member set to 2, and the low-order word of the dwParam 
                        member set to 1 (TRUE).  


Supported Events:
The base date and time widgets handler responds to the following events as well as those handled by any widget that supports Border Events.
Event                   Description
-----                   ------------------------------------------------------------
EVT_POINTER_DOWN,       The date and time widgets route these events to the attached touch 
EVT_POINTER_UP,         controller (if one is present).
EVT_POINTER_MOVE, and
EVT_POINTER_STALE_MOVE  

EVT_WDG_ENABLETOUCH     The widget will enable or disable touch as specified in the dwParam.

EVT_WDG_SCROLL          If the flag DTWF_USEUPDOWNKEYS has been enabled, the currently selected
                        field will be incremented or decremented depending on the direction of
                        the scroll.

EVT_KEY                 The date/time widget accepts the movement keys, numeric keys, and select
                        as follows.
                        AVK_LEFT/RIGHT    Moves between the elements of the date time widget or,
                                          in cursor mode (see PROP_FLAGS below), between the
                                          digits of the elements.
                        AVK_UP/DOWN       If the flag DTWF_USEUPDOWNKEYS has been enabled,
                                          increments or decrements the value of the field or
                                          digit under the cursor.
                        AVK_0-9           Enters the digit as the value of the field or digit under
                                          the cursor.  If in field mode, the next digit is then
                                          implicitly selected.  The value is capped within the
                                          range of the field, so, for example, when a 9 is entered
                                          as the minute value, it will automatically become '09'
                                          because the "ten minutes" column cannot be above 6.
                        AVK_SELECT        Toggles the AM/PM field (if that is the item selected).

EVT_WDG_CANTAKETOUCH    Updates the passed in dwParam to reflect whether or not the widget can
                        take touch events.  Refer to the IWidget_CanTakeTouch topic.

EVT_WDG_SETPROPERTY:    The date and time widgets respond to this event by attempting to set the
                        property identified by the wParam parameter.  The date and time widgets
                        allow the following properties to be set:
                        PROP_FONT_CLASS
                        PROP_FONT
                        PROP_FONT_OUTLINECOLOR
                        PROP_FONT_OUTLINEWIDTH
                        PROP_FLAGS
                        PROP_LOCALE
                        PROP_FORMATSTRING
                        PROP_DELIMITER
                        PROP_FIELDPAD
                        PROP_ARROWPAD
                        PROP_FGCOLOR
                        PROP_SELECTED_FGCOLOR
                        PROP_TEXT_SELECTED_FGCOLOR
                        PROP_SACTIVE_FGCOLOR
                        PROP_TEXT_SACTIVE_FGCOLOR
                        PROP_SINACTIVE_FGCOLOR
                        PROP_TEXT_SINACTIVE_FGCOLOR
                        PROP_ACTIVE_FGCOLOR
                        PROP_INACTIVE_FGCOLOR
                        PROP_TEXT_SELECTED_BGCOLOR
                        PROP_TEXT_SACTIVE_BGCOLOR
                        PROP_TEXT_SINACTIVE_BGCOLOR
                        PROP_IMAGESTRIP
                        PROP_FOCUSINDEX
                        PROP_READONLY
                        PROP_EX
                        PROPEX_TOUCH_CONTROLLER
                        PROPEX_USER_DATA
                        PROPEX_TOUCH_MODE

						Refer to the IWidget_SetProperty and IWidget_SetPropertyEx topics.
                        
EVT_WDG_GETPROPERTY:    The date and time widgets respond to this event by attempting to retrieve the
                        property identified by the wParam parameter.  The date and time widgets
                        allow the following properties to be retrieved:
                        PROP_FONT
                        PROP_FONT_OUTLINECOLOR
                        PROP_FONT_OUTLINEWIDTH
                        PROP_FLAGS
                        PROP_FIELDPAD
                        PROP_ARROWPAD
                        PROP_FGCOLOR
                        PROP_SELECTED_FGCOLOR
                        PROP_TEXT_SELECTED_FGCOLOR
                        PROP_SACTIVE_FGCOLOR
                        PROP_TEXT_SACTIVE_FGCOLOR
                        PROP_SINACTIVE_FGCOLOR
                        PROP_TEXT_SINACTIVE_FGCOLOR
                        PROP_ACTIVE_FGCOLOR
                        PROP_INACTIVE_FGCOLOR
                        PROP_TEXT_SELECTED_BGCOLOR
                        PROP_TEXT_SACTIVE_BGCOLOR
                        PROP_TEXT_SINACTIVE_BGCOLOR
                        PROP_FOCUSINDEX
                        PROP_JULIANVALUEMODEL
                        PROP_FORMATSTRING
                        PROP_DELIMITER
                        PROP_READONLY
                        PROP_EX
                        PROPEX_WIDGETELEMINFO
                        PROPEX_TOUCH_CONTROLLER
                        PROPEX_USER_DATA
                        PROPEX_TOUCH_MODE

						Refer to the IWidget_GetProperty, IWidget_GetPropertyEx, IWidget_GetPropBool, 
                        IWidget_GetPropInt, IWidget_GetPropPtr, and IWidget_GetPropRGB topics.

Properties:


Property                Description
--------                ------------------------------------------------------------
PROP_FONT               This property sets or retrieves the font that will be used by the date and time
                        widgets for display.  Refer to the IWidget_SetFont and IWidget_GetFont topics.
                             
PROP_FONT_CLASS         This property sets the class ID to create an IFont object that will be used
                        to render the text displayed within the date or time widget.  It is a
                        shortcut for PROP_FONT as it saves having to personally create an IFont
                        object to be used by the date and time widgets.  Refer to the IWidget_SetFontClass
						topic.

PROP_FONT_OUTLINEWIDTH  This property sets the width of the outline to be applied when rendering
                        text within the static widget.  Setting this property only has an effect
                        on the text if the current IFont instance understands this property (such
                        as an instance implementing IHFont).  Refer to the IWidget_SetFontOutlineWidth 
                        and IWidget_GetFontOutlineWidth topics.

PROP_FONT_OUTLINECOLOR  This property sets the color of the outline to be applied when rendering
                        text within the static widget.  Setting this property only affects the
                        text if an IFont object (such as an IHFont) that understands this 
                        property was set earlier via the PROP_FONT property.  Refer to the 
						IWidget_SetFontOutlineColor and IWidget_GetFontOutlineColor topics.
                             
PROP_LOCALE             This property sets the ILocale object that the widget will use to retrieve date/time 
                        display and entry characteristics such as date or time pattern string, field delimiter, 
                        and AM/PM designators. Note that this property will override any previous settings of 
                        PROP_FORMATSTRING and PROP_DELIMITER.  The ILocale items that are used by the date and
                        time widget are shown below. For more information about ILocale, see AEEILocale.h file.

                        ILocale parm items used by Time widget
                        --------------------------------------
                        ILOCALEPARM_DATETIME_SHORTTIMEPATTERN
                        ILOCALEPARM_DATETIME_TIMESEPARATOR
                        ILOCALEPARM_DATETIME_AMDESIGNATOR
                        ILOCALEPARM_DATETIME_PMDESIGNATOR
                            
                        ILocale parm items used by Date widget
                        --------------------------------------
                        ILOCALEPARM_DATETIME_SHORTDATEPATTERN
                        ILOCALEPARM_DATETIME_DATESEPARATOR

                        Refer to the IWidget_SetLocale topic.

PROP_FORMATSTRING       This property sets a format string that the widget will use to determine 
                        date/time field order and field characteristics.  The format string is
                        a NULL-terminated AECHAR string compatible with the short date and time 
                        patterns defined for ILocale (ILOCALEPARM_DATETIME_SHORTDATEPATTERN and 
                        ILOCALEPARM_DATETIME_SHORTTIMEPATTERN). The strings are composed of patterns 
                        that specify desired entry fields in the widget, as shown below.  All other 
                        characters in the string are ignored.

                        This string should be considered constant from the perspective of any user
                        who retrieves it through ILocale_GetXXX methods.  If any changes need to be made 
                        to the format string, the string should be copied before any such changes
                        occur.
                        
                        Allowable format patterns for the Date widget:
                        ----------------------------------------------
                        
                        d | dd | ddd | dddd     day, (two digits)
                        M | MM | MMM | MMMM     month (two digits)
                        y | yy | yyy            year (two digits)
                        Y | yyyy                year (four digits)

                        
                        Example date format string.
                           
                           const AECHAR wszFormat[] = {'M','d','Y',0};  
                           // fields displayed are: month (2 digits)
                           //                       day (2 Digits)
                           //                       year (4 digits)


                        
                        Allowable format patterns for the Time widget:
                        ----------------------------------------------
                        
                        h | hh                  hour, (1-12, two digits)
                        H | HH                  hour, (1-24, two digits)
                        m | mm                  minute, (two digits)
                        s | ss                  seconds, (two digits)
                        t                       AM/PM designator (single char)
                        T | tt                  AM/PM designator (two chars) 

                          
                        Example time format string:
                        ---------------------------
  
                        const AECHAR wszFormat[] = {'h','m','s','T',0};  
                        // fields displayed are: hours (12 hour time)
                        //                       minutes
                        //                       seconds
                        //                       AM/PM (2 chars)
                            IWidget_SetFormatString
                            IWidget_GetFormatString

PROP_DELIMITER          This property sets a delimiter string that the widget will display between
                        fields.  The delimiter string is a NULL-terminated AECHAR string.  If a
                        NULL delimiter string is provided, the default delimiter of the current
                        locale will be used.

                        This string should be considered constant from the perspective of any user
                        who retrieves it through one of the ILocale_GetXXX methods.  If any changes 
						need to be made to the delimiter string, the string should be copied before 
						any such changes occur.  Refer to the IWidget_SetDelimiterString and 
						IWidget_GetDelimiterString topics.

PROP_FIELDPAD           This property sets the amount of padding, in pixels, that will be displayed around 
                        each side of the bounding rectangle of the field text. When the field is selected, 
                        the selection highlight will encompass the text bounding rectangle plus the field pad.
                        Refer to the IWidget_SetFieldPad and IWidget_GetFieldPad topics.

PROP_ARROWPAD           This property sets the amount of padding, in pixels, that will be displayed
                        between the top and bottom of the field selection rectangle and the Up and Down
                        arrows, when visible.  Refer to the IWidget_SetArrowPad and IWidget_GetArrowPad 
						topics.

PROP_FLAGS              This property contains a set of flags that effect the behavior of the date and 
                        time widget.

                        DTWF_UPDATE_ONFIELDCHANGE
                        -------------------------
                        When this flag is set, the widget will update and notify through 
                        it's attached value model whenever the field selection is moved from 
                        a dirty field.  (A dirty field is one whose value has been changed.)  
                        Without this flag set, the default behavior is to only update and 
                        notify through the value model when focus is removed from the widget 
                        and one or more fields are dirty.  
                        
                        DTWF_USEUPDOWNKEYS
                        ------------------
                        When this flag is set, the widget will accept and handle Up/Down 
                        (AVK_UP/AVK_DOWN) keys by incrementing or decrementing the current 
                        field value.  Without this flag set, the default behavior is to 
                        ignore Up/Down keys.  
                        
                        DTWF_SHOWUPDOWNARROWS
                        ---------------------
                        When this flag is set in conjunction with the DTWF_USEUPDOWNKEYS flag, 
                        the widget will display Up/Down indicator arrows above and below 
                        each field to indicate that the field may be incremented or 
                        decremented.  If this flag is used without DTWF_USEUPDOWNKEYS, it 
                        will be ignored.  

                        DTWF_NOFIELDWRAP
                        -----------------
                        When this flag is set, the widget will not wrap from the first field to
                        the last field when left key (AVK_LEFT) is pressed, or from 
                        last field to first field when right key (AVK_RIGHT) is pressed. 
                        If this flag is not set, then corresponding keys will  be handled
                        by the widget and widget will wrap from/to first/last field on 
                        AVK_LEFT/AVK_RIGHT.

                        DTWF_SHOWCURSOR
                        -----------------
                        When this flag is set, the widget will enable entering digits  
                        from left to right, and a cursor will show the position where the 
                        digit will be entered. AVK_LEFT/AVK_RIGHT will move the cursor to 
                        the next/previous character position in the field, if there is 
                        no next/previous character positions left in the current field, 
                        then it will move the cursor to next/previous field,
                        When this flag is set in conjunction with DTWF_USEUPDOWNKEYS, the 
                        widget will accept and handle Up/Down (AVK_UP/AVK_DOWN) keys by 
                        incrementing or decrementing the current field value. If there is no 
                        field value above the current field (for AVK_UP) or below the field 
                        (for AVK_DOWN), then the key press will not be handled.
                        The widget will not allow the user to enter invalid input.
                        For example, If the user is on the first character of a month or field,
                        and tries to enters a number greater than 1, then the first character
                        of the month field will be filled with '0' and the second with the 
                        entered digit. If the user has entered a 1 in the first character, then
                        key presses with values greater than 2 will not be handled.  Refer to the 
                        IWidget_SetFlags, IWidget_AddFlags, IWidget_RemoveFlags, and 
						IWidget_GetFlags topics.

PROP_IMAGESTRIP         This property contains the bitmap the widget uses when drawing the
                        Up/Down indicator arrows above and below each field that indicate 
                        that the field may be incremented or decremented.  The bitmap is
                        made up of a horizontal image strip of the up arrow image followed
                        by the down arrow.  
                        
                        Setting PROP_IMAGESTRIP to NULL will cause the Date/Time Widget to 
                        revert to using the default images for the up and down indicators.

                        The bitmap is AddRef'ed internally and released when no longer
                        needed by the widget.  Refer to the IWidget_SetPropImageStrip topic.

PROP_FOCUSINDEX         This property contains which field in the date/time widget is
                        currently selected.  This value is zero-based, so index 0 indicates
                        the first field in the widget.  On set, the high 16 bits are used
                        as the caret position and the low 16 bits are used as the field
                        position.  The caret position is not reported when the focus index
                        is retrieved.  Refer to the IWidget_SetFocusIndex and 
						IWidget_GetFocusIndex topics.

PROP_JULIANVALUEMODEL   Get Only.  Retrieves whether or not the internal value model is stored
                        using a JulianValueModel.  This will be TRUE if the widget is a Julian
                        date or time widget and FALSE if it is the older, deprecated, date/time
                        widget.  Refer to the IWidget_GetJulianTypeValueModel topic.

PROP_FGCOLOR            This property contains the color that the date and time widget will use 
                        to draw its text.  Setting PROP_FGCOLOR will set the text color for all
                        combinations of the widget selection and activate, as indicated by
                        the following table.
                             
                                                                   Text color when 
                               Selection State    Active State     the widget is displayed
                               ---------------    ------------     -----------------------
                               Unselected         Inactive         PROP_FGCOLOR
                               Unselected         Active           PROP_FGCOLOR
                               Selected           Inactive         PROP_FGCOLOR
                               Selected           Active           RGB_WHITE
                             
                        Though setting the PROP_FGCOLOR will effect *all* combinations of
                        selection and activation, getting the value of the property will return
                        the text color that will be applied when drawing the widget in its active,
                        unselected state.

                        Note, setting PROP_FGCOLOR automatically sets the color to be used for
                        selected text to RGB_WHITE.  This allows applications to set the text
                        color to RGB_BLACK without making selected text invisible.  If your app
                        needs to draw selected text in a custom color, set PROP_SACTIVE_FGCOLOR
                        after setting PROP_FGCOLOR.  Refer to the IWidget_SetFGColor and 
						IWidget_GetFGColor topics.

PROP_SELECTED_FGCOLOR
PROP_TEXT_SELECTED_FGCOLOR
                        These synonymous properties contain the text color the Date/Time widget
                        will use for the selected field both when the widget does and does not
                        have focus.  Refer to the IWidget_SetSelectedFGColor topic.

PROP_SACTIVE_FGCOLOR
PROP_TEXT_SACTIVE_FGCOLOR
                        These synonymous properties contain the text color the Date/Time widget
                        will use for the selected field when the widget has focus.  Refer to the 
                        IWidget_SetSelectedActiveFGColor and IWidget_GetSelectedActiveFGColor 
						topics.

PROP_SINACTIVE_FGCOLOR
PROP_TEXT_SINACTIVE_FGCOLOR
                        These synonymous properties contain the text color the Date/Time widget
                        will use for the selected field when the widget does not have focus.
						Refer to the IWidget_SetSelectedInactiveFGColor and 
						IWidget_GetSelectedInactiveFGColor topics.

PROP_ACTIVE_FGCOLOR
                        This property contains the text color the Date/Time widget will use for
                        non-selected text when the widget has focus.  Refer to the 
						IWidget_SetActiveFGColor and IWidget_GetActiveFGColor topics.

PROP_INACTIVE_FGCOLOR
                        This property contains the text color the Date/Time widget will use for
                        non-selected text when the widget does not have focus.  Refer to the 
						IWidget_SetInactiveFGColor and IWidget_GetInactiveFGColor topics.

PROP_TEXT_SELECTED_BGCOLOR
                        This property contains the background color the Date/Time widget will use
                        to surround the selected text both when the widget does and does not have
                        focus.  This property only supports full transparency.  If a
                        semi-transparent color is used, it will be treated as if it were opaque.

PROP_TEXT_SACTIVE_BGCOLOR
                        This property contains the background color the Date/Time widget will use
                        to surround the selected text when the widget has focus.  This property
                        only supports full transparency.  If a semi-transparent color is used, it
                        will be treated as if it were opaque.

PROP_TEXT_SACTIVE_BGCOLOR
                        This property contains the background color the Date/Time widget will use
                        to surround the selected text when the widget does not have focus.  This
                        property only supports full transparency.  If a semi-transparent color is
                        used, it will be treated as if it were opaque.

PROP_READONLY:          This property sets and clears the readonly mode of the date/time widget.
                        If readonly mode is set, the widget will not handle any key events, and it
                        will not draw the selection field.  Refer to the IWidget_SetReadonlyMode
						and IWidget_GetReadonlyMode topics.

Required Model:
IValueModel
Model Data:
Julian Date Widget (AEECLSID_JulianDateWidget) and Julian Time Widget (AEECLSID_JulianTimeWidget)
AEEDateTime julian; // julian date structure representing any date
The julian date and julian time widgets differ from their counterparts in that they rely on a value model that contains a julian date structure (rather than a uint32) representing the date and time.
A default model is created and assigned to the widget when the widget is created with ISHELL_CreateInstance(). The client can replace the widget's model at any time with the method: IWidget_SetModel(), as long as the supplied model interface is of the type that the widget expects.
The Julian Date and Julian Time widgets both perform validation of the AEEDateTime date structure set in their model to ensure a valid date is stored and displayed. If an invalid date is passed in, the widgets will change the offending fields to make the date valid. This keeps their behavior in line with their non-julian counterparts.
The data supplied in the value model must be of type AEEDateTime.
Date Widget, Time Widget (DEPRECATED)
uint32 seconds; // number of seconds since phone reference time
The date and time widgets rely on a value model that contains an unsigned 32-bit integer representing the date/time value in seconds. This value represents the number of seconds since Jan 6 1980, the phone reference time. Use the library function GETJULIANDATE() to convert this value to a more usable AEEDateTime data structure. Use the library function JULIANTOSECONDS() to convert a AEEDateTime date/time to a seconds value compatible with this widget's value mode.
When using JULIANTOSECONDS() to create a uint32 'seconds' value for use in a time widget, make sure that the date fields of the AEEDateTime contain a valid date. Specifically, the wYear field should contain a value in the range of 1980-2115, the wMonth field should contain a value in the range of 1-12, and the wDay field should contain a value in the range of 1-31. The wWeekDay field is ignored when computing seconds with JULIANTOSECONDS().
A default model is created and assigned to the widget when the widget is created with ISHELL_CreateInstance(). The client can replace the widget's model at any time with the method: IWidget_SetModel(), as long as the supplied model interface is of the type that the widget expects.
The data supplied in the value model must be of type uint32.
Instantiaion
The Date/Time Widget is instanciated by passing any of the following into ISHELL_CreateInstance. - AEECLSID_JulianDateWidget
- AEECLSID_JulianTimeWidget
- AEECLSID_DateWidget
- AEECLSID_TimeWidget
Cleanup
The Date/Time Widget is reference counted. When you are done with your reference to the Date/Time widget, you should Release that reference. Any widget specific cleanup will be handled for you when all references have been released.
Default Interface Name
Comment
None
  • Follow