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

Detailed Description

The QContactModel class provides access to the Contacts data.

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

The contact 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 QContactView and any custom views.

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

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

See also QContact, QContactListView, QSortFilterProxyModel, and Pim Library.

Member Type Documentation

enum QContactModel::Field

Enumerates the columns when in table mode and columns used for sorting. Is a subset of data retrievable from a QContact.

See also localeNameTitles() and localeSuffixes().

enum QContactModel::FilterFlags

These flags describe what kind of contact information to filter contacts on.

See also setFilter().

enum QContactModel::QContactModelRole

Extends Qt::ItemDataRole

typedef QContactModel::SortField

The QContactModel::SortField structure provides sorting instructions.

This structure holds a QContactModel field to sort by, and a sorting direction. Typically an ordered list of these structures is used to allows arbitrary sorting to be performed on a QContactModel.

See also QContactModel.

Member Function Documentation

QContactModel::QContactModel ( QObject * parent = 0 )

Constructs contact model with the given parent.

QContactModel::~QContactModel ()   [virtual]

Destroys the contact model.

QUniqueId QContactModel::addContact ( const QContact & contact, const QPimSource & source = QPimSource() )

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

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

Note the current identifier of the specified appointment is ignored.

See also phoneSource(), simSource(), and mirrorToSource().

QUniqueId QContactModel::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 contact data can be added using a contact model. Valid formats are "vCard" or an empty string.

Reimplemented from QPimModel.

void QContactModel::clearFilter ()

Clears contact name and type filtering for the model. Does not affect category or presence filtering.

void QContactModel::clearPersonalDetails ()

Clears the personal details of the device owner. Does not remove and contacts from the contact model.

/sa setPersonalDetails()

void QContactModel::clearPresenceFilter ()

Clears any presence filtering done by the model.

See also setPresenceFilter().

QContact QContactModel::contact ( const QModelIndex & index ) const

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

QContact QContactModel::contact ( int row ) const

This is an overloaded member function, provided for convenience.

Return the contact for the given row.

QContact QContactModel::contact ( const QUniqueId & identifier ) const

This is an overloaded member function, provided for convenience.

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

QVariant QContactModel::contactField ( const QContact & contact, QContactModel::Field field )   [static]

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

See also setContactField().

QVariant QContactModel::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 contact to access and the column of the index is treated as a QContactModel::Field.

Reimplemented from QAbstractItemModel.

See also setData() and contactField().

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

Returns a icon representing the contact model field.

Returns a null icon if no icon is available.

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

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

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

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

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

Returns a translated string describing the contact model field.

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

int QContactModel::filterFlags () const

Returns the filter flags being used by the model.

See also setFilter().

QString QContactModel::filterText () const

Returns the filter text being used by the model.

See also setFilter().

int QContactModel::firstSimIndex ( const QPimSource & source = QPimSource() ) const

Returns the index of the first entry for a SIM cnotact data source.

bool QContactModel::hasPersonalDetails () const

Returns true if a contact in the contact model is specified as the personal details of the device owner.

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

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

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

bool QContactModel::isPersonalDetails ( const QModelIndex & row ) const

Returns true if the contact for the specified row represents the personal details of the device owner.

bool QContactModel::isPersonalDetails ( int row ) const

This is an overloaded member function, provided for convenience.

Returns true if the contact at the given row represents the personal details of the device owner.

bool QContactModel::isPersonalDetails ( const QUniqueId & identifier ) const

This is an overloaded member function, provided for convenience.

Returns true if the contact with specified identifier represents the personal details of the device owner.

bool QContactModel::isSimCardContact ( const QModelIndex & index ) const

Returns true if the contact at the given index is stored on the SIM card.

bool QContactModel::isSimCardContact ( const QUniqueId & identifier ) const

This is an overloaded member function, provided for convenience.

Returns true if the contact with the given identifier is on the SIM card.

QList<Field> QContactModel::labelFields ()   [static]

Returns the contact model fields that represent the label for a contact.

int QContactModel::lastSimIndex ( const QPimSource & source = QPimSource() ) const

Returns the index of the last entry for a SIM contact data source.

bool QContactModel::loadingSim ( const QPimSource & source = QPimSource() ) const

Returns true if the entries for the given SIM contact source are still being loaded into SQL storage.

See also simLoaded().

QStringList QContactModel::localeNameTitles ()   [static]

Returns known name titles for the current language settings. These are used to assist in parsing and constructing contact name information. Contacts are not restricted to these name titles.

QStringList QContactModel::localeSuffixes ()   [static]

Returns known suffixes for the current language settings. These are used to assist in parsing and constructing contact name information. Contacts are not restricted to these suffixes.

QModelIndexList QContactModel::match ( Field field, const QVariant & value, Qt::MatchFlags flags = Qt::MatchFlags( Qt::MatchStartsWith ), int start = 0, int hits = 1 )

Returns a list of indexes for the items where the data in the field value matches the specified value. The list that is returned may be empty.

The search starts from the start row and continues until the number of matching data items equals hits or the search reaches the last row.

The flags argument can contain any of the following flags:

- Qt::MatchWildcard - Qt::MatchFixedString (or equivalently Qt::MatchExactly) - Qt::MatchContains - Qt::MatchStartsWith - Qt::MatchCaseSensitive

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

This is an overloaded member function, provided for convenience.

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 and continues until the number of matching data items equals hits or the search reaches the last row

The arguments role and flags are currently ignored.

QContact QContactModel::matchChatAddress ( const QString & text, const QString & provider = QString() )

Returns the best match for the chat address text. If the provider is not empty, restricts matches to contacts with chat addresses from that QCollectivePresence provider. If no contact in the model has a chat address matching the given text returns a null contact.

See also QCollectivePresence.

QContact QContactModel::matchEmailAddress ( const QString & text )

Returns the best match for the email address text. If no contact in the model has an email address matching the given text returns a null contact.

QContact QContactModel::matchPhoneNumber ( const QString & text )

Returns the best match for the phone number text. If no contact in the model has a phone number matching the given text returns a null contact.

bool QContactModel::mirrorAll ( const QPimSource & source, const QPimSource & destination )

Exports the contacts stored in source storage source and imports them into the destination storage source. The contacts are modified by the source and destination storage contexts to account for storage restrictions.

Returns true upon success.

See also mirrorToSource().

bool QContactModel::mirrorToSource ( const QPimSource & destination, const QUniqueId & identifier )

Exports the contact in the model with the specified identifier and imports it into the destination storage source. The contact is modified by the source and destination storage contexts to account for storage restrictions. For instance a contact may be split into multiple contacts when mirrored to the active SIM card and contacts from the SIM card will be merged into contacts in local storage if they have equal name information.

Returns true upon success.

See also mirrorAll().

QContact QContactModel::personalDetails () const

Returns the contact representing the personal details of the device owner.

If no contact is specified as the personal details of the device owner, will return a null contact.

See also setPersonalDetails().

QUniqueId QContactModel::personalID () const

Returns the identifier for the contact representing the personal details of the device owner.

If no contact is specified as the personal details of the device owner, will return a null identifier.

QList<Field> QContactModel::phoneFields ()   [static]

Returns the contact model fields that represent the phone numbers for a contact.

QPimSource QContactModel::phoneSource () const

Returns the default identifier for storage sources relating to the device memory.

QList<QCollectivePresenceInfo::PresenceType> QContactModel::presenceFilter () const

Returns the presence filter being used by the model.

See also setPresenceFilter().

QByteArray QContactModel::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 "vCard" or an empty string.

Reimplemented from QPimModel.

See also contact().

bool QContactModel::removeContact ( const QContact & contact )

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

Returns true if the contact was successfully removed.

bool QContactModel::removeContact ( const QUniqueId & identifier )

This is an overloaded member function, provided for convenience.

Removes the contact from the model with the specified identifier.

Returns true if the contact was successfully removed.

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

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

Returns true if contacts were successfully removed.

bool QContactModel::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.

bool QContactModel::setContactField ( QContact & contact, QContactModel::Field field, const QVariant & value )   [static]

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

Returns true if the contact was modified.

See also contactField() and setData().

bool QContactModel::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 contact model only accepts data for the EditRole. The column of the specified index specifies the QContactModel::Field to set and the row of the index specifies which contact to modify.

Reimplemented from QAbstractItemModel.

See also data() and setContactField().

void QContactModel::setFilter ( const QString & text, int flags = 0 )

Sets the model to filter contacts by labels that start with text and contact type information specified flags. By default flags is 0 which means filtering will only occur based on label text.

See also FilterFlags, filterFlags(), and filterText().

void QContactModel::setPersonalDetails ( const QUniqueId & identifier )

Sets the personal details of the device owner to the contact with the given identifier. If there is no contact with the specified identifier in the contact model this will clear the personal details.

See also personalDetails() and clearPersonalDetails().

void QContactModel::setPresenceFilter ( QList<QCollectivePresenceInfo::PresenceType> types )

Sets the model to only contain those contacts that have a presence status in the supplied types.

See also presenceFilter().

QString QContactModel::simCardIdentity () const

Returns the identifier for the currently inserted SIM card.

QList<int> QContactModel::simCardIndexes ( const QUniqueId & identifier, const QPimSource & source = QPimSource() ) const

Returns the list of indexes in the given source of contact data on a SIM card for the contact with the given identifier.

int QContactModel::simFreeIndexCount ( const QPimSource & source = QPimSource() ) const

Returns the number of free indexes for a given SIM contact data source.

int QContactModel::simIndexCount ( const QPimSource & source = QPimSource() ) const

Returns the total number of indexes available for a given SIM contact data source.

int QContactModel::simLabelLimit ( const QPimSource & source = QPimSource() ) const

Returns the maximum number of characters for the label component of a SIM contact data source entry.

Note that when storing contacts with multiple phone numbers to a SIM, part of the label may be used to indicate the type phone number for the entries used.

void QContactModel::simLoaded ( const QPimSource & source )   [signal]

This signal is emitted when the given source of contact data on a SIM card completes syncing to the SQL storage.

See also loadingSim().

int QContactModel::simNumberLimit ( const QPimSource & source = QPimSource() ) const

Returns the maximum number of characters for the number component of a SIM contact data source entry.

QPimSource QContactModel::simSource () const

Returns the identifier for storage sources relating to the SIM Card.

int QContactModel::simUsedIndexCount ( const QPimSource & source = QPimSource() ) const

Returns the number of indexes used for a given SIM contact data source.

void QContactModel::sort ( QList<SortField> list )

Sorts the model by the fields specified in list. Each entry in the list specifies a field and an order (ascending or descending).

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

This is an overloaded member function, provided for convenience.

Sorts the model by column in the specified order.

Reimplemented from QAbstractItemModel.

bool QContactModel::updateContact ( const QContact & contact )

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

Returns true if the contact was successfully updated.

bool QContactModel::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 updateContact().

bool QContactModel::writeVCard ( const QString & filename )

Write vCards for all visible contacts in the model to the file specified by filename.

Returns true if successful.