- Qt 5.0
- Qt Contacts QML API
- Qt 5.0.0 Reference Documentation

# 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

Collection | Element represents a collection of items in a contacts manager
Contact | Element represents an addressbook contact
ContactDetail | Element represents a single, complete detail about a contact
ContactModel | Element provides access to contacts from the contacts store
FetchHint | Element provides hints to the manager about which contact information needs to be retrieved in an asynchronous fetch request or a synchronous function call
Filter | Element is used as a property of ContactModel, to allow selection of contacts which have certain details or properties
Relationship | Element describes a one-to-one relationship between a locally-stored contact and another (possibly remote) contact
RelationshipModel | Model of contact relationships from the contacts store
SortOrder | Element defines how a list of contacts should be ordered according to some criteria

### Detail Leaf Classes

Address | Element contains an address of a contact
Anniversary | Element contains an anniversary of a contact
Avatar | Element contains avatar URLs of a contact
Birthday | Element contains a birthday of a contact
DisplayLabel | Element contains a label that can be used by clients when displaying a contact, for example in a list
EmailAddress | Element contains an email address of a contact
ExtendedDetail | Element contains an extended detail of a contact
Family | Element contains names of family members of a contact
Favorite | Element indicates if a contact is a favorite contact as well as the position it should appear in an ordered list of favorites
Gender | Element contains the gender of a contact
GeoLocation | Element contains a global location coordinate associated with a contact
GlobalPresence | Element provides aggregated presence information for a contact, synthesized or supplied by the backend
Guid | Element contains a globally unique Id of a contact, for use in synchronization with other datastores
Hobby | Element contains a hobby of the contact
Name | Element contains a name of a contact
Nickname | Element contains a nickname of a contact
Note | Element contains a note associated with a contact
OnlineAccount | Element contains a note associated with a contact
Organization | Element provides details about an organization that the contact is either a part of, or stands for
PhoneNumber | Element provides a phone number of a contact
Presence | Element provides presence information for an online account of a contact
Ringtone | Element provides a ringtone associated with a contact
SyncTarget | Element provides a sync target for a contact
Tag | Element provides a contains a tag associated with a contact
Timestamp | Element contains the creation and last-modified timestamp associated with the contact
Url | Element contains a url associated with a contact

### Item matching and filtering

ActionFilter | Element provides a filter based around an action availability criterion
ChangeLogFilter | Element provides a filter based around a contact timestamp criterion
DetailFilter | Element provides a filter based around a detail value criterion
DetailRangeFilter | Element provides a filter based around a detail value range criterion
IdFilter | Element provides a filter based around a list of contact ids
IntersectionFilter | Element provides a filter which intersects the results of other filters
InvalidFilter | The InvalidFilter element provides a filter which will never match any contacts
RelationshipFilter | Element provides a filter based around relationship criteria
UnionFilter | Element provides a filter which unions the results of other filters

### Examples

The following sample applications show examples of API usage:

- Qt Quick Contacts List view