Contact pickers

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

A ContactPicker control 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.

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 about contacts, see Contacts.

Prerequisites for a contact picker

To work with contacts, your app must have the access_pimdomain_contacts permission. This permission can be set in your app's bar-descriptor.xml file. For more information about the bar-descriptor.xml file, see The bar-descriptor.xml file.

The following code sample creates a Button that opens a ContactPicker control when 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.

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

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

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

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

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

LIBS += -lbbcascadespickers -lbbpim

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

    
#include "applicationui.hpp"
#include <bb/cascades/Pickers/ContactPicker>

using namespace bb::cascades;
using namespace bb::cascades::pickers;
//...

contactPicker = new ContactPicker();
contactPicker->setMode(ContactSelectionMode::Single);

// Use the objectName attribute, which is set in QML,
// to access the Button object
contactPkrBtn = root->findChild<Button*>("contactPkrBtn");
contactPkrBtn->setText("Open contact picker");

// Use the objectName attribute, which is set in QML,
// to access the Label object
resultLbl = root->findChild<Label*>("result");

bool res = QObject::connect(contactPicker,
        SIGNAL(contactSelected(int)),
        this,
        SLOT(onContactsSelected(int)));
Q_ASSERT(res);

res = QObject::connect(contactPkrBtn,
        SIGNAL(clicked()),
        this,
        SLOT(onClicked()));
Q_ASSERT(res);
Q_UNUSED(res);

// ...

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()
{
    contactPicker->open();
}

Not applicable

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

Last modified: 2015-03-31



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

comments powered by Disqus