QContactDetail Class Reference

Detailed Description

The QContactDetail class provides access to a single, complete detail about a contact.

All of the information for a contact is stored in one or more QContactDetail objects.

A detail is a group of logically related bits of data - for example, a street address is a single detail that has multiple fields (number, region, country etc). Every QContactDetail has an associated QContactDetailDefinition id that describes the fields, their data type, any restrictions on their values, and any restrictions on creating or updating details of that definition.

A field which is common to all details is the context field. This field is intended to store the context that this detail is associated with. Commonly this will be something like "Home" or "Work", although no limitations are placed on which values may be stored in this field.

It is possible to inherit from QContactDetail to provide convenience or standardized access to values. For example, QContactPhoneNumber provides a convenient API for manipulating a QContactDetail as a phone number, according to the schema.

If you wish to create your own, customized contact detail, you should use the Q_DECLARE_CUSTOM_CONTACT_DETAIL macro in order to ensure proper operation. See the predefined leaf classes (like QContactPhoneNumber, QContactAddress) for more information.

QContactDetail objects act like values. In general, you can assign them to and fro and have reasonable behaviour, like the following example.

    QContactPhoneNumber number;
    number.setNumber("555-1212");
    // number.value(QContactPhoneNumber::FieldNumber) == "555-1212";
    // number.definitionName() == QContactPhoneNumber::staticType()

    QContactDetail detail = number;
    // detail.value(QContactPhoneNumber::FieldNumber) == "555-1212";
    // detail.definitionName() == QContactPhoneNumber::staticType()

    QContactPhoneNumber otherNumber = detail;
    // otherNumber.number() == "555-1212";
    // otherNumber.definitionName() == QContactPhoneNumber::staticType()

    QContactAddress address = detail;
    // address is now a default constructed QContactAddress
    // address.error() == QContactDetail::IncompatibleAssignmentError
    // address.value(QContactPhoneNumber::FieldNumber) is empty
    // address.definitionName() == QContactAddress::staticType()

    QContactAddress otherAddress = number;
    // otherAddress is now a default constructed QContactAddress
    // otherAddress.error() == QContactDetail::IncompatibleAssignmentError
    // otherAddress.value(QContactPhoneNumber::FieldNumber) is empty
    // otherAddress.definitionName() == QContactAddress::staticType()

See also QContact, QContactDetailDefinition, and Q_DECLARE_CUSTOM_CONTACT_DETAIL.

Member Function Documentation

    value(QContactDetail::FieldContext);

    setValue(QContactDetail::FieldContext, contexts);

    setValue(FieldContext, QStringList(context));

    class Q_CONTACTS_EXPORT QContactPhoneNumber : public QContactDetail
    {
    public:
    #ifdef Q_QDOC
        const char* DefinitionName;
        const char* FieldNumber;
        const char* FieldSubType;
        const char* SubTypeLandline;
        const char* SubTypeMobile;
        const char* SubTypeFacsimile;
        const char* SubTypePager;
        const char* SubTypeVoice;
        const char* SubTypeModem;
        const char* SubTypeVideo;
        const char* SubTypeCar;
        const char* SubTypeBulletinBoardSystem;
        const char* SubTypeMessagingCapable;
        const char* SubTypeAssistant;
        const char* SubTypeDtmfMenu;
    #else
        Q_DECLARE_CUSTOM_CONTACT_DETAIL(QContactPhoneNumber, "PhoneNumber")
        Q_DECLARE_LATIN1_LITERAL(FieldNumber, "PhoneNumber");
        Q_DECLARE_LATIN1_LITERAL(FieldSubTypes, "SubTypes");
        Q_DECLARE_LATIN1_LITERAL(SubTypeLandline, "Landline");
        Q_DECLARE_LATIN1_LITERAL(SubTypeMobile, "Mobile");
        Q_DECLARE_LATIN1_LITERAL(SubTypeFacsimile, "Facsimile");
        Q_DECLARE_LATIN1_LITERAL(SubTypePager, "Pager");
        Q_DECLARE_LATIN1_LITERAL(SubTypeVoice, "Voice");
        Q_DECLARE_LATIN1_LITERAL(SubTypeModem, "Modem");
        Q_DECLARE_LATIN1_LITERAL(SubTypeVideo, "Video");
        Q_DECLARE_LATIN1_LITERAL(SubTypeCar, "Car");
        Q_DECLARE_LATIN1_LITERAL(SubTypeBulletinBoardSystem, "BulletinBoardSystem");
        Q_DECLARE_LATIN1_LITERAL(SubTypeMessagingCapable, "MessagingCapable");
        Q_DECLARE_LATIN1_LITERAL(SubTypeAssistant, "Assistant");
        Q_DECLARE_LATIN1_LITERAL(SubTypeDtmfMenu, "DtmfMenu");
    #endif

        void setNumber(const QString& number) {setValue(FieldNumber, number);}
        QString number() const {return value(FieldNumber);}

        void setSubTypes(const QStringList& subTypes) {setValue(FieldSubTypes, subTypes);}
        void setSubTypes(const QString& subType) {setValue(FieldSubTypes, QStringList(subType));}
        QStringList subTypes() const {return value<QStringList>(FieldSubTypes);}
    };