|
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 reference |
|
11 PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd"> |
|
12 <reference id="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69" xml:lang="en"><title>The |
|
13 wsini.ini File Reference</title><shortdesc>This topic provides a reference to the <filepath>wsini.ini</filepath> file |
|
14 parameters. Some of the parameters are general, some are screen-specific and |
|
15 some are specific to individual plug-ins. </shortdesc><prolog><metadata><keywords/></metadata></prolog><refbody> |
|
16 <section id="GUID-51E0A97A-10CB-4C8A-8404-9D92BB3F075D"><title>Introduction</title> <p> <b>Variant</b>: <xref href="GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.dita">ScreenPlay</xref> and <xref href="GUID-F64E6551-670E-5E12-8103-DE504D3EC94F.dita">non-ScreenPlay</xref>. <b>Target |
|
17 audience</b>: Device creators. </p> <p>This topic divides the parameters into |
|
18 four groups: </p> <ul> |
|
19 <li id="GUID-406BCA6A-6E81-5FE8-BC08-1D85098BD299"><p><xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita#GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69/GUID-751AB9E9-B8C3-5BE3-B1D5-C334E68106F2">General parameters</xref> </p> </li> |
|
20 <li id="GUID-207497F2-A83C-5C9B-A781-EE0F170E8424"><p><xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita#GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69/GUID-794DD7D2-83DD-50E8-822C-A8AC0D123EE5"> Screen-specific parameters</xref> </p> </li> |
|
21 <li id="GUID-04044E59-4DFE-5184-BBEC-23A72159A7A6"><p><xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita#GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69/GUID-71ABB4DF-8C79-598F-BD4C-AC1EDD52AA04"> Plug-in specific parameters</xref> </p> </li> |
|
22 <li id="GUID-BD479EED-324F-5702-9B0F-F58C038F680A"><p><xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita#GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69/GUID-635178C9-CFF1-5261-8A72-CC291DE98531">Obsolete and deprecated parameters</xref> </p> </li> |
|
23 </ul> <p> <b>Notes</b>: </p> <ul> |
|
24 <li id="GUID-9252F124-EF48-54D9-9244-7A7EC30C7E58"><p>Although most of these |
|
25 parameters apply to the Window Server in both the ScreenPlay (NGA) variant |
|
26 and the non-ScreenPlay (non-NGA) variant, some of them apply to only one variant |
|
27 or the other. For the general and screen-specific parameters, there is an |
|
28 extra column on the right of the table that shows which variant the parameter |
|
29 applies to—<i>both</i> meaning both ScreenPlay and non-ScreenPlay variants. </p> </li> |
|
30 <li id="GUID-414DD0AE-E974-54C5-873E-A392F7AF915E"><p>You must specify all |
|
31 of the parameters using all uppercase letters. </p> </li> |
|
32 </ul> </section> |
|
33 <section id="GUID-751AB9E9-B8C3-5BE3-B1D5-C334E68106F2"><title>General parameters</title> <p>These |
|
34 are general parameters—that is, parameters that are not screen-specific or |
|
35 plug-in specific. Put these parameters first in the <filepath>wsini.ini</filepath> file, |
|
36 optionally under the <codeph>[DEFAULT]</codeph> section heading keyword. This |
|
37 first section can also include any screen-related parameters that apply to |
|
38 all screens. </p> <table id="GUID-D4597226-B6F0-501E-B871-433F3399FA7D"> |
|
39 <tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/> |
|
40 <thead> |
|
41 <row> |
|
42 <entry>Parameter </entry> |
|
43 <entry>Description </entry> |
|
44 <entry>Variant </entry> |
|
45 </row> |
|
46 </thead> |
|
47 <tbody> |
|
48 <row> |
|
49 <entry><p> <codeph>ABSOLUTEFADING</codeph> </p> </entry> |
|
50 <entry><p>If this is specified, the Window Server uses absolute fading. If |
|
51 not specified, the Window Server uses counted fading. Counted fading means |
|
52 that the Window Server maintains a count in order to support the nesting of <codeph>SetFaded()</codeph> calls. |
|
53 This mechanism provides support for nested pop-ups (where pop-ups cause the |
|
54 background to fade). </p> <p>In absolute fading, Window Server uses a <codeph>TBool</codeph> value |
|
55 instead, so that <codeph>SetFaded(ETrue/EFalse)</codeph> fades or unfades |
|
56 the window, regardless of nesting. </p> </entry> |
|
57 <entry><p>Both </p> </entry> |
|
58 </row> |
|
59 <row> |
|
60 <entry><p> <codeph>ANIMATIONGRACEPERIOD</codeph> <i>value</i> </p> </entry> |
|
61 <entry><p>Specifies the grace period (in microseconds) for animations. The |
|
62 grace period is the length of time that the Window Server waits between animation |
|
63 frames. If not specified, the grace period defaults to 35 milliseconds, in |
|
64 order to allow other threads to run. The animation grace period is a minimum |
|
65 period—the Window Server attempts to go faster if there is nothing else using |
|
66 the system. </p> </entry> |
|
67 <entry><p>Both </p> </entry> |
|
68 </row> |
|
69 <row> |
|
70 <entry><p> <codeph>ATOMICREDRAWS</codeph> </p> </entry> |
|
71 <entry><p>Specify this parameter to enable atomic redraws. </p> <p>Client |
|
72 redrawing is often performed as sequences of Begin/End redraw commands. If |
|
73 the screen is redrawn when the Window Server is part way through receiving |
|
74 the draw commands (that is between the Begin and End commands), the screen |
|
75 update is often incomplete or incorrect. This can result in flicker. </p> <p>Enabling |
|
76 atomic redraws ensures that the draw commands that are enclosed within the |
|
77 Begin/End redraw are drawn onto the screen only when the whole section of |
|
78 commands has been received by the Window Server. </p> <p>See <xref href="GUID-0AD34BA6-D0C5-5AD7-B8E1-F737BB5FC0AC.dita">Redraw |
|
79 Stores</xref> for more information. </p> </entry> |
|
80 <entry><p>Both </p> </entry> |
|
81 </row> |
|
82 <row> |
|
83 <entry><p> <codeph>BACKGROUNDALPHA</codeph> <i>value</i> </p> </entry> |
|
84 <entry><p>Sets the alpha value of the default background color for all windows. |
|
85 To override this default value for a specific window, set its background color |
|
86 explicitly. </p> <p>Specify <i>value</i> as an integer in the range 0–255. |
|
87 If this parameter is not specified, the default value is 0xFF or completely |
|
88 opaque. </p> <p>Note that a background alpha value of zero means that the |
|
89 window background color is not drawn at all. </p> </entry> |
|
90 <entry><p>Both </p> </entry> |
|
91 </row> |
|
92 <row> |
|
93 <entry><p> <codeph>BACKGROUNDCOLOR</codeph> <i>value</i> </p> </entry> |
|
94 <entry><p>Sets the default window background color. Enter <i>value</i> in |
|
95 the form: <codeph>0x</codeph> <i>rrggbb</i>. For example, the following specifies |
|
96 a red default background color: </p> <codeblock id="GUID-7EC633DA-ACF8-5DD4-BF47-C89E744FC0C8" xml:space="preserve">BACKGROUNDCOLOR 0xff0000</codeblock> <p>If |
|
97 this parameter is not specified, the default background color is white. </p> </entry> |
|
98 <entry><p>Both </p> </entry> |
|
99 </row> |
|
100 <row> |
|
101 <entry><p> <codeph>DEBUGBAR</codeph> </p> </entry> |
|
102 <entry><p>Turns on the Window Server’s debug bar. This overlays the normal |
|
103 UI and displays information about the current performance and behavior of |
|
104 the Window Server over two lines like this: </p> <codeblock id="GUID-679C6692-BE11-508C-A0A6-70418588A3E3" xml:space="preserve">KeyEvents 0; 0; WServ 0.0%; Drawing 0.0%; Reclaimed 0.0% |
|
105 RedrawStore size 0B; updates 0/s, pixels 0/s</codeblock> <ul> |
|
106 <li id="GUID-BC6FE170-EF64-58DB-BB4E-854C4E37F6AE"><p> <codeph>KeyEvents</codeph> shows |
|
107 the total number of key events and scheduler requests. </p> </li> |
|
108 <li id="GUID-568A332B-285B-520A-AEA6-51A518570199"><p> <codeph>Wserv</codeph> shows |
|
109 the percentage of scheduler activity occupied by the Window Server. </p> </li> |
|
110 <li id="GUID-1C57720D-65BA-516D-BADB-F2834891FFE0"><p> <codeph>Drawing</codeph> shows |
|
111 the percentage of Window Server activity that is spent drawing. </p> </li> |
|
112 <li id="GUID-C3A79CAD-AEB0-5689-8E2A-89DED30EE6EC"><p> <codeph>Reclaimed</codeph> shows |
|
113 the percentage of idle time reclaimed by the Window Server to perform drawing |
|
114 when there are is no higher priority activity. </p> </li> |
|
115 <li id="GUID-EA6E5DBB-7F1D-5CD9-A0F4-A2FE469CC906"><p> <codeph>RedrawStore |
|
116 size</codeph> shows the size in bytes of the redraw store—that is, the sum |
|
117 of the sizes of every redraw segment of every window currently owned by the |
|
118 Window Server. </p> </li> |
|
119 <li id="GUID-83A14FFE-5ED8-5C66-9FBB-251A462C9A5A"><p> <codeph>Updates</codeph> shows |
|
120 the number of screen updates per second. </p> </li> |
|
121 <li id="GUID-7310FFB7-5264-5E5C-9FC5-387920E2AEAF"><p> <codeph>Pixels</codeph> shows |
|
122 the number of pixels updated per second—that is, the pixel fill rate. </p> </li> |
|
123 </ul> </entry> |
|
124 <entry><p>Both </p> </entry> |
|
125 </row> |
|
126 <row> |
|
127 <entry><p> <codeph>DISABLEIDLEANIMATION</codeph> </p> </entry> |
|
128 <entry><p>The Window Server attempts to detect when the CPU is under light |
|
129 load and allows animations to go faster than the grace period under such circumstances. |
|
130 This feature is called <i>idle animation</i> and this parameter disables it. </p> <p>Symbian |
|
131 recommends that you always use this parameter, because there are numerous |
|
132 very short idle periods during application start up and running animations |
|
133 during these short idle periods slows down application start time. </p> <p>This |
|
134 parameter has no effect in the ScreenPlay variant, because idle animation |
|
135 is disabled by default in the ScreenPlay variant. </p> </entry> |
|
136 <entry><p>Non-ScreenPlay </p> </entry> |
|
137 </row> |
|
138 <row> |
|
139 <entry><p> <codeph>DSAANIMATIONGRACEPERIOD</codeph> <i>value</i> </p> </entry> |
|
140 <entry><p>Specifies the grace period (in microseconds) for Direct Screen Access |
|
141 (DSA) animations. The grace period is the length of time that the Window Server |
|
142 waits between DSA animation frames. If not specified this defaults to 35 milliseconds, |
|
143 in order to allow other threads to run. The animation grace period is a minimum |
|
144 period—the Window Server attempts to go faster if there is nothing else using |
|
145 the system. </p> </entry> |
|
146 <entry><p>Both </p> </entry> |
|
147 </row> |
|
148 <row> |
|
149 <entry><p> <codeph>FADEDISABLE</codeph> </p> </entry> |
|
150 <entry><p>Disables fading, which means that calls to the following functions |
|
151 have no visual effect on the Window Server's drawing: </p> <ul> |
|
152 <li id="GUID-C2F0C04F-E3D2-5EE9-A6DB-B0BDEFE92030"><p> <xref href="GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9.dita#GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9/GUID-16A33BE1-0181-3E2C-B563-20CD4C52049B"><apiname>RWsSession::SetSystemFaded()</apiname></xref> </p> </li> |
|
153 <li id="GUID-3CA1AA40-2215-517F-B63F-072298B602C8"><p> <xref href="GUID-1460DD8F-9AA1-3B99-8FFD-F309959CCA34.dita#GUID-1460DD8F-9AA1-3B99-8FFD-F309959CCA34/GUID-8B107A61-143A-39D0-B150-A724BDE12487"><apiname>RWindowBase::FadeBehind()</apiname></xref> </p> </li> |
|
154 <li id="GUID-947CA5D2-5227-51DB-A98E-60EADAC9519D"><p> <xref href="GUID-9FFD28C7-8747-3438-84BF-44AF26ACEC7D.dita#GUID-9FFD28C7-8747-3438-84BF-44AF26ACEC7D/GUID-317255C3-6CB3-3608-8104-53706BDBAFA0"><apiname>RWindowTreeNode::SetFaded()</apiname></xref> </p> </li> |
|
155 </ul> </entry> |
|
156 <entry><p>Both </p> </entry> |
|
157 </row> |
|
158 <row> |
|
159 <entry><p> <codeph>FINISHEVERYFLUSH</codeph> </p> </entry> |
|
160 <entry><p>Configures the behavior of <xref href="GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9.dita#GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9/GUID-B83C6F44-1A3E-3959-910C-CBBF66C4A3D4"><apiname>RWsSession::Flush()</apiname></xref>, |
|
161 so that the Window Server synchronizes the message buffer and forces the screen |
|
162 to update. If this parameter is not present, <codeph>Flush()</codeph> synchronizes |
|
163 the message buffer and does not guarantee to present any drawing commands |
|
164 within the buffer to the screen. </p> <p>Before the introduction of the Window |
|
165 Server improvements known as WSERV2, the Window Server, <codeph>Flush()</codeph> did |
|
166 two distinct things: </p> <ol id="GUID-73787DDB-B7B8-55A1-B5A0-D8A6FFD36D67"> |
|
167 <li id="GUID-9F73848F-F6D7-5A00-B150-208AD0540481"><p>Flushed the session's |
|
168 command buffer. </p> </li> |
|
169 <li id="GUID-7DAE082F-3768-589E-9287-A0A9D6852C3E"><p>Forced the presentation |
|
170 of any drawing commands to the screen. (This is a previously undocumented |
|
171 side effect of the old Window Server’s drawing behavior.) </p> </li> |
|
172 </ol> <p>By default <codeph>Flush()</codeph> now does the first of these steps |
|
173 only. Use <codeph>FINISHEVERYFLUSH</codeph> to cause <codeph>Flush()</codeph> to |
|
174 continue the previous behavior. </p> <p>In the improved Window Server (WServ2), |
|
175 there are two new methods that explicitly separate these two behaviors. The |
|
176 methods are <xref href="GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9.dita#GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9/GUID-1789E2F1-1291-39DE-861B-1851857A02AB"><apiname>RWsSession::SyncMsgBuf()</apiname></xref> and <xref href="GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9.dita#GUID-643DDA78-C7A7-386D-AB3F-8710141DDDA9/GUID-B431DC60-D11F-3239-8F52-4257B9B0E0C9"><apiname>RWsSession::Finish()</apiname></xref>. </p> </entry> |
|
177 <entry><p>Both </p> </entry> |
|
178 </row> |
|
179 <row> |
|
180 <entry><p> <codeph>FRAMECAPTURE</codeph> </p> </entry> |
|
181 <entry><p>This parameter is for use when debugging render stage plug-ins. |
|
182 When specified, the Window Server captures frame bitmaps and saves them in <filepath>frame_<timestamp>.mbm</filepath> files. |
|
183 These are located in the <filepath>epoc32\winscw\c</filepath> folder for winscw |
|
184 and <filepath>e:\storyboard\</filepath> for H4 boards. </p> <p>This option |
|
185 takes effect only when the Window Server and its plug-ins are compiled with |
|
186 the <codeph>USE_DEBUG_FRAME_CAPTURE</codeph> macro defined. </p> </entry> |
|
187 <entry><p>Both </p> </entry> |
|
188 </row> |
|
189 <row> |
|
190 <entry><p> <codeph>IGNORESWITCHOFFEVENT</codeph> </p> </entry> |
|
191 <entry><p>When specified and no shutdown manager is registered, all events |
|
192 that the Window Server passes to clients as OFF events are ignored. These |
|
193 events are <codeph>EEventSwitchOff</codeph>, <codeph>EEventCaseClosed</codeph>, <codeph>EEventKeySwitchOff</codeph> or <codeph>EEventRestartSystem</codeph>. </p> </entry> |
|
194 <entry><p>Both </p> </entry> |
|
195 </row> |
|
196 <row> |
|
197 <entry><p> <codeph>KEYCLICKPLUGIN</codeph> <i>filename</i> </p> </entry> |
|
198 <entry><p>The Window Server attempts to load the named key or pointer click |
|
199 plug-in DLL. If this fails or if this keyword does not appear, a plug-in is |
|
200 not used and key and pointer clicks are not enabled. </p> </entry> |
|
201 <entry><p>Both </p> </entry> |
|
202 </row> |
|
203 <row> |
|
204 <entry><p> <codeph>KEYCLICKPLUGINFIXED</codeph> </p> </entry> |
|
205 <entry><p>Stops Window Server clients from removing or changing the key or |
|
206 pointer click plug-in. Hardware manufacturers can use this keyword to disallow |
|
207 key or pointer clicks or force only one plug-in to be used. </p> </entry> |
|
208 <entry><p>Both </p> </entry> |
|
209 </row> |
|
210 <row> |
|
211 <entry><p> <codeph>LOG</codeph> <i>string</i> </p> </entry> |
|
212 <entry><p>Specifies the type of logging that is required. Loads one of the |
|
213 three logging DLLs, as specified by <i>string</i>. Possible values of <i>string</i> are: </p> <ul> |
|
214 <li id="GUID-901E83F0-F21E-56C2-AD2D-BAE394BF80C9"><p> <codeph>FL</codeph> — |
|
215 log to file </p> </li> |
|
216 <li id="GUID-AE205ACC-2A13-5950-B058-B552DA238B54"><p> <codeph>SR</codeph> — |
|
217 log to the serial port (MARM only) </p> </li> |
|
218 <li id="GUID-5FF305A9-1D2D-55CC-A970-3ED9EB9536BD"><p> <codeph>WN</codeph> — |
|
219 log to another WIN32 window (emulator only) </p> </li> |
|
220 </ul> </entry> |
|
221 <entry><p>Both </p> </entry> |
|
222 </row> |
|
223 <row> |
|
224 <entry><p> <codeph>LOGENABLE</codeph> <i>value</i> </p> </entry> |
|
225 <entry><p>If specified, enables logging from boot-up. You can optionally specify |
|
226 a value that must be one of the following: </p> <ul> |
|
227 <li id="GUID-A365CDBE-A9E7-5D7B-8E0A-7A3835E0D04E"><p>9 — Enables limited |
|
228 logging of Window Server messages, of the following types: loading of animation |
|
229 DLLs, application panics and all messages from the client side. </p> </li> |
|
230 <li id="GUID-C2DAFB31-E51C-58ED-B3D3-6123F3B96E46"><p>5 — Enables intermediate |
|
231 logging. This includes all the messages logged using limited logging, and |
|
232 adding and removing Window Server clients. </p> </li> |
|
233 <li id="GUID-3B61EC1F-2AA5-5EE6-891E-AA80BEA317E1"><p>1 — Enables full logging |
|
234 of all messages to and from the Window Server. This is the most commonly used |
|
235 option and is the default. </p> </li> |
|
236 </ul> </entry> |
|
237 <entry><p>Both </p> </entry> |
|
238 </row> |
|
239 <row> |
|
240 <entry><p> <codeph>LOGP</codeph> <i>filespec</i> </p> </entry> |
|
241 <entry><p>The fully qualified file name of the output log file. </p> </entry> |
|
242 <entry><p>Both </p> </entry> |
|
243 </row> |
|
244 <row> |
|
245 <entry><p> <codeph>MEMORYRESERVE</codeph> <i>value</i> </p> </entry> |
|
246 <entry><p>Sets the amount of memory that the Window Server's memory manager |
|
247 holds in reserve for use during critical sequences where the use is expected |
|
248 to be temporary. The memory reserve is not used for memory allocation failures |
|
249 and is currently used by the Window Server’s inner composition loop. </p> <p>If |
|
250 this parameter is not specified, the memory manager allocates 1024 bytes of |
|
251 memory to hold as its reserve. </p> </entry> |
|
252 <entry><p>Both </p> </entry> |
|
253 </row> |
|
254 <row> |
|
255 <entry><p> <codeph>MULTIFOCUSPOLICY</codeph> </p> </entry> |
|
256 <entry><p>Selects the Window Server multi-focus policy. This means that one |
|
257 window group on each screen all have focus. When this policy is not set, only |
|
258 one window group on one screen has focus. </p> <p>When a window group has <i>focus</i>, |
|
259 it means that the last focus event it received was a focus gained event rather |
|
260 than a focus lost event. The window group with focus is always the front-most |
|
261 focusable window group on its screen. </p> <p>This setting does not change |
|
262 the key event channeling policy. Key events are sent only to the focused window |
|
263 group on the focused screen (unless they are captured by another window). </p> </entry> |
|
264 <entry><p>Both </p> </entry> |
|
265 </row> |
|
266 <row> |
|
267 <entry><p> <codeph>NOBLANKSCREEN</codeph> </p> </entry> |
|
268 <entry><p>Use this keyword if, at boot time, you need to delay blanking the |
|
269 screen until the shell has started a session with the Window Server. </p> <p>Note |
|
270 that you specify the name of the shell by using the <codeph>STARTUP</codeph> parameter. </p> </entry> |
|
271 <entry><p>Both </p> </entry> |
|
272 </row> |
|
273 <row> |
|
274 <entry><p> <codeph>NONREDRAWAGELIMIT</codeph> <i>duration</i> </p> </entry> |
|
275 <entry><p>The lifetime in microseconds of non-redraw segments within the <xref href="GUID-0AD34BA6-D0C5-5AD7-B8E1-F737BB5FC0AC.dita">redraw stores</xref> in the |
|
276 non-ScreenPlay variant only. </p> <p>Non-redraw drawing (that is, drawing |
|
277 commands that are issued outside of Begin/End Redraw) are placed into a special |
|
278 non-redraw segment in the redraw store. To prevent these non-redraw segments |
|
279 from growing indefinitely as non-redraw commands are added to them, a limit |
|
280 is imposed on their life time within the redraw store. When adding non-redraw |
|
281 commands to the redraw store, the Window Server: </p> <ul> |
|
282 <li id="GUID-0257C4CF-7DCB-5F67-9A22-5F59347992A2"><p>checks the ages of the |
|
283 non-redraw segments within the store </p> </li> |
|
284 <li id="GUID-B923ED52-EF59-520F-9DC1-1C564858F12C"><p>discards any old non-redraw |
|
285 segments and if necessary requests a client-side redraw </p> </li> |
|
286 <li id="GUID-D0D64A40-8E46-5153-97EA-75C929C9B2E0"><p>creates a new non-redraw |
|
287 segment for new non-redraw commands. </p> </li> |
|
288 </ul> <p>The <codeph>NONREDRAWAGELIMIT</codeph> parameter allows for the customization |
|
289 of the age limit. If not defined, a default of 1,000,000 microseconds or 1 |
|
290 second is used. </p> </entry> |
|
291 <entry><p>Non-ScreenPlay </p> </entry> |
|
292 </row> |
|
293 <row> |
|
294 <entry><p> <codeph>ONINACTIVE</codeph> <i>value</i> </p> </entry> |
|
295 <entry><p>Specifies what happens when there is no key or pointer activity |
|
296 for a period of time. Possible values are: </p> <ul> |
|
297 <li id="GUID-051742BE-A01D-5C50-8C7D-2F0A494B3B7E"><p> <codeph>STOPANIMATION</codeph> — |
|
298 this means continue client-side redraws and stop all server-side drawing. |
|
299 This is the most obvious option. </p> </li> |
|
300 <li id="GUID-77282032-A0F8-5264-A03B-137C9B56B90D"><p> <codeph>STOPALLDRAWING</codeph> — |
|
301 this stops both client-side and server-side drawing. </p> </li> |
|
302 <li id="GUID-5C4F0C0C-6200-5F0D-B314-30717D859655"><p> <codeph>IGNORE</codeph> — |
|
303 this means ignore the inactivity and draw as normal. </p> </li> |
|
304 </ul> </entry> |
|
305 <entry><p>Both </p> </entry> |
|
306 </row> |
|
307 <row> |
|
308 <entry><p> <codeph>PLUGINS</codeph> <i>string</i> </p> </entry> |
|
309 <entry><p>Specifies the complete list of plug-ins that the Window Server’s |
|
310 plug-in manager is to load. For each plug-in that you specify, create a separate |
|
311 section in the <filepath>wsini.ini</filepath> file to specify its details |
|
312 (such as UID and type). See <xref href="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69.dita#GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69/GUID-71ABB4DF-8C79-598F-BD4C-AC1EDD52AA04">Plug-in |
|
313 Parameters</xref> for more information. </p> <p>If not specified, the plug-in |
|
314 manager loads the default plug-ins. In the ScreenPlay variant, these are <i>flickerbuffer</i> and <i>display</i>. |
|
315 In the non-ScreenPlay variant, they are <i>flickerbuffer</i>, <i>std </i> and <i>defaultfader</i>. </p> <p>If |
|
316 the default plug-ins are required, include them in the plug-in list. For example, |
|
317 in ScreenPlay, the following instructs the plug-in manager to load a custom |
|
318 plug-in called <i>newplugin</i> in addition to the default plug-ins: </p> <codeblock id="GUID-E4314976-ABD7-597B-883E-567AB824BB00" xml:space="preserve">PLUGINS flickerbuffer display newplugin</codeblock> </entry> |
|
319 <entry><p>Both </p> </entry> |
|
320 </row> |
|
321 <row> |
|
322 <entry><p> <codeph>PROTECTEDKEY</codeph> <i>keyvalue</i> </p> <p> <codeph>PROTECTEDKEYWINDOWNAME</codeph> <i>windowgroupname</i> </p> </entry> |
|
323 <entry><p>'Protects' a key, so that it can only be captured (by calling <xref href="GUID-64D4D428-D65F-3D9D-A0D4-C8338C848B25.dita#GUID-64D4D428-D65F-3D9D-A0D4-C8338C848B25/GUID-433AD95D-5F34-3AB2-A077-E9AED2CF0AED"><apiname>RWindowGroup::CaptureKey()</apiname></xref> or <xref href="GUID-64D4D428-D65F-3D9D-A0D4-C8338C848B25.dita#GUID-64D4D428-D65F-3D9D-A0D4-C8338C848B25/GUID-7FCBF67B-8E89-39D2-8E3E-8F4606C06F66"><apiname>RWindowGroup::CaptureKeyUpAndDowns()</apiname></xref>) by the window group identified by the <codeph>PROTECTEDKEYWINDOWNAME</codeph> parameter. </p> <p>Only |
|
324 one key can be protected in this way. This means that these two parameters |
|
325 must not appear more than once in the <filepath>wsini.ini</filepath> file. </p> <p>When |
|
326 a client attempts to capture a standard key event (rather than a key up or |
|
327 down event), <i>keyvalue</i> is matched against the key code (as defined in |
|
328 the <xref href="GUID-B67B6ED5-6C8F-3B36-934C-B47A109A515F.dita"><apiname>TKeyCode</apiname></xref> enum in <filepath>e32keys.h</filepath>) to |
|
329 see if the key is protected or not. </p> <p>When a client attempts to capture |
|
330 an up or down key event, <i>keyvalue</i> is matched against the scan code |
|
331 (as defined in the <xref href="GUID-4D92CE24-E651-3584-BDE0-F26046B4175B.dita"><apiname>TStdScanCode</apiname></xref> enum in <filepath>e32keys.h</filepath>) |
|
332 to see if the key is protected or not. </p> <p>Note that for many keys, the |
|
333 scan code and key code are the same, so this mechanism can by used to protect |
|
334 against the capture of both standard events and up/down events for these keys. </p> <p>You |
|
335 can specify <i>keyvalue</i> as a hexadecimal or decimal number. </p> <p> <i>windowgroupname</i> is |
|
336 the window group name (see <xref href="GUID-64D4D428-D65F-3D9D-A0D4-C8338C848B25.dita#GUID-64D4D428-D65F-3D9D-A0D4-C8338C848B25/GUID-FD28C803-2C90-3B73-91C5-869A85A2FEE8"><apiname>RWindowGroup::SetName()</apiname></xref>) or |
|
337 a substring of it. </p> </entry> |
|
338 <entry><p>Both </p> </entry> |
|
339 </row> |
|
340 <row> |
|
341 <entry><p> <codeph>REBOOT</codeph> <i>value</i> </p> </entry> |
|
342 <entry><p>The shell reboot mode. The following values are defined: </p> <ul> |
|
343 <li id="GUID-64F0EE9D-6E79-5BCA-932E-E68843037FA8"><p>0 — the Window Server |
|
344 tries to restart the shell as soon as the shell dies or exits. </p> </li> |
|
345 <li id="GUID-9F6B4509-2948-52E8-98AB-9E1D0C9E9608"><p>1 — the Window Server |
|
346 tries to restart the shell only if all other Window Server clients have exited. |
|
347 The Window Server detects an application exiting by its Window Server session |
|
348 being closed. However, in rare cases, an application may not have a Window |
|
349 Server session, or it may close its session without exiting. In such cases, |
|
350 the shell may restart even though some applications are still running. </p> </li> |
|
351 <li id="GUID-BA62D1DA-BC1C-5F1F-B225-077D3F20FEB0"><p>2 — the Window Server |
|
352 shuts down the machine as soon as the shell dies or exits — <b>for use during |
|
353 development only</b> . </p> </li> |
|
354 </ul> </entry> |
|
355 <entry><p>Both </p> </entry> |
|
356 </row> |
|
357 <row> |
|
358 <entry><p> <codeph>REDRAWGRACEPERIOD</codeph> <i>value</i> </p> </entry> |
|
359 <entry><p>Specifies the grace period (in microseconds) for redraws within |
|
360 the Window Server. The redraw grace period is the length of time the Window |
|
361 Server waits before performing a redraw. If not specified, the grace period |
|
362 defaults to zero, which means that the Window Server endeavors to perform |
|
363 redraws immediately. The redraw grace period is a minimum time—the Window |
|
364 Server attempts to go faster if there is nothing else using the system. </p> </entry> |
|
365 <entry><p>Both </p> </entry> |
|
366 </row> |
|
367 <row> |
|
368 <entry><p> <codeph>REPEATROLLOVER</codeph> <i>value</i> </p> </entry> |
|
369 <entry><p>Specify this parameter with value of 1 in order to allow key repeat |
|
370 rollovers. </p> </entry> |
|
371 <entry><p>Both </p> </entry> |
|
372 </row> |
|
373 <row> |
|
374 <entry><p> <codeph>ROOTBACKGROUNDALPHA</codeph> <i>value</i> </p> </entry> |
|
375 <entry><p>Sets the alpha value of the background color of the root window |
|
376 independently from the alpha value of the default background color of other |
|
377 windows. In the non-ScreenPlay variant, you can use this to make the initial |
|
378 background in the Window Server frame buffer transparent. If any windows in |
|
379 front are also transparent, this may lead to transparent pixels in the Window |
|
380 Server frame buffer at the end of rendering. This provides a technique for |
|
381 showing effects (such as particle effects) behind the Window Server frame |
|
382 buffer. </p> <p>This parameter is not used in the ScreenPlay variant, because |
|
383 this and similar use cases can be achieved by adding a background surface |
|
384 to a window. This results in that window's area in the frame buffer (now called |
|
385 the UI surface) being transparent. </p> <p>Specify <i>value</i> as an integer |
|
386 in the range 0–255. If this parameter is not specified, the alpha value of |
|
387 the root window’s background color is set to the alpha value of the default |
|
388 background color—that is, the value set by <codeph>BACKGROUNDALPHA</codeph> or <codeph>0xFF</codeph>, |
|
389 if it is not specified. </p> </entry> |
|
390 <entry><p>Non-ScreenPlay </p> </entry> |
|
391 </row> |
|
392 <row> |
|
393 <entry><p> <codeph>ROOTBACKGROUNDCOLOR</codeph> <i>value</i> </p> </entry> |
|
394 <entry><p>The background color of the root window, if you want to set it independently |
|
395 from the default background color of other windows. </p> <p>If not used, the |
|
396 root window’s background color is set to the default background window value—that |
|
397 is, the value set by <codeph>BACKGROUNDCOLOR</codeph> or <codeph>KRgbWhite</codeph> if |
|
398 it is not specified. </p> </entry> |
|
399 <entry><p>Both </p> </entry> |
|
400 </row> |
|
401 <row> |
|
402 <entry><p> <codeph>SHELLCMD</codeph> <i>string</i> </p> </entry> |
|
403 <entry><p>Specifies the command line argument to pass when starting the shell. |
|
404 This is similar to DOS command parameters under Microsoft Windows. </p> <p>Defaults |
|
405 to an empty string. </p> </entry> |
|
406 <entry><p>Both </p> </entry> |
|
407 </row> |
|
408 <row> |
|
409 <entry><p> <codeph>STARTUP</codeph> <i>string</i> </p> </entry> |
|
410 <entry><p>Specifies the name of the shell to use. Defaults to <filepath>shell</filepath>. </p> </entry> |
|
411 <entry><p>Both </p> </entry> |
|
412 </row> |
|
413 </tbody> |
|
414 </tgroup> |
|
415 </table> </section> |
|
416 <section id="GUID-794DD7D2-83DD-50E8-822C-A8AC0D123EE5"><title>Screen-specific |
|
417 parameters</title> <p>These parameters are screen specific and you can specify |
|
418 them separately for each screen. Do this by creating a section for each screen |
|
419 and use the <codeph>[SCREEN</codeph> <i>n</i> <codeph>]</codeph> keyword to |
|
420 indicate the start of each section. </p> <p>In a single-screen device, put |
|
421 these parameters in the first (<codeph>[DEFAULT]</codeph>) section and not |
|
422 in a separate section. In a multi-screen phone, you can put any screen-related |
|
423 parameters that apply to all screens in the first (<codeph>[DEFAULT]</codeph>) |
|
424 section. </p> <p>Each screen can have several <i>screen modes</i> (such as |
|
425 portrait and landscape), identified by a zero-based index. Some of the screen-specific |
|
426 parameters relate to the screen mode. For example, in the non-ScreenPlay variant |
|
427 you can use the <codeph>SCR_LEFT</codeph>, <codeph>SCR_TOP</codeph>, <codeph>SCR_XSCALE</codeph> and <codeph>SCR_YSCALE</codeph> parameters |
|
428 to change the origin of top-level windows and a scaling factor for each mode |
|
429 of every screen. Some of these parameters are not supported or work differently |
|
430 in ScreenPlay. See <xref href="GUID-0EBE5733-A267-5F4A-85AD-87C3ECF80731.dita">Dynamic |
|
431 Resolution Switching</xref> for more information. </p> <table id="GUID-4FF083DC-0AF1-56F9-A8BE-7F1E0F510359"> |
|
432 <tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/> |
|
433 <thead> |
|
434 <row> |
|
435 <entry>Keyword/Parameter </entry> |
|
436 <entry>Description </entry> |
|
437 <entry>Variant </entry> |
|
438 </row> |
|
439 </thead> |
|
440 <tbody> |
|
441 <row> |
|
442 <entry><p> <codeph>[SCREEN</codeph> <i>n</i> <codeph>]</codeph> </p> </entry> |
|
443 <entry><p>A <filepath>wsini.ini</filepath> file may be divided into sections |
|
444 to support phones with multiple screens. Each section that is preceded by |
|
445 this keyword contains the parameters whose value applies to one screen only. </p> <p>The <i>n</i> value |
|
446 is a number that indicates which screen the section applies to. For instance, <codeph>[SCREEN0]</codeph> is |
|
447 the first screen, <codeph>[SCREEN1]</codeph> the second. </p> <p>If the device |
|
448 does not support multiple screens, this keyword should not appear in the <filepath>wsini.ini</filepath> file. </p> </entry> |
|
449 <entry><p>Both </p> </entry> |
|
450 </row> |
|
451 <row> |
|
452 <entry><p> <codeph>AUTOCLEAR</codeph> <i>value</i> </p> </entry> |
|
453 <entry><p>When an <codeph>RWindow</codeph> is manipulated by an application, |
|
454 this parameter determines whether the invalid region is cleared to its background |
|
455 color (as set by either variant of <xref href="GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79.dita#GUID-683603DD-F3D3-3193-BEB3-8236C7DE7F79/GUID-6608DEE5-8F59-33B4-A998-73C23FDBBFAA"><apiname>RWindow::SetBackgroundColor()</apiname></xref>) |
|
456 before being redrawn. The possible values are: </p> <ul> |
|
457 <li id="GUID-A2E47136-EB18-5DE5-AEF9-FC5C6090A487"><p>0 — the background is |
|
458 not cleared, even if a background color has been set. This is for use in debugging |
|
459 only. </p> </li> |
|
460 <li id="GUID-2CC9C730-33F8-5F8E-9439-358F66555DCD"><p>1 — the default. The |
|
461 background is cleared if a background color has been set, but not if no background |
|
462 color has been set. </p> </li> |
|
463 </ul> </entry> |
|
464 <entry><p>Both </p> </entry> |
|
465 </row> |
|
466 <row> |
|
467 <entry><p> <codeph>BACKLIGHTCONTROL</codeph> </p> </entry> |
|
468 <entry><p>Enables calls to <xref href="GUID-30479BE3-296E-3B4D-914D-B080ABD733E4.dita#GUID-30479BE3-296E-3B4D-914D-B080ABD733E4/GUID-F23C4215-C8B3-3E4D-9CC8-4D56BEC1E503"><apiname>CWsScreenDevice::SetBackLight()</apiname></xref>. |
|
469 If this parameter is not specified, this function returns <codeph>KErrPermissionDenied</codeph>. </p> </entry> |
|
470 <entry><p>Both </p> </entry> |
|
471 </row> |
|
472 <row> |
|
473 <entry><p> <codeph>BLANKSCREENONROTATION</codeph> </p> </entry> |
|
474 <entry><p>Causes the Window Server to blank the screen after changing the |
|
475 orientation. If this parameter is not specified, screen content persists when |
|
476 the orientation changes. </p> </entry> |
|
477 <entry><p>Both </p> </entry> |
|
478 </row> |
|
479 <row> |
|
480 <entry><p> <codeph>BLTOFFSCREENBITMAP</codeph> </p> </entry> |
|
481 <entry><p>If this is specified in the non-ScreenPlay variant, the invalid |
|
482 region of the offscreen bitmap is not set to white or the background color, |
|
483 but is instead copied from the screen. </p> <p>This might reduce flicker if |
|
484 not all the pixels in the invalid region are redrawn. Users should be aware, |
|
485 however, that fading and shadowing are applied when copying from the off-screen |
|
486 buffer to the screen. It is possible that some pixels may be doubly shadowed |
|
487 or doubly faded when using this keyword. Another possible side-effect is that |
|
488 artefacts of sprites may get left behind. </p> </entry> |
|
489 <entry><p>Non-ScreenPlay </p> </entry> |
|
490 </row> |
|
491 <row> |
|
492 <entry><p> <codeph>CHANGETRACKING</codeph> </p> </entry> |
|
493 <entry><p>Changes the mode of the Window Server rendering loop from the default |
|
494 dirty-rectangle mode to change-tracking mode. Typically change-tracking mode |
|
495 is used only when a transition effects (TFX) render stage is in use, which |
|
496 builds up its own visuals stores. See <xref href="GUID-22093E74-EFE7-5642-93DE-1573E18F7C08.dita">Window |
|
497 Server Rendering Loop</xref> for more information. </p> </entry> |
|
498 <entry><p>ScreenPlay </p> </entry> |
|
499 </row> |
|
500 <row> |
|
501 <entry><p> <codeph>CHROMAKEYCOLOR</codeph> <i>value</i> </p> </entry> |
|
502 <entry><p>Specifies the chroma key color that the composition engine considers |
|
503 transparent for chroma keying transparency. The specified color must not be |
|
504 used in images on the layer other than to indicate transparency. </p> <p>Enter |
|
505 the value in the form <codeph>0xff</codeph> <i>rrggbb</i>, where <i>rr</i> is |
|
506 the hex value for red, <i>gg</i> for green and <i>bb</i> for blue. For example: </p> <codeblock id="GUID-3693500F-FCBE-53FC-B74B-899CA1105049" xml:space="preserve">CHROMAKEYCOLOR 0xFF123456</codeblock> <p>If |
|
507 this parameter is not specified, the default value is 0. </p> <p>Note: Chroma |
|
508 key transparency is not used in <codeph>EColor16MA</codeph> and <codeph>EColor16MAP</codeph> display |
|
509 modes. This is because they are RGBA modes and therefore have an alpha value |
|
510 in addition to the RGB value. </p> </entry> |
|
511 <entry><p>ScreenPlay </p> </entry> |
|
512 </row> |
|
513 <row> |
|
514 <entry><p> <codeph>DEBUGOSB</codeph> </p> </entry> |
|
515 <entry><p>Enables you to use Win32-dependent code for debugging the Window |
|
516 Server offscreen buffer and UI surface for each screen on the emulator. </p> </entry> |
|
517 <entry><p>Both </p> </entry> |
|
518 </row> |
|
519 <row> |
|
520 <entry><p> <codeph>DP_SCALING</codeph> <i>string</i> </p> </entry> |
|
521 <entry><p>This is used by the ScreenPlay render stage plug-ins that are supplied |
|
522 in the Window Server Plugins component. This parameter may therefore not be |
|
523 used—for example, if the supplied render stages are replaced. When it is used, |
|
524 it controls the type of scaling that the render stages perform. The value |
|
525 can be one of the following: </p> <ul> |
|
526 <li id="GUID-B8BC842B-CC3F-5E8E-8460-8BEE036A213C"><p>integer — this allows |
|
527 only virtual resolutions that are integer divisors of the physical resolution |
|
528 and sets a limit of four; that is, ½, 1/3 and 1/4. For example, for a real |
|
529 resolution dimension of 720 pixels, virtual resolution dimensions of 360, |
|
530 240 and 180 are allowed. </p> </li> |
|
531 <li id="GUID-DBE122E0-E894-5C43-B724-67AC96A43A99"><p>isotropic — this allows |
|
532 any scaling factor, not only integer ones. However, the horizontal and the |
|
533 vertical scaling factors are the same. </p> </li> |
|
534 <li id="GUID-210D6671-E0CF-51CF-B5A6-18A1B8641A77"><p>anisotropic — this allows |
|
535 any scaling factor and does not restrict the relationship between the horizontal |
|
536 and vertical scaling factors. </p> </li> |
|
537 </ul> <p>Any other value is taken to mean no scaling. </p> </entry> |
|
538 <entry><p>ScreenPlay </p> </entry> |
|
539 </row> |
|
540 <row> |
|
541 <entry><p> <codeph>FADER</codeph> <i>string</i> </p> </entry> |
|
542 <entry><p>Specifies a custom fader plug-in to be used. If not specified the |
|
543 default fader plug-in implementation is used. This simply performs a BitGDI <codeph>FadeArea</codeph> when |
|
544 windows are faded. </p> <p>In the non-ScreenPlay variant, handset manufacturers |
|
545 can create custom fader plug-ins to create different fading effects. (In the |
|
546 ScreenPlay variant, fading effects can be created using render stage plug-ins.) |
|
547 Fader plug-ins must also be specified using the <codeph>PLUGINS</codeph> parameter |
|
548 in order to be loaded. </p> <p>Fader plugins are specified per screen so it |
|
549 is possible to use different fading effects on different screens. Here is |
|
550 a simplified example: </p> <codeblock id="GUID-42879770-B76E-5F15-8EC0-ACA6ACC6AB93" xml:space="preserve">PLUGINS flickerbuffer std defaultfader customfaderA customfaderB |
|
551 SCREEN[0] |
|
552 FADER customfaderA |
|
553 SCREEN[1] |
|
554 FADER customfaderB |
|
555 </codeblock> <p> <b>Note</b>: Fading is essentially disabled in the non-ScreenPlay |
|
556 variant if a custom fader is not specified using the <codeph>FADER</codeph> parameter |
|
557 and the <codeph>PLUGINS</codeph> command is overridden so that the default |
|
558 fader plugin is not loaded. </p> </entry> |
|
559 <entry><p>Non-ScreenPlay </p> </entry> |
|
560 </row> |
|
561 <row> |
|
562 <entry><p> <codeph>FLICKERBUFFERMODE</codeph> <i>value</i> </p> </entry> |
|
563 <entry><p>The <codeph>TDisplayMode</codeph> of the flicker buffer if one is |
|
564 in use. If not specified, the flicker buffer has the same color depth as the |
|
565 screen. </p> </entry> |
|
566 <entry><p>Both </p> </entry> |
|
567 </row> |
|
568 <row> |
|
569 <entry><p> <codeph>NUMSCREENMODES</codeph> <i>value</i> </p> </entry> |
|
570 <entry><p>Removes the requirement that screen mode indexes must be consecutive. |
|
571 This enables UI factories to implement sparse index schemes and allows the |
|
572 screen mode index to have a particular meaning within the context of a UI. </p> <p>The <i>value</i> is |
|
573 a positive integer which specifies the highest screen mode index that is defined |
|
574 in the <filepath>wsini.ini</filepath> file. </p> <p>For example, in the following |
|
575 example, the last 3 lines would be ignored, unless <codeph>NUMSCREENMODES |
|
576 3</codeph> was specified beforehand: </p> <codeblock id="GUID-90042EF5-30BC-5864-A310-58043BE8A190" xml:space="preserve">SCR_WIDTH1 800 |
|
577 SCR_HEIGHT1 600 |
|
578 SCR_ROTATION1 180 |
|
579 SCR_WIDTH3 240 |
|
580 SCR_HEIGHT3 160 |
|
581 SCR_ROTATION3 270</codeblock> </entry> |
|
582 <entry><p>Both </p> </entry> |
|
583 </row> |
|
584 <row> |
|
585 <entry><p> <codeph>RENDERSTAGES</codeph> <i>string</i> </p> </entry> |
|
586 <entry><p>Specifies the type and order of the render stages to be used by |
|
587 the Window Server. </p> <p>If not defined, this defaults to <codeph>flickerbuffer |
|
588 display</codeph> in the ScreenPlay variant and <codeph>flickerbuffer |
|
589 std</codeph> in the non-ScreenPlay variant. This means that by default, the |
|
590 Window Server pipes its drawing through the flicker buffer render stage and |
|
591 then on to the <i>display</i> (called <i>std</i> in the non-ScreenPlay variant) |
|
592 render stage, which draws it to the screen. </p> <p>The render stages are |
|
593 plug-ins and you must also specify them in the <codeph>PLUGINS</codeph> parameter |
|
594 in order to be loaded. </p> </entry> |
|
595 <entry><p>Both </p> </entry> |
|
596 </row> |
|
597 <row> |
|
598 <entry><p> <codeph>SCREENMODE COLOR</codeph><i>value</i> ¦ <codeph>GRAY</codeph><i>value</i> </p> </entry> |
|
599 <entry><p>Specifies the display mode to be used for the screen device. The <codeph>COLOR</codeph> or <codeph>GRAY</codeph> prefix |
|
600 plus <i>value</i> must correspond to a member of the <xref href="GUID-19EFD25B-30D5-3BC3-80FB-2E4769203EDF.dita"><apiname>TDisplayMode</apiname></xref> enumerated |
|
601 type but without the initial <codeph>E</codeph>. </p><p>For example, <codeph>SCREENMODE |
|
602 COLOR16M</codeph> corresponds to <codeph>EColor16M</codeph> and gives a display |
|
603 mode of 16 million colors.</p> <p>If this parameter is not specified, |
|
604 or a screen device cannot be created in the specified depth, the default is |
|
605 the highest color mode available, up to <codeph>Color16MAP</codeph>. </p><p> <b>Note</b>: |
|
606 This parameter replaces the deprecated <codeph>WINDOWMODE</codeph> parameter. </p> </entry> |
|
607 <entry><p>Both </p> </entry> |
|
608 </row> |
|
609 <row> |
|
610 <entry><p> <codeph>SCR_LEFT</codeph> <i>n</i> <i>value</i> </p> </entry> |
|
611 <entry><p>The horizontal offset in pixels for a particular screen mode. Moves |
|
612 the screen's contents to the left. By default this is zero. </p> <p> <i>n</i> is |
|
613 an integer greater than zero that identifies the screen mode. <i>value</i> is |
|
614 the offset in pixels (greater than zero). </p> <p>In ScreenPlay, this parameter |
|
615 may be ignored (or used as a minimum margin hint) by the render stage chain, |
|
616 in order to position the screen mode more appropriately. However, it may be |
|
617 important to specify the offset for screen modes hosting legacy applications |
|
618 because it is also used for the DSA buffer for backwards compatibility reasons. |
|
619 See <xref href="GUID-0EBE5733-A267-5F4A-85AD-87C3ECF80731.dita">Dynamic Resolution |
|
620 Switching</xref> for more information. </p> </entry> |
|
621 <entry><p>Both </p> </entry> |
|
622 </row> |
|
623 <row> |
|
624 <entry><p> <codeph>SCR_TOP</codeph> <i>n</i> <i>value</i> </p> </entry> |
|
625 <entry><p>The vertical offset in pixels for a particular screen mode. Moves |
|
626 the screen's contents upwards. By default this is zero. </p> <p> <i>n</i> is |
|
627 an integer greater than zero that identifies the screen mode. <i>value</i> is |
|
628 the offset in pixels (greater than zero). </p> <p>In ScreenPlay, this parameter |
|
629 may be ignored (or used as a minimum margin hint) by the render stage chain, |
|
630 in order to position the screen mode more appropriately. However, it may be |
|
631 important to specify the offset for screen modes hosting legacy applications |
|
632 because it is also used for the DSA buffer for backwards compatibility reasons. |
|
633 See <xref href="GUID-0EBE5733-A267-5F4A-85AD-87C3ECF80731.dita">Dynamic Resolution |
|
634 Switching</xref> for more information. </p> </entry> |
|
635 <entry><p>Both </p> </entry> |
|
636 </row> |
|
637 <row> |
|
638 <entry><p> <codeph>SCR_XSCALE</codeph> <i>n</i> <i>factor</i> </p> </entry> |
|
639 <entry><p>The horizontal screen scaling factor for a particular screen mode. </p> <p> <i>n</i> is |
|
640 the screen mode and <i>factor</i> is the scaling factor (a positive integer). |
|
641 1 (the default) means no scaling. For example, specifying the following means |
|
642 that in the first screen mode, everything is drawn four times larger: </p> <codeblock id="GUID-51F8C455-837F-5664-A691-AB1EEAC7CF32" xml:space="preserve">SCR_XSCALE1 2 |
|
643 SCR_YSCALE1 2</codeblock> <p>In other words, drawing to logical pixel (0,0) |
|
644 causes physical pixels (0,0), (0,1), (1,0) and (1,1) to change. </p> <p>Note |
|
645 that on the emulator, screen scaling only works if the display mode is <codeph>Color256</codeph>. </p> <p>If |
|
646 an offset is specified (using <codeph>SCR_LEFT</codeph> or <codeph>SCR_TOP</codeph>) |
|
647 as well as a scaling factor, the offset is applied in unscaled coordinates. |
|
648 For example, suppose the following values are specified: </p> <codeblock id="GUID-7DF011F5-C559-5E85-8F99-77FA5FD9DB37" xml:space="preserve">SCR_LEFT1 5 |
|
649 SCR_XSCALE1 2</codeblock> <p>This means that the mapping between logical and |
|
650 physical pixels for the first screen mode is as follows: </p> <p><table id="GUID-696B38E9-CED3-58BF-A512-99586644F71E"> |
|
651 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
652 <tbody> |
|
653 <row> |
|
654 <entry><p> <b>Logical</b> </p> </entry> |
|
655 <entry><p> <b>Physical</b> </p> </entry> |
|
656 </row> |
|
657 <row> |
|
658 <entry><p>x=0 </p> </entry> |
|
659 <entry><p>x=5,6 </p> </entry> |
|
660 </row> |
|
661 <row> |
|
662 <entry><p>x=1 </p> </entry> |
|
663 <entry><p>x=7,8 </p> </entry> |
|
664 </row> |
|
665 <row> |
|
666 <entry><p>x=2 </p> </entry> |
|
667 <entry><p>x=9,10 </p> </entry> |
|
668 </row> |
|
669 <row> |
|
670 <entry><p>x=-1 </p> </entry> |
|
671 <entry><p>x=3,4 </p> </entry> |
|
672 </row> |
|
673 <row> |
|
674 <entry><p>x=-2 </p> </entry> |
|
675 <entry><p>x=1,2 </p> </entry> |
|
676 </row> |
|
677 <row> |
|
678 <entry><p>x=-3 </p> </entry> |
|
679 <entry><p>x=0 </p> </entry> |
|
680 </row> |
|
681 <row> |
|
682 <entry><p>x=45 </p> </entry> |
|
683 <entry><p>x=95,96 </p> </entry> |
|
684 </row> |
|
685 <row> |
|
686 <entry><p>x=46 </p> </entry> |
|
687 <entry><p>x=97,98 </p> </entry> |
|
688 </row> |
|
689 <row> |
|
690 <entry><p>x=47 </p> </entry> |
|
691 <entry><p>x=99 </p> </entry> |
|
692 </row> |
|
693 </tbody> |
|
694 </tgroup> |
|
695 </table> </p> <p>In this example, there are 51 addressable logical pixels. </p> <p>See |
|
696 also <xref href="GUID-30479BE3-296E-3B4D-914D-B080ABD733E4.dita#GUID-30479BE3-296E-3B4D-914D-B080ABD733E4/GUID-F442A58F-E559-3308-B6D9-9675447ED223"><apiname>CWsScreenDevice::GetScreenModeScale()</apiname></xref>, <xref href="GUID-30479BE3-296E-3B4D-914D-B080ABD733E4.dita#GUID-30479BE3-296E-3B4D-914D-B080ABD733E4/GUID-A8BD6475-3EC1-380D-88F9-AFE6B5DAA9E8"><apiname>CWsScreenDevice::GetCurrentScreenModeScale()</apiname></xref> </p> <p>This |
|
697 parameter is not used in ScreenPlay, because the UI pixel buffers (in the |
|
698 full UI area) are not scaled relative to the application's view. Instead the |
|
699 full UI area is mapped to the full composition/display area, if necessary |
|
700 using a virtual resolution. This provides a better facility and is completely |
|
701 under the control of the render stage chain rather than Window Server. See <xref href="GUID-0EBE5733-A267-5F4A-85AD-87C3ECF80731.dita">Dynamic Resolution Switching</xref> for |
|
702 more information. </p> </entry> |
|
703 <entry><p>Non-ScreenPlay </p> </entry> |
|
704 </row> |
|
705 <row> |
|
706 <entry><p> <codeph>SCR_YSCALE</codeph> <i>n</i> <i>factor</i> </p> </entry> |
|
707 <entry><p>The vertical screen scaling factor for a particular screen mode. |
|
708 See <codeph>SCR_XSCALE</codeph> for a description. </p> </entry> |
|
709 <entry><p>Non-ScreenPlay </p> </entry> |
|
710 </row> |
|
711 <row> |
|
712 <entry><p> <codeph>SCR_ROTATION</codeph> <i>n rotations</i> </p> </entry> |
|
713 <entry><p>Specifies a list of screen rotations for a particular screen mode. </p> <p>The <i>n</i> value |
|
714 is a positive integer which corresponds to a particular screen mode. </p> <p>The <i>rotations</i> value |
|
715 is a comma separated list that specifies, in degrees, the rotation values |
|
716 available for the given screen mode. For example: </p> <codeblock id="GUID-1258D3A3-F067-57E1-AF1C-38206D74D1E7" xml:space="preserve">SCR_ROTATION2 90,270</codeblock> <p>Note: While rotation is supported on the Symbian platform, it requires support |
|
717 in the UI to render screen furniture correctly. For example, Techview shows |
|
718 proof-of-concept rotation to profile screens. However, it is designed with |
|
719 a landscape orientation, which means that in other orientations it does not |
|
720 render the toolbar, and some menus are truncated. </p> </entry> |
|
721 <entry><p>Both </p> </entry> |
|
722 </row> |
|
723 <row> |
|
724 <entry><p> <codeph>SCR_WIDTH</codeph> <i>n</i> <i>width</i> </p> </entry> |
|
725 <entry><p>The screen width in pixels for a particular screen mode. The screen |
|
726 mode is set by <i>n</i> and <i>width</i> is the width in pixels. </p> <p>For |
|
727 example, the following sets a width of 240 pixels for screen mode 2: </p> <codeblock id="GUID-81982D9B-993A-5A69-B1D0-C894395C5D32" xml:space="preserve">SCR_WIDTH2 240</codeblock> <p>In |
|
728 the non-ScreenPlay variant, this value should be the same as, or smaller than, |
|
729 the actual screen size as defined by the screen driver, after taking into |
|
730 account the rotation, the top-left offset and any scaling. </p> <p>In ScreenPlay, |
|
731 to define a dynamic screen mode, set this and <codeph>SCR_HEIGHT</codeph> <i>n</i> to |
|
732 -1. See <xref href="GUID-0EBE5733-A267-5F4A-85AD-87C3ECF80731.dita">Dynamic Resolution |
|
733 Switching</xref> for more information. </p> </entry> |
|
734 <entry><p>Both </p> </entry> |
|
735 </row> |
|
736 <row> |
|
737 <entry><p> <codeph>SCR_HEIGHT</codeph> <i>n</i> <i>height</i> </p> </entry> |
|
738 <entry><p>The screen height in pixels for a particular screen mode. The screen |
|
739 mode is set by <i>n</i> and <i>height</i> is the height in pixels. </p> <p>In |
|
740 the non-ScreenPlay variant, this value should be the same as or smaller than |
|
741 the actual screen size as defined by the screen driver, after taking into |
|
742 account the rotation, the top-left offset and any scaling. </p> <p>In ScreenPlay, |
|
743 to define a dynamic screen mode, set this and <codeph>SCR_WIDTH</codeph> <i>n</i> to |
|
744 -1. See <xref href="GUID-0EBE5733-A267-5F4A-85AD-87C3ECF80731.dita">Dynamic Resolution |
|
745 Switching</xref> for more information. </p> </entry> |
|
746 <entry><p>Both </p> </entry> |
|
747 </row> |
|
748 <row> |
|
749 <entry><p> <codeph>SCR_TWIP_WIDTH</codeph> <i>n</i> <i>width</i> </p> </entry> |
|
750 <entry><p>The screen width in twips for a particular screen mode. The screen |
|
751 mode is set by <i>n</i> and <i>width</i> is the width in twips. </p> <p>For |
|
752 dynamic screen modes in ScreenPlay, do not specify the size in twips if you |
|
753 want the current resolution's size in twips to be used. If you do specify |
|
754 the size in twips for a dynamic screen mode, it overrides the current resolution |
|
755 setting when you call <xref href="GUID-30479BE3-296E-3B4D-914D-B080ABD733E4.dita#GUID-30479BE3-296E-3B4D-914D-B080ABD733E4/GUID-167EAE21-C9D5-3B54-BA3F-F2F83B2FD073"><apiname>CWsScreenDevice::SizeInTwips()</apiname></xref>. </p> </entry> |
|
756 <entry><p>Both </p> </entry> |
|
757 </row> |
|
758 <row> |
|
759 <entry><p> <codeph>SCR_TWIP_HEIGHT</codeph> <i>n</i> <i>height</i> </p> </entry> |
|
760 <entry><p>The screen height in twips for a particular screen mode. The screen |
|
761 mode is set by <i>n</i> and <i>height</i> is the height in twips. </p> <p>For |
|
762 dynamic screen modes in ScreenPlay, do not specify the size in twips if you |
|
763 want the current resolution's size in twips to be used. If you do specify |
|
764 the size in twips for a dynamic screen mode, it overrides the current resolution |
|
765 setting when you call <xref href="GUID-30479BE3-296E-3B4D-914D-B080ABD733E4.dita#GUID-30479BE3-296E-3B4D-914D-B080ABD733E4/GUID-167EAE21-C9D5-3B54-BA3F-F2F83B2FD073"><apiname>CWsScreenDevice::SizeInTwips()</apiname></xref>. </p> </entry> |
|
766 <entry><p>Both </p> </entry> |
|
767 </row> |
|
768 <row> |
|
769 <entry><p> <codeph>SIZE_MODE</codeph> <i>n</i> <i>value</i> </p> </entry> |
|
770 <entry><p>The screen mode enforcement for a particular screen mode. This is |
|
771 read when the system starts up. The screen mode is set by <i>n</i> and <i>value</i> is |
|
772 an integer corresponding one of the screen mode enforcement flags defined |
|
773 in TScreenModeEnforcement. If it is not set, a value of 0 (<codeph>ESizeEnforcementNone</codeph>) |
|
774 is used. </p> <p>See also: <xref href="GUID-30479BE3-296E-3B4D-914D-B080ABD733E4.dita#GUID-30479BE3-296E-3B4D-914D-B080ABD733E4/GUID-0E9358D4-023D-3B04-B0B8-D974AAA50D73"><apiname>CWsScreenDevice::ScreenModeEnforcement()</apiname></xref>, <xref href="GUID-30479BE3-296E-3B4D-914D-B080ABD733E4.dita#GUID-30479BE3-296E-3B4D-914D-B080ABD733E4/GUID-183BF89D-92A6-3E8A-930B-ADCFB1A03A1B"><apiname>CWsScreenDevice::SetScreenModeEnforcement()</apiname></xref> </p> </entry> |
|
775 <entry><p>Both </p> </entry> |
|
776 </row> |
|
777 </tbody> |
|
778 </tgroup> |
|
779 </table> </section> |
|
780 <section id="GUID-71ABB4DF-8C79-598F-BD4C-AC1EDD52AA04"><title>Plug-in specific |
|
781 parameters</title> <p>These parameters relate to Window Server plug-ins. For |
|
782 each plug-in, create a separate section in the <filepath>wsini.ini</filepath> file. |
|
783 Specify the plug-in name in square brackets (for example, <codeph>[MYPLUGIN]</codeph>) |
|
784 to indicate the start of the section. The plug-ins must also be specified |
|
785 in the first or <codeph>[DEFAULT]</codeph> section by using the <codeph>PLUGINS</codeph> parameter. </p> <p>The |
|
786 plug-in specific parameters are the same in both ScreenPlay and non-ScreenPlay |
|
787 variants. </p> <table id="GUID-B42CA314-CAB4-5FCD-8DB1-4007A1ED2084"> |
|
788 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
789 <thead> |
|
790 <row> |
|
791 <entry>Parameter </entry> |
|
792 <entry>Description </entry> |
|
793 </row> |
|
794 </thead> |
|
795 <tbody> |
|
796 <row> |
|
797 <entry><p> <codeph>[</codeph> <i>name</i> <codeph>]</codeph> </p> </entry> |
|
798 <entry><p>Specifies the name of the plug-in and indicates the start of a section |
|
799 that relates to that plug-in. </p> </entry> |
|
800 </row> |
|
801 <row> |
|
802 <entry><p> <codeph>ID</codeph> <i>value</i> </p> </entry> |
|
803 <entry><p>The UID of the plug-in DLL. The Window Server plug-in framework |
|
804 uses this to search for the DLL to load. For example, if the <codeph>ID</codeph> is |
|
805 12345678, the Window Server searches for a DLL called <i>12345678.dll</i>. </p> </entry> |
|
806 </row> |
|
807 <row> |
|
808 <entry><p> <codeph>DATA</codeph> <i>value</i> </p> </entry> |
|
809 <entry><p>Can be used to pass arbitrary data to the plug-in. </p> </entry> |
|
810 </row> |
|
811 <row> |
|
812 <entry><p> <codeph>TYPE</codeph> <i>value</i> </p> </entry> |
|
813 <entry><p>The type of the plug-in. For example, <codeph>CTestRenderStage</codeph>. </p> </entry> |
|
814 </row> |
|
815 </tbody> |
|
816 </tgroup> |
|
817 </table> </section> |
|
818 <section id="GUID-635178C9-CFF1-5261-8A72-CC291DE98531"><title>Obsolete and |
|
819 deprecated parameters</title> <p>The following table lists <filepath>wsini.ini</filepath> file |
|
820 parameters that were used in earlier versions of Symbian but which are now |
|
821 obsolete, deprecated or should not be used. Documentation for these parameters |
|
822 can be found in earlier versions of the Symbian Developer Library. </p> <table id="GUID-0E0BE51D-A1A2-5ABC-892D-FCB94DB2D2DA"> |
|
823 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
824 <thead> |
|
825 <row> |
|
826 <entry>Parameter</entry> |
|
827 <entry>Status</entry> |
|
828 </row> |
|
829 </thead> |
|
830 <tbody> |
|
831 <row> |
|
832 <entry><p> <codeph>ALLOWPARTIALREDRAWSTORING</codeph> </p> </entry> |
|
833 <entry><p>Obsolete </p> </entry> |
|
834 </row> |
|
835 <row> |
|
836 <entry><p> <codeph>FLICKERFREEREDRAW</codeph> </p> </entry> |
|
837 <entry><p>Obsolete </p> </entry> |
|
838 </row> |
|
839 <row> |
|
840 <entry><p> <codeph>NOREDRAWSTORING</codeph> </p> </entry> |
|
841 <entry><p>Obsolete </p> </entry> |
|
842 </row> |
|
843 <row> |
|
844 <entry><p> <codeph>OPT_LEVEL</codeph> </p> </entry> |
|
845 <entry><p>Planned for deprecation in S^4. Do not change the default value |
|
846 (1). </p> </entry> |
|
847 </row> |
|
848 <row> |
|
849 <entry><p> <codeph>PRESERVESTOREDCOMMANDS</codeph> </p> </entry> |
|
850 <entry><p>Obsolete </p> </entry> |
|
851 </row> |
|
852 <row> |
|
853 <entry><p> <codeph>REMOVEFADINGONFOCUSGAIN</codeph> </p> </entry> |
|
854 <entry><p>Deprecated </p> </entry> |
|
855 </row> |
|
856 <row> |
|
857 <entry><p> <codeph>TRANSPARENCY</codeph> </p> </entry> |
|
858 <entry><p>Obsolete </p> </entry> |
|
859 </row> |
|
860 <row> |
|
861 <entry><p> <codeph>WINDOWMODE</codeph> <codeph>COLOR</codeph> <i>value</i> ¦<codeph>GRAY</codeph> <i>value</i> </p> </entry> |
|
862 <entry><p>Deprecated </p> </entry> |
|
863 </row> |
|
864 </tbody> |
|
865 </tgroup> |
|
866 </table> </section> |
|
867 <section id="GUID-152B59F6-E7F1-4A32-A5EA-E07B0C42EE58"><title>Example</title> <p>This |
|
868 is an example of a <filepath>wsini.ini</filepath> file that configures an |
|
869 emulator with two screens for the non-ScreenPlay variant. The comments refer |
|
870 to the notes below. </p> <codeblock id="GUID-6B545480-53FE-5AF7-BB3A-2FB085CF7008" xml:space="preserve">LOG FL // 1 |
|
871 LOGP \DATA\WSERV.LOG |
|
872 LOGENABLE 9 |
|
873 REBOOT 1 |
|
874 STARTUP WSHELL |
|
875 KEYCLICKPLUGIN CLICK |
|
876 PLUGINS TESTRENDERSTAGE FLICKERBUFFER DISPLAY |
|
877 |
|
878 [SCREEN0] // 2 |
|
879 AUTOCLEAR 1 |
|
880 SCR_WIDTH1 0 |
|
881 SCR_HEIGHT1 0 |
|
882 SCR_ROTATION1 0,180 |
|
883 SCR_WIDTH2 240 |
|
884 SCR_HEIGHT2 80 |
|
885 SCR_ROTATION2 90 |
|
886 RENDERSTAGES TESTRENDERSTAGE FLICKERBUFFER DISPLAY |
|
887 |
|
888 [SCREEN1] // 3 |
|
889 AUTOCLEAR 0 SCR_WIDTH1 800 |
|
890 SCR_HEIGHT1 600 |
|
891 SCR_ROTATION1 180 |
|
892 SCR_WIDTH2 240 |
|
893 SCR_HEIGHT2 160 |
|
894 SCR_ROTATION2 270 |
|
895 |
|
896 [TESTRENDERSTAGE] // 4 |
|
897 TYPE CTestRenderStage</codeblock> <p><b>Notes</b>: </p> <ol id="GUID-A85361C9-9D55-539A-A9DE-ADCF9AACA87B"> |
|
898 <li id="GUID-7A71C13C-9C1E-5955-9B52-82624ABDB26C"><p>The logging parameters |
|
899 are not specific to the screen and so are placed in the first section. </p> </li> |
|
900 <li id="GUID-7F9D89E8-90B2-5383-8B07-D7266D710E76"><p>These keywords apply |
|
901 only to the first screen. </p> </li> |
|
902 <li id="GUID-F80D77DF-DC87-5E10-A761-D89BE08FF552"><p>These keywords apply |
|
903 only to the second screen. </p> </li> |
|
904 <li id="GUID-9250D069-A419-55AC-A471-322CC3443C56"><p>The section for the <codeph>testrenderstage</codeph> plug-in </p> </li> |
|
905 </ol> </section> |
|
906 </refbody><related-links> |
|
907 <link href="GUID-AA02BFA9-E62E-56FC-BF22-8FE092ABD9DA.dita"><linktext>The wsini.ini |
|
908 File</linktext></link> |
|
909 <link href="GUID-6E8807F5-9CC0-5A70-8182-22230D43AA9E.dita"><linktext>Setting Up |
|
910 Window Server Logging</linktext></link> |
|
911 </related-links></reference> |