<?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 reference

  PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">

<reference id="GUID-1D529BDC-6665-58E2-AB3F-7023D8A84F69" xml:lang="en"><title>The

wsini.ini File Reference</title><shortdesc>This topic provides a reference to the <filepath>wsini.ini</filepath> file

parameters. Some of the parameters are general, some are screen-specific and

some are specific to individual plug-ins. </shortdesc><prolog><metadata><keywords/></metadata></prolog><refbody>

<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

audience</b>: Device creators. </p> <p>This topic divides the parameters into

four groups: </p> <ul>

<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>

<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>

<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>

<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>

</ul> <p> <b>Notes</b>: </p> <ul>

<li id="GUID-9252F124-EF48-54D9-9244-7A7EC30C7E58"><p>Although most of these

parameters apply to the Window Server in both the ScreenPlay (NGA) variant

and the non-ScreenPlay (non-NGA) variant, some of them apply to only one variant

or the other. For the general and screen-specific parameters, there is an

extra column on the right of the table that shows which variant the parameter

applies to—<i>both</i> meaning both ScreenPlay and non-ScreenPlay variants. </p> </li>

<li id="GUID-414DD0AE-E974-54C5-873E-A392F7AF915E"><p>You must specify all

of the parameters using all uppercase letters. </p> </li>

</ul> </section>

<section id="GUID-751AB9E9-B8C3-5BE3-B1D5-C334E68106F2"><title>General parameters</title> <p>These

are general parameters—that is, parameters that are not screen-specific or

plug-in specific. Put these parameters first in the <filepath>wsini.ini</filepath> file,

optionally under the <codeph>[DEFAULT]</codeph> section heading keyword. This

first section can also include any screen-related parameters that apply to

all screens. </p> <table id="GUID-D4597226-B6F0-501E-B871-433F3399FA7D">

<tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/>

<thead>

<row>

<entry>Parameter </entry>

<entry>Description </entry>

<entry>Variant </entry>

</row>

</thead>

<tbody>

<row>

<entry><p> <codeph>ABSOLUTEFADING</codeph>  </p> </entry>

<entry><p>If this is specified, the Window Server uses absolute fading. If

not specified, the Window Server uses counted fading. Counted fading means

that the Window Server maintains a count in order to support the nesting of <codeph>SetFaded()</codeph> calls.

This mechanism provides support for nested pop-ups (where pop-ups cause the

background to fade). </p> <p>In absolute fading, Window Server uses a <codeph>TBool</codeph> value

instead, so that <codeph>SetFaded(ETrue/EFalse)</codeph> fades or unfades

the window, regardless of nesting. </p> </entry>

<entry><p>Both </p> </entry>

</row>

<row>

<entry><p> <codeph>ANIMATIONGRACEPERIOD</codeph>  <i>value</i>  </p> </entry>

<entry><p>Specifies the grace period (in microseconds) for animations. The

grace period is the length of time that the Window Server waits between animation

frames. If not specified, the grace period defaults to 35 milliseconds, in

order to allow other threads to run. The animation grace period is a minimum

period—the Window Server attempts to go faster if there is nothing else using

the system. </p> </entry>

<entry><p>Both </p> </entry>

</row>

<row>

<entry><p> <codeph>ATOMICREDRAWS</codeph>  </p> </entry>

<entry><p>Specify this parameter to enable atomic redraws. </p> <p>Client

redrawing is often performed as sequences of Begin/End redraw commands. If

the screen is redrawn when the Window Server is part way through receiving

the draw commands (that is between the Begin and End commands), the screen

update is often incomplete or incorrect. This can result in flicker. </p> <p>Enabling

atomic redraws ensures that the draw commands that are enclosed within the

Begin/End redraw are drawn onto the screen only when the whole section of

commands has been received by the Window Server. </p> <p>See <xref href="GUID-0AD34BA6-D0C5-5AD7-B8E1-F737BB5FC0AC.dita">Redraw

Stores</xref> for more information. </p> </entry>

<entry><p>Both </p> </entry>

</row>

<row>

<entry><p> <codeph>BACKGROUNDALPHA</codeph>  <i>value</i>  </p> </entry>

<entry><p>Sets the alpha value of the default background color for all windows.

To override this default value for a specific window, set its background color

explicitly. </p> <p>Specify <i>value</i> as an integer in the range 0–255.

If this parameter is not specified, the default value is 0xFF or completely

opaque. </p> <p>Note that a background alpha value of zero means that the

window background color is not drawn at all. </p> </entry>

<entry><p>Both </p> </entry>

</row>

<row>

<entry><p> <codeph>BACKGROUNDCOLOR</codeph>  <i>value</i>  </p> </entry>

<entry><p>Sets the default window background color. Enter <i>value</i> in

the form: <codeph>0x</codeph> <i>rrggbb</i>. For example, the following specifies

a red default background color: </p> <codeblock id="GUID-7EC633DA-ACF8-5DD4-BF47-C89E744FC0C8" xml:space="preserve">BACKGROUNDCOLOR 0xff0000</codeblock> <p>If

this parameter is not specified, the default background color is white. </p> </entry>

<entry><p>Both </p> </entry>

</row>

<row>

<entry><p> <codeph>DEBUGBAR</codeph>  </p> </entry>

<entry><p>Turns on the Window Server’s debug bar. This overlays the normal

UI and displays information about the current performance and behavior of

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%

RedrawStore size 0B; updates 0/s, pixels 0/s</codeblock> <ul>

<li id="GUID-BC6FE170-EF64-58DB-BB4E-854C4E37F6AE"><p> <codeph>KeyEvents</codeph> shows

the total number of key events and scheduler requests. </p> </li>

<li id="GUID-568A332B-285B-520A-AEA6-51A518570199"><p> <codeph>Wserv</codeph> shows

the percentage of scheduler activity occupied by the Window Server. </p> </li>

<li id="GUID-1C57720D-65BA-516D-BADB-F2834891FFE0"><p> <codeph>Drawing</codeph> shows

the percentage of Window Server activity that is spent drawing. </p> </li>

<li id="GUID-C3A79CAD-AEB0-5689-8E2A-89DED30EE6EC"><p> <codeph>Reclaimed</codeph> shows

the percentage of idle time reclaimed by the Window Server to perform drawing

when there are is no higher priority activity. </p> </li>

<li id="GUID-EA6E5DBB-7F1D-5CD9-A0F4-A2FE469CC906"><p> <codeph>RedrawStore

size</codeph> shows the size in bytes of the redraw store—that is, the sum

of the sizes of every redraw segment of every window currently owned by the

Window Server. </p> </li>

<li id="GUID-83A14FFE-5ED8-5C66-9FBB-251A462C9A5A"><p> <codeph>Updates</codeph> shows

the number of screen updates per second. </p> </li>

<li id="GUID-7310FFB7-5264-5E5C-9FC5-387920E2AEAF"><p> <codeph>Pixels</codeph> shows

the number of pixels updated per second—that is, the pixel fill rate. </p> </li>

</ul> </entry>

<entry><p>Both </p> </entry>

</row>

<row>

<entry><p> <codeph>DISABLEIDLEANIMATION</codeph>  </p> </entry>

<entry><p>The Window Server attempts to detect when the CPU is under light

load and allows animations to go faster than the grace period under such circumstances.

This feature is called <i>idle animation</i> and this parameter disables it. </p> <p>Symbian

recommends that you always use this parameter, because there are numerous

very short idle periods during application start up and running animations

during these short idle periods slows down application start time. </p> <p>This

parameter has no effect in the ScreenPlay variant, because idle animation

is disabled by default in the ScreenPlay variant. </p> </entry>

<entry><p>Non-ScreenPlay </p> </entry>

</row>

<row>

<entry><p> <codeph>DSAANIMATIONGRACEPERIOD</codeph>  <i>value</i>  </p> </entry>

<entry><p>Specifies the grace period (in microseconds) for Direct Screen Access

(DSA) animations. The grace period is the length of time that the Window Server

waits between DSA animation frames. If not specified this defaults to 35 milliseconds,

in order to allow other threads to run. The animation grace period is a minimum

period—the Window Server attempts to go faster if there is nothing else using

the system. </p> </entry>

<entry><p>Both </p> </entry>

</row>

<row>

<entry><p> <codeph>FADEDISABLE</codeph>  </p> </entry>

<entry><p>Disables fading, which means that calls to the following functions

have no visual effect on the Window Server's drawing: </p> <ul>

<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>

<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>

<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>

</ul> </entry>

<entry><p>Both </p> </entry>

</row>

<row>

<entry><p> <codeph>FINISHEVERYFLUSH</codeph>  </p> </entry>

<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>,

so that the Window Server synchronizes the message buffer and forces the screen

to update. If this parameter is not present, <codeph>Flush()</codeph> synchronizes

the message buffer and does not guarantee to present any drawing commands

within the buffer to the screen. </p> <p>Before the introduction of the Window

Server improvements known as WSERV2, the Window Server, <codeph>Flush()</codeph> did

two distinct things: </p> <ol id="GUID-73787DDB-B7B8-55A1-B5A0-D8A6FFD36D67">

<li id="GUID-9F73848F-F6D7-5A00-B150-208AD0540481"><p>Flushed the session's

command buffer. </p> </li>

<li id="GUID-7DAE082F-3768-589E-9287-A0A9D6852C3E"><p>Forced the presentation

of any drawing commands to the screen. (This is a previously undocumented

side effect of the old Window Server’s drawing behavior.) </p> </li>

</ol> <p>By default <codeph>Flush()</codeph> now does the first of these steps

only. Use <codeph>FINISHEVERYFLUSH</codeph> to cause <codeph>Flush()</codeph> to

continue the previous behavior. </p> <p>In the improved Window Server (WServ2),

there are two new methods that explicitly separate these two behaviors. The

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>

<entry><p>Both </p> </entry>

</row>

<row>

<entry><p> <codeph>FRAMECAPTURE</codeph>  </p> </entry>

<entry><p>This parameter is for use when debugging render stage plug-ins.

When specified, the Window Server captures frame bitmaps and saves them in <filepath>frame_&lt;timestamp&gt;.mbm</filepath> files.

These are located in the <filepath>epoc32\winscw\c</filepath> folder for winscw

and <filepath>e:\storyboard\</filepath> for H4 boards. </p> <p>This option

takes effect only when the Window Server and its plug-ins are compiled with

the <codeph>USE_DEBUG_FRAME_CAPTURE</codeph> macro defined. </p> </entry>

<entry><p>Both </p> </entry>

</row>

<row>

<entry><p> <codeph>IGNORESWITCHOFFEVENT</codeph>  </p> </entry>

<entry><p>When specified and no shutdown manager is registered, all events

that the Window Server passes to clients as OFF events are ignored. These

events are <codeph>EEventSwitchOff</codeph>, <codeph>EEventCaseClosed</codeph>, <codeph>EEventKeySwitchOff</codeph> or <codeph>EEventRestartSystem</codeph>. </p> </entry>

<entry><p>Both </p> </entry>

</row>

<row>

<entry><p> <codeph>KEYCLICKPLUGIN</codeph>  <i>filename</i>  </p> </entry>

<entry><p>The Window Server attempts to load the named key or pointer click

plug-in DLL. If this fails or if this keyword does not appear, a plug-in is

not used and key and pointer clicks are not enabled. </p> </entry>

<entry><p>Both </p> </entry>

</row>

<row>

<entry><p> <codeph>KEYCLICKPLUGINFIXED</codeph>  </p> </entry>

<entry><p>Stops Window Server clients from removing or changing the key or

pointer click plug-in. Hardware manufacturers can use this keyword to disallow

key or pointer clicks or force only one plug-in to be used. </p> </entry>

<entry><p>Both </p> </entry>

</row>

<row>

<entry><p> <codeph>LOG</codeph>  <i>string</i>  </p> </entry>

<entry><p>Specifies the type of logging that is required. Loads one of the

three logging DLLs, as specified by <i>string</i>. Possible values of <i>string</i> are: </p> <ul>

<li id="GUID-901E83F0-F21E-56C2-AD2D-BAE394BF80C9"><p> <codeph>FL</codeph> —

log to file </p> </li>

<li id="GUID-AE205ACC-2A13-5950-B058-B552DA238B54"><p> <codeph>SR</codeph> —

log to the serial port (MARM only) </p> </li>

<li id="GUID-5FF305A9-1D2D-55CC-A970-3ED9EB9536BD"><p> <codeph>WN</codeph> —

log to another WIN32 window (emulator only) </p> </li>

</ul> </entry>

<entry><p>Both </p> </entry>

</row>

<row>

<entry><p> <codeph>LOGENABLE</codeph>  <i>value</i>  </p> </entry>

<entry><p>If specified, enables logging from boot-up. You can optionally specify

a value that must be one of the following: </p> <ul>

<li id="GUID-A365CDBE-A9E7-5D7B-8E0A-7A3835E0D04E"><p>9 — Enables limited

logging of Window Server messages, of the following types: loading of animation

DLLs, application panics and all messages from the client side. </p> </li>

<li id="GUID-C2DAFB31-E51C-58ED-B3D3-6123F3B96E46"><p>5 — Enables intermediate

logging. This includes all the messages logged using limited logging, and

adding and removing Window Server clients. </p> </li>

<li id="GUID-3B61EC1F-2AA5-5EE6-891E-AA80BEA317E1"><p>1 — Enables full logging

of all messages to and from the Window Server. This is the most commonly used

option and is the default. </p> </li>

</ul> </entry>

<entry><p>Both </p> </entry>

</row>

<row>

<entry><p> <codeph>LOGP</codeph>  <i>filespec</i>  </p> </entry>

<entry><p>The fully qualified file name of the output log file. </p> </entry>

<entry><p>Both </p> </entry>

</row>

<row>

<entry><p> <codeph>MEMORYRESERVE</codeph>  <i>value</i>  </p> </entry>

<entry><p>Sets the amount of memory that the Window Server's memory manager

holds in reserve for use during critical sequences where the use is expected

to be temporary. The memory reserve is not used for memory allocation failures

and is currently used by the Window Server’s inner composition loop. </p> <p>If

this parameter is not specified, the memory manager allocates 1024 bytes of

memory to hold as its reserve. </p> </entry>

<entry><p>Both </p> </entry>

</row>

<row>

<entry><p> <codeph>MULTIFOCUSPOLICY</codeph>  </p> </entry>

<entry><p>Selects the Window Server multi-focus policy. This means that one

window group on each screen all have focus. When this policy is not set, only

one window group on one screen has focus. </p> <p>When a window group has <i>focus</i>,

it means that the last focus event it received was a focus gained event rather

than a focus lost event. The window group with focus is always the front-most

focusable window group on its screen. </p> <p>This setting does not change

the key event channeling policy. Key events are sent only to the focused window

group on the focused screen (unless they are captured by another window). </p> </entry>

<entry><p>Both </p> </entry>

</row>

<row>

<entry><p> <codeph>NOBLANKSCREEN</codeph>  </p> </entry>

<entry><p>Use this keyword if, at boot time, you need to delay blanking the

screen until the shell has started a session with the Window Server. </p> <p>Note

that you specify the name of the shell by using the <codeph>STARTUP</codeph> parameter. </p> </entry>

<entry><p>Both </p> </entry>

</row>

<row>

<entry><p> <codeph>NONREDRAWAGELIMIT</codeph>  <i>duration</i>  </p> </entry>

<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

non-ScreenPlay variant only. </p> <p>Non-redraw drawing (that is, drawing

commands that are issued outside of Begin/End Redraw) are placed into a special

non-redraw segment in the redraw store. To prevent these non-redraw segments

from growing indefinitely as non-redraw commands are added to them, a limit

is imposed on their life time within the redraw store. When adding non-redraw

commands to the redraw store, the Window Server: </p> <ul>

<li id="GUID-0257C4CF-7DCB-5F67-9A22-5F59347992A2"><p>checks the ages of the

non-redraw segments within the store </p> </li>

<li id="GUID-B923ED52-EF59-520F-9DC1-1C564858F12C"><p>discards any old non-redraw

segments and if necessary requests a client-side redraw </p> </li>

<li id="GUID-D0D64A40-8E46-5153-97EA-75C929C9B2E0"><p>creates a new non-redraw

segment for new non-redraw commands. </p> </li>

</ul> <p>The <codeph>NONREDRAWAGELIMIT</codeph> parameter allows for the customization

of the age limit. If not defined, a default of 1,000,000 microseconds or 1

second is used. </p> </entry>

<entry><p>Non-ScreenPlay </p> </entry>

</row>

<row>

<entry><p> <codeph>ONINACTIVE</codeph>  <i>value</i>  </p> </entry>

<entry><p>Specifies what happens when there is no key or pointer activity

for a period of time. Possible values are: </p> <ul>

<li id="GUID-051742BE-A01D-5C50-8C7D-2F0A494B3B7E"><p> <codeph>STOPANIMATION</codeph> —

this means continue client-side redraws and stop all server-side drawing.

This is the most obvious option. </p> </li>

<li id="GUID-77282032-A0F8-5264-A03B-137C9B56B90D"><p> <codeph>STOPALLDRAWING</codeph> —

this stops both client-side and server-side drawing. </p> </li>

<li id="GUID-5C4F0C0C-6200-5F0D-B314-30717D859655"><p> <codeph>IGNORE</codeph> —

this means ignore the inactivity and draw as normal. </p> </li>

</ul> </entry>

<entry><p>Both </p> </entry>

</row>

<row>

<entry><p> <codeph>PLUGINS</codeph>  <i>string</i>  </p> </entry>

<entry><p>Specifies the complete list of plug-ins that the Window Server’s

plug-in manager is to load. For each plug-in that you specify, create a separate

section in the <filepath>wsini.ini</filepath> file to specify its details

(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

Parameters</xref> for more information. </p> <p>If not specified, the plug-in

manager loads the default plug-ins. In the ScreenPlay variant, these are <i>flickerbuffer</i> and <i>display</i>.

In the non-ScreenPlay variant, they are <i>flickerbuffer</i>, <i>std </i> and <i>defaultfader</i>. </p> <p>If

the default plug-ins are required, include them in the plug-in list. For example,

in ScreenPlay, the following instructs the plug-in manager to load a custom

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>

<entry><p>Both </p> </entry>

</row>

<row>

<entry><p> <codeph>PROTECTEDKEY</codeph>  <i>keyvalue</i>  </p> <p> <codeph>PROTECTEDKEYWINDOWNAME</codeph> <i>windowgroupname</i>  </p> </entry>

<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

one key can be protected in this way. This means that these two parameters

must not appear more than once in the <filepath>wsini.ini</filepath> file. </p> <p>When

a client attempts to capture a standard key event (rather than a key up or

down event), <i>keyvalue</i> is matched against the key code (as defined in

the <xref href="GUID-B67B6ED5-6C8F-3B36-934C-B47A109A515F.dita"><apiname>TKeyCode</apiname></xref> enum in <filepath>e32keys.h</filepath>) to

see if the key is protected or not. </p> <p>When a client attempts to capture

an up or down key event, <i>keyvalue</i> is matched against the scan code

(as defined in the <xref href="GUID-4D92CE24-E651-3584-BDE0-F26046B4175B.dita"><apiname>TStdScanCode</apiname></xref> enum in <filepath>e32keys.h</filepath>)

to see if the key is protected or not. </p> <p>Note that for many keys, the

scan code and key code are the same, so this mechanism can by used to protect

against the capture of both standard events and up/down events for these keys. </p> <p>You

can specify <i>keyvalue</i> as a hexadecimal or decimal number. </p> <p> <i>windowgroupname</i> is

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

a substring of it. </p> </entry>

<entry><p>Both </p> </entry>

</row>

<row>

<entry><p> <codeph>REBOOT</codeph>  <i>value</i>  </p> </entry>

<entry><p>The shell reboot mode. The following values are defined: </p> <ul>

<li id="GUID-64F0EE9D-6E79-5BCA-932E-E68843037FA8"><p>0 — the Window Server

tries to restart the shell as soon as the shell dies or exits. </p> </li>

<li id="GUID-9F6B4509-2948-52E8-98AB-9E1D0C9E9608"><p>1 — the Window Server

tries to restart the shell only if all other Window Server clients have exited.

The Window Server detects an application exiting by its Window Server session

being closed. However, in rare cases, an application may not have a Window

Server session, or it may close its session without exiting. In such cases,

the shell may restart even though some applications are still running. </p> </li>

<li id="GUID-BA62D1DA-BC1C-5F1F-B225-077D3F20FEB0"><p>2 — the Window Server

shuts down the machine as soon as the shell dies or exits — <b>for use during

development only</b> . </p> </li>

</ul> </entry>

<entry><p>Both </p> </entry>

</row>

<row>

<entry><p> <codeph>REDRAWGRACEPERIOD</codeph>  <i>value</i>  </p> </entry>

<entry><p>Specifies the grace period (in microseconds) for redraws within

the Window Server. The redraw grace period is the length of time the Window

Server waits before performing a redraw. If not specified, the grace period

defaults to zero, which means that the Window Server endeavors to perform

redraws immediately. The redraw grace period is a minimum time—the Window

Server attempts to go faster if there is nothing else using the system. </p> </entry>

<entry><p>Both </p> </entry>

</row>

<row>

<entry><p> <codeph>REPEATROLLOVER</codeph>  <i>value</i>  </p> </entry>

<entry><p>Specify this parameter with value of 1 in order to allow key repeat

rollovers. </p> </entry>

<entry><p>Both </p> </entry>

</row>

<row>

<entry><p> <codeph>ROOTBACKGROUNDALPHA</codeph>  <i>value</i>  </p> </entry>

<entry><p>Sets the alpha value of the background color of the root window

independently from the alpha value of the default background color of other

windows. In the non-ScreenPlay variant, you can use this to make the initial

background in the Window Server frame buffer transparent. If any windows in

front are also transparent, this may lead to transparent pixels in the Window

Server frame buffer at the end of rendering. This provides a technique for

showing effects (such as particle effects) behind the Window Server frame

buffer. </p> <p>This parameter is not used in the ScreenPlay variant, because

this and similar use cases can be achieved by adding a background surface

to a window. This results in that window's area in the frame buffer (now called

the UI surface) being transparent. </p> <p>Specify <i>value</i> as an integer

in the range 0–255. If this parameter is not specified, the alpha value of

the root window’s background color is set to the alpha value of the default

background color—that is, the value set by <codeph>BACKGROUNDALPHA</codeph> or <codeph>0xFF</codeph>,

if it is not specified. </p> </entry>

<entry><p>Non-ScreenPlay </p> </entry>

</row>

<row>

<entry><p> <codeph>ROOTBACKGROUNDCOLOR</codeph>  <i>value</i>  </p> </entry>

<entry><p>The background color of the root window, if you want to set it independently

from the default background color of other windows. </p> <p>If not used, the

root window’s background color is set to the default background window value—that

is, the value set by <codeph>BACKGROUNDCOLOR</codeph> or <codeph>KRgbWhite</codeph> if

it is not specified. </p> </entry>

<entry><p>Both </p> </entry>

</row>

<row>

<entry><p> <codeph>SHELLCMD</codeph>  <i>string</i>  </p> </entry>

<entry><p>Specifies the command line argument to pass when starting the shell.

This is similar to DOS command parameters under Microsoft Windows. </p> <p>Defaults

to an empty string. </p> </entry>

<entry><p>Both </p> </entry>

</row>

<row>

<entry><p> <codeph>STARTUP</codeph>  <i>string</i>  </p> </entry>

<entry><p>Specifies the name of the shell to use. Defaults to <filepath>shell</filepath>. </p> </entry>

<entry><p>Both </p> </entry>

</row>

</tbody>

</tgroup>

</table> </section>

<section id="GUID-794DD7D2-83DD-50E8-822C-A8AC0D123EE5"><title>Screen-specific

parameters</title> <p>These parameters are screen specific and you can specify

them separately for each screen. Do this by creating a section for each screen

and use the <codeph>[SCREEN</codeph> <i>n</i> <codeph>]</codeph> keyword to

indicate the start of each section. </p> <p>In a single-screen device, put

these parameters in the first (<codeph>[DEFAULT]</codeph>) section and not

in a separate section. In a multi-screen phone, you can put any screen-related

parameters that apply to all screens in the first (<codeph>[DEFAULT]</codeph>)

section. </p> <p>Each screen can have several <i>screen modes</i> (such as

portrait and landscape), identified by a zero-based index. Some of the screen-specific

parameters relate to the screen mode. For example, in the non-ScreenPlay variant

you can use the <codeph>SCR_LEFT</codeph>, <codeph>SCR_TOP</codeph>, <codeph>SCR_XSCALE</codeph> and <codeph>SCR_YSCALE</codeph> parameters

to change the origin of top-level windows and a scaling factor for each mode

of every screen. Some of these parameters are not supported or work differently

in ScreenPlay. See <xref href="GUID-0EBE5733-A267-5F4A-85AD-87C3ECF80731.dita">Dynamic

Resolution Switching</xref> for more information. </p> <table id="GUID-4FF083DC-0AF1-56F9-A8BE-7F1E0F510359">

<tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/>

<thead>

<row>

<entry>Keyword/Parameter </entry>

<entry>Description </entry>

<entry>Variant </entry>

</row>

</thead>

<tbody>

<row>

<entry><p> <codeph>[SCREEN</codeph> <i>n</i> <codeph>]</codeph>  </p> </entry>

<entry><p>A <filepath>wsini.ini</filepath> file may be divided into sections

to support phones with multiple screens. Each section that is preceded by

this keyword contains the parameters whose value applies to one screen only. </p> <p>The <i>n</i> value

is a number that indicates which screen the section applies to. For instance, <codeph>[SCREEN0]</codeph> is

the first screen, <codeph>[SCREEN1]</codeph> the second. </p> <p>If the device

does not support multiple screens, this keyword should not appear in the <filepath>wsini.ini</filepath> file. </p> </entry>

<entry><p>Both </p> </entry>

</row>

<row>

<entry><p> <codeph>AUTOCLEAR</codeph>  <i>value</i>  </p> </entry>

<entry><p>When an <codeph>RWindow</codeph> is manipulated by an application,

this parameter determines whether the invalid region is cleared to its background

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>)

before being redrawn. The possible values are: </p> <ul>

<li id="GUID-A2E47136-EB18-5DE5-AEF9-FC5C6090A487"><p>0 — the background is

not cleared, even if a background color has been set. This is for use in debugging

only. </p> </li>

<li id="GUID-2CC9C730-33F8-5F8E-9439-358F66555DCD"><p>1 — the default. The

background is cleared if a background color has been set, but not if no background

color has been set. </p> </li>

</ul> </entry>

<entry><p>Both </p> </entry>

</row>

<row>

<entry><p> <codeph>BACKLIGHTCONTROL</codeph>  </p> </entry>

<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>.

If this parameter is not specified, this function returns <codeph>KErrPermissionDenied</codeph>. </p> </entry>

<entry><p>Both </p> </entry>

</row>

<row>

<entry><p> <codeph>BLANKSCREENONROTATION</codeph>  </p> </entry>

<entry><p>Causes the Window Server to blank the screen after changing the

orientation. If this parameter is not specified, screen content persists when

the orientation changes. </p> </entry>

<entry><p>Both </p> </entry>

</row>

<row>

<entry><p> <codeph>BLTOFFSCREENBITMAP</codeph>  </p> </entry>

<entry><p>If this is specified in the non-ScreenPlay variant, the invalid

region of the offscreen bitmap is not set to white or the background color,

but is instead copied from the screen. </p> <p>This might reduce flicker if

not all the pixels in the invalid region are redrawn. Users should be aware,

however, that fading and shadowing are applied when copying from the off-screen

buffer to the screen. It is possible that some pixels may be doubly shadowed

or doubly faded when using this keyword. Another possible side-effect is that

artefacts of sprites may get left behind. </p> </entry>

<entry><p>Non-ScreenPlay </p> </entry>

</row>

<row>

<entry><p> <codeph>CHANGETRACKING</codeph>  </p> </entry>

<entry><p>Changes the mode of the Window Server rendering loop from the default

dirty-rectangle mode to change-tracking mode. Typically change-tracking mode

is used only when a transition effects (TFX) render stage is in use, which

builds up its own visuals stores. See <xref href="GUID-22093E74-EFE7-5642-93DE-1573E18F7C08.dita">Window

Server Rendering Loop</xref> for more information. </p> </entry>

<entry><p>ScreenPlay </p> </entry>

</row>

<row>

<entry><p> <codeph>CHROMAKEYCOLOR</codeph>  <i>value</i>  </p> </entry>

<entry><p>Specifies the chroma key color that the composition engine considers

transparent for chroma keying transparency. The specified color must not be

used in images on the layer other than to indicate transparency. </p> <p>Enter

the value in the form <codeph>0xff</codeph> <i>rrggbb</i>, where <i>rr</i> is

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

this parameter is not specified, the default value is 0. </p> <p>Note: Chroma

key transparency is not used in <codeph>EColor16MA</codeph> and <codeph>EColor16MAP</codeph> display

modes. This is because they are RGBA modes and therefore have an alpha value

in addition to the RGB value. </p> </entry>

<entry><p>ScreenPlay </p> </entry>

</row>

<row>

<entry><p> <codeph>DEBUGOSB</codeph>  </p> </entry>

<entry><p>Enables you to use Win32-dependent code for debugging the Window

Server offscreen buffer and UI surface for each screen on the emulator. </p> </entry>

<entry><p>Both </p> </entry>

</row>

<row>

<entry><p> <codeph>DP_SCALING</codeph>  <i>string</i>  </p> </entry>

<entry><p>This is used by the ScreenPlay render stage plug-ins that are supplied

in the Window Server Plugins component. This parameter may therefore not be

used—for example, if the supplied render stages are replaced. When it is used,

it controls the type of scaling that the render stages perform. The value

can be one of the following: </p> <ul>

<li id="GUID-B8BC842B-CC3F-5E8E-8460-8BEE036A213C"><p>integer — this allows

only virtual resolutions that are integer divisors of the physical resolution

and sets a limit of four; that is, ½, 1/3 and 1/4. For example, for a real