Using Standard Application Views

The Avkon View-Switching Architecture is the Series 60 Application Framework that enables view switching across applications. As described in Chapter 4, for an application to use the view architecture, the main user interface class, ( AppUi ), must be derived from CAknViewAppUi , and all views must be derived from CAknView .

The design of view-switching applications is described in detail in Chapter 4. Here you can see how to use the views that are made available by some of the key applications in Series 60 devices. The code presented in this section is taken from the ViewManager example project.

To activate an external application's view you use CCoeAppUi::ActivateViewL() , which will have been inherited from CAknViewAppUi . The function ActivateViewL() has two overloaded forms:

[View full width]

 
 [View full width] 
 void ActivateViewL(const TVwsViewId& aViewId); void ActivateViewL(const TVwsViewId& aViewId, TUid aCustomMessageId, const TDesC8&  aCustomMessage); 

The TVwsViewId class is constructed using the UID of the application to switch to, and the UID of the view required within the application. If an application wishes to allow other applications to switch to any of its views, it should export the required UID s in a header file.

The second form of ActivateViewL() has two further parameters allowing custom-defined messages to be passed to the view being activated. The messages are passed to the view's DoActivateL() method. In this way, a view can take an action as it is being activated ”for example, a specific dialog pane could be displayed.

Phonebook View Switching

The Phonebook application (aka Contacts) has three main views: contacts view, groups view and a focused contact view. Note that to successfully switch to the group view or focused contact view from your application, it may be necessary for the Phonebook application to already be running in the background. To switch to the contacts view, you can use:

 const TUid KPhoneBookUid = { 0x101f4cce }; //from PbkUID.h ... const TUid KPhoneBookContactViewUid = { 1 }; ActivateViewL(TVwsViewId(KPhoneBookUid, KPhoneBookContactsViewUid)); 

To switch to the groups view, you can use:

 const TUid KPhoneBookGroupViewUid = { 2 }; ActivateViewL(TVwsViewId(KPhoneBookUid, KPhoneBookGroupsViewUid)); 

The focused contact view displays a specified contact. In order to switch to this view you need to use ActivateViewL() with three parameters. The phonebook API provides a helper class called CPbkViewState for use with this version of ActivateViewL() . To switch to the focused contact view, first construct a CPbkViewState object, and then set the ID and index of the contact and the field you want to focus on:

 CPbkViewState* pbkViewParam = CPbkViewState::NewLC(); // First contact pbkViewParam->SetFocusedContactId(0); pbkViewParam->SetFocusedFieldIndex(3); 

To create a descriptor of the required format use CPbkViewState::PackLC() and pass it to ActivateViewL() .

 HBufC8* paramBuf = pbkViewParam->PackLC(); const TUid KPhoneBookUid = { 0x101f4cce }; //from PbkUID.h const TUid KPhoneBookFocusedViewUid = { 4 }; const TVwsViewId viewId(KPhoneBookUid, KPhoneBookFocusedViewUid); // Activate the view ActivateViewL(viewId, CPbkViewState::Uid(), *paramBuf); 

Not all application APIs provide a helper class to assist in the creation of a message to pass into ActivateViewL() .

To create a descriptor to pass to an application without using a helper class, you need to know the format the descriptor needs to take. For the Phonebook application, this information can be found in CPbkViewState.h .

One way to write binary data to a descriptor is by using RDesWriteStream , and once created you can pass the descriptor to ActivateViewL() in the usual way.

 TBuf8<16> param; RDesWriteStream stream(param); stream.PushL(); stream.WriteInt8L(1);  // opcode EFocusedContactId // Contact ID of last contact stream.WriteInt32L(numberOfContacts - 1); stream.WriteInt8L(4);   // opcode EFocusedFieldIndex stream.WriteInt32L(3);  // field index 3 stream.CommitL(); CleanupStack::PopAndDestroy();  // stream 

Using RDesWriteStream rather than a helper class, although less straightforward, has the advantage of there being no dependency on CPbkViewState.h and PbkView.lib at compile time or PbkView.dll at runtime.

Calendar View Switching

The Calendar (aka Agenda) application does not take any messages to allow you to specify a particular date to switch to. However, using ActivateViewL() with only one parameter, you can switch to the month, week, or day view.

If the Calendar application is not already running in the background when you switch views, the view shown by Calendar will probably default to the day view for the current date. Even if you specify the month or week view, it will probably be displayed only briefly , before the day view is then displayed. This behavior is not as might be expected, but it has been observed on Series 60 1.x and 2.x devices and emulators.

If Calendar is currently running, and you switch to one of its views, the correct view will be shown, and the date displayed will be the last date that was selected by the user.

 const TUid KCalendarUid = { 0x10005901 }; // 0x01 Month view // 0x02 Week view // 0x03 Day view const TUidKCalendarMonthViewUid = { 0x01 }; ActivateViewL(TVwsViewId(KCalendarUid, KCalendarMonthViewUid)); 

While the Calendar application does not take any messages, the entries are accessible via the agenda model; see the subsection entitled, Calendar Engine Access later in this chapter.

Camera View Switching

To switch to a Camera view use:

 const TUid KCameraUid = { 0x1000593F }; // 0x01  standby mode // 0x02  viewfinder mode // 0x04  Name base, and Quality settings const TUid KViewFinderModeUid = { 0x02 }; ActivateViewL(TVwsViewId(KCameraUid, KViewFinderModeUid)); 

Like the Calendar application, the Camera application does not take any messages.

Note that on an emulator there is no camera hardware. Instead, special provisions have been made to allow applications to use the camera APIs while running on an emulator ”see the Camera APIs subsection later in this chapter.

Photo Album View Switching

The Photo Album (Series 60 1.x) application also does not take any messages. It offers three views that can be switched to:

 const TUid KPhotoAlbumUid = { 0x101F4CD1 }; // 0x01  Imagelist viewthe default view // 0x03  Messaging Picture Grid view // 0x04  Messaging Picture view const TUid photoAlbumViewUid = { 0x01 }; ActivateViewL(TVwsViewId(KPhotoAlbumUid, photoAlbumViewUid)); 

In Series 60 2.x you need to switch to the main view of the Media Gallery application, as this has replaced the Photo Album/Images application. This is illustrated in the FilmReel2 application described in Camera API Changes in Series 60 2.x later in this chapter.

Profiles View Switching

The Profiles application offers two switchable views: the main view and a settings view.

 const TUid KProfileUid = { 0x100058F8 }; // 0x01 main view  the default view // 0x02 settings view const TUid profileViewUid = { iViewIndex + 1 }; ActivateViewL(TVwsViewId(KProfileUid, profileViewUid)); 

Messaging View Switching

You can switch to three messaging views.Neither the main view, { 0x01} , nor the delivery report view, { 0x03} , take a message ID or message, whereas the folder view takes a message ID but not a message. Message IDs for the folder view are defined in msvstd.hrh and allow selection of the folder to view.

[View full width]

 
 [View full width] 
 const TUid KFolderViewUid = { 2 }; const TUid KMsvGlobalInBoxIndexEntryUid = { KmsvGlobalInBoxIndexEntryIdValue }; TBuf8<255> customMessage; ActivateViewL(TVwsViewId(KMessagingUid, KFolderViewUid), KMsvGlobalInBoxIndexEntryUid,  customMessage); 

It is not possible to switch to a view in order to write a new message; if this functionality is required, you can use CSendAppUi, as described in Chapter 10.

Nonswitchable Applications

Occasionally, you may require additional functionality that is not available through view switching. For example, launching a specific WAP or Web page by view switching to the browser application may not be possible on a particular Series 60 device. An alternative, when view switching does not provide the required functionality, is to use the application architecture framework. This can be used to launch an application with a specified document, or, if the application is already running, to send a message to load one.

To find out if an application is running, you can create a list of all running applications using TApaTaskList and then search the TApaTaskList object for the application of interest.

 const TInt KWmlBrowserUid = 0x10008D39; TUid id(TUid::Uid(KWmlBrowserUid)); TApaTaskList taskList(CEikonEnv::Static()->WsSession()); TApaTask task = taskList.FindApp(id); if (task.Exists())    {    ...    } 

It is possible to send a message to a running application using TApaTask::SendMessage(TUid aUid, const TDesC8& aParams) . The parameter aUid should be KUidApaMessageSwitchOpenFileValue to open the file passed in aParams, or KUidApaMessageSwitchCreateFileValue to create a new file. The message sent is handled by CEikAppUi::ProcessMessageL(TUid aUid, const TDesC8& aParams) . In the browser application, ProcessMessageL() has been implemented to ignore any value passed to aUid and launch the link passed by aParams .

 if (task.Exists())    {    HBufC8* param8 = HBufC8::NewLC(link->Length());    param8->Des().Append(*link);    // UID is not used    task.SendMessage(TUid::Uid(0), *param8); CleanupStack::PopAndDestroy();    } 

If the application is not running, then start it using RApaLsSession . This creates a session with the systems application server, which maintains a cached list of all installed applications on the device. Once connected to the application server, you can launch the application with a specified document using RApaLsSession::StartDocument(const TDesC& aFileName, TUid aAppUid, TThreadId& aId) , where aFileName is the document the application is to be launched with and aAppUid is the UID of the application to launch. On return, aId will contain the ID of thread created to launch the application. The browser application uses the descriptor passed to aFileName as the link to be launched in the browser window.

 RApaLsSession appArcSession; // Connect to AppArc server User::LeaveIfError(appArcSession.Connect()); TThreadId id; appArcSession.StartDocument(*link, TUid::Uid(KWmlBrowserUid), id); appArcSession.Close();