Contact pickers

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

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

  • Account: Use to show only those contacts that belong to the account of a specific contact.
  • Kind: Use to show only those contacts that have a specific ContactAtrribute, such as a specified email address or phone number.
  • SubKind: Use to show only those contacts that have a specific kind or sub-kind pairing, such as a 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.
  • MultipleAttribute: Use to select multiple attributes of contacts.

If a mode parameter is not specified, a ContactPicker is created in Single mode.

For more information on ContactPicker modes, see ContactSelectionMode.

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

For more information about contacts, see Contacts.


To work with contacts, your app must have the  access_pimdomain_contacts permission.

To use the ContactPicker class, you must link to the Pickers library.

Creating a contact picker

The following code sample creates a Button that opens a ContactPicker when the button is tapped. A Label is used to display the contactId of your selection.

When you want to access a ContactPicker object that's in your C++ code from your QML code, add the following line to your app's C++ constructor in the applicationui.cpp file to register your ContactPicker.

#include <bb/cascades/pickers/ContactPicker>    

    1, 0,

After you register your ContactPicker object, you can implement the ContactPicker object in QML.

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

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

To implement a ContactPicker in your app's C++ code, you must add the ContactPicker class and the appropriate namespaces to your applicationui.cpp file:

#include <bb/cascades/pickers/ContactPicker>

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

contactPicker = new ContactPicker();

contactPkrBtn = Button::create()
    .text("Open contact picker")
    .onClicked(this, SLOT(onClicked()));

resultLbl = new Label();

bool res = QObject::connect(contactPicker,

// ...

The slots used in this code sample are shown below:

void ApplicationUI::onContactsSelected(int contactId)
    resultLbl->setText("You chose contact: " 
        + QString::number(contactId));

void ApplicationUI::onClicked()

Not applicable

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

Last modified: 2015-07-24

Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus