The Palm OS® UI Library provides two system resources for accepting date and time input values. These resources are dialogs that contain gadgets for entering dates and times. The Palm OS UI Library also provides routines to manage the interaction with these resources. This chapter describes those functions.
Date and Time Selection Structures and Types
Date and Time Selection Constants
Date and Time Selection Events
Date and Time Selection Functions and Macros
The API described in this chapter is declared in the header files Day.h
, SelDay.h
, SelTime.h
, and SelTimeZone.h
.
Date and Time Selection Structures and Types
DaySelectorType Struct
Purpose
Private structure that represents a day selector gadget. The DaySelectorPtr
defines a pointer to the DaySelectorType
structure.
Declared In
Day.h
Prototype
typedef struct DaySelectorType DaySelectorType;
typedef DaySelectorType *DaySelectorPtr
Fields
HMSTime Struct
Purpose
Declared In
SelTime.h
Prototype
typedef struct { uint8_t hours; uint8_t minutes; uint8_t seconds; uint8_t reserved; } HMSTime
Fields
-
hours
- The number of hours.
-
minutes
- The number of minutes.
-
seconds
- The number of seconds.
-
reserved
- Not used.
Date and Time Selection Constants
Miscellaneous Constants
Purpose
Constants declared in SelDay.h
.
Declared In
SelDay.h
Constants
-
#define daySelectorMaxYear lastYear
- The furthest year in the future that the day selector gadget can display.
-
#define daySelectorMinYear firstYear
- The furthest year in the past that the day selector gadget can display.
SelectDayType Typedef
Purpose
Specifies how a user can select a date.
Declared In
Day.h
Prototype
typedef Enum8 SelectDayType
Constants
-
selectDayByDay
- The user can select individual days.
-
selectDayByWeek
- The user can only select a week at a time.
-
selectDayByMonth
- The user can only select a month at a time.
See Also
SelectTimeZoneDisplayType Typedef
Purpose
Controls what is displayed in the dialog displayed by SelectTimeZone()
.
Declared In
SelTimeZone.h
Prototype
typedef Enum8 SelectTimeZoneDisplayType
Constants
-
showNoTime = 0
- The dialog does not show the time of day.
-
showCurrentAndNewTimeZone
- The dialog shows the time of day in the current time zone as well as the newly selected time zone.
-
showDeviceTimeZone
- The dialog shows the device's time of day in the device's default time zone. This setting is used by the Setup application.
Date and Time Selection Events
daySelectEvent
Purpose
Sent when the pen touches and is lifted from a day number in the day selector gadget.
For this event, the EventType
data
field contains the structure shown in the Prototype section, below.
Declared In
Event.h
Prototype
struct daySelect { struct DaySelectorType *pSelector; int16_t selection; Boolean useThisDate; uint8_t reserved1; } daySelect;
Fields
-
pSelector
- Pointer to a day selector structure.
-
selection
- Not used.
-
useThisDate
- Set to
true
to automatically use the selected date. -
reserved1
- Unused.
Date and Time Selection Functions and Macros
DayDrawDays Function
Purpose
Draw only the days-of-the-month portion of a day selector gadget.
Declared In
Day.h
Prototype
void DayDrawDays (
const DaySelectorPtr selectorP
)
Parameters
Returns
Comments
This function is used when the year or month changes. Only drawing the portion of the control that presents the days of the month avoids the flicker that would occur if the week titles were redrawn.
Use this function only if you want to use the day selector gadget in a dialog that is different than the one used in the Date Book application.
See Also
DayDrawDaySelector()
, SelectDay()
DayDrawDaySelector Function
Purpose
Draws a day selector gadget on screen.
Declared In
Day.h
Prototype
void DayDrawDaySelector (
const DaySelectorPtr selectorP
)
Parameters
Returns
Comments
The gadget is drawn only if it is usable.
Use this function only if you want to use the day selector gadget in a dialog that is different than the one used in the Date Book application.
See Also
DayHandleEvent Function
Purpose
Handles an event in the specified day selector gadget.
Declared In
Day.h
Prototype
Boolean DayHandleEvent ( const DaySelectorPtrselectorP
, const EventType*pEvent
)
Parameters
-
→
selectorP
- Pointer to day selector gadget.
-
→
pEvent
- Pointer to an
EventType
structure.
Returns
true
if the event was handled or false
if it was not.
Comments
This function handles events in a similar fashion as CtlHandleEvent()
. It tracks the pen while the pen is down within the bounds of the day selector gadget. If the pen is released within the gadget's bounds, it adds a daySelectEvent
with information on whether to use the date. If the pen is released outside of the gadget's bounds, no event is posted.
SelectDay Function
Purpose
Displays a dialog showing a date; allows user to select a different date.
Declared In
SelDay.h
Prototype
Boolean SelectDay ( const SelectDayTypeselectDayBy
, int16_t*month
, int16_t*day
, int16_t*year
, const char*title
)
Parameters
-
→ selectDayBy
- The method by which the user should choose the day. See
SelectDayType
. -
↔
month, day, year
- Month, day, and year selected.
-
→
title
- String title for the dialog.
Returns
true
if the OK button was pressed. If true
, month
, day
, and year
contain the new date.
Comments
The dialog displayed is the same one used by the Date Book application when the Go To button is tapped.
See Also
DayDrawDays()
, DayDrawDaySelector()
SelectOneTime Function
Purpose
Displays a dialog showing the time and allows the user to select a different time.
Declared In
SelTime.h
Prototype
Boolean SelectOneTime ( int16_t*hour
, int16_t*minute
, const char*titleP
)
Parameters
-
↔
hour
- The hour selected in the form.
-
↔
minute
- The minute selected in the form.
-
→
titleP
- A pointer to a string to display as the title. Doesn't change as the function executes.
Returns
true
if the user selects OK and false
otherwise. If true
is returned, the values in hour
and minute
have probably been changed.
Comments
Use this function instead of SelectTime()
if you want to display a dialog that specifies a single point in time, not a range of time from start to end.
SelectTime Function
Purpose
Displays a dialog showing a start and end time. Allows the user to select a different time.
Declared In
SelTime.h
Prototype
Boolean SelectTime ( TimeType*startTimeP
, TimeType*EndTimeP
, const Booleanuntimed
, const char*titleP
, int16_tstartOfDay
, int16_tendOfDay
, int16_tstartOfDisplay
)
Parameters
-
↔
startTimeP, EndTimeP
- Pointers to values of type
TimeType
. Pass initial values to display in these two parameters. If the user makes a selection and taps the OK button, the selected values are returned here. -
→
untimed
- Pass in
true
to indicate that no time is selected. If the user later sets the time to no time thenstartTimeP
andEndTimeP
are both set to the constantnoTime
. -
→
titleP
- A pointer to a string to display as the title.
-
→
startOfDay
- The hour that the hour list displays at its top. To see earlier hours, the user can scroll the list up. The value must be between 0 to 12, inclusive.
-
→
endOfDay
- The hour used when the "All Day" button is selected.
-
→
startOfDisplay
- First hour initially visible if the user scrolls the list up to the top.
Returns
true
if the user taps OK or false
otherwise.
Comments
The dialog displayed by this function is intended for scheduling appointments. To select an individual time, use SelectOneTime()
instead.
See Also
SelectTimeZone Function
Purpose
Displays a dialog that allows the user to select a time zone.
Declared In
SelTimeZone.h
Prototype
Boolean SelectTimeZone ( char*ioZoneIDP
, const char*titleP
, SelectTimeZoneDisplayTypedisplayOption
)
Parameters
-
↔ ioZoneIDP
- A pointer to the initially selected time zone. This string should be
TZNAME_MAX
bytes long. Upon return, contains the user's selection. -
→ titleP
- A string to use as the title for the dialog. Pass
NULL
to use the default title, which is "Set Time Zone" in the US English locale. -
→ displayOption
- See
SelectTimeZoneDisplayType
.
Returns
true
if the user tapped the OK button in the dialog to change the time zone, or false
if the user tapped the Cancel button.
Comments
This function displays the time zone dialog used by the Date and Time panel in the Preferences application.
Example
The following example shows how to use the current time zone as the initial value for ioZoneIDP
:
char zoneID[TZNAME_MAX]; Boolean change; //get the current time zone gettimmezone(zoneID, TZNAME_MAX); change = SelectTimeZone(zoneID, NULL, showCurrentAndNewTimeZone); //set the device time zone to the newly selected time zone. if (change) { settimezone(timeZone); }
SelectTimeZoneV50 Function
Purpose
Displays a dialog that allows the user to select a different time zone.
Declared In
SelTimeZone.h
Prototype
Boolean SelectTimeZoneV50 ( int16_t*ioTimeZoneP
, LmLocaleType*ioLocaleInTimeZoneP
, const char*titleP
, BooleanshowTimes
, BooleananyLocale
)
Parameters
-
↔ ioTimeZoneP
- A pointer to the time zone, given as minutes east of Greenwich Mean Time (GMT). The initial value is used as the initial selection in the form. Upon return, this parameter contains a pointer to the new time zone that the user selected.
-
↔ ioLocaleInTimeZoneP
- A pointer to a locale (see
LmLocaleType
) that identifies the time zone country. This parameter is used for countries that share a time zone, such as Canada and Chile. - If the time zone specified by
ioTimeZoneP
is specific to a particular country, you do not have to initialize this parameter. Instead, set theanyLocale
parameter totrue
to have this parameter ignored upon entry. -
→ titleP
- A string to use as the title for the dialog. Pass
NULL
to use the default title, which is "Set Time Zone" in the US English locale. -
→ showTimes
- If
true
, the dialog shows the correct times in both the current and newly selected time zones. Iffalse
, the dialog doesn't show the current time. Usingfalse
provides a larger area for the list of time zones. -
→ anyLocale
- If
true
, ignoreioLocaleInTimeZoneP
upon entry.
Returns
true
if the user tapped the OK button in the dialog to change the time zone, or false
if the user tapped the Cancel button.
Comments
This function displays the time zone dialog used by the Date and Time panel in the Preferences application.
The time zones displayed in the dialog are listed by country. For this reason, if the time zone specified by ioTimeZoneP
is shared by several countries, you need to supply a value for ioLocaleInTimeZoneP
to identify which country should be selected when the list is first displayed. You can use the constant lmAnyLanguage
as the value for the language field of the structure pointed to by this parameter.
If you don't care which value is initially selected, pass true
for the anyLocale
parameter. In this case, the first country that matches the GMT offset given in ioTimeZoneP
is selected.
Example
The following example shows how to use the time zone preference as the initial value for ioTimeZoneP
.
int16_t timeZone = (int16_t)PrefGetPreference(prefTimeZone); CountryType timeZoneCountry = (CountryType) PrefGetPreference(prefTimeZoneCountry); LmLocaleType timeZoneLocale; Boolean change; timeZoneLocale.country = timeZoneCountry; timeZoneLocale.language = lmAnyLanguage; change = SelectTimeZoneV50(&timeZone, &timeZoneLocale, NULL, true, false); if (change) { PrefSetPreference(prefTimeZone, timeZone); PrefSetPreference(prefTimeZoneCountry, timeZoneCountry); }
Compatibility
This function is provided for backward compatibility only. Use SelectTimeZone()
instead.