Calendar API QML

DRAFT

This document just serves as draft for developing a QML Calendar API.

CalendarData component

CalendarData {
  startDate: QDateTime 
  endDate: QDateTime 
  types: Calendar.Holiday | Calendar.Event | Calendar.Todo | etc..
  errorMessage: QString
  loading: bool
  model: QAbstractItemModel
}

startDate

If start date is set the model will be populated with events that occur/reoccur from the date on.

endDate

If end date is set the model will be populated with events that occur/reoccur till the date on.

types

Types defines the kind of entries that will be populated by the model.

Calendar.Holiday

Items of type Calendar.Holiday provide the following roles: ... long list ...

Calendar.Event

Items of type Calendar.Event provide the following roles: ... long list ..

Calendar.Todo

Items of type Calendar.Todo provide the following roles: ... long list ..

Calendar.Journal

Items of type Calendar.Journal provide the following roles: ... long list ..

errorMessage

If there is an error in the PIM backend, the errorMessage property will contain a user visible description.

loading

While the model is fetching data, this value will be true. False otherwise.

model

Contains a QAbstractItemModel that can used directly in a QtQuick ListView.

Calendar component

The Calendar component is specialized CalendarData component that provides you with some additional members to indicate how many cells you need to draw. The endDate property has been left out because you only need to provide a start date. It will calculate the rest from there on. The proposed API is as follows:

Calendar {
  days: int 
  weeks: int 
  startDay: int 
  daysModel: QAbstractItemModel
  weeksModel: QList<int>
  startDate: QDateTime 
  types: Calendar.Holiday | Calendar.Event | Calendar.Todo | etc..
  errorMessage: QString
  loading: bool

  void next()
  void previous()
}

Note: this component is not as general as it could be. The ideal model would "probably" have a type enum for the type of days it should fetch. So for example an enum to indicate if the model should contain enough data for a:

• day overview
• week overview
• month overview
• list overview (would show all upcoming events)

days

The number of days for one row (week).

weeks

The number of rows (weeks) for a grid.

startDay

This sets how a row display it's days. The values can be:

1 = Monday
2 = Tuesday
3 = Wednesday
4 = Thursday
5 = Friday
6 = Saturday
7 = Sunday

daysModel

When you set the days and weeks properties, this model will be filled with day specific data. For every day it has the following properties available in the model - at the very least.

weeksModel

weeksModel is representing the week numbers as they come from QDate. This would usually be the number infront of the actual week row.

isPreviousMonth: bool

This property will be true when you see some days from the previous month in your model.

isCurrentMonth: bool

This property will be true for the current month.

isNextMonth: bool

This property will be true for the for the days that you might see in the next month.

containsHolidayItems: bool

This property will be true if the current day contains holiday items. False otherwise.

containsEventItems: bool

This property will be true if the current day contains event items. False otherwise.

containsTodoItems: bool

This property will be true if the current day contains todo items. False otherwise.

containsJournalItems: bool

This property will be true if the current day contains journal items. False otherwise.

startDate

If start date is set the model will be populated with events that occur/reoccur from the date on.

types

In this case the types property will narrow down the checks for the contains*Items properties. So if you only set Calendar.Holiday then the containsHolidayItems property will be populated for every day. The other properties will be populated if they are set as types or if nothing is set (which internally sets all).

errorMessage

If there is an error in the PIM backend, the errorMessage property will contain a user visible description.

loading

While the model is fetching data, this value will be true. False otherwise.

void next()

next will increase the internal start date offset based on the number of days and weeks available in this model and return a newly filled QAbstractItemModel (under the model property) with the new data.

void previous()

next will decrease the internal start date offset based on the number of days and weeks available in this model and return a newly filled QAbstractItemModel (under the model property) with the new data.