1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-779893C2-A9B5-591A-8A5B-6419C4244ACE-GENID-1-8-1-6-1-1-4-1-6-1-11-1" xml:lang="en"><title>How to |
|
13 - Multiple screens</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <section id="GUID-FD58790A-FD0B-563A-80AD-562222865636-GENID-1-8-1-6-1-1-4-1-6-1-11-1-2-1"><title>Contents</title> <ul> |
|
15 <li id="GUID-75FA7683-5209-5FA6-A10F-F7597498C6CD-GENID-1-8-1-6-1-1-4-1-6-1-11-1-2-1-2-1"><p> <xref href="GUID-779893C2-A9B5-591A-8A5B-6419C4244ACE-GENID-1-8-1-6-1-1-4-1-6-1-11-1.dita#GUID-779893C2-A9B5-591A-8A5B-6419C4244ACE-GENID-1-8-1-6-1-1-4-1-6-1-11-1/GUID-00999729-88B9-557B-B999-B2058D63AAB9-GENID-1-8-1-6-1-1-4-1-6-1-11-1-2-2">Introduction</xref> </p> </li> |
|
16 <li id="GUID-68F833FD-7519-5FE0-AEAA-FDB7B1FCBA0C-GENID-1-8-1-6-1-1-4-1-6-1-11-1-2-1-2-2"><p> <xref href="GUID-779893C2-A9B5-591A-8A5B-6419C4244ACE-GENID-1-8-1-6-1-1-4-1-6-1-11-1.dita#GUID-779893C2-A9B5-591A-8A5B-6419C4244ACE-GENID-1-8-1-6-1-1-4-1-6-1-11-1/GUID-903F3A00-48C8-583A-92E8-B66F08998DBF-GENID-1-8-1-6-1-1-4-1-6-1-11-1-2-3-2">Configuration</xref> </p> </li> |
|
17 <li id="GUID-ED3A4756-E173-587B-838C-9289C1471DF9-GENID-1-8-1-6-1-1-4-1-6-1-11-1-2-1-2-3"><p> <xref href="GUID-779893C2-A9B5-591A-8A5B-6419C4244ACE-GENID-1-8-1-6-1-1-4-1-6-1-11-1.dita#GUID-779893C2-A9B5-591A-8A5B-6419C4244ACE-GENID-1-8-1-6-1-1-4-1-6-1-11-1/GUID-DA870E94-50CA-5175-B69E-39248E57EFFA-GENID-1-8-1-6-1-1-4-1-6-1-11-1-2-3-5">Building the ROM image</xref> </p> </li> |
|
18 <li id="GUID-C84723E9-97D6-5E74-A74B-14E4566C824C-GENID-1-8-1-6-1-1-4-1-6-1-11-1-2-1-2-4"><p> <xref href="GUID-779893C2-A9B5-591A-8A5B-6419C4244ACE-GENID-1-8-1-6-1-1-4-1-6-1-11-1.dita#GUID-779893C2-A9B5-591A-8A5B-6419C4244ACE-GENID-1-8-1-6-1-1-4-1-6-1-11-1/GUID-7B313E77-1089-5FF2-A228-9F82C1C25796-GENID-1-8-1-6-1-1-4-1-6-1-11-1-2-3-7">Example Code</xref> </p> </li> |
|
19 <li id="GUID-3609B180-CD0D-501B-9A45-405530FAC78F-GENID-1-8-1-6-1-1-4-1-6-1-11-1-2-1-2-5"><p> <xref href="GUID-779893C2-A9B5-591A-8A5B-6419C4244ACE-GENID-1-8-1-6-1-1-4-1-6-1-11-1.dita#GUID-779893C2-A9B5-591A-8A5B-6419C4244ACE-GENID-1-8-1-6-1-1-4-1-6-1-11-1/GUID-C9E09ADA-07D9-551C-A3D6-46CE3F70269D-GENID-1-8-1-6-1-1-4-1-6-1-11-1-2-3-44">Limitations</xref> </p> </li> |
|
20 </ul> </section> |
|
21 <section id="GUID-00999729-88B9-557B-B999-B2058D63AAB9-GENID-1-8-1-6-1-1-4-1-6-1-11-1-2-2"><title>Introduction</title> <p id="GUID-01F1BC97-47DD-5281-A73B-A0281BF826FB-GENID-1-8-1-6-1-1-4-1-6-1-11-1-2-2-2"><b>Purpose and scope</b> </p> <p>This |
|
22 document explains how an application can draw to multiple screens. It is aimed |
|
23 at a developer who is already familiar with creating a simple application |
|
24 GUI. In this document, the CONE and WSERV interfaces that support multiple |
|
25 screens are referred to.</p> </section> |
|
26 <section id="GUID-094C6D9D-317C-50E2-8440-2217082B89AC-GENID-1-8-1-6-1-1-4-1-6-1-11-1-2-3"><title>How to create |
|
27 multiple screens</title> <p id="GUID-903F3A00-48C8-583A-92E8-B66F08998DBF-GENID-1-8-1-6-1-1-4-1-6-1-11-1-2-3-2"><b>Configuration</b> </p> <p>The |
|
28 first screen is indexed as zero and the nth screen is indexed as n-1. The |
|
29 changes below should be made to the <codeph>wsini.ini</codeph> file which |
|
30 resides under <codeph>\epoc32\data\z\system\data</codeph>. </p> <codeblock id="GUID-BF1B0027-D28C-5AFD-8D0D-9D848FE073C0-GENID-1-8-1-6-1-1-4-1-6-1-11-1-2-3-4" xml:space="preserve">[screen 0] |
|
31 [screen 1] |
|
32 [screen n-1]</codeblock> <p id="GUID-DA870E94-50CA-5175-B69E-39248E57EFFA-GENID-1-8-1-6-1-1-4-1-6-1-11-1-2-3-5"><b>Building |
|
33 the ROM image</b> </p> <p>The secondary screen is supported through TV-OUT |
|
34 on H4 board. The H4 base port only supports landscape mode with 16 bpp resolution. |
|
35 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-6-1-1-4-1-6-1-11-1-2-3-7"><b>Example Code</b> </p> <p id="GUID-3431BCF4-D0C2-5DB3-A0D2-6A245C558A9A-GENID-1-8-1-6-1-1-4-1-6-1-11-1-2-3-8"><b>Setup example code</b> </p> <p>The |
|
36 following code is the basis for the examples that follow.</p> <p>This is a <codeph>wsini.ini</codeph> file |
|
37 used to create two fixed screens:</p> <codeblock id="GUID-BDC24C06-7B6C-5664-B75E-62192F90A4B2-GENID-1-8-1-6-1-1-4-1-6-1-11-1-2-3-11" xml:space="preserve">AUTOCLEAR 1 |
|
38 STARTUP \SYS\BIN\Start |
|
39 WINDOWMODE COLOR64K |
|
40 KEYCLICKPLUGIN KeyClickRef |
|
41 TRANSPARENCY |
|
42 MULTIFOCUSPOLICY |
|
43 [screen 0] |
|
44 [screen 1]</codeblock> <p>This is a class <codeph>CTRedControl</codeph>, which |
|
45 draws a rectangle on the second screen:</p> <codeblock id="GUID-A840ED6A-5339-56D3-B0EC-685A8231B425-GENID-1-8-1-6-1-1-4-1-6-1-11-1-2-3-13" xml:space="preserve">const TInt KSndScreenNo = 1; |
|
46 |
|
47 class CTRedControl : public CCoeControl |
|
48 { |
|
49 public: |
|
50 CTRedControl(){}; |
|
51 ~CTRedControl(){}; |
|
52 void ConstructL(RWindowGroup* aWinGp); |
|
53 |
|
54 private: // From CCoeControl |
|
55 void Draw(const TRect& aRect) const; |
|
56 }; |
|
57 |
|
58 void CTRedControl::ConstructL(RWindowGroup* aWinGp) |
|
59 { |
|
60 CreateWindowL(aWinGp); |
|
61 SetExtent(TPoint(20,20),TSize(100,100)); |
|
62 SetFocus(ETrue); |
|
63 ActivateL(); |
|
64 } |
|
65 |
|
66 void CTRedControl::Draw(const TRect& aRect) const |
|
67 { |
|
68 CWindowGc& gc=SystemGc(); |
|
69 if (IsFocused()) |
|
70 { |
|
71 gc.SetPenColor(KRgbRed); |
|
72 } |
|
73 |
|
74 gc.DrawRect(aRect); |
|
75 }</codeblock> <p id="GUID-D8F54A7C-3F22-59A2-9C6C-A1ACAA22AFBC-GENID-1-8-1-6-1-1-4-1-6-1-11-1-2-3-14"><b>Windows |
|
76 on multiple screens</b> </p> <p>Using the above example code as a basis, the |
|
77 following methods can be used to facilitate access to multiple screens:</p> <p>Class <codeph>RWsSession</codeph> provides |
|
78 the interface to query WSERV about window groups on a particular screen and |
|
79 the number of screens in the system. The application calls the function below |
|
80 to get the number of screens supported on the phone:</p> <codeblock id="GUID-C8CBEEE7-440D-5438-93F0-6B7A71F4C0CD-GENID-1-8-1-6-1-1-4-1-6-1-11-1-2-3-17" xml:space="preserve">iCoeEnv->WsSession().NumberOfScreens();</codeblock> <p>The class <codeph>CWsScreenDevice</codeph> provides the interface to |
|
81 query the physical limitations of the screen and set the parameters of the |
|
82 corresponding logical screen. The class <codeph>RWindowGroup</codeph> is the |
|
83 client side handle to the server side window group. A pair of screen device |
|
84 and window group is required to draw on a screen. </p> <p>CONE maintains an |
|
85 array of screen devices and window groups. The screen number is used to index |
|
86 this array to retrieve a particular window group and its corresponding screen |
|
87 device.</p> <p>The application calls <codeph>ScreenDevice()</codeph> to get |
|
88 the second screen device:</p> <codeblock id="GUID-FEF6A8DE-EE98-5E66-8890-84011B6DCD9D-GENID-1-8-1-6-1-1-4-1-6-1-11-1-2-3-21" xml:space="preserve">iCoeEnv->ScreenDevice(KSndScreenNo);</codeblock> <p>The |
|
89 application calls <codeph>RootWin()</codeph> to get the window group on the |
|
90 second screen:</p> <codeblock id="GUID-0376DBC0-1025-575E-8A7C-490A9580FD5F-GENID-1-8-1-6-1-1-4-1-6-1-11-1-2-3-23" xml:space="preserve">iCoeEnv->RootWin(KSndScreenNo);</codeblock> <p>The |
|
91 application calls <codeph>NumWindowGroups(</codeph> <codeph>)</codeph> to |
|
92 get the number of window groups with <codeph>EAllPriorities</codeph> on the |
|
93 second screen:</p> <codeblock id="GUID-992EE967-FACA-5F18-B727-85FFBDD28845-GENID-1-8-1-6-1-1-4-1-6-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 |
|
94 get the list of window groups with <codeph>EAllPriorities</codeph> on the |
|
95 second screen:</p> <codeblock id="GUID-88D13DA1-95C7-5B4F-948E-A81B56A6553F-GENID-1-8-1-6-1-1-4-1-6-1-11-1-2-3-27" xml:space="preserve">CArrayFixFlat<TInt>* list = new(ELeave) CArrayFixFlat<TInt>(1); |
|
96 iCoeEnv->WsSession().WindowGroupList(list,KSndScreenNo,EAllPriorities);</codeblock> <p>The |
|
97 application calls <codeph>GetFocusWindowGroup()</codeph> to get the window |
|
98 group that has the keyboard focus on the second screen:</p> <codeblock id="GUID-510FD612-678F-5371-AD24-4AA9448F84C2-GENID-1-8-1-6-1-1-4-1-6-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 |
|
99 get the default owning window group on the second screen:</p> <codeblock id="GUID-CE5F2A11-614E-53FA-A2E2-6785E1AA6C39-GENID-1-8-1-6-1-1-4-1-6-1-11-1-2-3-31" xml:space="preserve">iCoeEnv ->WsSession().GetDefaultOwningWindow(KSndScreenNo);</codeblock> <p>The application calls <codeph>GetDefModeMaxNumColors()</codeph> to get |
|
100 the maximum colour and display mode supported on the second screen:</p> <codeblock id="GUID-0B57742A-EDB8-5FA6-AD95-7E680D102893-GENID-1-8-1-6-1-1-4-1-6-1-11-1-2-3-33" xml:space="preserve">TInt colour, grey; |
|
101 iCoeEnv->WsSession().GetDefModeMaxNumColors(KSndScreenNo,colour,grey);</codeblock> <p>The |
|
102 application calls <codeph>GetColorModeList()</codeph> to get the list of colour |
|
103 modes supported on the second screen:</p> <codeblock id="GUID-CD614F8F-EC68-5F1A-8DB6-93D98AA5A67B-GENID-1-8-1-6-1-1-4-1-6-1-11-1-2-3-35" xml:space="preserve">CArrayFixFlat<TInt>* list = new(Eleave) CArrayFixFlat<TInt>(1); |
|
104 iCoeEnv ->WsSession().GetColorModeList(KSndScreenNo, list);</codeblock> <p id="GUID-B6CD7117-E316-5C57-A22F-B5B63D708851-GENID-1-8-1-6-1-1-4-1-6-1-11-1-2-3-36"><b>Creating a control on a |
|
105 particular screen</b> </p> <p>A window group is associated with a screen device, |
|
106 which in turn is associated to a screen. A control is associated with a window |
|
107 group. Therefore a control is constructed on the second screen using the function |
|
108 below, in the control’s <codeph>ConstructL()</codeph>:</p> <codeblock id="GUID-C43130E9-74F7-5F64-A333-EB8C673636B8-GENID-1-8-1-6-1-1-4-1-6-1-11-1-2-3-38" xml:space="preserve">CTRedControl redControl=new(Eleave) CTRedControl(); |
|
109 redControl->ConstructL(CCoeEnv::Static()->RootWin(KSndScreenNo));</codeblock> <p id="GUID-0F5FDB1D-EF43-572F-B68F-47E47025AB45-GENID-1-8-1-6-1-1-4-1-6-1-11-1-2-3-39"><b>Graphics Context</b> </p> <p>The |
|
110 class <codeph>CWindowGc</codeph> provides the interface for the application’s |
|
111 window graphics context and can be activated on any window in the application. |
|
112 This means that it can be used on any screen on the phone. The function call |
|
113 below is used to find the screen device on which the graphics context was |
|
114 last activated.</p> <codeblock id="GUID-88F5AE9B-EBE1-544A-AE96-953C2FDDC8A7-GENID-1-8-1-6-1-1-4-1-6-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-6-1-1-4-1-6-1-11-1-2-3-42"><b>Window Group Focus Policy</b> </p> <p>There |
|
115 are two focus policies supported by WSERV. The default focus policy is that |
|
116 there is only the focused window group on the focused screen receives key |
|
117 events. The new policy is that any window group can receive key events and |
|
118 can be switched on by defining the keyword <codeph>MULTIFOCUSPOLICY</codeph> in |
|
119 the <codeph>wsini.ini</codeph> file.</p> <p id="GUID-C9E09ADA-07D9-551C-A3D6-46CE3F70269D-GENID-1-8-1-6-1-1-4-1-6-1-11-1-2-3-44"><b>Limitations</b> </p> <p id="GUID-C16D1C3E-0326-58CB-8220-F02F2A57321E-GENID-1-8-1-6-1-1-4-1-6-1-11-1-2-3-45"><b>Pointer Events </b> </p> <p>The |
|
120 first screen created is also the primary screen in the system. It is important |
|
121 to note that only the primary screen can respond to pointer events. This is |
|
122 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-6-1-1-4-1-6-1-11-1-2-3-47"><b>Cone-Based UI</b> </p> <p>Due |
|
123 to limitations in the legacy implementation of Cone and the control sets implemented |
|
124 on top of it (for example, Eikon, Avkon or Qikon), it is nearly impossible |
|
125 to make the same application draw Cone-based UI on two different screens at |
|
126 the same time. However, a secondary screen can be used to draw non-Cone-based |
|
127 graphics (for example, a picture or PowerPoint slide-show, or a UI not using |
|
128 Cone for its widgets). If it must appear as if an application supports displaying |
|
129 itself on the secondary screen, then this can be done by moving that UI into |
|
130 a second application instance. This second instance could be a server application |
|
131 that only acts as a slave UI of the main application. In any case, that secondary |
|
132 application instance would have to set the secondary screen as its default |
|
133 screen. There are two main problems: </p> <ol id="GUID-85EC1750-E58A-5BA3-839E-D07AC1958CE0-GENID-1-8-1-6-1-1-4-1-6-1-11-1-2-3-49"> |
|
134 <li id="GUID-67511BE4-B68A-5958-9D87-7413E2244327-GENID-1-8-1-6-1-1-4-1-6-1-11-1-2-3-49-1"><p> All controls have to |
|
135 be associated with a window, and window owning controls do not currently try |
|
136 to make sure that the window they create is associated with the screen that |
|
137 they should appear on. This means, for example, that a pop-out window created |
|
138 by a choice list widget will always appear on the application's primary screen, |
|
139 rather than on the screen on which the choice list itself is located. </p> </li> |
|
140 <li id="GUID-BB68FC89-0AA7-5AEC-8CAC-7959CB79C6B2-GENID-1-8-1-6-1-1-4-1-6-1-11-1-2-3-49-2"><p> None of the legacy |
|
141 widget implementations referencing the screen device take into consideration |
|
142 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>, |
|
143 and <codeph>CEikAppUi's ClientRect()</codeph> and <codeph>ApplicationRect()</codeph>). </p> </li> |
|
144 </ol> <p>Neither of these problems can be solved currently.</p> </section> |
|
145 </conbody></concept> |
|