<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept xml:lang="en" id="GUID-87DB3E71-AAE1-57B6-BC79-CBAF8382614A"><title>Multiple Screens Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody><section id="GUID-3CAFBA33-DED4-572F-8CCC-03A1204397F5"><title>Purpose</title> <p>Multiple screens allow an application to be displayed on more than one screen simultaneously, and also to react to a change in the active screen whilst the application is running. Prior to the implementation of this feature, applications could only display on one screen during its lifetime. </p> <p>When an application creates a view it will be allowed to specify which screen that view will be displayed on. The view will be fixed to that screen, but the application can then create another view on a different screen. If the characteristics (for example, size or colour depth) of the screens are similar, the view on the second screen could just be a second instance of the original view. </p> <p>Some typical uses for taking advantage of multiple screens could be: </p> <ul><li id="GUID-981E73A1-7B5B-5286-94FB-B6A46B2FA90F"><p>A clamshell device with a screen on the inside and one on the outside. The user is working on an application on one screen. The device is opened or closed and the application switches itself to the other screen. </p> </li> <li id="GUID-22C700DD-AC66-5DF1-B35C-509E5C097773"><p>A clamshell device with two screens one on each side of the inside. An application shows part of its data on each screen. </p> </li> <li id="GUID-BC79265B-6156-5B76-908F-B1FC1D808A07"><p>A phone application which displays itself on all screens when the user is not using them for other purposes. </p> </li> </ul> </section> <section><title>Architectural Relationships</title> <p><b>Component Changes</b> </p> <p>The CONE component (which provides the control environment) has been extended to support multiple screens.<codeph>iCoeEnv-&gt;ScreenDevice(</codeph> <i>screennumber</i> <codeph>)</codeph> will return a pointer to the requested screen. </p> <p>WSERV has also been extended to support multiple screens. Specifically, <xref href="GUID-64D4D428-D65F-3D9D-A0D4-C8338C848B25.dita#GUID-64D4D428-D65F-3D9D-A0D4-C8338C848B25/GUID-D784A90A-C7C0-37A9-A6AF-A83A50E78F72"><apiname>RWindowGroup::ConstructL()</apiname></xref> has been overloaded so that a screen device that is associated with a screen can be passed as a parameter during the construction of a window group. </p> </section> <section><title>Description</title> <p><b>Finding out information about a screen</b> </p> <p>The class <xref href="GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9.dita"><apiname>RWsSession</apiname></xref> can be used to query WSERV about the window groups on a particular screen and the number of screens on the device. </p> <p>The class <xref href="GUID-30479BE3-296E-3B4D-914D-B080ABD733E4.dita"><apiname>CWsScreenDevice</apiname></xref> can be used to query the physical characteristics of the screen, and set the parameters of the corresponding logical screen associated with it. </p> <p>The class <xref href="GUID-64D4D428-D65F-3D9D-A0D4-C8338C848B25.dita"><apiname>RWindowGroup</apiname></xref> is the client side handle to the server side window group. </p> <p>Both <xref href="GUID-30479BE3-296E-3B4D-914D-B080ABD733E4.dita"><apiname>CWsScreenDevice</apiname></xref> and <xref href="GUID-64D4D428-D65F-3D9D-A0D4-C8338C848B25.dita"><apiname>RWindowGroup</apiname></xref> are needed as a pair to draw on a screen. </p> <p>The Cone component maintains the array of screen devices and window group pairs through its <xref href="GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9.dita#GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9/GUID-0179374E-3601-3C6C-BC0F-168C7F34BC14"><apiname>RWsSession::WsSession()</apiname></xref> method. The screen number is used to index this array in order to retrieve a particular window group and its corresponding screen device. This array can be queried in order to find out information such as: </p> <ul><li id="GUID-D93FCD79-B12B-525B-8A2F-BA28436DCFEC"><p>the window group with the current keyboard focus </p> </li> <li id="GUID-EECD3D6D-D0A1-566A-B1DF-05AF59A7995F"><p>the window group with focus on a particular screen </p> </li> <li id="GUID-C4733651-B987-5990-962D-40A83A1F4B81"><p>the maximum colour and display mode on a particular screen </p> </li> <li id="GUID-B8617AA3-A46A-5866-8E0E-BD9763FB9EA7"><p>the list of colour modes for a particular screen </p> </li> </ul> <p><b>Creating a control on a particular screen</b> </p> <p>A control is associated with a window and a particular window group. A window group is associated with a screen device, which in turn is associated with a screen. To create a control on a particular screen, retrieve an appropriate window group on that screen and use it as the parameter in the control’s <codeph>ConstructL()</codeph>. The window for that control will then be created on that screen </p> <p><b>Graphics Context</b> </p> <p>The class <xref href="GUID-0AEE5955-C530-35F1-A904-69183331B294.dita"><apiname>CWindowGc</apiname></xref> provides the interface for the application’s window graphics context and can be activated on any window in the application. This means that it can be used on any screen on the phone </p> <p><b>Window Group Focus Policy</b> </p> <p>There are two focus policies supported by WSERV. The default focus policy is that it is only the focused window group on the focused screen that receives focus gained and focus lost events. The new policy is that any window group can receive focus gained and lost events and can be switched on by defining the keyword <codeph>MULTIFOCUSPOLICY</codeph> in the <codeph>wsini.ini</codeph> file. </p> <p><b>Limitations</b> </p> <p><b>Pointer Events </b> </p> <p>The first screen created is also the primary screen in the system. It is important to note that only the primary screen can respond to pointer events. This is due to the fact that the kernel supports only one screen digitiser. </p> <p>For information about further limitations specifically related to the legacy nature of Cone, please see <xref href="GUID-779893C2-A9B5-591A-8A5B-6419C4244ACE.dita">How To Multiple Screens</xref>. </p> </section> </conbody></concept>