7 Date and Time Selector

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 routines 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, and SelTime.h.

Date and Time Selections Data Structures

SelectDayType

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

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

typedef struct {

    UInt8 hours;
    UInt8 minutes;
    UInt8 seconds;
    UInt8 reserved;
} HMSTime;

Date and Time Selection Functions

DayHandleEvent

Purpose

Handle event in the specified control. This routine handles two types of events, penDownEvent and ctlEnterEvent.

Prototype

Boolean DayHandleEvent (const DaySelectorPtr pSelector, const EventType *pEvent)

Parameters

-> pSelector

Pointer to control object.

-> pEvent

Pointer to an EventType structure.

Result

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 routine 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 routine exits.

When this routine receives a dayEnterEvent, it checks that the control id in the event record matches the id of the control specified. If they match, this routine 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.

SelectDay

Purpose

Display a form showing a date; allow user to select a different date.

Prototype

Boolean SelectDay (const SelectDayType selectDayBy, Int16 *month, Int16 *day, Int16 *year, const Char *title)

Parameters

selectDayByThe method by which the user should choose the day. Possible values are selectDayByDay,

The method by which the user should choose the day. Possible values are selectDayByDay,selectDayByWeek, and selectDayByMonth. See SelectDayType

<-> month, day, year

Month, day, and year selected.

-> title

String title for the dialog.

Result

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

SelectDayV10

Purpose

Display a form showing a date, allow user to select a different date.

Prototype

Boolean SelectDay (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.

Result

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

SelectDay

SelectOneTime

Purpose

Display a form showing the time and allow the user to select a different time.

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.

Result

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

SelectTimeV33

SelectTime

Purpose

Display a form showing a start and end time. Allow the user to select a different time.

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

Result

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

SelectDay, SelectOneTime

SelectTimeV33

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.

Prototype

Boolean SelectTimeV33 (TimeType *startTimeP, TimeType *EndTimeP, Boolean untimed, Char *title, 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 then startTimeP and EndTimeP are both set to the constant noTime (-1).

-> title

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.

Result

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 routines!

---

See Also

SelectDay, SelectOneTime