<?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 id="GUID-779893C2-A9B5-591A-8A5B-6419C4244ACE" xml:lang="en"><title>How to

- Multiple screens</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-FD58790A-FD0B-563A-80AD-562222865636"><title>Contents</title> <ul>

<li id="GUID-75FA7683-5209-5FA6-A10F-F7597498C6CD"><p> <xref href="GUID-779893C2-A9B5-591A-8A5B-6419C4244ACE.dita#GUID-779893C2-A9B5-591A-8A5B-6419C4244ACE/GUID-00999729-88B9-557B-B999-B2058D63AAB9">Introduction</xref> </p> </li>

<li id="GUID-68F833FD-7519-5FE0-AEAA-FDB7B1FCBA0C"><p> <xref href="GUID-779893C2-A9B5-591A-8A5B-6419C4244ACE.dita#GUID-779893C2-A9B5-591A-8A5B-6419C4244ACE/GUID-903F3A00-48C8-583A-92E8-B66F08998DBF">Configuration</xref> </p> </li>

<li id="GUID-ED3A4756-E173-587B-838C-9289C1471DF9"><p> <xref href="GUID-779893C2-A9B5-591A-8A5B-6419C4244ACE.dita#GUID-779893C2-A9B5-591A-8A5B-6419C4244ACE/GUID-DA870E94-50CA-5175-B69E-39248E57EFFA">Building the ROM image</xref> </p> </li>

<li id="GUID-C84723E9-97D6-5E74-A74B-14E4566C824C"><p> <xref href="GUID-779893C2-A9B5-591A-8A5B-6419C4244ACE.dita#GUID-779893C2-A9B5-591A-8A5B-6419C4244ACE/GUID-7B313E77-1089-5FF2-A228-9F82C1C25796">Example Code</xref> </p> </li>

<li id="GUID-3609B180-CD0D-501B-9A45-405530FAC78F"><p> <xref href="GUID-779893C2-A9B5-591A-8A5B-6419C4244ACE.dita#GUID-779893C2-A9B5-591A-8A5B-6419C4244ACE/GUID-C9E09ADA-07D9-551C-A3D6-46CE3F70269D">Limitations</xref> </p> </li>

</ul> </section>

<section id="GUID-00999729-88B9-557B-B999-B2058D63AAB9"><title>Introduction</title> <p id="GUID-01F1BC97-47DD-5281-A73B-A0281BF826FB"><b>Purpose and scope</b> </p> <p>This

document explains how an application can draw to multiple screens. It is aimed

at a developer who is already familiar with creating a simple application

GUI. In this document, the CONE and WSERV interfaces that support multiple

screens are referred to.</p> </section>

<section id="GUID-094C6D9D-317C-50E2-8440-2217082B89AC"><title>How to create

multiple screens</title> <p id="GUID-903F3A00-48C8-583A-92E8-B66F08998DBF"><b>Configuration</b> </p> <p>The

first screen is indexed as zero and the nth screen is indexed as n-1. The

changes below should be made to the <codeph>wsini.ini</codeph> file which

resides under <codeph>\epoc32\data\z\system\data</codeph>. </p> <codeblock id="GUID-BF1B0027-D28C-5AFD-8D0D-9D848FE073C0" xml:space="preserve">[screen 0]

[screen 1]

[screen n-1]</codeblock> <p id="GUID-DA870E94-50CA-5175-B69E-39248E57EFFA"><b>Building

the ROM image</b> </p> <p>The secondary screen is supported through TV-OUT

on H4 board. The H4 base port only supports landscape mode with 16 bpp resolution.

The ROM image must be built with <codeph>-DWITH_TVOUT</codeph> as a parameter.</p> <p id="GUID-7B313E77-1089-5FF2-A228-9F82C1C25796"><b>Example Code</b> </p> <p id="GUID-3431BCF4-D0C2-5DB3-A0D2-6A245C558A9A"><b>Setup example code</b> </p> <p>The

following code is the basis for the examples that follow.</p> <p>This is a <codeph>wsini.ini</codeph> file

used to create two fixed screens:</p> <codeblock id="GUID-BDC24C06-7B6C-5664-B75E-62192F90A4B2" xml:space="preserve">AUTOCLEAR 1

STARTUP \SYS\BIN\Start

WINDOWMODE COLOR64K

KEYCLICKPLUGIN KeyClickRef

TRANSPARENCY

MULTIFOCUSPOLICY

[screen 0]

[screen 1]</codeblock> <p>This is a class <codeph>CTRedControl</codeph>, which

draws a rectangle on the second screen:</p> <codeblock id="GUID-A840ED6A-5339-56D3-B0EC-685A8231B425" xml:space="preserve">const TInt KSndScreenNo = 1;

class CTRedControl : public CCoeControl

     {

public:

    CTRedControl(){};

    ~CTRedControl(){};

    void ConstructL(RWindowGroup* aWinGp);

private: // From CCoeControl

    void Draw(const TRect& aRect) const;

    };

void CTRedControl::ConstructL(RWindowGroup* aWinGp)

    {    

    CreateWindowL(aWinGp);

    SetExtent(TPoint(20,20),TSize(100,100));

    SetFocus(ETrue);

    ActivateL();        

    }

void CTRedControl::Draw(const TRect& aRect) const

    {

    CWindowGc& gc=SystemGc();

    if (IsFocused())

        {

        gc.SetPenColor(KRgbRed);

        }

    gc.DrawRect(aRect);     

    }</codeblock> <p id="GUID-D8F54A7C-3F22-59A2-9C6C-A1ACAA22AFBC"><b>Windows

on multiple screens</b> </p> <p>Using the above example code as a basis, the

following methods can be used to facilitate access to multiple screens:</p> <p>Class <codeph>RWsSession</codeph> provides

the interface to query WSERV about window groups on a particular screen and

the number of screens in the system. The application calls the function below

to get the number of screens supported on the phone:</p> <codeblock id="GUID-C8CBEEE7-440D-5438-93F0-6B7A71F4C0CD" xml:space="preserve">iCoeEnv-&gt;WsSession().NumberOfScreens();</codeblock> <p>The class <codeph>CWsScreenDevice</codeph> provides the interface to

query the physical limitations of the screen and set the parameters of the

corresponding logical screen. The class <codeph>RWindowGroup</codeph> is the

client side handle to the server side window group. A pair of screen device

and window group is required to draw on a screen. </p> <p>CONE maintains an

array of screen devices and window groups. The screen number is used to index

this array to retrieve a particular window group and its corresponding screen

device.</p> <p>The application calls <codeph>ScreenDevice()</codeph> to get

the second screen device:</p> <codeblock id="GUID-FEF6A8DE-EE98-5E66-8890-84011B6DCD9D" xml:space="preserve">iCoeEnv-&gt;ScreenDevice(KSndScreenNo);</codeblock> <p>The

application calls <codeph>RootWin()</codeph> to get the window group on the

second screen:</p> <codeblock id="GUID-0376DBC0-1025-575E-8A7C-490A9580FD5F" xml:space="preserve">iCoeEnv-&gt;RootWin(KSndScreenNo);</codeblock> <p>The

application calls <codeph>NumWindowGroups(</codeph> <codeph>)</codeph> to

get the number of window groups with <codeph>EAllPriorities</codeph> on the

second screen:</p> <codeblock id="GUID-992EE967-FACA-5F18-B727-85FFBDD28845" xml:space="preserve">iCoeEnv-&gt;WsSession().NumWindowGroups(KSndScreenNo,EAllPriorities);</codeblock> <p>The application creates a new list and then populates it with <codeph>WindowGroupList()</codeph> <codeph> </codeph> to

get the list of window groups with <codeph>EAllPriorities</codeph> on the

second screen:</p> <codeblock id="GUID-88D13DA1-95C7-5B4F-948E-A81B56A6553F" xml:space="preserve">CArrayFixFlat&lt;TInt&gt;* list = new(ELeave) CArrayFixFlat&lt;TInt&gt;(1);

iCoeEnv-&gt;WsSession().WindowGroupList(list,KSndScreenNo,EAllPriorities);</codeblock> <p>The

application calls <codeph>GetFocusWindowGroup()</codeph> to get the window

group that has the keyboard focus on the second screen:</p> <codeblock id="GUID-510FD612-678F-5371-AD24-4AA9448F84C2" xml:space="preserve">iCoeEnv-&gt;WsSession().GetFocusWindowGroup(KSndScreenNo);</codeblock> <p>Each screen has a default owning window group. The application calls <codeph>GetDefaultOwningWindow()</codeph> to

get the default owning window group on the second screen:</p> <codeblock id="GUID-CE5F2A11-614E-53FA-A2E2-6785E1AA6C39" xml:space="preserve">iCoeEnv -&gt;WsSession().GetDefaultOwningWindow(KSndScreenNo);</codeblock> <p>The application calls <codeph>GetDefModeMaxNumColors()</codeph> to get

the maximum colour and display mode supported on the second screen:</p> <codeblock id="GUID-0B57742A-EDB8-5FA6-AD95-7E680D102893" xml:space="preserve">TInt colour, grey;

iCoeEnv-&gt;WsSession().GetDefModeMaxNumColors(KSndScreenNo,colour,grey);</codeblock> <p>The

application calls <codeph>GetColorModeList()</codeph> to get the list of colour

modes supported on the second screen:</p> <codeblock id="GUID-CD614F8F-EC68-5F1A-8DB6-93D98AA5A67B" xml:space="preserve">CArrayFixFlat&lt;TInt&gt;* list = new(Eleave) CArrayFixFlat&lt;TInt&gt;(1);

iCoeEnv -&gt;WsSession().GetColorModeList(KSndScreenNo, list);</codeblock> <p id="GUID-B6CD7117-E316-5C57-A22F-B5B63D708851"><b>Creating a control on a

particular screen</b> </p> <p>A window group is associated with a screen device,

which in turn is associated to a screen. A control is associated with a window

group. Therefore a control is constructed on the second screen using the function

below, in the control’s <codeph>ConstructL()</codeph>:</p> <codeblock id="GUID-C43130E9-74F7-5F64-A333-EB8C673636B8" xml:space="preserve">CTRedControl  redControl=new(Eleave) CTRedControl();

redControl-&gt;ConstructL(CCoeEnv::Static()-&gt;RootWin(KSndScreenNo));</codeblock> <p id="GUID-0F5FDB1D-EF43-572F-B68F-47E47025AB45"><b>Graphics Context</b> </p> <p>The

class <codeph>CWindowGc</codeph> 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. The function call

below is used to find the screen device on which the graphics context was

last activated.</p> <codeblock id="GUID-88F5AE9B-EBE1-544A-AE96-953C2FDDC8A7" xml:space="preserve">CCoeEnv::Static()-&gt;SystemGc().Device();</codeblock> <p id="GUID-D7EFBD5D-1AF3-526A-A1FF-5FC9F75E68CF"><b>Window Group Focus Policy</b> </p> <p>There

are two focus policies supported by WSERV. The default focus policy is that

there is only the focused window group on the focused screen receives key

events. The new policy is that any window group can receive key events and

can be switched on by defining the keyword <codeph>MULTIFOCUSPOLICY</codeph> in

the <codeph>wsini.ini</codeph> file.</p> <p id="GUID-C9E09ADA-07D9-551C-A3D6-46CE3F70269D"><b>Limitations</b> </p> <p id="GUID-C16D1C3E-0326-58CB-8220-F02F2A57321E"><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 id="GUID-E4D55BC0-9D6A-5D6D-BCA1-8724DCB920D1"><b>Cone-Based UI</b> </p> <p>Due

to limitations in the legacy implementation of Cone and the control sets implemented

on top of it (for example, Eikon, Avkon or Qikon), it is nearly impossible

to make the same application draw Cone-based UI on two different screens at

the same time. However, a secondary screen can be used to draw non-Cone-based

graphics (for example, a picture or PowerPoint slide-show, or a UI not using

Cone for its widgets). If it must appear as if an application supports displaying

itself on the secondary screen, then this can be done by moving that UI into

a second application instance. This second instance could be a server application

that only acts as a slave UI of the main application. In any case, that secondary

application instance would have to set the secondary screen as its default

screen. There are two main problems: </p> <ol id="GUID-85EC1750-E58A-5BA3-839E-D07AC1958CE0">

<li id="GUID-67511BE4-B68A-5958-9D87-7413E2244327"><p> All controls have to

be associated with a window, and window owning controls do not currently try

to make sure that the window they create is associated with the screen that

they should appear on. This means, for example, that a pop-out window created

by a choice list widget will always appear on the application's primary screen,

rather than on the screen on which the choice list itself is located. </p> </li>

<li id="GUID-BB68FC89-0AA7-5AEC-8CAC-7959CB79C6B2"><p> None of the legacy

widget implementations referencing the screen device take into consideration

that there might be more than one screen on the device. These include <codeph>CCoeControl</codeph>'s <codeph>SetExtentToWholeScreen()</codeph>, <codeph>SetCornerAndSize()</codeph>, <codeph>AccumulatedZoom()</codeph>, <codeph>PositionRelativeToScreen()</codeph>,

and <codeph>CEikAppUi's ClientRect()</codeph> and <codeph>ApplicationRect()</codeph>). </p> </li>

</ol> <p>Neither of these problems can be solved currently.</p> </section>

</conbody></concept>