<?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&amp; aRect) const;
    };

void CTRedControl::ConstructL(RWindowGroup* aWinGp)
    {    
    CreateWindowL(aWinGp);
    SetExtent(TPoint(20,20),TSize(100,100));
    SetFocus(ETrue);
    ActivateL();        
    }

void CTRedControl::Draw(const TRect&amp; aRect) const
    {
    CWindowGc&amp; 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>