ContactBuilder

Since: BlackBerry 10.0.0

#include <bb/pim/contacts/ContactBuilder>

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

The ContactBuilder class lets you create, and specify properties for, a new Contact or edit an existing Contact.

You can use this class to set properties, such as attributes, a postal address, or a photo, for a Contact. This class uses the builder pattern to create a Contact and set its properties. Each of the functions returns a self reference to the builder, allowing you to chain function calls together. For example, here's how to create a Contact with two attributes using the builder pattern:

Contact createARandomContact()
{
    ContactService *service = new ContactService();
    ContactBuilder builder;
    builder.addAttribute(ContactAttributeBuilder()
                              .setKind(AttributeKind::Name)
                              .setSubKind(AttributeSubKind::NameGiven)
                              .setValue(QString("Random" + QString::number(
                                                    std::rand()))));
    builder.addAttribute(ContactAttributeBuilder()
                              .setKind(AttributeKind::Name)
                              .setSubKind(AttributeSubKind::NameNickname)
                              .setValue("Bobo The Clown"));
    return service->createContact(builder, false);
}

Any changes that you make to a Contact using this builder are temporary until the changes are persisted by using the ContactService.


Overview

Public Functions Index

ContactBuilder ()
ContactBuilder (Contact &contact)
ContactBuilder (const ContactBuilder &copy)
~ContactBuilder ()
ContactBuilder &addAttribute (const ContactAttribute &attrib)
ContactBuilder &addFromContact (const Contact &c)
ContactBuilder &addPhoto (const ContactPhoto &photo, bool isPrimary=true)
ContactBuilder &addPostalAddress (const ContactPostalAddress &addr)
ContactBuilder &deleteAttribute (const ContactAttribute &attr)
ContactBuilder &deletePhoto (QString origPhotoFilepath)
ContactBuilder &deletePhoto (const ContactPhoto &photo)
ContactBuilder &deletePostalAddress (const ContactPostalAddress &addr)
operator Contact ()
ContactBuilder &operator= (const ContactBuilder &cb)
ContactBuilder &setFavorite (bool isFavorite)
ContactBuilder &setNotes (const QString &notes)
ContactBuilder &setPrimaryPhoto (const ContactPhoto &photo)
boolupdateContact (const Contact &existingContact, const Contact &newContact)

Public Functions

ContactBuilder ()

Constructs a new ContactBuilder.

Since:

BlackBerry 10.0.0

ContactBuilder (

Edits the provided Contact.

You can use this function to edit the properties of an existing Contact, as an alternative to calling Contact::edit().

Parameters
contact

The Contact to edit.

See also:

Contact::edit()

Since:

BlackBerry 10.0.0

ContactBuilder (

Copy constructor.

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

Parameters
copy

The ContactBuilder to be copied.

Since:

BlackBerry 10.0.0

~ContactBuilder ()

Destructor.

Since:

BlackBerry 10.0.0

ContactBuilder & addAttribute (

Adds an attribute to the contact.

Attributes are represented by the ContactAttribute class. You can use a ContactAttributeBuilder to easily create a ContactAttribute to add to a contact.

Parameters
attrib

The ContactAttribute to add.

Return:

A ContactBuilder with the provided ContactAttribute.

Since:

BlackBerry 10.0.0

ContactBuilder & addFromContact (

Copies information from the provided contact into this contact.

This function copies externally visible data from the Contact that is passed in. None of the IDs are copied.

Parameters
c

The Contact to copy information from.

Return:

A ContactBuilder with the information from the provided Contact.

Since:

BlackBerry 10.0.0

ContactBuilder & addPhoto (

Adds a photo to the contact.

Photos are represented by the ContactPhoto class. You can use a ContactPhotoBuilder to easily create a ContactPhoto to add to a contact.

Parameters
photo

The ContactPhoto to add.

isPrimary

If true this photo is the primary photo for the contact, if false this photo is not the primary photo for the contact.

Return:

A ContactBuilder with the provided ContactPhoto.

Since:

BlackBerry 10.0.0

ContactBuilder & addPostalAddress (

Adds a postal address to the contact.

Postal addresses are represented by the ContactPostalAddress class. You can use a ContactPostalAddressBuilder to easily create a ContactPostalAddress to add to a contact.

Parameters
addr

The ContactPostalAddress to add.

Return:

A ContactBuilder with the provided ContactPostalAddress.

Since:

BlackBerry 10.0.0

ContactBuilder & deleteAttribute (

Deletes the provided attribute from the contact.

The provided ContactAttribute must be one of the attributes of the contact. Otherwise, this function does nothing.

Parameters
attr

The ContactAttribute to delete.

Return:

A ContactBuilder with the provided ContactAttribute deleted.

Since:

BlackBerry 10.0.0

ContactBuilder & deletePhoto (

Deletes the photo with the provided file path from the contact.

This function deletes a ContactPhoto from the contact, where the original file path of the ContactPhoto matches the provided parameter. The ContactPhoto with the provided file path must be part of the contact. Otherwise, this function does nothing.

Parameters
origPhotoFilepath

The file path of the ContactPhoto to delete.

Return:

A ContactBuilder with the provided ContactPhoto deleted.

Since:

BlackBerry 10.0.0

ContactBuilder & deletePhoto (

Deletes the provided photo from the contact.

The provided ContactPhoto must be part of the contact. Otherwise, this function does nothing.

Parameters
photo

The ContactPhoto to delete.

Return:

A ContactBuilder with the provided ContactPhoto deleted.

Since:

BlackBerry 10.0.0

ContactBuilder & deletePostalAddress (

Deletes the provided postal address from the contact.

The provided ContactPostalAddress must be part of the contact. Otherwise, this function does nothing.

Parameters
addr

The ContactPostalAddress to delete.

Return:

A ContactBuilder with the provided ContactPostalAddress deleted.

Since:

BlackBerry 10.0.0

operator Contact ()

Cast operator.

This operator casts an object to the Contact type.

Since:

BlackBerry 10.0.0

ContactBuilder & operator= (

Assignment operator.

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

Parameters
cb

The ContactBuilder from which to copy all values.

Return:

A ContactBuilder with all copied data

Since:

BlackBerry 10.0.0

ContactBuilder & setFavorite (
  • boolisFavorite)

Sets whether the contact is a favorite contact.

Favorite contacts are displayed in the favorites grid in the Contacts application.

Parameters
isFavorite

If true the contact is a favorite contact, if false the contact is not a favorite contact.

Return:

A ContactBuilder with the provided indication of whether the contact is a favorite contact.

Since:

BlackBerry 10.0.0

ContactBuilder & setNotes (

Sets notes for the contact.

There should be only one note attribute per contact.

Parameters
notes

The notes to set.

Return:

A ContactBuilder with the provided notes.

Since:

BlackBerry 10.0.0

ContactBuilder & setPrimaryPhoto (

Sets an existing contact photo as the primary photo for the contact.

There should be only one primary photo per contact.

Parameters
photo

The photo to set.

Return:

A ContactBuilder with the provided primary photo.

Since:

BlackBerry 10.3.0

bool updateContact (

Updates any new attributes that exist in one contact but not in another contact.

This function adds any attributes that exist in one of the Contact parameters (newContact) but don't exist in the other Contact parameter (existingContact). You can use this function to provide new updates for a contact.

Parameters
existingContact

The existing contact.

newContact

The contact with possibly new attributes.

Return:

true if any attributes were added, false otherwise.

Since:

BlackBerry 10.1.0

Last modified: 2014-06-24



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

comments powered by Disqus