Phonebook 2 Presentation API Specification Document

Changes in Phonebook 2 Presentation API documentation

Version Date Status Description

1.0

04.12.2006

Approved

Changes in Phonebook 2 Presentation API

Version Description

1.0

First version.

Purpose

The purpose of Phonebook 2 Presentation API is to define how the contacts are presented to the end-user. Examples of the presentation options are contact name format and display order.

API description

Phonebook 2 Presentation API implements the formatting functionality specifying how a client needs to display the information to the end-user. This API contains seven classes providing a method call interface.

Pbk2ContactNameFormatterFactory is used to create and return an MPbk2ContactNameFormatter instance. Class MPbk2ContactNameFormatter provides interfaces used to get the length of the contact title or the title text. Pbk2FieldPropertiesFactory is used to create and return an MPbk2FieldPropertyArray instance. The interface class MPbk2FieldPropertyArray can be used to find formatting rules for a given field type. The interface MPbk2FieldProperty provides several methods needed in the contact formatting. Class TPbk2IconId is for Phonebook 2 icon identification. CPbk2SortOrderManager is a Phonebook 2 sort order manager for contact view. Pbk2FieldProperty.hrh provides definitions for all Phonebook 2 contact fields.

Use cases

The most common use cases of Phonebook 2 Presentation API are the following:

  • Formatting a contact title

  • Formatting contact fields

  • Managing the sorting order of a contact view

  • Creating Phonebook 2 Icons

Related APIs
  • CPbk2SortOrderManager
  • MPbk2ContactNameFormatter
  • MPbk2FieldProperty
  • MPbk2FieldPropertyArray
  • Pbk2ContactNameFormatterFactory
  • Pbk2FieldPropertiesFactory
  • TPbk2IconId

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
  • MPbk2FieldProperty
  • MPbk2FieldPropertyArray
  • Pbk2FieldPropertiesFactory

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
  • CPbk2SortOrderManager
  • CVPbkContactViewDefinition
  • MPbk2SortOrderObserver::SortOrderChanged
  • SetContactViewL()
  • 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
  • TPbk2IconId

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
  • TRAP

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
  • KMPbk2FieldPropertyExtension2Uid
  • MPbk2FieldProperty
  • MPbk2FieldProperty.h
  • MPbk2FieldProperty2
  • MPbk2FieldProperty::FieldPropertyExtension()
  • MPbk2FieldPropertyArray
  • MPbk2FieldPropertyArray2
Related APIs
  • CPbk2SortOrderManager
  • CVPbkContactManager

Glossary

Abbreviations

None.

Definitions

None.

References

References

1. Virtual Phonebook View Definition API Specification Document