SY

MB

IA

N

OS

Symbian OS View Architecture Version 1.0 May 27, 2005

Symbian OS View Architecture | 2 Legal Notice

Copyright © 2005 Nokia Corporation. All rights reserved.

Nokia and Nokia Connecting People are registered trademarks of Nokia Corporation. Java and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. Other product and company names mentioned herein may be trademarks or trade names of their respective owners.

Disclaimer

The information in this document is provided “as is,” with no warranties whatsoever, including any warranty of merchantability, fitness for any particular purpose, or any warranty otherwise arising out of any proposal, specification, or sample. Furthermore, information provided in this document is preliminary, and may be changed substantially prior to final release. This document is provided for informational purposes only.

Nokia Corporation disclaims all liability, including liability for infringement of any proprietary rights, relating to implementation of information presented in this document. Nokia Corporation does not warrant or represent that such use will not infringe such rights.

Nokia Corporation retains the right to make changes to this specification at any time, without notice.

License

A license is hereby granted to download and print a copy of this specification for personal use only. No other license to any other intellectual property rights is granted herein.

Version 1.0 | May 27, 2005

Symbian OS View Architecture | 3 Contents

1. Introduction ......................................................................................................... 5 2. An Overview of the View Architecture .............................................................. 6

2.1 An Overview of Views .....................................................................................................6 2.2 Coding for the View Architecture ....................................................................................8

2.2.1 View objects ...........................................................................................................8 2.2.2 Constructing and switching views ..........................................................................9 2.2.3 View observers .....................................................................................................10

2.3 View Architectures on Different Symbian OS Platforms ...............................................11 2.4 When to Use Views.......................................................................................................11

3. Summary............................................................................................................ 12 4. References ......................................................................................................... 13 5. Evaluate This Document................................................................................... 14

Version 1.0 | May 27, 2005

Symbian OS View Architecture | 4 Change History

May 27, 2005 Version 1.0 Initial document release

Version 1.0 | May 27, 2005

Symbian OS View Architecture | 5

1 . I n t r o d u c t i o n

On a desktop computer, a window system, such as Microsoft Windows, facilitates the switching of focus between application windows. A desktop display can have many windows visible at one time and can switch between them at a mouse click. On a mobile device, the smaller screen and more limited input methods do not allow the desktop model to be duplicated. All the requirements for switching are still there — the need to display different application views with their own unique menu items or command buttons — but the mouse is gone and there is little, if any, use of multiple “windows” on the device display.

The designers of Symbian OS have implemented the requirements of switching between applications through the Symbian OS view architecture. The view architecture is a structure that allows applications to bundle their user interface requirements into a single element called a view. The view architecture then provides the capability to switch quickly between the views established for applications running on the device. It is the same concept as switching windows on a desktop system, but implemented for mobile devices.

This document provides an overview of the view architecture and how to use it.

Version 1.0 | May 27, 2005

Symbian OS View Architecture | 6

2 . A n O v e r v i e w o f t he V i e w A r c h i t e c t u r e

This chapter provides an overview of the view architecture on Symbian OS v7.0. A high-level view of how the architecture components fit together is given first. Then a description is given of how these components translate into code pieces and how these code pieces fit together. This is followed by a look at how the various view architectures differ across Symbian OS platforms before finishing with an examination of the situations where views are the best choice for an interface.

2.1 An Overview of Views

A view is a collection of interface elements — controls, menus, command button areas, events, and the like — that make up an application. When an application uses only one set of these elements, there really is no need to consider using the view architecture. However, when there are multiple interface elements to be displayed, the use of multiple views should be considered.

There are many examples of views among the standard applications included on Nokia devices. Consider the Web browsing application: there are at least two views in a Web browser, a Web page view, as shown in Figure 1, and a bookmark view, as shown in Figure 2. Notice that the interface elements are different between the views. The Web page view needs an area for URL input and as wide a display area as possible. The bookmark view displays a bookmark list and uses a set of command buttons to allow the bookmarks to be manipulated. They each have different menus. Switching views between these two will switch all of these interface elements as well.

Figure 1: The Web page view for the Nokia 7710 Web browser

Version 1.0 | May 27, 2005

Symbian OS View Architecture | 7

Figure 2: The bookmark view for the Nokia 7710 Web browser

Another use for views is demonstrated by the example of the Web browser. In the view architecture, both local and remote switching of views is allowed. Local view switching occurs when an application switches between its own views. Remote view switching occurs when an application switches another application’s views. For example, an application could display a Web page by sending a request to activate the Web page view providing the URL of the page to be displayed in the request.

Another important feature of view switching is that it is an event that can be observed by other components in an application. Components can register themselves as observers and can be notified when switching happens. This is especially useful if the act of switching interface elements in a second application needs to be used as the trigger to start or stop another activity.

Consider another example, one that is used in the rest of this document. Many Nokia devices include a messaging application with the ability to receive messages and organize them into folders. An application could expand this functionality to use message filtering, for example, to filter out spam. The application would survey the stream of messages as they arrive and apply filters that have been established by the developer or user to manage messages in that stream. When a message was found to fit a filter’s definition, some action could be taken, such as deleting the message, filing it away in a folder, or providing an automatic reply. This kind of application would have at least two views:

Filter view: One view would be a listing of the filters already established for the application, giving a brief description and indicating whether the filter was enabled.

Log view: This view would give a log of activities performed by the application, such as receipt of a message or the matching between a message and a filter.

This two views approach is quite different from running a single view with a dialog. The application could be created with a log display and then present the filter list in a dialog box; this would not require the view architecture. However, consider the user functionality that the application needs to implement. The filter view might allow the selection and editing of certain filters or a change in the order in which the filters are applied to messages. The log view might offer a way to clear the log or to save it to a file. In fact, each “view” would require a set of dialogs — file dialogs for saving a log or editing dialogs for altering a filter. However, this approach would result in complex code,

Version 1.0 | May 27, 2005

Symbian OS View Architecture | 8 which could be difficult to understand and maintain; implementing two separate views is much cleaner and more efficient.

Each view is managed by the view server, which collects and records views when they are constructed and registered. Each view is given a unique identifier (a value of the type TVwsViewId). Views are activated and deactivated by the application UI after getting notification from the view server. The events of activation or deactivation — as well as other view events — can be identified and acted upon by the application supporting the view.

Applications can have only a single view active at any one time. The current view is the view that interacts with the user, receiving events and menu choices as if it were the only set of UI elements. The current view is changed when the application contacts the view server and requests a switching of views.

There are several advantages to this approach.

Encapsulation — In the view architecture, the data and functions for a view are encapsulated in the view object. Rather than having an external CEikAppUi object control moving between views, each view handles its own activation or deactivation.

Modularity — In addition to controlling its own code, using a view abstracts all operations into a single object. The view approach is more object-oriented and adapts better to situations that require modification.

When dialogs will not fit — Views are especially applicable for applications that require additional windows/screens but dialogs do not fit the need. When more control is required or more user interaction is necessary, the view architecture is very applicable.

External applications can switch an application’s views — Because views are managed on an external server, applications may make a request to switch any other application’s view. This allows interdependence between applications that shares functionality, reduces the complexity of individual applications, and makes each application more efficient.

2.2 Coding for the View Architecture

2.2.1 View objects

In a single view application, the user interface is typically built from a menu system, a set of hotkeys, and a command button area (CBA) specified in a resource file. A class derived from the CCoeControl class implements a container of control objects. When an application takes advantage of the view architecture, it uses view objects derived from the MCoeView class. Each view object is comprised of a menu system, a set of hotkeys, a CBA, and a container of control objects. Note that a view object does not replace any of the interface objects, but that each view object contains its own complete set of interface objects.

The MCoeView class is an abstract class. When deriving a view class from the MCoeView class, the new class must provide a definition for each of the following functions:

TVwsViewId ViewId() const This function defines the unique identifier of the view as a constant.

Version 1.0 | May 27, 2005

Symbian OS View Architecture | 9

void ViewActivatedL(const TVwsViewId& aPrevViewId,TUid aCustomMessageId,const TDesC8& aCustomMessage) This is the function that is called by the operating system when a view is activated. The call gets several arguments: the view ID of the previous view that was displayed (in case a switch back to it is desired), and the identifier and text of a message that comes from the process that is activating the view. This message can convey specialized information, such as information on what to display, from the activating process.

void ViewDeactivated() This function is called by the operating system when a view is deactivated.

The TVwsViewId class represents a view ID, which is the combination of two other IDs. The first is the UID of the application and the second is the UID of the view itself within the application.

The way these functions are called by the system can be a bit unexpected. Exact pairings of calls — for example, ViewActivatedL() followed by a ViewDeactivated() — rarely happen. It is more likely, for example, that several calls to ViewActivatedL() might occur before a view is deactivated, resulting in a call to ViewDeactivated(). This happens because a view is often activated, then activated again, for example an application may display a list within a view (say, the bookmark list in the browser), then as the result of a change made by the user refresh the list and reactivate the view. These situations are quite common and result in behavior that might otherwise be unexpected.

2.2.2 Constructing and switching views

View objects are constructed using the pattern similar to those of other types of control containers. They are typically created in the ConstructL() function of the application’s CCoeAppUi object. Like container objects, view objects are created by instantiating them, then by calling the ConstructL() function of the view object. Finally, the newly created and constructed view is added to the CCoeAppUi object’s view collection by calling RegisterView() to register it with the view server, as shown below:

void RegisterViewL(MCoeView& aView)

The default view, the view displayed when the application starts, is set by calling SetDefaultViewL(), as shown below:

void SetDefaultViewL(const MCoeView& aView)

Views are switched by calling ActivateViewL(), which can switch the views locally within an application or in a remote application. There are two versions of this function. The simple version takes the view ID of the view to switch to, while the extended version also takes a message ID and a message. These message elements are utilized by the ViewActivatedL() function if its definition includes these components. These message elements are arbitrary, and are designed to allow communication between applications. Note that communication is one-way; the view being activated cannot pass information back to the application originating the call.

When a CCoeAppUi object is about to be destroyed, it must deregister any views that have been registered. This is done through the DeregisterView() function, as shown below:

void DeregisterView(const MCoeView& aView)

Version 1.0 | May 27, 2005

Symbian OS View Architecture | 10

Note that this function takes a view as the argument. Failure to deregister views will most likely cause the application to crash.

2.2.3 View observers

An application can register as an observer of a view. Observers can register with the view server as activation observers, deactivation observers, or as generic observers.

Objects that want to register as activation observers must be derived from the MCoeViewActivationObserver class. This class has a single function that must be implemented by the child class

void HandleViewActivation(const TVwsViewId& aNewlyActivatedViewId,const TVwsViewId& aViewIdToBeDeactivated)

This function is called by the system with two parameters: the view ID of the view being activated and the view ID of the view it is replacing.

Once defined, the MCoeViewActivationObserver object must be registered by the CCoeAppUi object as an activation observer. This is done through the call

void AddViewActivationObserverL(MCoeViewActivationObserver* aViewActivationObserver)

This call contains a pointer to the observer object as an argument.

In a similar fashion, deactivation observers can be added. These are derived from the MCoeViewDeactivationObserver class, which requires that the following function be defined:

void HandleViewDeactivation(const TVwsViewId& aViewIdToBeDeactivated,const TVwsViewId& aNewlyActivatedViewId)

The system will call this function, including the view ID of the view being deactivated as the first argument and the view ID of the view that replaces it as the second argument.

As with activation observers, deactivation observers are registered by the CCoeAppUi call

AddViewDeactivationObserverL(MCoeViewDeactivationObserver* aViewDeactivationObserver)

Classes that are to observe all view events are derived from the MCoeViewObserver class, which requires the definition of the function

void HandleViewEventL(const TVwsViewEvent& aEvent)

The class defines a set of view events that include activation, deactivation, and others (such as notification of activation and deactivation). It also includes information about the view ID of the view the event is sent to. General observers are registered with the CCoeAppUi call

void AddViewObserverL(MCoeViewObserver* aViewObserver)

View observers should be deregistered when they are no longer needed. The calls for deregistration are

void RemoveViewActivationObserver(MCoeViewActivationObserver* aViewActivationObserver)

Version 1.0 | May 27, 2005

Symbian OS View Architecture | 11

void RemoveViewDeactivationObserver(MCoeViewDeactivationObserver* aViewDeactivationObserver)

void RemoveViewObserver(MCoeViewObserver* aViewObserver)

2.3 View Architectures on Different Symbian OS Platforms

Among the various Symbian OS platforms, there are several different implementations of views. These implementations come from the version of Symbian OS on which the platform is based.

Views were introduced in Symbian OS version 6.0. The Nokia 9210 Communicator was based on this version. Series 60 Platform 1.0 was based on Symbian OS version 6.1. This version continued to support the view architecture. In this version, the way that views were implemented was altered:

Classes implementing views were based on the CAknView class, which was based on the MCoeView class.

CAknView-based classes implement a different set of functions to obtain notification of view events. For example, they must implement DoActivateL() and DoDeactivate() rather than ViewActivatedL() and ViewDeactivated(). In addition, they could field several other types of events, such as foreground events and view size changes.

To activate views, an application had to distinguish between local and remote views. Each was activated with a different function call.

There was a special set of syntax to define views in the resource file.

In Symbian OS version 7.0, the use of views was streamlined. From that version onwards, views have a much less specialized form and are permitted to use the same constructs as other components. Observers were introduced in this version as well. The Series 60 Platform 2nd Edition is based on Symbian OS version 7.0s, as is the Nokia 7710; these platforms use the streamlined, simpler version of the view architecture. This view architecture is also carried forward into Symbian OS v8.0.

2.4 When to Use Views

When considering whether to use the view architecture, there are several criteria to consider.

There are three types of display architectures. The first is the “traditional” architecture with a single display. This model has a single main view complemented by dialogs for other types of data entry or display. The second type is dialog architecture, where the main display is a modeless dialog box. Multiple display areas can be constructed using nested dialogs or a tabbed dialog pane. The third architecture is the view display with multiple views in an application.

Views are appropriate in applications that require multiple displays with many user interaction elements for each display. When choosing a view over a dialog, it should be considered that a dialog typically contains few interface components and buttons for acceptance or cancellation. Where several different user interface elements are needed, and these use a significant portion of the screen the use of a view becomes more appropriate. Similarly views are beneficial when an application’s display is connected to new sets of menus or command buttons. Views are also appropriate when a requirement exists for displays to be switched remotely, allowing multiple applications to take advantage of the functionality of another.

Version 1.0 | May 27, 2005

Symbian OS View Architecture | 12

3 . S u m m a r y

The Symbian OS view architecture provides developers with an efficient way to build multiple views within an application and switch between them easily and simply. The use of views also allows applications to take advantage of object orientation to encapsulate code, keeping it simple and clear.

The view architecture also provides the ability for one application to activate the view of another. This is a particularly useful mechanism were a developer wants to use an existing display or editing capability without going to the expense of integrating a component into their application.

Version 1.0 | May 27, 2005

Symbian OS View Architecture | 13

4 . R e f e r e n c e s

A version of this document with an additional discussion of an example application is available in Nokia 7710: In-Depth Developer's Guide.

Version 1.0 | May 27, 2005

Symbian OS View Architecture | 14

Version 1.0 | May 27, 2005

5 . E v a l u a t e T h i s D o c u m e n t

In order to improve the quality of documentation, we kindly ask you to fill in the document survey.