Symbian3/SDK/Source/GUID-779893C2-A9B5-591A-8A5B-6419C4244ACE-GENID-1-8-1-3-1-1-7-1-11-1.dita
--- a/Symbian3/SDK/Source/GUID-779893C2-A9B5-591A-8A5B-6419C4244ACE-GENID-1-8-1-3-1-1-7-1-11-1.dita Wed Mar 31 11:11:55 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,145 +0,0 @@
-<?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-GENID-1-8-1-3-1-1-7-1-11-1" xml:lang="en"><title>How to
-- Multiple screens</title><prolog><metadata><keywords/></metadata></prolog><conbody>
-<section id="GUID-FD58790A-FD0B-563A-80AD-562222865636-GENID-1-8-1-3-1-1-7-1-11-1-2-1"><title>Contents</title> <ul>
-<li id="GUID-75FA7683-5209-5FA6-A10F-F7597498C6CD-GENID-1-8-1-3-1-1-7-1-11-1-2-1-2-1"><p> <xref href="GUID-779893C2-A9B5-591A-8A5B-6419C4244ACE-GENID-1-8-1-3-1-1-7-1-11-1.dita#GUID-779893C2-A9B5-591A-8A5B-6419C4244ACE-GENID-1-8-1-3-1-1-7-1-11-1/GUID-00999729-88B9-557B-B999-B2058D63AAB9-GENID-1-8-1-3-1-1-7-1-11-1-2-2">Introduction</xref> </p> </li>
-<li id="GUID-68F833FD-7519-5FE0-AEAA-FDB7B1FCBA0C-GENID-1-8-1-3-1-1-7-1-11-1-2-1-2-2"><p> <xref href="GUID-779893C2-A9B5-591A-8A5B-6419C4244ACE-GENID-1-8-1-3-1-1-7-1-11-1.dita#GUID-779893C2-A9B5-591A-8A5B-6419C4244ACE-GENID-1-8-1-3-1-1-7-1-11-1/GUID-903F3A00-48C8-583A-92E8-B66F08998DBF-GENID-1-8-1-3-1-1-7-1-11-1-2-3-2">Configuration</xref> </p> </li>
-<li id="GUID-ED3A4756-E173-587B-838C-9289C1471DF9-GENID-1-8-1-3-1-1-7-1-11-1-2-1-2-3"><p> <xref href="GUID-779893C2-A9B5-591A-8A5B-6419C4244ACE-GENID-1-8-1-3-1-1-7-1-11-1.dita#GUID-779893C2-A9B5-591A-8A5B-6419C4244ACE-GENID-1-8-1-3-1-1-7-1-11-1/GUID-DA870E94-50CA-5175-B69E-39248E57EFFA-GENID-1-8-1-3-1-1-7-1-11-1-2-3-5">Building the ROM image</xref> </p> </li>
-<li id="GUID-C84723E9-97D6-5E74-A74B-14E4566C824C-GENID-1-8-1-3-1-1-7-1-11-1-2-1-2-4"><p> <xref href="GUID-779893C2-A9B5-591A-8A5B-6419C4244ACE-GENID-1-8-1-3-1-1-7-1-11-1.dita#GUID-779893C2-A9B5-591A-8A5B-6419C4244ACE-GENID-1-8-1-3-1-1-7-1-11-1/GUID-7B313E77-1089-5FF2-A228-9F82C1C25796-GENID-1-8-1-3-1-1-7-1-11-1-2-3-7">Example Code</xref> </p> </li>
-<li id="GUID-3609B180-CD0D-501B-9A45-405530FAC78F-GENID-1-8-1-3-1-1-7-1-11-1-2-1-2-5"><p> <xref href="GUID-779893C2-A9B5-591A-8A5B-6419C4244ACE-GENID-1-8-1-3-1-1-7-1-11-1.dita#GUID-779893C2-A9B5-591A-8A5B-6419C4244ACE-GENID-1-8-1-3-1-1-7-1-11-1/GUID-C9E09ADA-07D9-551C-A3D6-46CE3F70269D-GENID-1-8-1-3-1-1-7-1-11-1-2-3-44">Limitations</xref> </p> </li>
-</ul> </section>
-<section id="GUID-00999729-88B9-557B-B999-B2058D63AAB9-GENID-1-8-1-3-1-1-7-1-11-1-2-2"><title>Introduction</title> <p id="GUID-01F1BC97-47DD-5281-A73B-A0281BF826FB-GENID-1-8-1-3-1-1-7-1-11-1-2-2-2"><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-GENID-1-8-1-3-1-1-7-1-11-1-2-3"><title>How to create
-multiple screens</title> <p id="GUID-903F3A00-48C8-583A-92E8-B66F08998DBF-GENID-1-8-1-3-1-1-7-1-11-1-2-3-2"><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-GENID-1-8-1-3-1-1-7-1-11-1-2-3-4" xml:space="preserve">[screen 0]
-[screen 1]
-[screen n-1]</codeblock> <p id="GUID-DA870E94-50CA-5175-B69E-39248E57EFFA-GENID-1-8-1-3-1-1-7-1-11-1-2-3-5"><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-GENID-1-8-1-3-1-1-7-1-11-1-2-3-7"><b>Example Code</b> </p> <p id="GUID-3431BCF4-D0C2-5DB3-A0D2-6A245C558A9A-GENID-1-8-1-3-1-1-7-1-11-1-2-3-8"><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-GENID-1-8-1-3-1-1-7-1-11-1-2-3-11" 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-GENID-1-8-1-3-1-1-7-1-11-1-2-3-13" 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-GENID-1-8-1-3-1-1-7-1-11-1-2-3-14"><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-GENID-1-8-1-3-1-1-7-1-11-1-2-3-17" 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-GENID-1-8-1-3-1-1-7-1-11-1-2-3-21" 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-GENID-1-8-1-3-1-1-7-1-11-1-2-3-23" 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-GENID-1-8-1-3-1-1-7-1-11-1-2-3-25" 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-GENID-1-8-1-3-1-1-7-1-11-1-2-3-27" 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-GENID-1-8-1-3-1-1-7-1-11-1-2-3-29" 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-GENID-1-8-1-3-1-1-7-1-11-1-2-3-31" 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-GENID-1-8-1-3-1-1-7-1-11-1-2-3-33" 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-GENID-1-8-1-3-1-1-7-1-11-1-2-3-35" 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-GENID-1-8-1-3-1-1-7-1-11-1-2-3-36"><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-GENID-1-8-1-3-1-1-7-1-11-1-2-3-38" xml:space="preserve">CTRedControl redControl=new(Eleave) CTRedControl();
-redControl->ConstructL(CCoeEnv::Static()->RootWin(KSndScreenNo));</codeblock> <p id="GUID-0F5FDB1D-EF43-572F-B68F-47E47025AB45-GENID-1-8-1-3-1-1-7-1-11-1-2-3-39"><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-GENID-1-8-1-3-1-1-7-1-11-1-2-3-41" xml:space="preserve">CCoeEnv::Static()->SystemGc().Device();</codeblock> <p id="GUID-D7EFBD5D-1AF3-526A-A1FF-5FC9F75E68CF-GENID-1-8-1-3-1-1-7-1-11-1-2-3-42"><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-GENID-1-8-1-3-1-1-7-1-11-1-2-3-44"><b>Limitations</b> </p> <p id="GUID-C16D1C3E-0326-58CB-8220-F02F2A57321E-GENID-1-8-1-3-1-1-7-1-11-1-2-3-45"><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-GENID-1-8-1-3-1-1-7-1-11-1-2-3-47"><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-GENID-1-8-1-3-1-1-7-1-11-1-2-3-49">
-<li id="GUID-67511BE4-B68A-5958-9D87-7413E2244327-GENID-1-8-1-3-1-1-7-1-11-1-2-3-49-1"><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-GENID-1-8-1-3-1-1-7-1-11-1-2-3-49-2"><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