ContactPicker

#include <bb/cascades/pickers/ContactPicker>

To link against this class, add the following line to your .pro file: LIBS += -lbbcascadespickers

A picker for selecting a contact, multiple contacts, or an attribute of a contact.

A ContactPicker is a full screen control that allows the user to select a contact, multiple contacts, or an attribute of a contact. The picker can be configured to show only contacts that match specific criteria. When selection is completed, a signal is emitted from the picker with the selected information. A canceled() signal is emitted if the user cancels the selection.

Filter criteria:

Account - The ContactPicker can be filtered to show only contacts belonging to a specific contacts account.

Kind - Only contacts that have a specific kind of ContactAttribute (e.g. Email, Phone) will be shown in the picker. When the picker is in ContactAttributeSelection mode, only those attributes will be shown.

SubKind - Only contacts that have a specific kind/subKind pair (e.g. Work Email) will be shown in the picker. When the picker is in ContactAttributeSelection mode, only those attributes will be shown.

The following example demonstrates how to create a ContactPicker for selecting multiple contacts that are filtered to show only contacts that have phone numbers:

  ContactPicker *contactPicker = new ContactPicker();
  contactPicker->setMode(ContactSelectionMode::Multiple);
  contactPicker->setKindFilters(QSet<bb::pim::contacts::AttributeKind::Type>() 
       << bb::pim::contacts::AttributeKind::Phone);
  
  QObject::connect(contactPicker, 
       SIGNAL(contactsSelected(QList<int> &)), 
       this, 
       SLOT(onContactsSelected(QList<int> &)));
  
  QObject::connect(contactPicker, 
       SIGNAL(canceled()), 
       this, 
       SLOT(onCanceled()));
  contactPicker->open();
*

Since:

BlackBerry 10.0.0

QML properties

mode: bb::cascades::pickers::ContactSelectionMode::Type
title: QString
confirmButtonLabel: QString
account: int

Public Functions Index

ContactPicker (QObject *parent=0)
virtual ~ContactPicker ()
Q_SLOT voidopen ()
Q_SLOT voidclose ()
Q_SLOT voidsetMode (bb::cascades::pickers::ContactSelectionMode::Type mode)
bb::cascades::pickers::ContactSelectionMode::Typemode () const
Q_SLOT voidsetTitle (const QString &title)
QStringtitle () const
Q_SLOT voidsetAccount (int accountId)
intaccount () const
Q_SLOT voidsetExcludeAccounts (const QList< int > &accountIds)
QList< int >excludedAccounts () const
Q_SLOT voidsetConfirmButtonLabel (const QString &confirmButtonLabel)
QStringconfirmButtonLabel () const
Q_SLOT voidsetKindFilters (const QSet< bb::pim::contacts::AttributeKind::Type > &kindFilters)
QSet< bb::pim::contacts::AttributeKind::Type >kindFilters () const
Q_SLOT voidsetSubKindFilters (const QSet< bb::pim::contacts::KindSubKindSpecifier > &subKindFilters)
QSet< bb::pim::contacts::KindSubKindSpecifier >subKindFilters () const
intselectedContactId () const
QList< int >selectedContactsIds () const
SelectedContactAttributeselectedContactAttribute () const
voidsetPerimeter (bb::system::SecurityPerimeter::Type perimeter)

Signals Index

voidcanceled ()
voiderror ()
voidcontactSelected (int contactId)
voidcontactsSelected (const QList< int > &contactIds)
voidcontactAttributeSelected (const bb::cascades::pickers::SelectedContactAttribute &attribute)
voidmodeChanged (bb::cascades::pickers::ContactSelectionMode::Type newMode)
voidconfirmButtonLabelChanged (const QString &newLabel)
voidkindFiltersChanged (const QSet< bb::pim::contacts::AttributeKind::Type > &kindFilters)
voidsubKindFiltersChanged (const QSet< bb::pim::contacts::KindSubKindSpecifier > &subKindFilters)
voidtitleChanged (const QString &newTitle)
voidaccountChanged (int newAccount)
voidexcludedAccountsChanged (const QList< int > &accountIds)

Properties

bb::cascades::pickers::ContactSelectionMode::Type mode

The mode the picker should be launched in.

Since:

BlackBerry 10.0.0

QString title

A custom message to be displayed in the title of the picker.

Since:

BlackBerry 10.0.0

QString confirmButtonLabel

A custom label to be displayed in the confirmation button of the picker.

Since:

BlackBerry 10.0.0

int account

A specific account to select contacts from.

When this is set, only contacts that belong to this account will be displayed.

Since:

BlackBerry 10.0.0

Public Functions

ContactPicker (

Constructs a ContactPicker.

By default the picker is in the ContactSelectionMode::Single mode.

Parameters
parent

The parent or 0. If not 0, the ownership of constructed ContactPicker will be transferred to the parent.
Since:

BlackBerry 10.0.0

virtual~ContactPicker ()

Destructor.

Since:

BlackBerry 10.0.0

Q_SLOT void open ()

Opens the ContactPicker.

This will display the contact picker allowing the user to perform the selection.

Any filters or customizations to the picker need to be set before open() is called. Any call to setters after open() is called will be ignored.

Since:

BlackBerry 10.0.0

Q_SLOT void close ()

Closes the picker.

Use this only when the user's input is no longer needed. Typically, the picker is closed as soon the user completes the selection.

Since:

BlackBerry 10.0.0

Q_SLOT void setMode (

Sets the mode the picker should be launched in.

By default, the picker is launched in ContactSelectionMode::Single mode.

Parameters
ContactSelectionMode

The selection mode for the picker.
Since:

BlackBerry 10.0.0

bb::cascades::pickers::ContactSelectionMode::Type mode ()

Returns the mode of the picker.

Return:

The ContactSelectionMode.

Since:

BlackBerry 10.0.0

Q_SLOT void setTitle (

Sets a message to be displayed in the title of the picker.

If this is not set, the default title will be used.

Parameters
QString

The title for the picker.
Since:

BlackBerry 10.0.0

QString title ()

Returns the title of the picker.

Return:

The title of the picker as a QString.

Since:

BlackBerry 10.0.0

Q_SLOT void setAccount (
  • intaccountId)

Sets a specific account to select contacts from.

When this is set, only contacts that belong to this account will be displayed.

See:

AccountService

Parameters
accountId

The account id
Since:

BlackBerry 10.0.0

int account ()

See:

setAccount()

Since:

BlackBerry 10.0.0

Q_SLOT void setExcludeAccounts (
  • const QList< int > &accountIds)

Filters the list of contacts displayed to contain only contacts where the sources of the contact do not belong to any of the provided account IDs.

Parameters
accountIds

The set of account IDs to filter based on.

QList< int > excludedAccounts ()

See:

excludeAccounts()

Q_SLOT void setConfirmButtonLabel (

Sets a custom label to be displayed in the confirmation button of the picker.

If this is not set, the default label will be used.

Parameters
confirmButtonLabel

The label displayed in the confirmation button.
Since:

BlackBerry 10.0.0

QString confirmButtonLabel ()

See:

setConfirmButtonLabel.

Since:

BlackBerry 10.0.0

Q_SLOT void setKindFilters (

Sets a set of attribute kinds (e.g.

Email, Phone) that should be used for filtering the contacts in the picker.

A contact must have one or more of the attributes in this set in order to be displayed.

See:

ContactConsts

Parameters
kindFilters

The set of filters.
Since:

BlackBerry 10.0.0

QSet< bb::pim::contacts::AttributeKind::Type > kindFilters ()

Returns the attribute kind filters.

See:

setKindFilters()

Since:

BlackBerry 10.0.0

Q_SLOT void setSubKindFilters (

Sets a set of Attribute kind/subKind pairs to should be used for filtering the contacts in the picker.

A contact must have at least one attribute that matches one of the pairs of kind/subKind.

See:

ContactConsts

Parameters
subKindFilters

The set of kindSubKindSpecifier.
Since:

BlackBerry 10.0.0

QSet< bb::pim::contacts::KindSubKindSpecifier > subKindFilters ()

See:

setSubKindFilters()

Since:

BlackBerry 10.0.0

int selectedContactId ()

Returns the id of the contact that was selected in the ContactPicker when in ContactSelectionMode::Single mode.

If the picker mode is not ContactSelectionMode::Single, this value is undefined.

Since:

BlackBerry 10.0.0

QList< int > selectedContactsIds ()

Returns the ids of the contacts that were selected in the ContactPicker when in ContactSelectionMode::Multiple mode.

If the picker mode is not ContactSelectionMode::Multiple, this value is undefined.

Since:

BlackBerry 10.0.0

SelectedContactAttribute selectedContactAttribute ()

Returns the attribute selected in the ContactPicker when in ContactSelectionMode::Attribute mode.

If the picker mode is not ContactSelectionMode::Attribute, this value is undefined.

Since:

BlackBerry 10.0.0

void setPerimeter (

Sets the security perimeter in which ContactPicker should be invoked.

Only required for hybrid applications using this api.

Parameters
perimeter

Security perimeter to use for ContactPicker invocation.
Since:

BlackBerry 10.1.0

Signals

void canceled ()

Emitted when the cancel button is clicked in the ContactPicker.

Since:

BlackBerry 10.0.0

void error ()

Emitted when launching the picker fails.

This occurs only when system resources are depleted.

Since:

BlackBerry 10.0.0

void contactSelected (
  • intcontactId)

Emitted when a contact is selected when not in multi-select mode.

Parameters
contactId

The id of the selected contact.
Since:

BlackBerry 10.0.0

void contactsSelected (
  • const QList< int > &contactIds)

Emitted completes the selection when in multi-select mode.

Parameters
contactIds

The list of selected contactIds.
Since:

BlackBerry 10.0.0

void contactAttributeSelected (

Emitted when a contact attribute is selected.

Parameters
attribute

A SelectedContactAttribute object populated with the values of the selected attribute.
Since:

BlackBerry 10.0.0

void modeChanged (

Emitted when the Mode property changes.

Parameters
newMode

The new Mode of the ContactPicker.
Since:

BlackBerry 10.0.0

void confirmButtonLabelChanged (

Emitted when the confirm label changes.

Parameters
newLabel

The new Mode of the ContactPicker.
Since:

BlackBerry 10.0.0

void kindFiltersChanged (

Emitted when the kind filter list is replaced.

Since:

BlackBerry 10.0.0

void subKindFiltersChanged (

Emitted when the kind filter list is replaced.

Since:

BlackBerry 10.0.0

void titleChanged (

Emitted when the title property changes.

Parameters
newTitle

The new title for the ContactPicker.
Since:

BlackBerry 10.0.0

void accountChanged (
  • intnewAccount)

Emitted when the account filter changes.

Parameters
newAccount

The new account id.
Since:

BlackBerry 10.0.0

void excludedAccountsChanged (
  • const QList< int > &accountIds)

Emitted when the excluded accounts change.

Parameters
accountIds

The new set of excluded accounts.