Home · All Classes · Annotated · Functions

Calendar
Functional Description

The Calendar application allows a user to plan their schedule. This includes the scheduling of timed events such as meetings, day events such as birthdays, and multi-day events such as workshops. The application also provides the facility to set alarms for events and to specify a pattern of repetition for events.

Data

An event consists of the following:

• A single line text description.
• A single line text location.
• A multi-line text note.
• A start date and time.
• An end date and time.
• A timezone for start and end times. This is only available where the event is associated with a timezone.
• A pattern of repetition.
• An alarm, including if it is audible and how long before the event it should be activated.
• One or more categories. If the event is not assigned any category it is categorized as unfiled.

Patterns of repetition

The user is able to set an event to: repeat daily, weekly, monthly, yearly or other. These are standard patterns of repetition and the user is able to create a more complex pattern using the advanced options.

Daily

These events happen once each day. In the advanced options the user is able to specify the number of days between each occurrence of the event.

Weekly

These events happen once each week. In the advanced options the user is able to specify how many weeks apart each repeating event should be, as well as specifying that an event occurs on multiple days of a week. The date of the starting day for an event is always the first day the event will occur in a week. Therefore an event occurring every four weeks on Wednesday, Friday, and Monday occurs on the Wednesday, then the Friday of that week and the immediately following Monday, and then does not re-occur until the forth Wednesday following that.

This is not guaranteed to be maintained when syncing to non-Qtopia devices or software.

Monthly

These events happen once each month on the same day of month as the start event. In the advanced options the user is able to specify how many months apart each repeating event will occur.

It is also possible to specify that the event:

• Occurs on a specific day of the month. For example, every 2 months on the 18th of the month.
• Occurs so many weeks from the start of the month. For example, every 2 months on the 2nd Sunday of the month.
• Occurs so many weeks from the end of the month. For example, every 2 months on the last Thursday of the month.

If a repeated event falls on a day not included in a particular month, the event is skipped for that month.

Yearly

This event happens once each year. In the advanced options the user is able to specify how many years apart each repeating event will occur.

Application views

It is possible to view the events in the following ways:

• The events for a single day.
• The events for a single month.
• A detailed view of a single event.
• An event opened for editing.

Day view

This shows the events that occur for a particular date. Repeating events are shown in pale blue and non-repeating events are shown in pale red. All day events are shown at the top of the view. The view also adjusts the height of hours through the day to show as much detail of the events for that day as possible.

The user is able to navigate to other days. The 1 and 3 keys are used to change back and forth by week, the 4 and 6 keys change by month, and the 7 and 9 keys by year. The 5 key can then be used to navigate to the current day.

The user is able to edit the general settings such as the default alarm preset and the default day start time.

The user is able to change to the month view, a detailed view of the current event or add a new event.

Month view

This shows the events that occur for a particular month. Repeating events are shown in blue, non-repeating events in red.

Each event is represented as a bar giving an approximate indication of when during the day the event occurs. For multiple events on a single day the bars for those events are merged. All day events are shown by shading the day pale red for non-repeating events, pale blue for repeating events or a combination of the two colors if both occur on a particular day.

The user is able to navigate to other days. The 1 and 3 keys are used to change back and forth by week, the 4 and 6 keys change by month, and the 7 and 9 keys by year. The 5 key can then be used to navigate to the current day.

The user is able to edit the general settings such as the default alarm preset and the default day start time.

The user is also able to show the details for a particular day or add a new event.

Detailed view

The detailed view of an event displays the data for a single event. This is shown as rich text. All the information for the event is shown formatted for optimum readability.

From the detailed list view the user is able to:

• Edit the current event, using the Edit view of the event.
• Delete the current event.
• Beam the current event via IR.

Edit view

The edit view of an event allows the user to specify the data for a new event or modify that of an existing event.

Non-applicable values are disabled. For example, the start time entry are disabled if the event is marked as an all day event.

When the editing has been completed the user is able to either accept or cancel the changes they have made.

Features

Add event

It is possible to add events to the Calendar.

Delete event

It is possible to delete events. The user is prompted to verify the deletion of an event. If an occurrence of a repeating event is deleted then the user is asked if they mean to delete just that occurrence, all of the following events for that sequence, or the entire sequence.

Edit event

It is possible to modify events. If an occurrence of a repeating event is modified, the user is prompted to indicate if they mean to modify just that occurrence, all of the following events for that sequence, or the entire sequence.

Repeat event

It is possible to set an event to repeat over a specified period of time.

All day events

It is possible to specify events as taking all day. These events are not affected by timezone changes.

Navigation

Navigation between dates and events is easy and clear and the date is visible at all times.

Alarms

Alarmed events sound or display an alarm at the specified time. The Calendar application does not need to be running in order for the alarm to sound.

Configure day view

It is possible to configure the day view to display events starting from a particular time.

Beaming

It is possible to beam events to or from another device using IR.

QDL support

It is possible to access occurrences of events from other applications using the QDL service interface. When activated the Calender application runs and displays the occurrence of the event.

QDL links are embedded into the notes of an event. When in the Detailed View, clicking on a QDL link activates the link's application.

Files

The Calendar application has two data files.

• $HOME/Applications/datebook/datebook.xml - main list of tasks data.
• $HOME/.caljournal - journal of changes to list of tasks since application started.

Both files are in an xml-like format. datebook.xml contains the main list of events, and is the file sent to Qtopia Desktop on syncing. .caljournal contains a list of adds, edits and deletes made to the list of events since the Calendar application started.

Config

The settings for Calendar are stored in $HOME/Settings/DateBook.conf .

• [Main]
• startviewtime - preferred start hour for the day in Day View.
• alarmpreset - true if an alarm is set by default when creating a new event.
• presettime - if alarmpreset is true, the number of minutes the alarm preset is by default when creating a new event.

Services

• IR Receive text/x-vCalendar-Events
• Calendar - allows editing of events via PIM Library interface.
• TimeMonitor - accepts notifications of time modification (timezone, time setting, time format)
• QDL