--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-779893C2-A9B5-591A-8A5B-6419C4244ACE.dita Fri Jun 11 12:39:03 2010 +0100
@@ -0,0 +1,145 @@
+<?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->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->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->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->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<TInt>* list = new(ELeave) CArrayFixFlat<TInt>(1);
+iCoeEnv->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->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 ->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->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<TInt>* list = new(Eleave) CArrayFixFlat<TInt>(1);
+iCoeEnv ->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->ConstructL(CCoeEnv::Static()->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()->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>
\ No newline at end of file