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"

         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