Phonebook 2 UI Utilities API Specification Document

Changes in Phonebook 2 UI Services API documentation

1.0 04.01.2007 Approved

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:

  • Activating a view based on the received view state information

  • Switching into a new view by using the view state information

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
  • CVPbkContactmanager
  • DoActivateL()
  • 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
  • ActivateViewL
  • ActivateViewL()
  • EPbk2ContactInfoViewId
  • KPbk2UID3
  • MVPbkContactLink
  • iContactLink
  • iCurrentFieldIndex

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

Glossary

Abbreviations

None.

Definitions

None.

References

None.