How to set date and time

The format of the date and time data for an entry depends on the type of entry.

An appointment typically has a start date-and-time and an end date-and-time. These can be set using CAgnAppt::SetStartAndEndDateTime(), and retrieved using CAgnAppt::StartDateTime() and CAgnAppt::EndDateTime().

Appointments do not have to be timed: if they are not timed, they are known as day notes. Instead of having a start and end date-and-time, a day note has a date and a display time, which can be used by the user interface to tell it where to display the day note in a view that contains times of day, such as a day or week view.

You can set the display time using CAgnAppt::SetDisplayTime() and retrieve it using CAgnAppt::DisplayTime().

Day notes are given the default display time when created, which is overridden by SetDisplayTime(). You can find out if an entry has the default display time, using CAgnBasicEntry::HasDefaultDisplayTime(). If SetDisplayTime() has been called, this will return EFalse.

Note that a timed appointment cannot be given a display time. The display time is inherent in the start date/time.

A to-do entry represents a task or an action to be carried out. It has no start or end date or time. It does have a display time, which allows it to be displayed in views that contain times of day, such as day or week views. Also, it may optionally have a start date (the first date on which it is displayed in day or week views) and either a due date (to indicate the date by which the action should be carried out) or a crossed out date (the date the action was carried out). An undated to-do entry does not have a due date, a crossed out date or a start date. To-do details include the ID of the to-do list to which the to-do belongs and a priority.

To set and get the due or crossed out date, use the functions CAgnTodo::SetDueDate(), CAgnTodo::CrossedOutDate(), and CAgnTodo::SetCrossedOutDate().

A to-do also has a display time, to allow it to be displayed in a view that contains times of day, such as a day or week view. This can be set using CAgnTodo::SetDisplayTime() and retrieved using CAgnTodo::DisplayTime().

An event has a start date and optionally an end date, and a display time. These can be set/retrieved using the following CAgnEvent functions: CAgnEvent::SetStartAndEndDate(), CAgnEvent::StartDate(), CAgnEvent::EndDate(), CAgnEvent::DisplayTime(), CAgnEvent::SetDisplayTime().

SetStartAndEndDate() can optionally be called with the start date only: in this case, the end date is set to the same as the start date.

To create an anniversary entry that repeats yearly on a particular date, create a CAgnAnniv object and set its repeat details using CAgnEntry::SetRptDefL(). The repeat details should be set to repeat yearly from a start to an end date, or forever. Useful functions in setting up the repeat details are CAgnRptDef::SetYearlyByDate() and the TAgnYearlyByDateRpt functions SetStartDate(), SetInterval() and SetRepeatForever().

An anniversary can also be given a base year. This is typically used to display the number of years from the base year to the current anniversary — for example, to show someone's age this birthday. The base year is set using CAgnAnniv::SetBaseYear(). If the base year is set to a year after the start date, SetBaseYear() adjusts the start date to be in the base year. The base year can be inquired using CAgnAnniv::BaseYear(), and CAgnAnniv::HasBaseYear() can be used to discover whether or not an anniversary entry has had its base year set. CAgnAnniv::SetHasBaseYear() may be used to set and unset this.

Note that an anniversary does not have to be a repeating entry: the model does not require it to be repeating. An anniversary can be added to the model with just a start date, which can be set using SetStartAndEndDate() (inherited from CAgnEvent). This would typically be called with the start date only (which would make the end date the same as the start date by default), as it is unusual to have an anniversary that spans more than one day. Note that the start and end date set by SetStartAndEndDate() are not the same as the repeat start and end date set in the repeat details. However, if the repeat details are set after calling SetStartAndEndDate(), the start date will be adjusted to make it the same as the start date in the repeat details. If an anniversary entry's repeat details are set, there is no need to call SetStartAndEndDate() on the entry — the start date is set to the start date of the repeat when SetRptDefL() is called.

If an anniversary is made repeating, its repeat interval should be set to one year. Calling SetBaseYear() checks this, and causes a panic if the interval is not one year (in debug builds only).

Anniversaries may optionally be given a non-default display time using SetDisplayTime().