O S

Symbian OS View
Architecture

S Y M B I A N
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. Introduction
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. An Overview of the View Architecture

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. Summary
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. References
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

5. Evaluate This Document

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

Version 1.0 | May 27, 2005