Qt Contacts QML API

Overview

To be able to use this component the QML import statement needs to reference the module before it can used. Simply add the following to the QML file:

  import QtContacts 5.0

The Contacts API enables client to search for contacts data from local backends and use filters to get only the relevant results. The QML Contacts API delivers this capability in easy to use form.

The following describes the API. The Examples section contains sample code for the QML API.

Contact Model

The Contact itself is represented by a model called a ContactModel. This model supplies a rich selection of properties to display or to use as filter criteria. The model is then used to perform requests on a contacts store.

Filters

Developers can construct a series of filters and combine them using the IntersectionFilter and UnionFilter types to represent a logical and and or of the results. There are also other properties that give control over the filter logic, such as RangeFlags and the MatchFlags.

As an example, consider the follow QML code which has a ContactModel type containing a filter and a list of sort orders. The contacts will be restricted to those living in Finland who are either male or born between 1970 and 1984.

The list of contacts in this ContactModel will be first sorted on the contacts' organization name and then on the contacts' first name.

  import QtContacts 5.0

  ...

  model: ContactModel {

      filter: IntersectionFilter {
          DetailFilter {
              detail:ContactDetail.Address
              field: Address.Country
              value: "Finland"
          }
          UnionFilter {
              DetailRangeFilter {
                  detail:ContactDetail.Birthday
                  field:Birthday.Birthday
                  min: '1970-01-01'
                  max: '1984-12-31'
              }
              DetailFilter {
                  detail:ContactDetail.Gender
                  field:Gender.Gender
                  value:Gender.Male
              }
          }
      }
      sortOrders: [
         SortOrder {
            detail:ContactDetail.Organization
            field:Organization.Name
            direction:Qt.AscendingOrder
         },
         SortOrder {
            detail:ContactDetail.Name
            field:Name.FirstName
            direction:Qt.AscendingOrder
         }
      ]
  }

Contact type

The Contact type represents a single contact instance from the contacts store. All contact details are organized as group properties.

The following snippet shows how you can construct a Contact object in QML:

  Rectangle {
      id: topItem
      width: 360
      height: 640
      x: 0
      y: 0

      Contact {
          id: myContact
          Name {
              firstName:"John"
              lastName:"Gates"
          }

          EmailAddress {
              emailAddress:"john@example.com"
          }
          EmailAddress {
              emailAddress:"mygmailaccount@gmail.com"
          }

          address.street:"53 Mysteet St"
          address.locality: "My City"
          address.region: "My Region"
          address.postcode:"1111"
          address.country:"My Country"
          address.subTypes:[Address.Postal, Address.Domestic]
          address.postOfficeBox:"1111"

          Nickname {
              nickname:"John"
          }

          PhoneNumber {
              number: "1111111111"
              subTypes:[PhoneNumber.Mobile]
          }

          PhoneNumber {
              number: "2222222222"
              subTypes:[PhoneNumber.Fax]
          }

          PhoneNumber {
              number: "3333333333"
              subTypes:[PhoneNumber.Landline]
          }
      }

      Column {
          spacing:4

          //access the same property with different syntaxes
          Text { text:"Name(from property name):" + myContact.name.firstName + " " + myContact.name.lastName }
          Text { text:"Name(from detail type):" + myContact.detail(ContactDetail.Name).firstName + " " + myContact.name.lastName }

          Text { text:"Address:" + myContact.address.street + " " + myContact.address.locality + " " + myContact.address.region + " " + myContact.address.postcode }

          //If a contact contains multiple details for the same detail type, you can access them with the property in plural
          Text { text:"How many email accounts?:" + myContact.emails.length }
          Text { text:"Email[0]:" + myContact.emails[0].emailAddress }

          Text { text:"How many phone numbers?:" + myContact.phoneNumbers.length }
          Text { text:"phone number[0]:" + myContact.phoneNumbers[0].number }
          Text { text:"phone number[1]:" + myContact.phoneNumbers[1].number }
          Text { text:"phone number[2]:" + myContact.phoneNumbers[2].number }
      }
  }

Reference documentation

Main Classes

Detail Leaf Classes

Item matching and filtering

Examples

The following sample applications show examples of API usage:

• Qt Quick Contacts List view