The wsini.ini File Reference

ABSOLUTEFADING

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 SetFaded() calls. This mechanism provides support for nested pop-ups (where pop-ups cause the background to fade).

In absolute fading, Window Server uses a TBool value instead, so that SetFaded(ETrue/EFalse) fades or unfades the window, regardless of nesting.

Both

ANIMATIONGRACEPERIOD value

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.

Both

ATOMICREDRAWS

Specify this parameter to enable atomic redraws.

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.

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.

See Redraw Stores for more information.

Both

BACKGROUNDALPHA value

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.

Specify value as an integer in the range 0–255. If this parameter is not specified, the default value is 0xFF or completely opaque.

Note that a background alpha value of zero means that the window background color is not drawn at all.

Both

BACKGROUNDCOLOR value

Sets the default window background color. Enter value in the form: 0x rrggbb. For example, the following specifies a red default background color:

BACKGROUNDCOLOR 0xff0000

If this parameter is not specified, the default background color is white.

Both

DEBUGBAR

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:

KeyEvents 0; 0; WServ 0.0%; Drawing 0.0%; Reclaimed 0.0%
RedrawStore size 0B; updates 0/s, pixels 0/s

• KeyEvents shows the total number of key events and scheduler requests.

• Wserv shows the percentage of scheduler activity occupied by the Window Server.

• Drawing shows the percentage of Window Server activity that is spent drawing.

• Reclaimed shows the percentage of idle time reclaimed by the Window Server to perform drawing when there are is no higher priority activity.

• RedrawStore size 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.

• Updates shows the number of screen updates per second.

• Pixels shows the number of pixels updated per second—that is, the pixel fill rate.

Both

DISABLEIDLEANIMATION

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 idle animation and this parameter disables it.

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.

This parameter has no effect in the ScreenPlay variant, because idle animation is disabled by default in the ScreenPlay variant.

Non-ScreenPlay

DSAANIMATIONGRACEPERIOD value

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.

Both

FADEDISABLE

Disables fading, which means that calls to the following functions have no visual effect on the Window Server's drawing:

• RWsSession::SetSystemFaded()

• RWindowBase::FadeBehind()

• RWindowTreeNode::SetFaded()

Both

FINISHEVERYFLUSH

Configures the behavior of RWsSession::Flush(), so that the Window Server synchronizes the message buffer and forces the screen to update. If this parameter is not present, Flush() synchronizes the message buffer and does not guarantee to present any drawing commands within the buffer to the screen.

Before the introduction of the Window Server improvements known as WSERV2, the Window Server, Flush() did two distinct things:

1. Flushed the session's command buffer.

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

By default Flush() now does the first of these steps only. Use FINISHEVERYFLUSH to cause Flush() to continue the previous behavior.

In the improved Window Server (WServ2), there are two new methods that explicitly separate these two behaviors. The methods are RWsSession::SyncMsgBuf() and RWsSession::Finish().

Both

FRAMECAPTURE

This parameter is for use when debugging render stage plug-ins. When specified, the Window Server captures frame bitmaps and saves them in frame_<timestamp>.mbm files. These are located in the epoc32\winscw\c folder for winscw and e:\storyboard\ for H4 boards.

This option takes effect only when the Window Server and its plug-ins are compiled with the USE_DEBUG_FRAME_CAPTURE macro defined.

Both

IGNORESWITCHOFFEVENT

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 EEventSwitchOff, EEventCaseClosed, EEventKeySwitchOff or EEventRestartSystem.

Both

KEYCLICKPLUGIN filename

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.

Both

KEYCLICKPLUGINFIXED

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.

Both

LOG string

Specifies the type of logging that is required. Loads one of the three logging DLLs, as specified by string. Possible values of string are:

• FL — log to file

• SR — log to the serial port (MARM only)

• WN — log to another WIN32 window (emulator only)

Both

LOGENABLE value

If specified, enables logging from boot-up. You can optionally specify a value that must be one of the following:

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

• 5 — Enables intermediate logging. This includes all the messages logged using limited logging, and adding and removing Window Server clients.

• 1 — Enables full logging of all messages to and from the Window Server. This is the most commonly used option and is the default.

Both

LOGP filespec

The fully qualified file name of the output log file.

Both

MEMORYRESERVE value

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.

If this parameter is not specified, the memory manager allocates 1024 bytes of memory to hold as its reserve.

Both

MULTIFOCUSPOLICY

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.

When a window group has focus, 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.

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

Both

NOBLANKSCREEN

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.

Note that you specify the name of the shell by using the STARTUP parameter.

Both

NONREDRAWAGELIMIT duration

The lifetime in microseconds of non-redraw segments within the redraw stores in the non-ScreenPlay variant only.

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:

• checks the ages of the non-redraw segments within the store

• discards any old non-redraw segments and if necessary requests a client-side redraw

• creates a new non-redraw segment for new non-redraw commands.

The NONREDRAWAGELIMIT parameter allows for the customization of the age limit. If not defined, a default of 1,000,000 microseconds or 1 second is used.

Non-ScreenPlay

ONINACTIVE value

Specifies what happens when there is no key or pointer activity for a period of time. Possible values are:

• STOPANIMATION — this means continue client-side redraws and stop all server-side drawing. This is the most obvious option.

• STOPALLDRAWING — this stops both client-side and server-side drawing.

• IGNORE — this means ignore the inactivity and draw as normal.

Both

PLUGINS string

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 wsini.ini file to specify its details (such as UID and type). See Plug-in Parameters for more information.

If not specified, the plug-in manager loads the default plug-ins. In the ScreenPlay variant, these are flickerbuffer and display. In the non-ScreenPlay variant, they are flickerbuffer, std and defaultfader.

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 newplugin in addition to the default plug-ins:

PLUGINS flickerbuffer display newplugin

Both

PROTECTEDKEY keyvalue

PROTECTEDKEYWINDOWNAME windowgroupname

'Protects' a key, so that it can only be captured (by calling RWindowGroup::CaptureKey() or RWindowGroup::CaptureKeyUpAndDowns()) by the window group identified by the PROTECTEDKEYWINDOWNAME parameter.

Only one key can be protected in this way. This means that these two parameters must not appear more than once in the wsini.ini file.

When a client attempts to capture a standard key event (rather than a key up or down event), keyvalue is matched against the key code (as defined in the TKeyCode enum in e32keys.h) to see if the key is protected or not.

When a client attempts to capture an up or down key event, keyvalue is matched against the scan code (as defined in the TStdScanCode enum in e32keys.h) to see if the key is protected or not.

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.

You can specify keyvalue as a hexadecimal or decimal number.

windowgroupname is the window group name (see RWindowGroup::SetName()) or a substring of it.

Both

REBOOT value

The shell reboot mode. The following values are defined:

• 0 — the Window Server tries to restart the shell as soon as the shell dies or exits.

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

• 2 — the Window Server shuts down the machine as soon as the shell dies or exits — for use during development only .

Both

REDRAWGRACEPERIOD value

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.

Both

REPEATROLLOVER value

Specify this parameter with value of 1 in order to allow key repeat rollovers.

Both

ROOTBACKGROUNDALPHA value

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.

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.

Specify value 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 BACKGROUNDALPHA or 0xFF, if it is not specified.

Non-ScreenPlay

ROOTBACKGROUNDCOLOR value

The background color of the root window, if you want to set it independently from the default background color of other windows.

If not used, the root window’s background color is set to the default background window value—that is, the value set by BACKGROUNDCOLOR or KRgbWhite if it is not specified.

Both

SHELLCMD string

Specifies the command line argument to pass when starting the shell. This is similar to DOS command parameters under Microsoft Windows.

Defaults to an empty string.

Both

STARTUP string

Specifies the name of the shell to use. Defaults to shell.

Both

[SCREEN n ]

A wsini.ini 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.

The n value is a number that indicates which screen the section applies to. For instance, [SCREEN0] is the first screen, [SCREEN1] the second.

If the device does not support multiple screens, this keyword should not appear in the wsini.ini file.

Both

AUTOCLEAR value

When an RWindow is manipulated by an application, this parameter determines whether the invalid region is cleared to its background color (as set by either variant of RWindow::SetBackgroundColor()) before being redrawn. The possible values are:

• 0 — the background is not cleared, even if a background color has been set. This is for use in debugging only.

• 1 — the default. The background is cleared if a background color has been set, but not if no background color has been set.

Both

BACKLIGHTCONTROL

Enables calls to CWsScreenDevice::SetBackLight(). If this parameter is not specified, this function returns KErrPermissionDenied.

Both

BLANKSCREENONROTATION

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.

Both

BLTOFFSCREENBITMAP

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.

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.

Non-ScreenPlay

CHANGETRACKING

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 Window Server Rendering Loop for more information.

ScreenPlay

CHROMAKEYCOLOR value

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.

Enter the value in the form 0xff rrggbb, where rr is the hex value for red, gg for green and bb for blue. For example:

CHROMAKEYCOLOR 0xFF123456

If this parameter is not specified, the default value is 0.

Note: Chroma key transparency is not used in EColor16MA and EColor16MAP display modes. This is because they are RGBA modes and therefore have an alpha value in addition to the RGB value.

ScreenPlay

DEBUGOSB

Enables you to use Win32-dependent code for debugging the Window Server offscreen buffer and UI surface for each screen on the emulator.

Both

DP_SCALING string

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:

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

• isotropic — this allows any scaling factor, not only integer ones. However, the horizontal and the vertical scaling factors are the same.

• anisotropic — this allows any scaling factor and does not restrict the relationship between the horizontal and vertical scaling factors.

Any other value is taken to mean no scaling.

ScreenPlay

FADER string

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 FadeArea when windows are faded.

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 PLUGINS parameter in order to be loaded.

Fader plugins are specified per screen so it is possible to use different fading effects on different screens. Here is a simplified example:

PLUGINS flickerbuffer std defaultfader customfaderA customfaderB
SCREEN[0]
FADER customfaderA
SCREEN[1]
FADER customfaderB

Note: Fading is essentially disabled in the non-ScreenPlay variant if a custom fader is not specified using the FADER parameter and the PLUGINS command is overridden so that the default fader plugin is not loaded.

Non-ScreenPlay

FLICKERBUFFERMODE value

The TDisplayMode of the flicker buffer if one is in use. If not specified, the flicker buffer has the same color depth as the screen.

Both

NUMSCREENMODES value

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.

The value is a positive integer which specifies the highest screen mode index that is defined in the wsini.ini file.

For example, in the following example, the last 3 lines would be ignored, unless NUMSCREENMODES 3 was specified beforehand:

SCR_WIDTH1 800
SCR_HEIGHT1 600
SCR_ROTATION1 180
SCR_WIDTH3 240
SCR_HEIGHT3 160
SCR_ROTATION3 270

Both

RENDERSTAGES string

Specifies the type and order of the render stages to be used by the Window Server.

If not defined, this defaults to flickerbuffer display in the ScreenPlay variant and flickerbuffer std 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 display (called std in the non-ScreenPlay variant) render stage, which draws it to the screen.

The render stages are plug-ins and you must also specify them in the PLUGINS parameter in order to be loaded.

Both

SCREENMODE COLORvalue ¦ GRAYvalue

Specifies the display mode to be used for the screen device. The COLOR or GRAY prefix plus value must correspond to a member of the TDisplayMode enumerated type but without the initial E.

For example, SCREENMODE COLOR16M corresponds to EColor16M and gives a display mode of 16 million colors.

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

Note: This parameter replaces the deprecated WINDOWMODE parameter.

Both

SCR_LEFT n value

The horizontal offset in pixels for a particular screen mode. Moves the screen's contents to the left. By default this is zero.

n is an integer greater than zero that identifies the screen mode. value is the offset in pixels (greater than zero).

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 Dynamic Resolution Switching for more information.

Both

SCR_TOP n value

The vertical offset in pixels for a particular screen mode. Moves the screen's contents upwards. By default this is zero.

n is an integer greater than zero that identifies the screen mode. value is the offset in pixels (greater than zero).

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 Dynamic Resolution Switching for more information.

Both

SCR_XSCALE n factor

The horizontal screen scaling factor for a particular screen mode.

n is the screen mode and factor 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:

SCR_XSCALE1 2
SCR_YSCALE1 2

In other words, drawing to logical pixel (0,0) causes physical pixels (0,0), (0,1), (1,0) and (1,1) to change.

Note that on the emulator, screen scaling only works if the display mode is Color256.

If an offset is specified (using SCR_LEFT or SCR_TOP) as well as a scaling factor, the offset is applied in unscaled coordinates. For example, suppose the following values are specified:

SCR_LEFT1 5
SCR_XSCALE1 2

This means that the mapping between logical and physical pixels for the first screen mode is as follows:

In this example, there are 51 addressable logical pixels.

See also CWsScreenDevice::GetScreenModeScale(), CWsScreenDevice::GetCurrentScreenModeScale()

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 Dynamic Resolution Switching for more information.

Non-ScreenPlay

SCR_YSCALE n factor

The vertical screen scaling factor for a particular screen mode. See SCR_XSCALE for a description.

Non-ScreenPlay

SCR_ROTATION n rotations

Specifies a list of screen rotations for a particular screen mode.

The n value is a positive integer which corresponds to a particular screen mode.

The rotations value is a comma separated list that specifies, in degrees, the rotation values available for the given screen mode. For example:

SCR_ROTATION2 90,270

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.

Both

SCR_WIDTH n width

The screen width in pixels for a particular screen mode. The screen mode is set by n and width is the width in pixels.

For example, the following sets a width of 240 pixels for screen mode 2:

SCR_WIDTH2 240

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.

In ScreenPlay, to define a dynamic screen mode, set this and SCR_HEIGHT n to -1. See Dynamic Resolution Switching for more information.

Both

SCR_HEIGHT n height

The screen height in pixels for a particular screen mode. The screen mode is set by n and height is the height in pixels.

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.

In ScreenPlay, to define a dynamic screen mode, set this and SCR_WIDTH n to -1. See Dynamic Resolution Switching for more information.

Both

SCR_TWIP_WIDTH n width

The screen width in twips for a particular screen mode. The screen mode is set by n and width is the width in twips.

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 CWsScreenDevice::SizeInTwips().

Both

SCR_TWIP_HEIGHT n height

The screen height in twips for a particular screen mode. The screen mode is set by n and height is the height in twips.

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 CWsScreenDevice::SizeInTwips().

Both

SIZE_MODE n value

The screen mode enforcement for a particular screen mode. This is read when the system starts up. The screen mode is set by n and value is an integer corresponding one of the screen mode enforcement flags defined in TScreenModeEnforcement. If it is not set, a value of 0 (ESizeEnforcementNone) is used.

See also: CWsScreenDevice::ScreenModeEnforcement(), CWsScreenDevice::SetScreenModeEnforcement()

Both

[ name ]

Specifies the name of the plug-in and indicates the start of a section that relates to that plug-in.

ID value

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 ID is 12345678, the Window Server searches for a DLL called 12345678.dll.

DATA value

Can be used to pass arbitrary data to the plug-in.

TYPE value

The type of the plug-in. For example, CTestRenderStage.

ALLOWPARTIALREDRAWSTORING

Obsolete

FLICKERFREEREDRAW

Obsolete

NOREDRAWSTORING

Obsolete

OPT_LEVEL

Planned for deprecation in S^4. Do not change the default value (1).

PRESERVESTOREDCOMMANDS

Obsolete

REMOVEFADINGONFOCUSGAIN

Deprecated

TRANSPARENCY

Obsolete

WINDOWMODE COLOR value ¦GRAY value

Deprecated