Week 28 contribution of SDK documentation content. See release notes for details. Fixes bugs Bug 1897 and Bug 1522.
<?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_<timestamp>.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
resolution dimension of 720 pixels, virtual resolution dimensions of 360,
240 and 180 are allowed. </p> </li>
<li id="GUID-DBE122E0-E894-5C43-B724-67AC96A43A99"><p>isotropic — this allows
any scaling factor, not only integer ones. However, the horizontal and the
vertical scaling factors are the same. </p> </li>
<li id="GUID-210D6671-E0CF-51CF-B5A6-18A1B8641A77"><p>anisotropic — this allows
any scaling factor and does not restrict the relationship between the horizontal
and vertical scaling factors. </p> </li>
</ul> <p>Any other value is taken to mean no scaling. </p> </entry>
<entry><p>ScreenPlay </p> </entry>
</row>
<row>
<entry><p> <codeph>FADER</codeph> <i>string</i> </p> </entry>
<entry><p>Specifies a custom fader plug-in to be used. If not specified the
default fader plug-in implementation is used. This simply performs a BitGDI <codeph>FadeArea</codeph> when
windows are faded. </p> <p>In the non-ScreenPlay variant, handset manufacturers
can create custom fader plug-ins to create different fading effects. (In the
ScreenPlay variant, fading effects can be created using render stage plug-ins.)
Fader plug-ins must also be specified using the <codeph>PLUGINS</codeph> parameter
in order to be loaded. </p> <p>Fader plugins are specified per screen so it
is possible to use different fading effects on different screens. Here is
a simplified example: </p> <codeblock id="GUID-42879770-B76E-5F15-8EC0-ACA6ACC6AB93" xml:space="preserve">PLUGINS flickerbuffer std defaultfader customfaderA customfaderB
SCREEN[0]
FADER customfaderA
SCREEN[1]
FADER customfaderB
</codeblock> <p> <b>Note</b>: Fading is essentially disabled in the non-ScreenPlay
variant if a custom fader is not specified using the <codeph>FADER</codeph> parameter
and the <codeph>PLUGINS</codeph> command is overridden so that the default
fader plugin is not loaded. </p> </entry>
<entry><p>Non-ScreenPlay </p> </entry>
</row>
<row>
<entry><p> <codeph>FLICKERBUFFERMODE</codeph> <i>value</i> </p> </entry>
<entry><p>The <codeph>TDisplayMode</codeph> of the flicker buffer if one is
in use. If not specified, the flicker buffer has the same color depth as the
screen. </p> </entry>
<entry><p>Both </p> </entry>
</row>
<row>
<entry><p> <codeph>NUMSCREENMODES</codeph> <i>value</i> </p> </entry>
<entry><p>Removes the requirement that screen mode indexes must be consecutive.
This enables UI factories to implement sparse index schemes and allows the
screen mode index to have a particular meaning within the context of a UI. </p> <p>The <i>value</i> is
a positive integer which specifies the highest screen mode index that is defined
in the <filepath>wsini.ini</filepath> file. </p> <p>For example, in the following
example, the last 3 lines would be ignored, unless <codeph>NUMSCREENMODES
3</codeph> was specified beforehand: </p> <codeblock id="GUID-90042EF5-30BC-5864-A310-58043BE8A190" xml:space="preserve">SCR_WIDTH1 800
SCR_HEIGHT1 600
SCR_ROTATION1 180
SCR_WIDTH3 240
SCR_HEIGHT3 160
SCR_ROTATION3 270</codeblock> </entry>
<entry><p>Both </p> </entry>
</row>
<row>
<entry><p> <codeph>RENDERSTAGES</codeph> <i>string</i> </p> </entry>
<entry><p>Specifies the type and order of the render stages to be used by
the Window Server. </p> <p>If not defined, this defaults to <codeph>flickerbuffer
display</codeph> in the ScreenPlay variant and <codeph>flickerbuffer
std</codeph> in the non-ScreenPlay variant. This means that by default, the
Window Server pipes its drawing through the flicker buffer render stage and
then on to the <i>display</i> (called <i>std</i> in the non-ScreenPlay variant)
render stage, which draws it to the screen. </p> <p>The render stages are
plug-ins and you must also specify them in the <codeph>PLUGINS</codeph> parameter
in order to be loaded. </p> </entry>
<entry><p>Both </p> </entry>
</row>
<row>
<entry><p> <codeph>SCREENMODE COLOR</codeph><i>value</i> ¦ <codeph>GRAY</codeph><i>value</i> </p> </entry>
<entry><p>Specifies the display mode to be used for the screen device. The <codeph>COLOR</codeph> or <codeph>GRAY</codeph> prefix
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
type but without the initial <codeph>E</codeph>. </p><p>For example, <codeph>SCREENMODE
COLOR16M</codeph> corresponds to <codeph>EColor16M</codeph> and gives a display
mode of 16 million colors.</p> <p>If this parameter is not specified,
or a screen device cannot be created in the specified depth, the default is
the highest color mode available, up to <codeph>Color16MAP</codeph>. </p><p> <b>Note</b>:
This parameter replaces the deprecated <codeph>WINDOWMODE</codeph> parameter. </p> </entry>
<entry><p>Both </p> </entry>
</row>
<row>
<entry><p> <codeph>SCR_LEFT</codeph> <i>n</i> <i>value</i> </p> </entry>
<entry><p>The horizontal offset in pixels for a particular screen mode. Moves
the screen's contents to the left. By default this is zero. </p> <p> <i>n</i> is
an integer greater than zero that identifies the screen mode. <i>value</i> is
the offset in pixels (greater than zero). </p> <p>In ScreenPlay, this parameter
may be ignored (or used as a minimum margin hint) by the render stage chain,
in order to position the screen mode more appropriately. However, it may be
important to specify the offset for screen modes hosting legacy applications
because it is also used for the DSA buffer for backwards compatibility reasons.
See <xref href="GUID-0EBE5733-A267-5F4A-85AD-87C3ECF80731.dita">Dynamic Resolution
Switching</xref> for more information. </p> </entry>
<entry><p>Both </p> </entry>
</row>
<row>
<entry><p> <codeph>SCR_TOP</codeph> <i>n</i> <i>value</i> </p> </entry>
<entry><p>The vertical offset in pixels for a particular screen mode. Moves
the screen's contents upwards. By default this is zero. </p> <p> <i>n</i> is
an integer greater than zero that identifies the screen mode. <i>value</i> is
the offset in pixels (greater than zero). </p> <p>In ScreenPlay, this parameter
may be ignored (or used as a minimum margin hint) by the render stage chain,
in order to position the screen mode more appropriately. However, it may be
important to specify the offset for screen modes hosting legacy applications
because it is also used for the DSA buffer for backwards compatibility reasons.
See <xref href="GUID-0EBE5733-A267-5F4A-85AD-87C3ECF80731.dita">Dynamic Resolution
Switching</xref> for more information. </p> </entry>
<entry><p>Both </p> </entry>
</row>
<row>
<entry><p> <codeph>SCR_XSCALE</codeph> <i>n</i> <i>factor</i> </p> </entry>
<entry><p>The horizontal screen scaling factor for a particular screen mode. </p> <p> <i>n</i> is
the screen mode and <i>factor</i> is the scaling factor (a positive integer).
1 (the default) means no scaling. For example, specifying the following means
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
SCR_YSCALE1 2</codeblock> <p>In other words, drawing to logical pixel (0,0)
causes physical pixels (0,0), (0,1), (1,0) and (1,1) to change. </p> <p>Note
that on the emulator, screen scaling only works if the display mode is <codeph>Color256</codeph>. </p> <p>If
an offset is specified (using <codeph>SCR_LEFT</codeph> or <codeph>SCR_TOP</codeph>)
as well as a scaling factor, the offset is applied in unscaled coordinates.
For example, suppose the following values are specified: </p> <codeblock id="GUID-7DF011F5-C559-5E85-8F99-77FA5FD9DB37" xml:space="preserve">SCR_LEFT1 5
SCR_XSCALE1 2</codeblock> <p>This means that the mapping between logical and
physical pixels for the first screen mode is as follows: </p> <p><table id="GUID-696B38E9-CED3-58BF-A512-99586644F71E">
<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
<tbody>
<row>
<entry><p> <b>Logical</b> </p> </entry>
<entry><p> <b>Physical</b> </p> </entry>
</row>
<row>
<entry><p>x=0 </p> </entry>
<entry><p>x=5,6 </p> </entry>
</row>
<row>
<entry><p>x=1 </p> </entry>
<entry><p>x=7,8 </p> </entry>
</row>
<row>
<entry><p>x=2 </p> </entry>
<entry><p>x=9,10 </p> </entry>
</row>
<row>
<entry><p>x=-1 </p> </entry>
<entry><p>x=3,4 </p> </entry>
</row>
<row>
<entry><p>x=-2 </p> </entry>
<entry><p>x=1,2 </p> </entry>
</row>
<row>
<entry><p>x=-3 </p> </entry>
<entry><p>x=0 </p> </entry>
</row>
<row>
<entry><p>x=45 </p> </entry>
<entry><p>x=95,96 </p> </entry>
</row>
<row>
<entry><p>x=46 </p> </entry>
<entry><p>x=97,98 </p> </entry>
</row>
<row>
<entry><p>x=47 </p> </entry>
<entry><p>x=99 </p> </entry>
</row>
</tbody>
</tgroup>
</table> </p> <p>In this example, there are 51 addressable logical pixels. </p> <p>See
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
parameter is not used in ScreenPlay, because the UI pixel buffers (in the
full UI area) are not scaled relative to the application's view. Instead the
full UI area is mapped to the full composition/display area, if necessary
using a virtual resolution. This provides a better facility and is completely
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
more information. </p> </entry>
<entry><p>Non-ScreenPlay </p> </entry>
</row>
<row>
<entry><p> <codeph>SCR_YSCALE</codeph> <i>n</i> <i>factor</i> </p> </entry>
<entry><p>The vertical screen scaling factor for a particular screen mode.
See <codeph>SCR_XSCALE</codeph> for a description. </p> </entry>
<entry><p>Non-ScreenPlay </p> </entry>
</row>
<row>
<entry><p> <codeph>SCR_ROTATION</codeph> <i>n rotations</i> </p> </entry>
<entry><p>Specifies a list of screen rotations for a particular screen mode. </p> <p>The <i>n</i> value
is a positive integer which corresponds to a particular screen mode. </p> <p>The <i>rotations</i> value
is a comma separated list that specifies, in degrees, the rotation values
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
in the UI to render screen furniture correctly. For example, Techview shows
proof-of-concept rotation to profile screens. However, it is designed with
a landscape orientation, which means that in other orientations it does not
render the toolbar, and some menus are truncated. </p> </entry>
<entry><p>Both </p> </entry>
</row>
<row>
<entry><p> <codeph>SCR_WIDTH</codeph> <i>n</i> <i>width</i> </p> </entry>
<entry><p>The screen width in pixels for a particular screen mode. The screen
mode is set by <i>n</i> and <i>width</i> is the width in pixels. </p> <p>For
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
the non-ScreenPlay variant, this value should be the same as, or smaller than,
the actual screen size as defined by the screen driver, after taking into
account the rotation, the top-left offset and any scaling. </p> <p>In ScreenPlay,
to define a dynamic screen mode, set this and <codeph>SCR_HEIGHT</codeph> <i>n</i> to
-1. See <xref href="GUID-0EBE5733-A267-5F4A-85AD-87C3ECF80731.dita">Dynamic Resolution
Switching</xref> for more information. </p> </entry>
<entry><p>Both </p> </entry>
</row>
<row>
<entry><p> <codeph>SCR_HEIGHT</codeph> <i>n</i> <i>height</i> </p> </entry>
<entry><p>The screen height in pixels for a particular screen mode. The screen
mode is set by <i>n</i> and <i>height</i> is the height in pixels. </p> <p>In
the non-ScreenPlay variant, this value should be the same as or smaller than
the actual screen size as defined by the screen driver, after taking into
account the rotation, the top-left offset and any scaling. </p> <p>In ScreenPlay,
to define a dynamic screen mode, set this and <codeph>SCR_WIDTH</codeph> <i>n</i> to
-1. See <xref href="GUID-0EBE5733-A267-5F4A-85AD-87C3ECF80731.dita">Dynamic Resolution
Switching</xref> for more information. </p> </entry>
<entry><p>Both </p> </entry>
</row>
<row>
<entry><p> <codeph>SCR_TWIP_WIDTH</codeph> <i>n</i> <i>width</i> </p> </entry>
<entry><p>The screen width in twips for a particular screen mode. The screen
mode is set by <i>n</i> and <i>width</i> is the width in twips. </p> <p>For
dynamic screen modes in ScreenPlay, do not specify the size in twips if you
want the current resolution's size in twips to be used. If you do specify
the size in twips for a dynamic screen mode, it overrides the current resolution
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>
<entry><p>Both </p> </entry>
</row>
<row>
<entry><p> <codeph>SCR_TWIP_HEIGHT</codeph> <i>n</i> <i>height</i> </p> </entry>
<entry><p>The screen height in twips for a particular screen mode. The screen
mode is set by <i>n</i> and <i>height</i> is the height in twips. </p> <p>For
dynamic screen modes in ScreenPlay, do not specify the size in twips if you
want the current resolution's size in twips to be used. If you do specify
the size in twips for a dynamic screen mode, it overrides the current resolution
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>
<entry><p>Both </p> </entry>
</row>
<row>
<entry><p> <codeph>SIZE_MODE</codeph> <i>n</i> <i>value</i> </p> </entry>
<entry><p>The screen mode enforcement for a particular screen mode. This is
read when the system starts up. The screen mode is set by <i>n</i> and <i>value</i> is
an integer corresponding one of the screen mode enforcement flags defined
in TScreenModeEnforcement. If it is not set, a value of 0 (<codeph>ESizeEnforcementNone</codeph>)
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>
<entry><p>Both </p> </entry>
</row>
</tbody>
</tgroup>
</table> </section>
<section id="GUID-71ABB4DF-8C79-598F-BD4C-AC1EDD52AA04"><title>Plug-in specific
parameters</title> <p>These parameters relate to Window Server plug-ins. For
each plug-in, create a separate section in the <filepath>wsini.ini</filepath> file.
Specify the plug-in name in square brackets (for example, <codeph>[MYPLUGIN]</codeph>)
to indicate the start of the section. The plug-ins must also be specified
in the first or <codeph>[DEFAULT]</codeph> section by using the <codeph>PLUGINS</codeph> parameter. </p> <p>The
plug-in specific parameters are the same in both ScreenPlay and non-ScreenPlay
variants. </p> <table id="GUID-B42CA314-CAB4-5FCD-8DB1-4007A1ED2084">
<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
<thead>
<row>
<entry>Parameter </entry>
<entry>Description </entry>
</row>
</thead>
<tbody>
<row>
<entry><p> <codeph>[</codeph> <i>name</i> <codeph>]</codeph> </p> </entry>
<entry><p>Specifies the name of the plug-in and indicates the start of a section
that relates to that plug-in. </p> </entry>
</row>
<row>
<entry><p> <codeph>ID</codeph> <i>value</i> </p> </entry>
<entry><p>The UID of the plug-in DLL. The Window Server plug-in framework
uses this to search for the DLL to load. For example, if the <codeph>ID</codeph> is
12345678, the Window Server searches for a DLL called <i>12345678.dll</i>. </p> </entry>
</row>
<row>
<entry><p> <codeph>DATA</codeph> <i>value</i> </p> </entry>
<entry><p>Can be used to pass arbitrary data to the plug-in. </p> </entry>
</row>
<row>
<entry><p> <codeph>TYPE</codeph> <i>value</i> </p> </entry>
<entry><p>The type of the plug-in. For example, <codeph>CTestRenderStage</codeph>. </p> </entry>
</row>
</tbody>
</tgroup>
</table> </section>
<section id="GUID-635178C9-CFF1-5261-8A72-CC291DE98531"><title>Obsolete and
deprecated parameters</title> <p>The following table lists <filepath>wsini.ini</filepath> file
parameters that were used in earlier versions of Symbian but which are now
obsolete, deprecated or should not be used. Documentation for these parameters
can be found in earlier versions of the Symbian Developer Library. </p> <table id="GUID-0E0BE51D-A1A2-5ABC-892D-FCB94DB2D2DA">
<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
<thead>
<row>
<entry>Parameter</entry>
<entry>Status</entry>
</row>
</thead>
<tbody>
<row>
<entry><p> <codeph>ALLOWPARTIALREDRAWSTORING</codeph> </p> </entry>
<entry><p>Obsolete </p> </entry>
</row>
<row>
<entry><p> <codeph>FLICKERFREEREDRAW</codeph> </p> </entry>
<entry><p>Obsolete </p> </entry>
</row>
<row>
<entry><p> <codeph>NOREDRAWSTORING</codeph> </p> </entry>
<entry><p>Obsolete </p> </entry>
</row>
<row>
<entry><p> <codeph>OPT_LEVEL</codeph> </p> </entry>
<entry><p>Planned for deprecation in S^4. Do not change the default value
(1). </p> </entry>
</row>
<row>
<entry><p> <codeph>PRESERVESTOREDCOMMANDS</codeph> </p> </entry>
<entry><p>Obsolete </p> </entry>
</row>
<row>
<entry><p> <codeph>REMOVEFADINGONFOCUSGAIN</codeph> </p> </entry>
<entry><p>Deprecated </p> </entry>
</row>
<row>
<entry><p> <codeph>TRANSPARENCY</codeph> </p> </entry>
<entry><p>Obsolete </p> </entry>
</row>
<row>
<entry><p> <codeph>WINDOWMODE</codeph> <codeph>COLOR</codeph> <i>value</i> ¦<codeph>GRAY</codeph> <i>value</i> </p> </entry>
<entry><p>Deprecated </p> </entry>
</row>
</tbody>
</tgroup>
</table> </section>
<section id="GUID-152B59F6-E7F1-4A32-A5EA-E07B0C42EE58"><title>Example</title> <p>This
is an example of a <filepath>wsini.ini</filepath> file that configures an
emulator with two screens for the non-ScreenPlay variant. The comments refer
to the notes below. </p> <codeblock id="GUID-6B545480-53FE-5AF7-BB3A-2FB085CF7008" xml:space="preserve">LOG FL // 1
LOGP \DATA\WSERV.LOG
LOGENABLE 9
REBOOT 1
STARTUP WSHELL
KEYCLICKPLUGIN CLICK
PLUGINS TESTRENDERSTAGE FLICKERBUFFER DISPLAY
[SCREEN0] // 2
AUTOCLEAR 1
SCR_WIDTH1 0
SCR_HEIGHT1 0
SCR_ROTATION1 0,180
SCR_WIDTH2 240
SCR_HEIGHT2 80
SCR_ROTATION2 90
RENDERSTAGES TESTRENDERSTAGE FLICKERBUFFER DISPLAY
[SCREEN1] // 3
AUTOCLEAR 0 SCR_WIDTH1 800
SCR_HEIGHT1 600
SCR_ROTATION1 180
SCR_WIDTH2 240
SCR_HEIGHT2 160
SCR_ROTATION2 270
[TESTRENDERSTAGE] // 4
TYPE CTestRenderStage</codeblock> <p><b>Notes</b>: </p> <ol id="GUID-A85361C9-9D55-539A-A9DE-ADCF9AACA87B">
<li id="GUID-7A71C13C-9C1E-5955-9B52-82624ABDB26C"><p>The logging parameters
are not specific to the screen and so are placed in the first section. </p> </li>
<li id="GUID-7F9D89E8-90B2-5383-8B07-D7266D710E76"><p>These keywords apply
only to the first screen. </p> </li>
<li id="GUID-F80D77DF-DC87-5E10-A761-D89BE08FF552"><p>These keywords apply
only to the second screen. </p> </li>
<li id="GUID-9250D069-A419-55AC-A471-322CC3443C56"><p>The section for the <codeph>testrenderstage</codeph> plug-in </p> </li>
</ol> </section>
</refbody><related-links>
<link href="GUID-AA02BFA9-E62E-56FC-BF22-8FE092ABD9DA.dita"><linktext>The wsini.ini
File</linktext></link>
<link href="GUID-6E8807F5-9CC0-5A70-8182-22230D43AA9E.dita"><linktext>Setting Up
Window Server Logging</linktext></link>
</related-links></reference>