To-do List Overview

The To-do List API allows lists of to-do entries to be managed. A to-do entry represents an action which needs to be carried out. All to-do entries belong to a to-do list. To-do lists have a name, a unique ID and display settings. The display settings include the sort order for the contained to-do entries and whether and how to-do entries should be displayed in views. To-do lists are grouped into to-do list lists (ordered lists of to-do list IDs).

The To-do List API is closely related to the following APIs:

Agenda Entry and Instance. This is the interface to the other agenda entry types.

Agenda File. To-do entries, instances and to-do lists can be added to agenda files. They are added to and deleted from the file and are accessed in the file using the Agenda File API.

Agenda Model Utilities. The dates and times used in the To-do List API (e.g. the due and crossed out dates and the display time) are agenda model dates and times rather than TTime values, as used elsewhere. These are documented in the Agenda Model Utilities API.

Like other agenda entry types, to-do entries store alarm, repeat and synchronisation information and use a rich text object to hold the text associated with the entry. They are uniquely identified by an ID: either an entry ID, an instance ID or a unique ID. For a discussion of the differences between the types of ID, see the Agenda Entry and Instance API overview.

Unlike other entry types, to-do entries have a priority and a to-do list ID, (identifies the to-do list to which they belong). They have no start or end date or time; instead 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).

To-do lists are uniquely identified within an agenda file by a to-do list ID and also by a unique ID. Both are assigned when the to-do list is added to the file. The to-do list ID is used to identify the to-do list within the file. The unique ID is used to identify the to-do list during synchronisation.

Agenda Entry and Instance Overview

Agenda File Overview

Agenda Model Utilities Overview