Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

17    Date and Time Selection Reference

User Interface

Exploring Palm OS®

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 ^TOP^

DaySelectorType Struct ^TOP^

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

None.

HMSTime Struct ^TOP^

Purpose

Represents a time of day.

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 ^TOP^

Miscellaneous Constants ^TOP^

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 ^TOP^

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

SelectDay()

SelectTimeZoneDisplayType Typedef ^TOP^

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 ^TOP^

daySelectEvent ^TOP^

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 ^TOP^

DayDrawDays Function ^TOP^

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

selectorP
Pointer to the day selector gadget to draw.

Returns

Nothing.

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 ^TOP^

Purpose

Draws a day selector gadget on screen.

Declared In

Day.h

Prototype

void DayDrawDaySelector (
   const DaySelectorPtr selectorP
)

Parameters

selectorP
Pointer to the day selector gadget to draw.

Returns

Nothing.

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

DayDrawDays(), SelectDay()

DayHandleEvent Function ^TOP^

Purpose

Handles an event in the specified day selector gadget.

Declared In

Day.h

Prototype

Boolean DayHandleEvent (
   const DaySelectorPtr selectorP,
   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 ^TOP^

Purpose

Displays a dialog showing a date; allows user to select a different date.

Declared In

SelDay.h

Prototype

Boolean SelectDay (
   const SelectDayType selectDayBy,
   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 ^TOP^

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 ^TOP^

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 Boolean untimed,
   const char *titleP,
   int16_t startOfDay,
   int16_t endOfDay,
   int16_t startOfDisplay
)

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 then startTimeP and EndTimeP are both set to the constant noTime.
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

SelectDay()

SelectTimeZone Function ^TOP^

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,
   SelectTimeZoneDisplayType displayOption
)

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 ^TOP^

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,
   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 the anyLocale parameter to true 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. If false, the dialog doesn't show the current time. Using false provides a larger area for the list of time zones.
anyLocale
If true, ignore ioLocaleInTimeZoneP 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.