Phonebook
2 UI Utilities API Specification Document
Changes
in Phonebook 2 UI Services API documentation
Changes in Phonebook 2 UI Services API
Purpose
The
Purpose of Phonebook 2 UI Utilities API is to encapsulate the state information
of a Phonebook 2 view, for example the focus position or marked items. The
encapsulated state information can then be easily stored or transferred as
a parameter.
API description
Phonebook
2 UI Utilities API is a library API. It provides an easy way to encapsulate
Phonebook 2 view state information.
Use
cases
The typical use cases of Phonebook 2 UI Utilities API
are the following:
Using
Phonebook 2 UI Utilities API
The two examples below highlight
the usage of the UI Utilities API.
Activating
a view based on the received view state information
A view
is activated in the view’s
DoActivateL() method that takes
two custom parameters and the previous view ID. When using the UI Utilities
API, the first custom parameter identifies the message type and the second
parameter holds the view state information. The example below demonstrates
how to use this API to activate a view.
#include
<Pbk2UID.h> // Phonebook 2 UIDs #include <CPbk2ViewState.h> //
The view state class, remember also the Pbk2CommonUI.lib void CExampleAppView::DoActivateL(
const TVwsViewId& aPrevViewId, TUid aCustomMessageId, const TDesC8&
aCustomMessage ) { CPbk2ViewState* viewState = NULL; // Check message
type // if ( aCustomMessageId == TUid::Uid( KPbkViewStateUid ) )
{ // Transform old data into a Phonebook 2 view state
// CPbk2ViewStateTransformer* transformer = CPbk2ViewStateTransformer::NewLC(
iContactManager ); viewState = transformer->TransformLegacyViewStateToPbk2ViewStateLC(
aCustomMessage ); CleanupStack::Pop( viewState ); CleanupStack::PopAndDestroy(
transformer ); } else if ( aCustomMessageId == CPbk2ViewState::Uid() )
{ // Create a Phonebook 2 view state instance from the aCustomMessage
// viewState = CPbk2ViewState::NewL( aCustomMessage ); ... } else
{ // The received parameter type is not valid // User::Leave( KErrArgument
); } // Use the view state information to activate the view correctly,
// e.g. get the index of the focused field // TInt focusedFiledIndex
= viewState->FocusedFieldIndex(); ... }
In
this example,
iContactManager is an instance of the class CVPbkContactmanager.
The example assumes that the instance has been initialized.
Related APIs
CVPbkContactmanagerDoActivateL()iContactManager
Switching into a new view by using the view state information
The
ActivateViewL method
can be used to switch into a new view. Phonebook 2 UI Utilities API can be
used to transfer the required view state information as a parameter of this
method.
First, a view state instance needs to be created. Then, the
specified view state attributes can be set. Finally, the instance is packaged
into a buffer and passed as a parameter for the
ActivateViewL() method.
The example below demonstrates this sequence in code.
#include
<Pbk2UID.h> // Phonebook 2 UIDs #include <CPbk2ViewState.h> //
The view state class, remember also the Pbk2CommonUI.lib ... // Construct
a CPbk2ViewState instance. // CPbk2ViewState* pbk2ViewParam = CPbk2ViewState::NewLC();
// Set correct states of the instance. // pbk2ViewParam->SetFocusedContact(
iContactLink ); pbk2ViewParam->SetFocusedFieldIndex( iCurrentFieldIndex );
// Encapsulate the view state information into a buffer // HBufC8* paramBuf
= pbk2ViewParam->PackLC(); // Create a view id pointing to Phonebook 2 application's
Contact Info View // const TVwsViewId viewId( KPbk2UID3, EPbk2ContactInfoViewId
); // Activate the view // AppUi()->ActivateViewL( viewId, CPbk2ViewState::Uid(),
*paramBuf ); // Cleanup // CleanupStack::PopAndDestroy( paramBuf ); CleanupStack::PopAndDestroy(
pbk2ViewParam );
The example above assumes that
the member variable
iContactLink holds a pointer to a MVPbkContactLink and
the iCurrentFieldIndex holds the index of the currently selected
contact field. In the example, KPbk2UID3 is the Application
UID of Phonebook 2 (from Pbk2UID.h) and the EPbk2ContactInfoViewId
is the ID of Contact Info View (from Pbk2ViewId.hrh)
Related APIs
ActivateViewLActivateViewL()EPbk2ContactInfoViewIdKPbk2UID3MVPbkContactLinkiContactLinkiCurrentFieldIndex
Error handling
Some methods may leave,
for example if running out of memory. Normal error handling practices should
be used, including using cleanup stack and
TRAP harness.
Related APIs