How to create and use entries

To create a new entry, use:

• CAgnAppt::NewL()

• CAgnEvent::NewL()

• CAgnAnniv::NewL()

• CAgnTodo::NewL()

Alternatively, use the corresponding NewLC() functions.

You can also create a new entry, copying its details from an existing entry, using the entry classes' respective CopyFromL() functions.

Entries can be retrieved using functions provided by the model classes. When entries or instances are retrieved from the model they have to be retrieved into a CAgnEntry, because their type is unknown at this stage.

• Use CAgnEntry::Type(), which is implemented by each of the concrete entry classes, to find the type of an entry or an instance which has been read from the model.

• You then have to cast the entry to its proper type in order to use the functions provided by the concrete class for that type. (Functions provided by CAgnEntry can be used without casting the entry.) The functions for casting entries are CAgnEntry::CastToAppt(), CAgnEntry::CastToTodo(), CAgnEntry::CastToEvent(), and CAgnEntry::CastToAnniv().

Entries contain text which is typically displayed by the user interface. The Agenda model stores this text as rich text, which means it can contain embedded pictures and other objects such as Word documents. An entry's rich text can be accessed using CAgnEntry::RichTextL(), which returns a pointer to a CRichText object. CRichText provides an API for retrieving and updating the rich text.

To make an entry repeating:

• create a CAgnRptDef and configure it for the required repeats and any exceptions to the repeats (for example, a particular week in which a weekly-repeating entry should not occur)

• call CAgnEntry::SetRptDefL(), passing the CAgnRptDef as the argument. This sets the repeat details of the entry.

• In the instance model, instances have their date and time fields set for one of the repeats defined in the repeat details. All the repeat details are also present in each instance.

• If you edit one individual instance of a repeating series, a new non-repeating entry is created with its date(s) set to the date(s) of the instance. This new entry has no link to the repeating series of instances to which it once belonged, and in the repeating entry an exception is created corresponding to the date of the edited entry. Therefore, for example, if you cross out one instance of a repeating series, and subsequently uncross it out, you do not get back to where you started.

• If you edit a repeating entry via the entry model (e.g., set its crossed-out status), this will cause all its instances to be modified (e.g. they will all be crossed out).

• The classes TAgnDailyRpt, TAgnWeeklyRpt, TAgnMonthlyRpt, TAgnMonthlyByDaysRpt, TAgnMonthlyByDatesRpt, TAgnYearlyByDateRpt and TAgnYearlyByDayRpt provide utilities for setting up repeat details.

To check if an entry has any categories, use CAgnEntry::HasCategory(). Retrieve the entry's category using CAgnEntry::FetchCategory().