The entry model, instance model and indexed model

For an application to access the data in an Agenda document, it must open the Agenda model at run-time. The Agenda model routes calls from the UI to the appropriate server functions. There are three different types of model it can open:

• The entry model, provided by CAgnEntryModel, is the interface to the entries and to-do lists in the file. Repeating entries are represented by a single entry object. The entry model should be used if the application has no user interface, such as a format conversion application.

• The indexed model, provided by CAgnIndexedModel, extends the entry model: it adds indexes of the data, which allows the information to be filtered before entries are read. The indexed model can be used for greater efficiency than the instance model by applications which have no user interface and which need to access only a subset of the data in the file.

• The instance model, provided by CAgnModel, extends the indexed model: it provides a separate object for each instance of a repeating entry. This makes it most suitable for use by applications that need to show repeating entries in a user interface.

If an application opens an entry model (CAgnEntryModel), it can access the Agenda data as entries. There are four types of entry: appointments, to-do entries, events, and anniversaries. These are implemented by the classes CAgnAppt, CAgnTodo, CAgnEvent, and CAgnAnniv, respectively.

If an application opens an instance model (CAgnModel), it can access the Agenda data as instances. Instances are required by applications with a user interface, because of repeating entries. In the entry model, a repeating entry is represented as a single entry with its repeat details set, but for a user interface this representation is insufficient: a repeating entry needs to be presented to the user as if it consists of individual entries, one on each date on which a repeat occurs. In the instance model a repeating entry is represented by a number of instances, one for each date and time on which a repeat occurs.

Instances are implemented by the same classes as entries, namely CAgnAppt, CAgnTodo, CAgnEvent and CAgnAnniv, but, when they are accessed using the instance model, a separate object (an instance) is created for each repeat of the entry, with its date and time information set for one of the individual repeats. A non-repeating entry or a to-do entry is represented by one single instance in the instance model.

(Note: entries, as well as instances, have date and time information, but it makes no sense to access this data for repeating entries, as it will contain the date and time of only one of the repeats. For this reason, date and time information should in general be accessed only via instances.)

An entry is identified by its entry ID. Because a repeating entry has multiple instances, all of which have the same entry ID, an instance is identified by the combination of entry ID and instance date, (each instance date for a repeating entry is unique).

The start date of an entry may be queried by calls to functions such as CAgnEvent::StartDate(). The start date of a particular instance of the entry may be queried by calls to such functions as CAgnEvent::InstanceStartDate().

For example, an appointment could be created with a start date/time of 6pm 1st January and an end date/time of 9pm 1st January. It is set to repeat every 2 days.

The following table shows the different date/time values for the instance of the appointment which occurs on the 3rd January.

Function call Return value appt->StartDateTime() A TTime set to 6pm 1st January, i.e. the entry's start date/time. appt->EndDateTime() A TTime set to set to 9pm 1st January, i.e. the entry's end date/time appt->InstanceStartDate() A TTime set to set to 3rd January, i.e. the instance's start date appt->InstanceEndDate() A TTime set to set to 3rd January, i.e. the instance's end date appt->DisplayTime() A TTimeIntervalMinutes set to 1080 minutes since midnight (i.e. 6pm)

An indexed model (CAgnIndexedModel) is opened as an intermediate stage in opening the instance model, but can also be used in its own right. When an indexed model is opened, indexes of the data in an Agenda document are built. The indexes contain a subset of the information for each entry in the document, which allows the information to be filtered before whole entries are read, for greater efficiency.