ContactPicker

Since: BlackBerry 10.0.0

#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();
*


Overview

QML properties

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

Public Functions Index

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

Signals Index

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

Properties

int account

A specific account to select contacts from.

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

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

The mode the picker should be launched in.

Since:

BlackBerry 10.0.0

bool remoteSearchEnabled

Enable remote search to be used in the contact picker.

When this is set to true, remote search will be allowed in the picker if it is supported by any accounts.

Since:

BlackBerry 10.3.0

QString title

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

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

int account ()

See also:

setAccount()

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

QString confirmButtonLabel ()

Since:

BlackBerry 10.0.0

QList< int > excludedAccounts ()

See also:

excludeAccounts()

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

Returns the attribute kind filters.

Since:

BlackBerry 10.0.0

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

Returns the mode of the picker.

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

bool remoteSearchEnabled ()

Returns true if remote search is enabled in the current contact picker.

Since:

BlackBerry 10.3.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

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

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 also:

AccountService

Parameters
accountId

The account id

Since:

BlackBerry 10.0.0

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

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.

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 also:

ContactConsts

Parameters
kindFilters

The set of filters.

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

Q_SLOT void setRemoteSearchEnabled (
  • boolremoteSearchEnabled)

Sets a flag to allow remote search to be used in the contact picker, this allows the picker to search remote accounts for contacts if supported.

If this is not set, remote search will not be enabled in the picker.

Parameters
remoteSearchEnabled

the flag whether to enable remote search

Since:

BlackBerry 10.3.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 also:

ContactConsts

Parameters
subKindFilters

The set of kindSubKindSpecifier.

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

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

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

Signals

void accountChanged (
  • intnewAccount)

Emitted when the account filter changes.

Parameters
newAccount

The new account id.

Since:

BlackBerry 10.0.0

void canceled ()

Emitted when the cancel button is clicked in 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 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 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 error ()

Emitted when launching the picker fails.

This occurs only when system resources are depleted.

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.

void kindFiltersChanged (

Emitted when the kind filter list is replaced.

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 remoteSearchEnabledChanged (
  • boolremoteSearchEnabled)

Emitted when the flag for allowing remote search changes.

Parameters
remoteSearchEnabled

The value whether remote search is allowed.

Since:

BlackBerry 10.3.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

Last modified: 2014-06-24



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

comments powered by Disqus