ContactListFilters

Since: BlackBerry 10.0.0

#include <bb/pim/contacts/ContactListFilters>

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

The ContactListFilters class represents a set of filters that are used for listing and sorting contacts.

You can use this class to list and sort Contact objects. This class is designed to work with ContactService::contacts() to specify the number, type, and sorting of the contacts that are returned.


Overview

Public Functions Index

ContactListFilters ()
ContactListFilters (const ContactListFilters &copy)
~ContactListFilters ()
ContactIdanchorId () const
QVariantListcontactIds () const
QVariantListexcludeContacts () const
boolisFavourite () const
boolisVideoChatContact () const
intlimit () const
intoffset () const
ContactListFilters &operator= (const ContactListFilters &operand)
ContactListFilters &setAnchorId (ContactId contactId, bool inclusive=false)
ContactListFilters &setBelongsToGroups (QList< GroupId > groupIds)
ContactListFilters &setContactIds (QList< int > &contactIds)
ContactListFilters &setExcludeAccount (AccountId accountId)
ContactListFilters &setExcludeAccount (AccountId accountId, bool includeMergedContacts)
ContactListFilters &setExcludeAccounts (const QList< AccountId > &accountId)
ContactListFilters &setExcludeAccounts (const QList< AccountId > &accountId, bool includeMergedContacts)
ContactListFilters &setExcludeContacts (const QList< ContactId > &contactIds)
ContactListFilters &setHasAccount (AccountId accountId)
ContactListFilters &setHasAccounts (const QList< AccountId > &accountId)
ContactListFilters &setHasAttribute (AttributeKind::Type present)
ContactListFilters &setHasAttribute (const QSet< AttributeKind::Type > &present)
ContactListFilters &setHasKindSubkind (const KindSubKindSpecifier present)
ContactListFilters &setHasKindSubkind (const QSet< KindSubKindSpecifier > &present)
ContactListFilters &setHasPhoto (bool hasPhoto)
ContactListFilters &setIncludeAttribute (AttributeKind::Type kind)
ContactListFilters &setIncludeAttributes (const QList< AttributeKind::Type > &kinds)
ContactListFilters &setIncludeGroups (bool value)
ContactListFilters &setIncludePhotos (bool value)
ContactListFilters &setIncludePostalAddress (bool value)
ContactListFilters &setIsFavourite (bool isFavourite)
ContactListFilters &setIsVideoChatContact (bool isVideoChatContact)
ContactListFilters &setLimit (int limit)
ContactListFilters &setOffset (int offset)
ContactListFilters &setShowSources (bool value)
ContactListFilters &setSortAndAnchorBy (const AnchorValueSpecifier &anchorValue)
ContactListFilters &setSortAndAnchorBy (const QList< AnchorValueSpecifier > &anchorValues)
ContactListFilters &setSortBy (SortColumn::Type column, SortOrder::Type order)
ContactListFilters &setSortBy (const SortSpecifier &sort)
ContactListFilters &setSortBy (const QList< SortSpecifier > &sorts)

Public Functions

ContactListFilters ()

Constructs a new ContactListFilters.

Since:

BlackBerry 10.0.0

ContactListFilters (

Copy constructor.

This function constructs a ContactListFilters containing exactly the same values as the provided ContactListFilters.

Parameters
copy

The ContactListFilters to be copied.

Since:

BlackBerry 10.0.0

~ContactListFilters ()

Destructor.

Since:

BlackBerry 10.0.0

ContactId anchorId ()

Retrieves the anchor ID of this ContactListFilters.

This function returns the anchor ID of the contact for the list of contacts that you receive by calling ContactService::contacts().

Return:

The anchor ID of this ContactListFilters.

Since:

BlackBerry 10.0.0

QVariantList contactIds ()

Retrieves the list of contact IDs that are associated with this ContactListFilters.

Return:

A list of contact IDs that are associated with this ContactListFilters.

Since:

BlackBerry 10.0.0

QVariantList excludeContacts ()

Retrieves the list of contact IDs that are excluded with this ContactListFilters.

Return:

A list of contact IDs that are excluded with this ContactListFilters.

Since:

BlackBerry 10.3.0

bool isFavourite ()

Indicates whether only favorite contacts are returned when using this ContactListFilters.

Return:

true if only favorite contacts are returned, false otherwise.

Since:

BlackBerry 10.0.0

bool isVideoChatContact ()

Indicates whether only video chat contacts are returned when using this ContactListFilters.

Return:

true if only video chat contacts are returned, false otherwise.

Since:

BlackBerry 10.0.0

int limit ()

Retrieves the result limit of this ContactListFilters.

This value represents the maximum number of results that are returned for the contact list.

Return:

The result limit of this ContactListFilters.

Since:

BlackBerry 10.0.0

int offset ()

retrieve the offset of this ContactListFilters

This value represent the place to start query from

Return:

The offset of this ContactListFilters

Since:

BlackBerry 10.0.0

ContactListFilters & operator= (

Assignment operator.

This operator copies all values from the provided ContactListFilters into this ContactListFilters.

Parameters
operand

The ContactListFilters from which to copy all values.

Return:

A ContactListFilters with all copied data

Since:

BlackBerry 10.0.0

ContactListFilters & setAnchorId (
  • ContactIdcontactId,
  • boolinclusive )

Sets the anchor ID and indicates how paging works in the returned contact list.

This function sets the anchor ID to the provided contact ID. If paging is set to inclusive (that is, the inclusive parameter is true), the contact with the specified contact ID is returned as the first contact. Otherwise, the first contact that's returned is the next logical contact in the list.

Parameters
contactId

The contact ID to set as the anchor ID.

inclusive

If true the contact with the specified contact ID is returned as the first contact in the list, if false the contact after the one with the specified contact ID is returned as the first contact.

Return:

A ContactListFilters with the provided anchor ID and paging behavior.

Since:

BlackBerry 10.0.0

ContactListFilters & setBelongsToGroups (
  • QList< GroupId >groupIds)

Filters the contact list to contacts that belong to the specified contact groups.

This is useful if you want to list group members.

Parameters
groupIds

the ids of the groups that the contacts returned must belong to.

Return:

A ContactListFilters with the specified groups filter set.

Since:

BlackBerry 10.3.0

ContactListFilters & setContactIds (
  • QList< int > &contactIds)

Sets the list of contact IDs that are returned when using this ContactListFilters.

Parameters
contactIds

The list of contact IDs that should be returned.

Return:

A ContactListFilters with the provided list of contact IDs.

Since:

BlackBerry 10.0.0

ContactListFilters & setExcludeAccount (
  • AccountIdaccountId)

Filters the returned contact list to contain only contacts where the source of the contact doesn't come from the provided account ID.

Parameters
accountId

The account ID to filter based on.

Return:

A ContactListFilters with the provided account ID filter.

Since:

BlackBerry 10.0.0

ContactListFilters & setExcludeAccount (
  • AccountIdaccountId,
  • boolincludeMergedContacts )

Filters the returned contact list to contain the contacts where the source of the contact doesn't come from the provided account ID.

Parameters
accountId

The account ID to filter based on.

includeMergedContacts

Indicates whether contacts that belong to more than one account should be included in the result if one of the source accounts is not excluded.

Return:

A ContactListFilters with the provided account ID filter.

Since:

BlackBerry 10.0.0

ContactListFilters & setExcludeAccounts (
  • const QList< AccountId > &accountId)

Filters the returned contact list to contain only contacts where the sources of the contact don't come from any of the provided account IDs.

Parameters
accountId

The set of account IDs to filter based on.

Return:

A ContactListFilters with the provided account ID filter.

Since:

BlackBerry 10.0.0

ContactListFilters & setExcludeAccounts (
  • const QList< AccountId > &accountId,
  • boolincludeMergedContacts )

Filters the returned contact list to contain the contacts where the sources of the contact don't come from any of the provided account IDs.

Parameters
accountId

The set of account IDs to filter based on.

includeMergedContacts

Indicates whether contacts that belong to more than one account should be included in the result if one of the source accounts is not excluded.

Return:

A ContactListFilters with the provided account ID filter.

Since:

BlackBerry 10.0.0

ContactListFilters & setExcludeContacts (
  • const QList< ContactId > &contactIds)

Sets the list of contact IDs that are excluded when using this ContactListFilters.

This function is mutually exclusive with setContactIds(). If setContactIds() was called with a list of Contact IDs, this setExcludeContacts() filter does nothing.

Parameters
contactIds

The list of contact IDs that should be excluded.

Return:

A ContactListFilters with the provided list of contact IDs.

Since:

BlackBerry 10.3.0

ContactListFilters & setHasAccount (
  • AccountIdaccountId)

Filters the returned contact list to contain only contacts where the source of the contact comes from the provided account ID.

Parameters
accountId

The account ID to filter based on.

Return:

A ContactListFilters with the provided account ID filter.

Since:

BlackBerry 10.0.0

ContactListFilters & setHasAccounts (
  • const QList< AccountId > &accountId)

Filters the returned contact list to contain only contacts where the sources of the contact come from any of the provided account IDs.

Parameters
accountId

The set of account IDs to filter based on.

Return:

A ContactListFilters with the provided account ID filter.

Since:

BlackBerry 10.0.0

ContactListFilters & setHasAttribute (

Filters the returned contact list to contain only contacts with the provided attribute kind.

Parameters
present

The attribute kind to filter based on.

Return:

A ContactListFilters with the provided attribute kind filter.

Since:

BlackBerry 10.0.0

ContactListFilters & setHasAttribute (

Filters the returned contact list to contain only contacts with the provided set of attribute kinds.

Parameters
present

The set of attribute kinds to filter based on.

Return:

A ContactListFilters with the provided attribute kind filter.

Since:

BlackBerry 10.0.0

ContactListFilters & setHasKindSubkind (

Filters the returned contact list to contain only contacts with the provided kind/sub-kind combination.

Parameters
present

The kind/sub-kind combination to filter based on.

Return:

A ContactListFilters with the provided kind/sub-kind combination filter.

Since:

BlackBerry 10.0.0

ContactListFilters & setHasKindSubkind (

Filters the returned contact list to contain only contacts with the provided set of kind/sub-kind combinations.

Parameters
present

The set of kind/sub-kind combinations to filter based on.

Return:

A ContactListFilters with the provided kind/sub-kind combination filter.

Since:

BlackBerry 10.0.0

ContactListFilters & setHasPhoto (
  • boolhasPhoto)

This function filters the returned contact list to contain only contacts with a display picture.

Parameters
hasPhoto

If true, only contacts with a display picture are included in the returned contact list. If false, this filter does nothing.

Return:

A ContactListFilters with the provided hasPhoto filter.

Since:

BlackBerry 10.3.0

ContactListFilters & setIncludeAttribute (

Filters the returned contact list to contain only contacts with the provided attribute kind.

This function is mutually exclusive with setIncludeAttributes().

Parameters
kind

The attribute kind to filter based on.

Return:

A ContactListFilter with the provided attribute kind filter.

Since:

BlackBerry 10.0.0

ContactListFilters & setIncludeAttributes (

Filters the returned contact list to contain only contacts with the provided attribute kinds.

This function is mutually exclusive with setIncludeAttribute().

Parameters
kinds

The set of attribute kinds to filter based on.

Return:

A ContactListFilter with the provided attribute kinds filter.

Since:

BlackBerry 10.0.0

ContactListFilters & setIncludeGroups (
  • boolvalue)

Sets whether contact groups should be included in the results or not.

If set to true, groups will be returned as a part of the results.

Parameters
value

True if groups should be included, false otherwise.

Return:

A ContactListFilters with the specified groups included mode.

Since:

BlackBerry 10.3.0

ContactListFilters & setIncludePhotos (
  • boolvalue)

Sets whether to include photos in the returned contact list.

If set to true, the primary photos that are associated with the contacts are returned. The default value is false.

Parameters
value

If true photos are included in the returned contact list, if false photos are not included in the returned contact list.

Return:

A ContactListFilters with the provided indication of whether to include photos in the returned contact list.

Since:

BlackBerry 10.0.0

ContactListFilters & setIncludePostalAddress (
  • boolvalue)

Sets whether to include postal addresses in the returned contact list.

This function specifies whether postal addresses are included in the response, if these addresses are available for the contacts.

Parameters
value

If true postal addresses are included in the returned contact list, if false postal addresses are not included in the returned contact list.

Return:

A ContactListFilters with the provided indication of whether to include postal addresses in the returned contact list.

Since:

BlackBerry 10.0.0

ContactListFilters & setIsFavourite (
  • boolisFavourite)

Sets whether only favorite contacts are returned when using this ContactListFilters.

Parameters
isFavourite

If true only favorite contacts are returned, if false all contacts are returned.

Return:

A ContactListFilters with the provided indication of whether favorite contacts are returned.

Since:

BlackBerry 10.0.0

ContactListFilters & setIsVideoChatContact (
  • boolisVideoChatContact)

Sets whether only video chat contacts are returned when using this ContactListFilters.

Parameters
isVideoChatContact

If true only video chat contacts are returned, if false all contacts are returned.

Return:

A ContactListFilters with the provided indication of whether video chat contacts are returned.

Since:

BlackBerry 10.0.0

ContactListFilters & setLimit (
  • intlimit)

Sets the result limit of this ContactListFilters.

This value represents the maximum number of results that are returned for the contact list. The default value is 20 results. If you specify 0, it will return all results. For reasonable performance specify limit as 100 or 200.

Parameters
limit

The maximum number of results that are returned.

Return:

A ContactListFilters with the provided result limit.

Since:

BlackBerry 10.0.0

ContactListFilters & setOffset (
  • intoffset)

Set offset to start query of this ContactListFilters.

@ details This value represents the place to start query from

Parameters
offset

The offset number to start searching from

Return:

A ContactListFilters with the provided offset

Since:

BlackBerry 10.0.0

ContactListFilters & setShowSources (
  • boolvalue)

Sets whether to include account IDs for content sources in the search results.

If set to true, contacts that are returned include a list of account IDs that are the sources of content for the contacts.

Parameters
value

If true account IDs are included in the search results, if false account IDs are not included in the search results.

Return:

A ContactListFilters with the the provided indication of whether to include source accounts list

Since:

BlackBerry 10.3.0

ContactListFilters & setSortAndAnchorBy (

Sets the sort column, sort order, and anchor value of this ContactListFilters using an AnchorValueSpecifier.

This function specifies a sort column and order, and offsets the response by a certain anchor value. When anchoring by value, contacts matching the values are included in the response.

Parameters
anchorValue

The sort column, sort order, and anchor value to set, represented by a AnchorValueSpecifier object.

Return:

A ContactListFilters with the provided sort column, sort order, and anchor value.

Since:

BlackBerry 10.0.0

ContactListFilters & setSortAndAnchorBy (

Sets the sort columns, sort orders, and anchor values of this ContactListFilters using a list of AnchorValueSpecifier objects.

This function specifies a set of sort columns and orders, and offsets the response by anchor values. When anchoring by value, contacts matching the values are included in the response.

Parameters
anchorValues

The set of sort columns, sort orders, and anchor values to set, represented by AnchorValueSpecifier objects.

Return:

A ContactListFilters with the provided sort columns, sort orders, and anchor values.

Since:

BlackBerry 10.0.0

ContactListFilters & setSortBy (

Sets the sort column and sort order of this ContactListFilters.

The default sort column is FirstName and the default sort order is ascending.

Parameters
column

The sort column to set.

order

The sort order to set.

Return:

A ContactListFilters with the provided sort column and sort order.

Since:

BlackBerry 10.0.0

ContactListFilters & setSortBy (

Sets the sort column and sort order of this ContactListFilters using a SortSpecifier.

The default sort column is FirstName and the default sort order is ascending.

Parameters
sort

The sort column and sort order pair to set, represented by a SortSpecifier.

Return:

A ContactListFilters with the provided sort column and sort order.

Since:

BlackBerry 10.0.0

ContactListFilters & setSortBy (

Sets the sort columns and sort orders of this ContactListFilters using a list of SortSpecifier objects.

The default sort column is FirstName and the default sort order is ascending. The returned contact list is first sorted according to the first SortSpecifier in the provided list, then by the second SortSpecifier in the list, and so on.

Parameters
sorts

The set of sort column and sort order pairs to set, represented by SortSpecifier objects.

Return:

A ContactListFilters with the provided sort columns and sort orders.

Since:

BlackBerry 10.0.0

Last modified: 2014-09-29



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

comments powered by Disqus