Contact pickers

A ContactPicker is a full screen control used to select a contact, multiple contacts, or an attribute of a contact.

A ContactPicker supports filters you can use to show only the contacts that match specific criteria. The supported filter types are:

  • Account: Use to show only contacts that belong to the account of a specific contact.
  • Kind: Use to show only contacts that have a specific ContactAtrribute, such as a specified Email address or phone number.
  • SubKind: Use to show only contacts that have a specific kind/subkind pairing, such as a specified Work Email address.
Screen showing a contact picker.

A ContactPicker supports the following modes:

  • Single: Use to select a single contact.
  • Multiple: Use to select multiple contacts.
  • Attribute: Use to select an attribute of a contact, such as a phone number or email address.

A ContactPicker is created in Single mode by default if no mode parameter is specified.

For more information on ContactPicker modes, see the ContactSelectionMode reference.

When a user selects a contact, the ContactPicker emits a contactSelected signal that contains the information of the selected contact.

For more information on contacts, see Contacts.

Implementing a contact picker

When you implement a ContactPicker, you need to link to the appropriate libraries to be able to use the classes you want in your app. In your .pro file, add the following line immediately after the CONFIG line:

LIBS += -lbbcascadespickers -lbbpim

Your app must also have the access_pimdomain_contacts permission, which you specify in the bar-descriptor.xml file for your app. To learn more about the bar-descriptor.xml file, see The bar-descriptor.xml file.

To implement a ContactPicker in your app, you must add the appropriate classes and namespaces to your main.cpp file:

#include <bb/cascades/Application>
#include <bb/cascades/QmlDocument>
#include <bb/cascades/AbstractPane>
#include <QLocale>
#include <QTranslator>
#include "applicationui.hpp"
#include <bb/cascades/Pickers/ContactPicker>
#include <Qt/qdeclarativedebug.h>

using namespace bb::cascades;
using namespace bb::cascades::pickers;

Next, register your ContactPicker so you can use it in QML:

qmlRegisterType<ContactPicker>("bb.cascades.pickers", 1, 0, "ContactPicker");

After you register your ContactPicker, you can implement the ContactPicker in QML. The following sample creates a Button that opens a ContactPicker when tapped. A Label is used to display the contactId of your selection.

import bb.cascades 1.0
import bb.cascades.pickers 1.0

Page {
    Container {
        Button {
            text: "Open contact picker"
            onClicked: {
            attachedObjects: [
                ContactPicker {
                    id: contactPicker
                    onContactSelected: {
                        result.text = "You chose contact: " + contactId;
        Label {
            id: result
            text: "You chose contact: "

You can then use the contactId to retrieve more detailed information about the selected contact using ContactService.

Last modified: 2014-01-23

comments powered by Disqus