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 
  startDate: QDateTime 
  types: Calendar.Holiday | Calendar.Event | Calendar.Todo | etc..
  errorMessage: QString
  loading: bool
  model: QAbstractItemModel

  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

This property holds the number of days in one row.

weeks

This property holds the number of weeks in one calendar grid.

startDate

If start date is set the model will be populated with events that occur/reoccur from 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. The property: "hasEntries: bool" tells you if there are any items available on that day (holiday, event, todo item or perhaps even a journal).

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.