Using Phonebook 2 Presentation API
Phonebook 2 Presentation API
needs instances of classes
CVPbkContactManager and CPbk2SortOrderManager in
order to provide its services.
// Define the contact
DB uri // _LIT( KCntDbUri, "cntdb://contacts.cdb" ); // Create an URI list
// CVPbkContactStoreUriArray* uriList = CVPbkContactStoreUriArray::NewLC();
uriList->AppendL( TVPbkContactStoreUriPtr( KCntDbUri ) ); // Instantiate
CVPbkContactManager // Assumption: this class has access to a File Server
session instance, iFs // CVPbkContactManager* contactManager = CVPbkContactManager::NewL(
*uriList, &iFs ); // Clean up temporary variables // CleanupStack::PopAndDestroy(
uriList ); // Instantiate CPbk2SortOrderManager // CPbk2SortOrderManager*
sortOrderManager = CPbk2SortOrderManager::NewL( contactManager->FieldTypes(),
&iFs );
Formatting a contact title
An instance of a class implementing the
MPbk2ContactNameFormatter interface
can be used to get and format the title fields of a contact. The contact
name formatter defines how the contact title is presented to the end-user.
The formatter can also be used to check whether a given field can be used
a the contact title or get the default title for a contact that does not have
a title yet.
The examples below demonstrate three ways for creating
a contact name formatter. The first method uses a default contact title given
by the system. The second method can be used to override the default contact
title proposed by the system. The third method can be used to override the
system default for fields that are accepted as a contact title.
//
Method one: use a default contact title given by the system. // Call the
formatter factory with proper parameters. // MPbk2ContactNameFormatter* nameFormatterThree
= Pbk2ContactNameFormatterFactory::CreateL ( contactManager->FieldTypes(),
*sortOrderManager, &iFs ); // Method two: load the default contact title
from a resource file. // Load the default title from a resource file // HBufC*
unnamedBuf = StringLoader::LoadLC( R_QTN_PHOB_UNNAMED ); TPtr unnamed = unnamedBuf->Des();
// Call the formatter factory with the buffer as a parameter // MPbk2ContactNameFormatter*
nameFormatterOne = Pbk2ContactNameFormatterFactory::CreateL ( unnamed, contactManager->FieldTypes(),
*sortOrderManager, &iFs ); // Clean temporary resources
// CleanupStack::PopAndDestroy( unnamedBuf ); // Method three: // - Load
the default contact title from a resource file. // - Use a resource file to
select which contact fields can be used as a title. // Load the default title
from a resource file // HBufC* unnamedBuf = StringLoader::LoadLC( R_QTN_PHOB_UNNAMED
); TResourceReader reader; // Create a resource reader pointing to the VPBK_FIELD_TYPE_SELECTOR
structure // CCoeEnv::Static()->CreateResourceReaderLC( reader, R_TITLE_FIELD_SELECTOR
); // Call the formatter factory with the buffer and the resource reader
parameters // MPbk2ContactNameFormatter* nameFormatterTwo = Pbk2ContactNameFormatterFactory::CreateL
( contactManager->FieldTypes(), *sortOrderManager, reader, unnamedBuf, &iFs
); // Clean temporary resources // CleanupStack::PopAndDestroy( &reader
); CleanupStack::PopAndDestroy( unnamedBuf );
After
creating an
MPbk2ContactNameFormatter instance, it can be
used to get the length of the contact title or the title text. If there is
no data suitable as a contact title, the default title will be returned.
Related APIs
MPbk2ContactNameFormatter
Formatting contact fields
Phonebook 2
Presentation API provides several classes to be used when formatting contact
field information. Each field, such as a telephone number or an address, can
store information related to formatting in the UI.
When formatting contact
fields, the list of formatting rules must be asked from
Pbk2FieldPropertiesFactory.
After that the MPbk2FieldPropertyArray can be used to find
formatting rules for a given field type. The interface MPbk2FieldProperty
provides several methods needed in the contact formatting.
The code
clips below demonstrate the usage of these three classes.
//
Create the list of contact field types // MPbk2FieldPropertyArray* fieldProperties
= Pbk2FieldPropertiesFactory::CreateLC( contactManager->FieldTypes(),
contactManager->FsSession() ); // Assumption: the member variable iField
is a pointer to a MVPbkFieldType object // Find a given contact field
type // MPbk2FieldProperty* property = fieldProperties->FindProperty( *iField
); // Read the formatting information of the field type // TInt fieldLen
= property->MaxLength(); TPbk2FieldEditMode editMode = property->EditMode();
TPbk2FieldDefaultCase defaultCase = property->DefaultCase(); ... // Use the
formatting information in creating a contact view ... // Clean temporary
resources // CleanupStack::PopAndDestroy( fieldProperties );
Related APIs
MPbk2FieldPropertyMPbk2FieldPropertyArrayPbk2FieldPropertiesFactory
Managing the sorting order of a contact view
Class
CPbk2SortOrderManager is
used to manage the sorting order of a contact view. A contact view can be
ordered using one of the options defined in TPbk2NameDisplayOrder.
The order defines which one of 'Last name' or 'First name' is defined first
and whether there is any separator mark. By using this class, clients can
also retrieve the current name display/sorting order and change it.
When
using the class, a contact view needs to be assigned using the
SetContactViewL() method.
After this, the manager can get the sort order of the contact view or set
the name displaying order.
For more information about creating a
CPbk2SortOrderManager instance,
please refer to the code clips at the beginning part of this section. For
more information about the CVPbkContactViewDefinition refer
to the Virtual Phonebook View Definition API Specification.
//
Instantiate CPbk2SortOrderManager // ... // Create a MVPbkContactViewBase
object // Constructed from a VPBK_CONTACT_VIEW resource structure // TResourceReader
reader; CEikonEnv::Static()->CreateResourceReaderLC( reader, R_CONTACT_VIEW_STRUCTURE
); // Instantiate CVPbkContactViewDefinition // CVPbkContactViewDefinition*
def = CVPbkContactViewDefinition::NewL( reader ); CleanupStack::PopAndDestroy(
&reader ); CleanupStack::PushL( def ); // Assumption: class CTestContactViewObserver
is derived from MVPbkContactViewObserver // Instantiate CTestContactViewObserver
// CTestContactViewObserver* contactViewObserver = new ( ELeave ) CTestContactViewObserver;
CleanupStack::PushL( contactViewObserver ); // Get the contact view // MVPbkContactViewBase*
allContactsView = contactManager->CreateContactViewLC( *contactViewObserver,
*def, contactManager->FieldTypes() ); // Set the view to the sort manager
// sortOrderManager->SetContactViewL( *allContactsView ); // Get the current
sort order. // The method returns a list of field types indicating the sorting
order. // MVPbkFieldTypeList& fieldTypeList = sortOrderManager->SortOrder();
Setting
the name displaying order for the managed contact view. If the contact view
detects that the name displaying order has been changed, the
MPbk2SortOrderObserver::SortOrderChanged event
will be called.
// Set the name display order // sortOrderManager->SetNameDisplayOrderL(
EPbk2NameDisplayOrderLastNameSeparatorFirstName ); // Get the current name
display order // TPbk2NameDisplayOrder nameDisplayOrder = sortOrderManager->NameDisplayOrder();
Related APIs
CPbk2SortOrderManagerCVPbkContactViewDefinitionMPbk2SortOrderObserver::SortOrderChangedSetContactViewL()TPbk2NameDisplayOrder
Creating Phonebook Icons
Class
TPbk2IconId provides
services for creating and comparing Phonebook icons. Phonebook icons can be
used in a contact view to indicate the type of a contact field. Comparing
is sometimes needed when finding a specific icon from an icon container.
TPbk2IconId represents
an icon and there are two alternative methods for instantiating a TPbk2IconId object.
The first one reads the icon information from a resource file defined by the
PHONEBOOK2_ICON_ID structure and the second one creates the icon based on
the owner UID and icon ID. The following examples demonstrate the two methods.
//
Method one. Construct the instance from a PHONEBOOK2_ICON_ID resource structure
// TResourceReader resourceReader; CEikonEnv::Static()->CreateResourceReaderLC(
resourceReader, R_PBK2_ICON_ID ); TPbk2IconId pbk2IconIdOne = TPbk2IconId(
resourceReader ); CleanupStack::PopAndDestroy(); // resourceReader // Method
Two. Construct the instance by giving the owner UID and the icon ID as parameters
// const TInt KExampleIconID = 3; TPbk2IconId pbk2IconIdTwo( TUid::Uid( KPbk2UID3
), KExampleIconID ); // Returns true if the icon IDs are the same // TBool
isSame = ( pbk2IconIdTwo == TPbk2IconId( pbk2IconIdOne ) );
Related APIs
Error handling
The methods leave in case
of an error situation. Normal error handling practises should be used, e.g.
using cleanup stack and
TRAP harness.
Related APIs
Extensions to the API
Currently there
are 2 extensions:
MPbk2FieldProperty2 and MPbk2FieldPropertyArray2 which
are extensions for MPbk2FieldProperty and MPbk2FieldPropertyArray correspondingly. MPbk2FieldProperty2 can be accessed by calling MPbk2FieldProperty::FieldPropertyExtension() providing KMPbk2FieldPropertyExtension2Uid as a parameter, see documentation in header MPbk2FieldProperty.h.
See below a code example:
MPbk2FieldProperty2* fieldPropertyExtension
= reinterpret_cast<MPbk2FieldProperty2*>( const_cast<MPbk2FieldProperty&>(
iFieldProperty ).FieldPropertyExtension( KMPbk2FieldPropertyExtension2Uid
) );
It is client's responsibility then to check
that returned pointer is not a NULL. In a similar way,
MPbk2FieldPropertyArray2 can
be used:
MPbk2FieldPropertyArray2* fieldPropertyExtension
= reinterpret_cast<MPbk2FieldPropertyArray2*>( const_cast<MPbk2FieldPropertyArray&>(
iFieldPropertiesArray ).FieldPropertyArrayExtension( KMPbk2FieldPropertyArrayExtension2Uid
) );
Related APIs
KMPbk2FieldPropertyExtension2UidMPbk2FieldPropertyMPbk2FieldProperty.hMPbk2FieldProperty2MPbk2FieldProperty::FieldPropertyExtension()MPbk2FieldPropertyArrayMPbk2FieldPropertyArray2
Related APIs
CPbk2SortOrderManagerCVPbkContactManager