QTaskModel Class Reference
[QtMessagingModule, QtPimModule, QtTelephonyModule, QtUiModule]

Detailed Description

The QTaskModel class provides access to Tasks data.

User tasks are represented in the task model as a table, with each row corresponding to a particular task and each column as on of the fields of the task. Complete QTask objects can be retrieved using the task() function which takes either a row, index, or unique identifier.

The task model is a descendant of QAbstractItemModel, so it is suitable for use with the Qt View classes such as QListView and QTableView, as well as QTaskListView or any custom views.

The task model provides functions for filtering of tasks by category and completion status, and by default will sort by completion status, priority and description. Note that this sort order may change in future versions of Qtopia.

The appointment model provides functions for sorting and some filtering of items. For filters or sorting that is not provided by the task model, it is recommended that QSortFilterProxyModel be used to wrap the task model.

A QTaskModel instance will also reflect changes made in other instances of QTaskModel, both within this application and from other applications. This will result in the modelReset() signal being emitted.

See also QTask, QTaskListView, QSortFilterProxyModel, and Pim Library.

Member Type Documentation

enum QTaskModel::Field

Enumerates the columns when in table mode and columns used for sorting. This is a subset of the data retrievable from a QTask.

Member Function Documentation

QTaskModel::QTaskModel ( QObject * parent = 0 )

Constructs a task model with the given parent.

QTaskModel::~QTaskModel ()   [virtual]

Destroys the task model.

QUniqueId QTaskModel::addRecord ( const QByteArray & bytes, const QPimSource & source, const QString & format = QString() )   [virtual]

Adds the PIM record encoded in bytes to the model under the specified storage source. The format of the record in bytes is given by format. An empty format string will cause the record to be read using the data stream operators for the PIM data type of the model. If the specified source is null the function will add the record to the default storage source.

Returns a valid identifier for the record if the record was successfully added. Otherwise returns a null identifier.

Can only add PIM data that is represented by the model. This means that only task data can be added using a task model. Valid formats are "vCalendar" or an empty string.

Reimplemented from QPimModel.

See also addTask().

QUniqueId QTaskModel::addTask ( const QTask & task, const QPimSource & source = QPimSource() )

Adds the task to the model under the specified storage source. If source is null the function will add the task to the default storage source.

Returns a valid identifier for the task if the task was successfully added. Otherwise returns a null identifier.

Note the current identifier of the specified appointment is ignored.

QVariant QTaskModel::data ( const QModelIndex & index, int role ) const   [virtual]

Returns the data stored under the given role for the item referred to by the index.

The row of the index specifies which task to access and the column of the index is treated as a QTaskModel::Field.

Reimplemented from QAbstractItemModel.

See also setData() and taskField().

QIcon QTaskModel::fieldIcon ( Field field )   [static]

Returns an icon representing the task model field.

Returns a null icon if no icon is available.

See also fieldLabel(), fieldIdentifier(), and identifierField().

QString QTaskModel::fieldIdentifier ( Field field )   [static]

Returns a non-translated string describing the task model field.

See also fieldLabel(), fieldIcon(), and identifierField().

QString QTaskModel::fieldLabel ( Field field )   [static]

Returns a translated string describing the task model field.

See also fieldIcon(), fieldIdentifier(), and identifierField().

bool QTaskModel::filterCompleted () const

Returns true if the model contains only completed tasks.

See also setFilterCompleted().

Field QTaskModel::identifierField ( const QString & identifier )   [static]

Returns the task model field for the non-translated field identifier.

See also fieldLabel(), fieldIcon(), and fieldIdentifier().

QModelIndexList QTaskModel::match ( const QModelIndex & start, int role, const QVariant & value, int hits = 1, Qt::MatchFlags flags = Qt::MatchFlags( Qt::MatchStartsWith | Qt::MatchWrap ) ) const

Returns a list of indexes for the items where the data matches the specified value. The list that is returned may be empty. The search starts from the start index.

Currently unimplemented, this function ignores start, role, value, hits and flags.

QByteArray QTaskModel::record ( const QUniqueId & identifier, const QString & format = QString() ) const   [virtual]

Returns the record in the model with the specified identifier encoded in the format specified by the format string. An empty format string will cause the record to be written using the data stream operators for the PIM data type of the model.

Valid formats are "vCalendar" or an empty string.

Reimplemented from QPimModel.

See also task().

bool QTaskModel::removeList ( const QList<QUniqueId> & identifiers )

Removes the records in the model specified by the list of identifiers.

Returns true if tasks were successfully removed.

bool QTaskModel::removeRecord ( const QUniqueId & identifier )   [virtual]

Removes the record from the model with the specified identifier.

Returns true if the record was successfully removed.

Reimplemented from QPimModel.

See also removeTask().

bool QTaskModel::removeTask ( const QTask & task )

Removes the task from the model with the same identifier as the specified task.

Returns true if the task was successfully removed.

bool QTaskModel::removeTask ( const QUniqueId & identifier )

This is an overloaded member function, provided for convenience.

Removes the task from the model with the specified identifier.

Returns true if the task was successfully removed.

bool QTaskModel::setData ( const QModelIndex & index, const QVariant & value, int role )   [virtual]

Sets the role data for the item at index to value. Returns true if successful.

The task model only accepts data for the EditRole. The column of the specified index specifies the QTaskModel::Field to set and the row of the index specifies which task to modify.

Reimplemented from QAbstractItemModel.

See also data() and setTaskField().

void QTaskModel::setFilterCompleted ( bool completedOnly )

Sets whether the model contains only completed Tasks to completedOnly.

See also filterCompleted().

bool QTaskModel::setTaskField ( QTask & task, QTaskModel::Field field, const QVariant & value )   [static]

Sets the value for the specified field of the given task to value.

Returns true if the task was modified.

See also taskField() and setData().

void QTaskModel::sort ( int column, Qt::SortOrder order = Qt::AscendingOrder )   [virtual]

Sorts the model by column in ascending order

Currently order is ignored but may be implemented at a future date.

Reimplemented from QAbstractItemModel.

QTask QTaskModel::task ( const QModelIndex & index ) const

Returns the task for the row specified by index. The column of index is ignored.

QTask QTaskModel::task ( const QUniqueId & identifier ) const

This is an overloaded member function, provided for convenience.

Returns the task in the model with the given identifier. The task does not have to be in the current filter mode for it to be returned.

QTask QTaskModel::task ( int row ) const

This is an overloaded member function, provided for convenience.

Return the task for the given row.

QVariant QTaskModel::taskField ( const QTask & task, QTaskModel::Field field )   [static]

Returns the value for the specified field of the given task.

Note: Certain fields (Alarm, RepeatRule, RepeatFrequency, RepeatEndDate and RepeatWeekFlags) are not accessible by this function. Use data() instead, or fetch the dependent QAppointment directly.

See also setTaskField() and data().

bool QTaskModel::updateRecord ( const QUniqueId & id, const QByteArray & bytes, const QString & format = QString() )   [virtual]

Updates the corresponding record in the model to equal the record encoded in bytes. The format of the record in bytes is given by the format string. An empty format string will cause the record to be read using the data stream operators for the PIM data type of the model. If id is not null will set the record identifier to id before attempting to update the record.

Returns true if the record was successfully updated.

Valid formats are "vCalendar" or an empty string.

Reimplemented from QPimModel.

See also updateTask().

bool QTaskModel::updateRecurringTasks ()

This function will update any recurring tasks that require updating (for example, to set the new due date). This should be called in response to the QCop message "Tasks::updateRecurringTasks()", or when the application wants to ensure that all recurring tasks are up to date.

The library will generate the QCop message at the appropriate times.

Returns true if updates were successful, false otherwise.

bool QTaskModel::updateTask ( const QTask & task )

Updates the task in the model with the same identifier as the specified task to equal the specified task.

Returns true if the task was successfully updated.