The Palm OS® UI provides two system resources for accepting date and time input values. These resources are dialog boxes that contain UI gadgetry for entering dates and times. The Palm OS UI also provides functions to manage the interaction with these resources. This chapter describes those functions.
The API described in this chapter is declared in the header files Day.h
, SelDay.h
, SelTime.h
, and SelTimeZone.h
.
Date and Time Selections Data Structures
SelectDayType Struct
Prototype
typedef enum { selectDayByDay, // return d/m/y selectDayByWeek, // return d/m/y with d as // same day of the week selectDayByMonth // return d/m/y with d as // same day of the month } SelectDayType;
DaySelectorType Struct
Prototype
typedef struct DaySelectorType { RectangleType bounds; Boolean visible; UInt8 reserved1; Int16 visibleMonth; // month actually // displayed Int16 visibleYear; // year actually // displayed DateTimeType selected; SelectDayType selectDayBy; UInt8 reserved2; } DaySelectorType;
HMSTime Struct
Prototype
typedef struct { UInt8 hours; UInt8 minutes; UInt8 seconds; UInt8 reserved; } HMSTime;
Date and Time Selection Functions
DayDrawDays Function
Purpose
Draw only the days-of-the-month portion of a day selector control object.
Declared In
Day.h
Prototype
void DayDrawDays( const DaySelectorType *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.
Compatibility
If either 5.0 New Feature Set or Palm OS Cobalt Feature Set is present this function is unimplemented.
See Also
DayDrawDaySelector Function
Purpose
Draw a day selector control object on screen.
Declared In
Day.h
Prototype
void DayDrawDaySelector( const DaySelectorType *selectorP )
Parameters
Returns
Comments
The control is drawn only if it is usable.
Compatibility
If either 5.0 New Feature Set or Palm OS Cobalt Feature Set is present this function is unimplemented.
See Also
DayHandleEvent Function
Purpose
Handle event in the specified control. This function handles two types of events, penDownEvent
and ctlEnterEvent
. It is primarily intended for use by the operating system; applications do not typically use this function.
Declared In
Day.h
Prototype
Boolean DayHandleEvent( DaySelectorType *selectorP, const EventType *pEvent )
Parameters
Returns
true
if the event was handled or false
if it was not.
Posts a daySelectEvent
with information on whether to use the date.
Comments
A date is used if the user selects a day in the visible month.
When this function receives a penDownEvent
, it checks if the pen position is within the bounds of the control object. If it is, a dayEnterEvent
is added to the event queue and the function exits.
When this function receives a dayEnterEvent
, it checks that the control id in the event record matches the id of the control specified. If they match, this function will track the pen until it comes up in the bounds in which case daySelectEvent is sent.
If the pen exits the bounds a dayExitEvent
is sent.
Compatibility
If Palm OS Cobalt Feature Set is present this function is unimplemented.
SelectDay Function
Purpose
Display a form showing a date; allow user to select a different date.
Declared In
SelDay.h
Prototype
Boolean SelectDay( const SelectDayType selectDayBy, Int16 *month, Int16 *day, Int16 *year, const Char *title )
Parameters
-
selectDayBy
- The method by which the user should choose the day. Possible values are
selectDayByDay
,selectDayByWeek
, andselectDayByMonth
. SeeSelectDayType
-
↔
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.
Compatibility
Implemented only if 2.0 New Feature Set is present.
See Also
SelectDayV10 Function
Purpose
Display a form showing a date, allow user to select a different date.
Declared In
SelDay.h
Prototype
Boolean SelectDayV10 ( Int16 *month, Int16 *day, Int16 *year, const Char *title )
Parameters
-
↔
month, day, year
- Month, day, and year selected. The initial values passed in these parameters must be valid.
-
→
title
- String title for the dialog.
Returns
Returns true
if the OK button was pressed. In that case, the parameters passed are changed.
Compatibility
This function corresponds to the 1.0 version of SelectDay
.
See Also
SelectOneTime Function
Purpose
Display a form showing the time and allow the user to select a different time.
Declared In
SelTime.h
Prototype
Boolean SelectOneTime ( Int16 *hour, Int16 *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
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.
Compatibility
Implemented only if 3.1 New Feature Set is present.
See Also
SelectTime Function
Purpose
Display a form showing a start and end time. Allow the user to select a different time.
Declared In
SelTime.h
Prototype
Boolean SelectTime ( TimeType *startTimeP, TimeType *EndTimeP, Boolean untimed, const Char*titleP, Int16 startOfDay, Int16 endOfDay, Int16 startOfDisplay )
Parameters
-
↔
startTimeP, EndTimeP
- Pointers to values of type
TimeType
. Pass 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 sets the time to no time thenstartTimeP
andEndTimeP
are both set to the constantnoTime (-1)
. -
→
titleP
- A pointer to a string to display as the title. Doesn't change as the function executes.
-
→
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.
Returns
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
This version of SelectTime
adds the endOfDay
and startOfDisplay
functionality.
Compatibility
Implemented if 3.5 New Feature Set is present.
See Also
SelectTimeV33 Function
Purpose
Display a form showing the time and allow the user to select a different time.
This function is obsolete and should not be used.
Declared In
SelTime.h
Prototype
Boolean SelectTimeV33 ( TimeType *startTimeP, TimeType *EndTimeP, Boolean untimed, const Char *titleP, Int16 startOfDay )
Parameters
-
↔
startTimeP, EndTimeP
- Pointers to values of type
TimeType
. Pass 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 sets the time to no time thenstartTimeP
andEndTimeP
are both set to the constantnoTime (-1)
. -
→
titleP
- A pointer to a string to display as the title. Doesn't change as the function executes.
-
→
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.
Returns
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
NOTE: Obsolete functions are provided ONLY for backward compatibility; for example, so a 1.0 application will work on 3.x OS releases. New code should not call these functions!
See Also
SelectTimeZone Function
Purpose
Display a form that allows the user to select a different time zone.
Declared In
SelTimeZone.h
Prototype
Boolean SelectTimeZone ( Int16 *ioTimeZoneP, LmLocaleType *ioLocaleInTimeZoneP, const Char *titleP, Boolean showTimes, Boolean anyLocale )
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". -
→
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
Returns true
if the user clicked the OK button in the dialog to change the time zone, or false
if the user clicked the Cancel button.
Comments
The time zones displayed in the form 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 ioLocaleTimeZoneP
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.
You might want to use the current time zone stored in the system preferences as the initial value for the ioTimeZoneP
parameter. To obtain this time zone, do the following:
Int16 timeZone = (Int16)PrefGetPreference(prefTimeZone); CountryType timeZoneCountry = (CountryType) PrefGetPreference(prefTimeZoneCountry); LmLocaleType timeZoneLocale; Boolean change; timeZoneLocale.country = timeZoneCountry; timeZoneLocale.language = lmAnyLanguage; change = SelectTimeZone(&timeZone, &timeZoneLocale, NULL, true, false);
Compatibility
Implemented if 4.0 New Feature Set is present.