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

Detailed Description

The QContact class holds the data of an address book entry.

This data includes information the name of the contact, phone numbers and email addresses, postal address information, and business information such as department and job title.

It also allows a portrait picture (and corresponding thumbnail) to be specified, provides functions for matching a contact against a regular expression, and converting to and from vCard format.

See also QContactAddress and Pim Library.

Member Type Documentation

enum QContact::GenderType

This enum describes the three possible choices for gender.

enum QContact::Location

Enumerates the types of addresses a contact can have.

enum QContact::PhoneType

Enumerates the types of phone numbers that can be assigned to a contact.

Member Function Documentation

QContact::QContact ()

Constructs a new QContact.

QContact::QContact ( const QContact & contact )

Constructs a new QContact that is a copy of contact.

QContact::~QContact ()   [virtual]

Destroys the contact.

QContactAddress QContact::address ( Location location ) const

Returns the contact's address for the specified location.

See also setAddress().

QMap<Location, QContactAddress> QContact::addresses () const

Returns the contact's list of addresses with their types.

See also setAddresses().

QDate QContact::anniversary () const

Return the contact's anniversary date. If this has not been set, the returned date will be null.

See also setAnniversary().

QString QContact::assistant () const

Returns the assistant of the contact.

See also setAssistant().

QDate QContact::birthday () const

Return the contact's birthday. If this has not been set, the returned date will be null.

See also setBirthday().

QString QContact::businessCity () const

Returns the business city of the contact.

See also setBusinessCity().

QString QContact::businessCountry () const

Returns the business country of the contact.

See also setBusinessCountry().

QString QContact::businessFax () const

Returns the business fax number of the contact.

See also setBusinessFax().

QString QContact::businessMobile () const

Returns the business mobile number of the contact.

See also setBusinessMobile().

QString QContact::businessPager () const

Returns the business pager number of the contact.

See also setBusinessPager().

QString QContact::businessPhone () const

Returns the business phone number of the contact.

See also setBusinessPhone().

QString QContact::businessState () const

Returns the business state of the contact.

See also setBusinessState().

QString QContact::businessStreet () const

Returns the business street address of the contact.

See also setBusinessStreet().

QString QContact::businessVOIP () const

Returns the business VOIP URL of the contact.

See also setBusinessVOIP().

QString QContact::businessWebpage () const

Returns the business webpage of the contact.

See also setBusinessWebpage().

QString QContact::businessZip () const

Returns the business zip of the contact.

See also setBusinessZip().

void QContact::changePortrait ( const QPixmap & p )

Changes the contacts portrait to the given pixmap p. The pixmap is saved to the contactimages directory in the Qtopia "addressbook" application storage directory, and removes the file previously used as the contact's portrait. The corresponding filename will be set as the Portrait field of this contact.

Note: the previous image is removed immediately if it is in the "addressbook" application data storage area, but the database will not be updated until QContactModel::updateContact is called.

void QContact::changePortrait ( const QImage & image )

This is an overloaded member function, provided for convenience.

Changes the contacts portrait to the given image. The image is saved to the contactimages directory in the Qtopia "addressbook" application storage directory, and removes the file previously used as the contact's portrait. The corresponding filename will be set as the Portrait field of this contact.

Note: the previous image is removed immediately if it is in the "addressbook" application data storage area, but the database will not be updated until QContactModel::updateContact is called.

void QContact::changePortrait ( const QString & imageLocation, const QRect & rect = QRect() )

This is an overloaded member function, provided for convenience.

Changes the contacts portrait to the image at the given imageLocation. The image is loaded, scaled and then saved to the contactimages directory in the Qtopia "addressbook" application storage directory. If the specified clip rectangle rect is not null, only the clip area of the image specified is used. The file previously used as the contact's portrait is removed. The corresponding filename will be set as the Portrait field of this contact.

Note: the previous image is removed immediately if it is in the "addressbook" application data storage area, but the database will not be updated until QContactModel::updateContact is called.

QString QContact::children () const

Returns the children of the contact.

See also setChildren().

void QContact::clearAddresses ()

Clears the addresses of the contact.

void QContact::clearEmailList ()

Clear the email list for the contact, including the default email.

void QContact::clearPhoneNumbers ()

Clears the phone number list of the contact, including the default phone number.

QString QContact::company () const

Returns the company for the contact.

See also setCompany().

QString QContact::companyPronunciation () const

Returns the pronunciation of the contact's company name.

See also setCompanyPronunciation().

QString QContact::defaultEmail () const

Returns the default email address of the contact.

See also setDefaultEmail().

QString QContact::defaultPhoneNumber () const

Return the default phone number of the contact. If no default phone number is set, this returns the null string.

See also setDefaultPhoneNumber().

QString QContact::department () const

Returns the department for the contact.

See also setDepartment().

QString QContact::displayAddress ( Location location ) const

Returns a formatted string with the contact's address of type location.

QString QContact::displayBusinessAddress () const

Returns a formatted string with the contact's business address.

QString QContact::displayHomeAddress () const

Returns a formatted string with the contact's home address.

QStringList QContact::emailList () const

Returns a list of email addresses belonging to the contact, including the default email address.

See also setEmailList() and defaultEmail().

QString QContact::firstName () const

Returns the first name of the contact.

See also setFirstName().

QString QContact::firstNamePronunciation () const

Returns the pronunciation of the contact's first name.

See also setFirstNamePronunciation().

GenderType QContact::gender () const

Returns the gender of the contact as type GenderType.

See also setGender().

QString QContact::homeCity () const

Returns the home city of the contact.

See also setHomeCity().

QString QContact::homeCountry () const

Returns the home country of the contact.

See also setHomeCountry().

QString QContact::homeFax () const

Returns the home fax number of the contact.

See also setHomeFax().

QString QContact::homeMobile () const

Returns the home mobile number of the contact.

See also setHomeMobile().

QString QContact::homePhone () const

Returns the home phone number of the contact.

See also setHomePhone().

QString QContact::homeState () const

Returns the home state of the contact.

See also setHomeState().

QString QContact::homeStreet () const

Returns the home street address of the contact.

See also setHomeStreet().

QString QContact::homeVOIP () const

Returns the home VOIP URL of the contact.

See also setHomeVOIP().

QString QContact::homeWebpage () const

Returns the home webpage of the contact.

See also setHomeWebpage().

QString QContact::homeZip () const

Returns the home zip of the contact.

See also setHomeZip().

QIcon QContact::icon () const

Returns the portrait of the contact as an icon. If there is no portrait set for the contact will return a default icon.

See also portrait() and thumbnailSize().

void QContact::insertEmail ( const QString & email )

Adds email to the list of email address for the contact. If no default email is set, the default email will be set to email.

QString QContact::jobTitle () const

Returns the job title of the contact.

See also setJobTitle().

QString QContact::label () const

Returns a suitable display string for the contact. This is built up by using fields of the contact and the format set for generating the contact labels.

See also labelFormat() and labelFields().

QStringList QContact::labelFields ()   [static]

Returns the string identifiers suitable for describing the format for the contact label.

See also labelFormat() and label().

QString QContact::labelFormat ()   [static]

Returns the format for contact labels.

The format is a set of pattern separated by '|'s. Each pattern is a set of space separated tokens. A token can either be _ for a space, an identifier as from identifierKey(), or any string. The format for label will the first pattern for which all fields specified are non null for the contact.

For example: lastname , _ firstname | lastname | firstname | company

See also setLabelFormat(), labelFields(), and label().

QString QContact::lastName () const

Returns the last name of the contact.

See also setLastName().

QString QContact::lastNamePronunciation () const

Returns the pronunciation of the contact's last name.

See also setLastNamePronunciation().

QString QContact::manager () const

Returns the manager of the contact.

See also setManager().

bool QContact::match ( const QRegExp & expression ) const

Returns true if one of this contact's fields matches the given expression.

The function does not compare the gender, unique identifier, birthday or anniversary of the contact.

bool QContact::match ( const QString & expression ) const

This is an overloaded member function, provided for convenience.

Returns true if one of this contact's fields matches the given expression.

The function does not compare the gender, unique identifier, birthday or anniversary of the contact.

QString QContact::middleName () const

Returns the middle name of the contact.

See also setMiddleName().

QString QContact::nameTitle () const

Returns the title of the contact (e.g. Dr., Prof.)

See also setNameTitle().

QString QContact::nickname () const

Returns the nickname of the contact.

See also setNickname().

QString QContact::notes () const   [virtual]

Returns the notes relating to the the contact.

Reimplemented from QPimRecord.

See also setNotes().

QString QContact::office () const

Returns the office for the contact.

See also setOffice().

QContact QContact::parseLabel ( const QString & text, const QContact & contact = QContact() )   [static]

Parses the given text using contact name formatting rules and merges the information with contact. Returns the merged contact.

Formatting rules include using () for the nick name, "" for pronunciation, standard name titles and suffixes as well as detecting first, middle and last name ordering, similar to the default label formatting.

See also label().

QIcon QContact::phoneIcon ( PhoneType type )   [static]

Returns an icon representing the phone number type. Returns a null icon if no icon is available for the phone number type.

See also phoneIconResource().

QString QContact::phoneIconResource ( PhoneType type )   [static]

Returns the resource location (e.g. ":icon/addressbook/homephone") for an icon representing the phone number type. Returns a null string if no icon is available for the phone number type.

See also phoneIcon().

QString QContact::phoneNumber ( PhoneType type ) const

Returns the phone number of type for the contact. If the contact does not have a corresponding phone number, this will return a null QString.

See also setPhoneNumber().

QMap<PhoneType, QString> QContact::phoneNumbers () const

Returns the contact's list of phone numbers and their types.

See also setPhoneNumbers().

QList<PhoneType> QContact::phoneTypes ()   [static]

Returns a list of phone types that can be assigned as a contact phone number.

QPixmap QContact::portrait () const

Returns the portrait of the contact as a pixmap. If there is no portrait set for the contact, this will return a default pixmap based on the contact's fields.

See also icon() and portraitSize().

QString QContact::portraitFile () const

Returns the path for the portrait file of the contact. This is either a resource file path (e.g. ":icon/happyface") or the name of a file that is stored in the "addressbook/contactimages" directory in the Qt Extended application data storage directory.

See also setPortraitFile().

QSize QContact::portraitSize ()   [static]

Returns the size of the portrait pixmap of a contact.

See also portrait() and thumbnailSize().

QString QContact::profession () const

Returns the profession of the contact.

See also setProfession().

QList<QContact> QContact::readVCard ( QIODevice * device )   [static]

Reads a list of vCards from the given device and returns the equivalent set of contacts.

See also writeVCard().

QList<QContact> QContact::readVCard ( const QString & filename )   [static]

This function is deprecated.

This is an overloaded member function, provided for convenience.

Reads the file specified by filename as a list of vCard objects and returns the list of contacts that correspond to the vCard objects.

Note: the fields stored by QContact may not correspond exactly to the vCard data.

See also writeVCard().

QList<QContact> QContact::readVCard ( const QByteArray & vcard )   [static]

This function is deprecated.

This is an overloaded member function, provided for convenience.

Reads the given vCard data in vcard, and returns the list of corresponding contacts.

Note: the fields stored by QContact may not correspond exactly to the vCard data.

See also writeVCard().

QList<QContact> QContact::readVCard ( VObject * vobject )   [static]

This is an overloaded member function, provided for convenience.

Reads the given vCard data in vobject, and returns the list of corresponding contacts.

Note: the fields stored by QContact may not correspond exactly to the vCard data.

See also writeVCard().

void QContact::removeEmail ( const QString & email )

Removes email from the list of email address for the contact. If the email is the default email, the default email will be set to the first one in the list.

void QContact::setAddress ( Location location, const QContactAddress & address )

Sets the contact's address for the given location to address. If the address is empty, this will effectively remove that Location type for this contact.

See also address().

void QContact::setAddresses ( const QMap<Location, QContactAddress> & addresses )

Sets the contact addresses to the given addresses

See also addresses().

void QContact::setAnniversary ( const QDate & date )

Sets the contact's anniversary to date.

See also anniversary().

void QContact::setAssistant ( const QString & str )

Sets the assistant of the contact to str.

See also assistant().

void QContact::setBirthday ( const QDate & date )

Sets the contact's birthday to date.

See also birthday().

void QContact::setBusinessCity ( const QString & str )

Sets the business city of the contact to str.

See also businessCity().

void QContact::setBusinessCountry ( const QString & str )

Sets the business country of the contact to str.

See also businessCountry().

void QContact::setBusinessFax ( const QString & str )

Sets the business fax number of the contact to str.

See also businessFax().

void QContact::setBusinessMobile ( const QString & str )

Sets the business mobile phone number of the contact to str.

See also businessMobile().

void QContact::setBusinessPager ( const QString & str )

Sets the business pager number of the contact to str.

See also businessPager().

void QContact::setBusinessPhone ( const QString & str )

Sets the business phone number of the contact to str.

See also businessPhone().

void QContact::setBusinessState ( const QString & str )

Sets the business state of the contact to str.

See also businessState().

void QContact::setBusinessStreet ( const QString & str )

Sets the business street address of the contact to str.

See also businessStreet().

void QContact::setBusinessVOIP ( const QString & str )

Sets the business VOIP URL of the contact to str. This should be in the form of a URL (e.g. 'sip:user@sipserver').

See also businessVOIP().

void QContact::setBusinessWebpage ( const QString & str )

Sets the business webpage of the contact to str.

See also businessWebpage().

void QContact::setBusinessZip ( const QString & str )

Sets the business zip code of the contact to str.

See also businessZip().

void QContact::setChildren ( const QString & str )

Sets the children of the contact to str.

See also children().

void QContact::setCompany ( const QString & str )

Sets the company for contact to str.

See also company().

void QContact::setCompanyPronunciation ( const QString & str )

Sets the pronunciation of the contact's company name to str.

See also companyPronunciation().

void QContact::setDefaultEmail ( const QString & v )

Sets the default email to v. If the given email address v is not already in the contact's list of email addresses, this function adds it.

See also defaultEmail() and setEmailList().

void QContact::setDefaultPhoneNumber ( const QString & str )

If the contact has an existing phone number that matches str, it will be set as the default phone number.

See also defaultPhoneNumber().

void QContact::setDefaultPhoneNumber ( PhoneType type )

This is an overloaded member function, provided for convenience.

If the contact has an existing phone number of a type that matches type, it will be set as the default phone number.

void QContact::setDepartment ( const QString & str )

Sets the department for contact to str.

See also department().

void QContact::setEmailList ( const QStringList & emails )

Sets the email list to emails

See also emailList() and defaultEmail().

void QContact::setFirstName ( const QString & str )

Sets the first name of the contact to str.

See also firstName().

void QContact::setFirstNamePronunciation ( const QString & str )

Sets the pronunciation of the contact's first name to str.

See also firstNamePronunciation().

void QContact::setGender ( GenderType g )

Sets the contact's gender to the enum value specified in g.

See also gender().

void QContact::setHomeCity ( const QString & str )

Sets the home city of the contact to str.

See also homeCity().

void QContact::setHomeCountry ( const QString & str )

Sets the home country of the contact to str.

See also homeCountry().

void QContact::setHomeFax ( const QString & str )

Sets the home fax number of the contact to str.

See also homeFax().

void QContact::setHomeMobile ( const QString & str )

Sets the home mobile phone number of the contact to str.

See also homeMobile().

void QContact::setHomePhone ( const QString & str )

Sets the home phone number of the contact to str.

See also homePhone().

void QContact::setHomeState ( const QString & str )

Sets the home state of the contact to str.

See also homeState().

void QContact::setHomeStreet ( const QString & str )

Sets the home street address of the contact to str.

See also homeStreet().

void QContact::setHomeVOIP ( const QString & str )

Sets the home VOIP URL of the contact to str. This should be in the form of a URL (e.g. 'sip:user@sipserver').

See also homeVOIP().

void QContact::setHomeWebpage ( const QString & str )

Sets the home webpage of the contact to str.

See also homeWebpage().

void QContact::setHomeZip ( const QString & str )

Sets the home zip code of the contact to str.

See also homeZip().

void QContact::setJobTitle ( const QString & str )

Sets the job title of the contact to str.

See also jobTitle().

void QContact::setLabelFormat ( const QString & f )   [static]

Sets the format for contact labels to that described by f.

The format is a set of pattern separated by '|'s. Each pattern is a set of space separated tokens. A token can either be _ for a space, an identifier as from identifierKey(), or any string. The format used for label() will be the first pattern for which all fields specified are non null for the contact.

For example: lastname , _ firstname | lastname | firstname | company

See also labelFormat(), labelFields(), and label().

void QContact::setLastName ( const QString & str )

Sets the last name of the contact to str.

See also lastName().

void QContact::setLastNamePronunciation ( const QString & str )

Sets the pronunciation of the contact's last name to str.

See also lastNamePronunciation().

void QContact::setManager ( const QString & str )

Sets the manager of the contact to str.

See also manager().

void QContact::setMiddleName ( const QString & str )

Sets the middle name of the contact to str.

See also middleName().

void QContact::setNameTitle ( const QString & str )

Sets the title of the contact to str.

See also nameTitle().

void QContact::setNickname ( const QString & str )

Sets the nickname of the contact to str.

See also nickname().

void QContact::setNotes ( const QString & str )   [virtual]

Sets the notes about the contact to str.

Reimplemented from QPimRecord.

See also notes().

void QContact::setOffice ( const QString & str )

Sets the office for contact to str.

See also office().

void QContact::setPhoneNumber ( PhoneType type, const QString & str )

Sets the phone number of type type to str.

If there is no default phone number set, this will set the given number as the default phone number.

See also phoneNumber().

void QContact::setPhoneNumbers ( const QMap<PhoneType, QString> & numbers )

Sets the set of phone numbers of the contact to the given numbers

See also phoneNumbers().

void QContact::setPortraitFile ( const QString & str )

Sets the path for the portrait file of the contact to str.

The string is interpreted as follows: - if the path starts with a ':' character, it is interpreted as a Qt Resource system path - otherwise, the string will be interpreted as a path relative to the "contactimages" subdirectory of the "addressbook" application storage directory (retrieved using Qtopia::applicationFileName).

See also portraitFile().

void QContact::setProfession ( const QString & str )

Sets the profession of the contact to str.

See also profession().

void QContact::setSpouse ( const QString & str )

Sets the spouse of the contact to str.

See also spouse().

void QContact::setSuffix ( const QString & str )

Sets the suffix of the contact to str.

See also suffix().

QString QContact::spouse () const

Returns the spouse of the contact.

See also setSpouse().

QString QContact::suffix () const

Returns the suffix of the contact.

See also setSuffix().

QPixmap QContact::thumbnail () const

Returns the portrait of the contact, scaled down to the thumbnail size.

If there is no portrait set for the contact, this will return a default pixmap based on the contact's fields.

See also thumbnailSize().

QSize QContact::thumbnailSize ()   [static]

Returns the size of the thumbnail of a contact's portrait.

See also thumbnail() and portraitSize().

QString QContact::toRichText () const

Returns a rich text formatted QString of the QContact.

bool QContact::writeVCard ( QIODevice * device, const QList<QContact> & contacts )   [static]

Writes the given list of contacts to the given device as vCards.

Returns true on success.

See also readVCard().

bool QContact::writeVCard ( QIODevice * device, const QContact & contact )   [static]

This is an overloaded member function, provided for convenience.

Writes the given contact to the given device as vCards.

Returns true on success.

See also readVCard().

bool QContact::writeVCard ( const QString & filename, const QList<QContact> & contacts )   [static]

This function is deprecated.

This is an overloaded member function, provided for convenience.

Write the list of contacts as vCard objects to the file specified by filename.

Returns true on success, false on failure.

See also readVCard().

bool QContact::writeVCard ( const QString & filename ) const

This function is deprecated.

This is an overloaded member function, provided for convenience.

Writes the contact as a vCard object to the file specified by filename.

Returns true on success, false on failure.

See also readVCard().

void QContact::writeVCard ( QFile & file ) const

This function is deprecated.

This is an overloaded member function, provided for convenience.

Writes the contact as a vCard object to the given file, which must be already open for writing.

See also readVCard().

void QContact::writeVCard ( QDataStream * stream ) const

This function is deprecated.

This is an overloaded member function, provided for convenience.

Writes the contact as a vCard object to the given stream, which must be writable.

See also readVCard().

bool QContact::operator!= ( const QContact & other ) const

Returns false if other is identical to this contact. Otherwise return true.

QContact & QContact::operator= ( const QContact & contact )

Makes a copy of contact and assigns it to this QContact.

bool QContact::operator== ( const QContact & other ) const

Compares to other contact and returns true if it is equivalent. Otherwise returns false.