MeeGo 1.2 Harmattan Developer Documentation Develop for the Nokia N9

Contacts QML Plugin

Overview

The identifying string for this component is "QtMobility.contacts". Use this in the QML import statement.

The Contacts QML plugin supplies filters to search for contacts with particular values for various properties in the contact details. 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. We can also construct a series of filters and combine them using the IntersectionFilter and UnionFilter to represent a logical 'and' and 'or' of the results. Other properties also give control over the filter logic, such as RangeFlags and the MatchFlags.

ContactModel element

The ContactModel element is used to perform the requests on a contacts store. As an example consider the follow QML code which has a ContactModel element containing a filter and a list of sort orders. The contacts will be restricted to those living in Australia who are either male or born between 1970 and 1984.

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

 import QtMobility.contacts 1.1

 ...

 model: ContactModel {

     filter: IntersectionFilter {
         DetailFilter {
             detail:ContactDetail.Address
             field: Address.Country
             value: "Australia"
         }
         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 element

The Contact element represents a single contact instance from a 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"
         address.extendedAddress:"Suite 2"

         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:"Name(from detail name):" + myContact.detail("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 dynamic property names.
         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 }
     }
 }

Contacts Elements

QML ActionFilter Element

The ActionFilter element provides a filter based around an action availability criterion.

QML Address Element

The Address element contains an address of a contact.

QML Anniversary Element

The Anniversary element contains an anniversary of a contact.

QML Avatar Element

The Avatar element contains avatar URLs of a contact.

QML Birthday Element

The Birthday element contains a birthday of a contact.

QML ChangeLogFilter Element

The ChangeLogFilter element provides a filter based around a contact timestamp criterion.

QML Contact Element

The Contact element represents an addressbook contact, A Contact object has a collection of details (like a name, phone numbers and email addresses). Each detail (which can have multiple fields) is stored in an appropriate subclass of ContactDetail, and the Contact allows retrieving these details in various ways.

QML ContactDetail Element

The ContactDetail element represents a single, complete detail about a contact.

QML ContactModel Element

The ContactModel element provides access to contacts from the contacts store.

QML DetailFilter Element

The DetailFilter element provides a filter based around a detail value criterion.

QML DetailRangeFilter Element

The DetailRangeFilter element provides a filter based around a detail value range criterion.

QML DisplayLabel Element

The DisplayLabel element contains the (possibly synthesized) display label of a contact.

QML EmailAddress Element

The EmailAddress element contains an email address of a contact.

QML Family Element

The Family element contains names of family members of a contact.

QML Favorite Element

The Favorite element indicates if a contact is a favorite contact as well as the position it should appear in an ordered list of favorites.

QML FetchHint Element

The 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.

QML Filter Element

The Filter element is used as a property of ContactModel, to allow selection of contacts which have certain details or properties.

QML Gender Element

The Gender element contains the gender of a contact.

QML GeoLocation Element

The GeoLocation element contains a global location coordinate associated with a contact.

QML GlobalPresence Element

The GlobalPresence element provides aggregated presence information for a contact, synthesized or supplied by the backend.

QML Guid Element

The Guid element contains a globally unique Id of a contact, for use in synchronization with other datastores.

QML Hobby Element

The Hobby element contains a hobby of the contact.

QML IdFilter Element

The IdFilter element provides a filter based around a list of contact ids.

QML IntersectionFilter Element

The IntersectionFilter element provides a filter which intersects the results of other filters.

QML InvalidFilter Element

the InvalidFilter element provides a filter which will never match any contacts.

QML Name Element

The Name element contains a name of a contact.

QML Nickname Element

The Nickname element contains a nickname of a contact.

QML Note Element

The Note element contains a note associated with a contact.

QML OnlineAccount Element

The OnlineAccount element contains a note associated with a contact.

QML Organization Element

The Organization element provides details about an organization that the contact is either a part of, or stands for.

QML PhoneNumber Element

The PhoneNumber element provides a phone number of a contact.

QML Presence Element

The Presence element provides presence information for an online account of a contact.

QML Relationship Element

The Relationship element describes a one-to-one relationship between a locally-stored contact and another (possibly remote) contact.

QML RelationshipFilter Element

The RelationshipFilter element provides a filter based around relationship criteria.

QML RelationshipModel Element

The RelationshipModel provides a model of contact relationships from the contacts store.

QML Ringtone Element

The Ringtone element provides a ringtone associated with a contact.

QML SortOrder Element

The SortOrder element defines how a list of contacts should be ordered according to some criteria.

QML SyncTarget Element

The SyncTarget element provides a sync target for a contact.

QML Tag Element

The Tag element provides a contains a tag associated with a contact.

QML Timestamp Element

The Timestamp element contains the creation and last-modified timestamp associated with the contact.

QML UnionFilter Element

The UnionFilter element provides a filter which unions the results of other filters.

QML Url Element

The Url element contains a url associated with a contact.