Agenda Entry and Instance Overview

The Agenda Entry and Instance API is the interface to individual entries and instances in an agenda file. It is also the interface to the repeat details, synchronisation and alarm information, because this information is associated with an entry.

The Agenda Entry and Instance API is closely related to the following APIs: —

Agenda File. Entries and instances exist in agenda files. They are added to and deleted from the file and are accessed in the file using the Agenda File API.

To-do List. The to-do entry type (represents an action which needs to be carried out) is documented in the To-do Lists API.

Agenda Model Utilities. The dates and times associated with agenda entries (e.g. the start date/time of an appointment) are represented using agenda model dates and times rather than TTime values, as used elsewhere. These are documented in the Agenda Model Utilities API.

Versit. vEvents and vTodos can be imported into an agenda file as entries. Conversely, agenda entries can be exported from the agenda file as vEvents and vTodos.

Text and Text Attributes. All entries own a rich text object. The use of rich text means that entry text can contain formatting which applies to individual characters and paragraphs, embedded pictures and other objects such as Word documents, voice notes etc.

The API has the following key concepts:

Entry type. All entries have a type. The following entry types are supported:

• Events (see class CAgnEvent). These have a start date and a display time and optionally an end date. Events are all-day entries with no start or end times.

• Anniversaries (see class CAgnAnniv). These are events (CAgnAnniv extends CAgnEvent) which can only occur once a year, for example a birthday.

• Appointments (see class CAgnAppt). These are entries with a start date and time and an end date and time. The display time is inherent in the start date/time. Day notes are appointments whose end date/time is the same as their start date/time.

• To-dos (see class CAgnTodo). To-do entries have no start or end date or time. They have 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). For display purposes, they have a display time and an optional start date (the first date on which it can be displayed). The CAgnTodo class is documented in the To-do List API.

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

IDs. Entries and instances are uniquely identified in an agenda file by IDs. Different types of ID are used in different circumstances:

• Entry ID. This is assigned to an entry when it is added to the file, but can change if the entry is updated. It therefore cannot be used to identify the entry for synchronisation.

• Instance 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).

• Unique ID. Used to identify both agenda entries and to-do lists. This is assigned to the entry or to-do list when it is added to the file and is preserved during updates. Because of this, it can be used to identify the entry or to-do list during synchronisation.

Agenda File Overview

To-do List Overview

Agenda Model Utilities Overview

Versit Overview

Text and Text Attributes Overview