Prev: Personal Data
Module agenda: Agenda Database
This module allows to read and manipulate the agenda (calendar and to-do list) stored on the phone. There are different types of agenda entries, each type identified by its flag:
- Appointment (agenda.appt flag): an entry starting at a date and time and ending on the same day, e.g. a team meeting.
- Event (agenda.event flag): an entry starting at a date and ending on a date, e.g. holidays.
- Anniversary (agenda.anniv flag): an entry occuring at a date, with an optional base year (e.g. the year of birth).
- To-do list item (agenda.todo flag): an entry with a due date and a priority. When done, it also gets a done ("crossed out") date.
The standard calendar application on the phone often does not support all entry types and attributes.
In the phone's database, an agenda entry is identified by its id, an integer number.
Agenda Fields
In m, an agenda entry is represented as an array whose elements are the fields of the entry. Fields are identified by their (array) keys. m recognizes the following keys, with the corresponding data type:
| Key | Meaning | Type | Used in |
| | | appt | event | anniv | todo |
| alarm | Alarm date/time | Seconds | • | • | • | • |
| base | Base year | Number | | | • | |
| desc | Description | String | • | • | • | • |
| done | Done date | Seconds | | | | • |
| end | End date/time | Seconds | • | • | | • |
| flags | Entry flags (see below) | Number | • | • | • | • |
| loc | Location | String | • | • | • | • |
| prio | Priority | Number | | | | • |
| rep | Repeat details (see below) | Array | • | • | • | • |
| start | Start date/time | Seconds | • | • | • | • |
| sync | Synchronisation | Number | • | • | • | • |
| text | Entry text | String | • | • | • | • |
| |
Key names are not case sensitive.
All dates and times of an entry are represented as seconds since the start of year zero in local time (see also module time). Valid dates are January 1st, 1980 or 1900 to December 31st, 2100. The functions of this module throw ExcValueOutOfRange if a date outside this range is used. The only exception is the base year (base) of an anniversary entry, which is simply an integer indicating any year.
The order of fields in the array describing an entry is arbitrary. Arrays returned by functions in this module always start with the two fields text and flags.
Agenda Entry Flags
The
flags field is a bitwise combination of the following values:
• const anniv = 4
Entry is an anniversary.
• const appt = 1
Entry is an appointment.
• const done = 32
To-do entry is done.
• const event = 2
Entry is an event.
• const rep = 16
Entry is repeated.
• const remind = 64
Entry is a reminder.
• const todo = 8
Entry is a to-do list item.
Flags can be used to select entries in agenda.find, and they must be used to indicate the type of the new entry in agenda.add.
For use in agenda.find, there is also the value
• const all = 127
All flags combined.
Synchronization mode
The
sync field defines how an entry is handled during synchronisation:
• const public = 0
Synchronise and make entry visible if the calendar is online.
• const private = 1
Hide entry from viewers if the calendar is available online.
• const none = 2
Entry will not be copied to computer.
Repetitive Entries
All dated entries can be repetitive: a repetitive entry is automatically repeated according to its repeat details. For instance, an anniversary is typically repeated on the same date every year. Repeating an entry does not duplicate the entry; deleting or updating a repetitive entry also deletes or updates all its repetitions.
In m, the repeat details of an entry are represented as an array stored in the entry's rep field. m recognizes the following keys of this array, with the corresponding data type:
| Key | Meaning | Type |
| end | Repeat end date | Seconds |
| interval | Repeat interval (days, months, years) | Number |
| type | Repeat type (see below) | Number |
| when | Repeat selection (see below) | Array of Number |
| |
If end=null (the default), the entry is repeated forever. The default interval is 1. type must be one of the following six values:
• const daily = Repeat daily.
Repeat the entry every interval days.
// plan for an 30 minute exercise at 8am
// every three days, starting today
today=86400 * math.trunc(time.get() / 86400);
e=["text":"exercise",
"start":today+8*3600,
"end":today+8*3600+1800,
"flags":agenda.appt,
"rep":["type":agenda.daily, "interval":3]]
|
• const weekly = Repeat weekly.
Repeat the entry every interval weeks, on the week days indicated by when. Week days start with zero as Monday; see also time.dayofweek.
// repeat every week on Tuesday and Friday
e["rep"]=["type":agenda.weekly, "when":[1,4]]
|
• const monthlydate = Repeat monthly, at given dates.
Repeat the entry every interval months, on the days indicated by when.
// repeat every two months on the 10th and 25th
e["rep"]=["type":agenda.monthlydate,
"interval":2, "when":[10,25]]
|
• const monthlyday = Repeat monthly, at given days of weeks.
Repeat the entry every interval months, on the week days in the weeks indicated by when: when[2*i] indicates the week of the month (1 is the first, 4 is the fourth, 5 the last), and when[2*i+1] indicates the day of week (0 is Monday).
// repeat every month on the Tuesday (1) of the 2nd
// week (2), and on the Tuesday (1) of the last week (5)
e["rep"]=["type":agenda.monthlyday, "when":[2,1,5,1]]
|
• const yearlydate = Repeat yearly, at a given date.
Repeat the entry every interval years, on the date implied by the entry's start date. This repeat type is typically used for anniversaries.
// repeat every year
e["rep"]=["type":agenda.yearlydate]
|
• const yearlyday = Repeat yearly, at a given day of a week of a month.
Repeat the entry every interval years, on the day indicated by when: when[0] indicates the month, when[1] the week of the month (1 ist the first, 4 is the fourth, 5 is the last), and when[2] the day of week (0 is Monday).
// repeat yearly, on Sunday (6) of the 1st week in April
e["rep"]=["type":agenda.yearlyday,"when":[4,1,6]]
|
agenda.add
• function add(entry) → Number
Permissions: WriteApp
Add an entry to the agenda database, and return its id. The entry must be an array with keys from the above tables. The entry type is derived from the flags array element; if there is no flags element, an agenda.appt entry is added.
// Add a 30 minute meeting starting in two hours,
// in the CEO's office
start=time.get()+2*3600;
e=["text":"Group meeting",
"flags":agenda.appt,
"start":start,
"end":start+1800,
"loc":"CEO's office"];
agenda.add(e)
→ 402653204
// Add an anniversary, repeating every year
e=["text": "Shakespeare's Birthday",
"flags": agenda.anniv,
"start": time.num("2005-04-23"),
"base": 1564,
"rep": ["type":agenda.yearlydate]];
agenda.add(e)
→ 117440532
|
agenda.delete
• function delete(id) → null
Permissions: WriteApp
Delete the contact with the given id.
Throws ErrNotFound if there is no such contact.
// delete the anniversary added in the add example
agenda.delete(117440532)
|
agenda.find
• function find(start=null, end=null, flags=agenda.appt | agenda.event | agenda.anniv | agenda.rep) → Array
Permissions: ReadApp
Searches the agenda for entries overlapping with the period between start and end, and with an entry type indicated by flags. The default flags exclude to-do list entries.
Repeated entries are only reported if the first repetition falls within the period. Use agenda.findall to find all events within a period, including repetitions.
start and end must be given in seconds since year zero; start=null indicates the earliest possible start date, end=null the latest possible end date.
// get the number of entries in the agenda
print len(agenda.find(null, null, agenda.all))
→ 53
// print the text and start of today's entries
today=86400*math.trunc(time.get()/86400);
for id in agenda.find(today,today+86400) do
e=agenda.get(id);
print e["text"], time.str(e["start"], "hh:mm")
end
→ ...
Group meeting 18:40
...
// delete all entries up to now, excluding repetitives
for id in agenda.find(null, time.get(),
agenda.all & ~agenda.rep)
agenda.delete(id)
end
|
agenda.findall
• function findall(start, end, flags=agenda.appt | agenda.event | agenda.anniv | agenda.rep) → Array
Permissions: ReadApp
This is similar to agenda.find, except that all instances of repeated entries are reported if they fall within the period. The function returns an array with an element for each instance found. Each element is again an array with the following elements:
| Key | Meaning |
| id | The id of the entry, as returned by agenda.find. |
| at | The start time of the instance. For a non-repeated entry, this is the same as the entry's start time. For a repeated entry, this is the start time of the instance falling within the selected period. |
| |
// print the text and start of today's instances
today=86400*math.trunc(time.get()/86400);
for idtime in agenda.findall(today,today+86400) do
e=agenda.get(idtime["id"]);
print e["text"], time.str(idtime["at"], "hh:mm")
end
→ ...
Group meeting 18:40
Weekly Yoga session 20:30
...
|
agenda.get
• function get(id) → Array
Permissions: ReadApp
Get the fields of the agenda entry with id id.
Throws ErrNotFound if there is no entry with this id.
// get the entry added before
e=agenda.get(402653204);
print e
→ [Group meeting,1,63284611200,63284613000,
CEO's office]
print time.str(e["start"])
→ 2005-05-17 18:40:00
|
agenda.set
• function set(id, entry) → null
Permissions: WriteApp
Updates the entry with id id, updating the fields in array entry. entry must be an array with keys from the above tables. Fields which are null in the array are cleared in the entry.
// Change the location of the group meeting
agenda.set(402653204, ["loc":"My office"])
// Set all done entries in the to-do list to "not done"
ids=agenda.find(null, null, agenda.todo | agenda.done);
for id in ids do
agenda.set(id, ["done":null])
end
|
Next: Module contacts: Contacts Database© 2004-2011 airbit AG, CH-8008 Zürich
Document AB-M-LIB-888
