WSINI.INI

Parameter

Description

[SCREENn]

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 first section, which is not preceded by this keyword, contains the parameters that do not relate to the screen, for instance the logging parameters, and any screen-related parameters whose value is the same for all screens. Note that there can only be one such section. The documentation for each parameter, below, indicates whether it is screen-related or not. The first section may optionally be preceded by the keyword [DEFAULT].

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 phone does not support multiple screens, this keyword should not appear in its wsini.ini file.

ABSOLUTEFADING

If this is specified, the window server uses absolute fading. If not specified, it uses counted fading. Counted fading means that a window is faded only if SetFaded(ETrue) has been called on it more often than SetFaded(EFalse). This system provides support for nested popups (where popups cause the background to fade). Absolute fading overrides this, so that calling SetFaded(ETrue) on an unfaded window causes it to become faded, and SetFaded(EFalse) on a faded window causes it to become unfaded, regardless of the window's fade count.

Screen-related.

AUTOCLEAR value

When an RWindow is manipulated by an application, this argument determines whether the invalid region will be cleared to its background colour (as set by either variant of RWindow::SetBackgroundColor()) before being redrawn.

The possible values are:

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

1 — the default. The background will be cleared if a background colour has been set, but not if no background colour has been set.

Screen-related.

FLICKERFREEREDRAW

When this is specified, all redraw drawing is done via an offscreen bitmap allocated by the window server, which has the same size and bitdepth as the screen. The relevant part of the offscreen bitmap is transferred to the screen in a single bitblit operation in the window's EndRedraw() function. Because the screen is redrawn in a single operation, flicker is eliminated.

Note that specifying the TRANSPARENCY keyword also causes redraws to use offscreen bitmaps. If neither keyword is specified, then redraw drawing is done directly to the screen.

The offscreen bitmap uses the highest display mode available and therefore can use a lot of memory. This memory is allocated at system boot time.

Notes:

• redraw drawing using offscreen bitmaps begins by clearing the part of the offscreen bitmap corresponding to the window's invalid region, using the window's background colour. If the window has no background colour, white is used. Therefore, all pixels in the invalid region that should not have this colour must be explicitly redrawn.

• redraw drawing without using offscreen bitmaps may either clear the invalid parts of the window that are not explicitly redrawn, using the window's background colour (as when drawing to an offscreen bitmap), or it may leave them unchanged, depending mainly on how the region was invalidated.

• See also BLTOFFSCREENBITMAP (below)

Screen-related.

KEYCLICKPLUGIN filename

The window server attempts to load the named key or pointer click plug-in DLL. If this fails or if this keyword doesn't appear, a plug-in will not be used and key and pointer clicks will not be enabled.

Not screen-related.

KEYCLICKPLUGINFIXED

Disallows window server clients from removing or changing the key or pointer click plug-in. This would be used on hardware where the manufacturer wants to disallow key or pointer clicks or where only one plug-in should be used.

Not screen-related.

LOG string

Used to specify the type of logging which is required. Loads one of the three logging DLLs, as specified by string. Possible values are:

FL — log to file

SR — log to the serial port (MARM only)

WN — log to another WIN32 window (emulator only)

Not screen-related.

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 in addition, 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 and is the default.

Not screen-related.

LOGP filespec

Use this keyword to specify a fully qualified file name for the output log file.

Not screen-related.

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 the name of the shell is specified on the STARTUP keyword.

NOREDRAWSTORING

Suppresses window server redraw storing.

When redraw storing is used, the window server stores the sequence of drawing commands used by clients the first time they need to do a server-initiated redraw (for instance when part of a window has become exposed). All subsequent server-initiated redraws are done by the server itself, by repeating the sequence of stored commands, rather than by sending redraw requests to the client. The benefits of this are that the number of client-server transactions is minimised, and redraws are done as soon as the server detects they are needed.

Suppressing redraw storing causes the window server to revert to pre-v8.0 behaviour, so that redraws are done by the client in response to redraw requests from the server. This keyword is provided for legacy code that depends on this behaviour.

For reasons of efficiency, redraw storing cannot be suppressed when transparent windows are used (see the TRANSPARENCY keyword).

Screen-related.

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

Screen-related.

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 in the PROTECTEDKEYWINDOWNAME parameter.

Note that only one key can be protected in this way; in other words, these two parameters cannot 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 should be 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 should be 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.

Keyvalue can be specified either as a hexadecimal or decimal number.

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

REBOOT value

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

2 — the window server shuts down the machine as soon as the shell dies or exits — for use during development only

Note: the window server detects an application exiting by its window server session being closed. In rare cases, an application may not have a window server session, or it may have closed its session without exiting. In such cases, when REBOOT 1 is specified in wsini.ini, the shell might restart even though some applications are still running.

Not screen-related.

SCR_LEFTn value

The screen's horizontal offset in pixels. Moves the screen's contents to the left.

By default this is zero.

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

Screen-related.

SCR_TOPn value

The screen's vertical offset in pixels. Moves the screen's contents upwards.

By default this is zero.

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

Screen-related.

SCR_XSCALEn factor

The horizontal screen scaling factor.

n is the screen mode and factor is the scaling factor (a positive integer). 1 (the default) means no scaling. For example, specifying:

SCR_XSCALE1 2
SCR_YSCALE1 2

means that in the first screen mode, everything is drawn 4 times larger; in other words, drawing to logical pixel (0,0) will cause 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, if the following values are specified:

SCR_LEFT1 5
SCR_XSCALE1 2

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

Screen-related.

SCR_YSCALEn factor

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

Screen-related.

SCR_ROTATIONn rotations

Specifies a list of screen rotations.

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

The rotations value is a comma separated list which specifies, in degrees, the rotation values available for the given screen size.

For example, SCR_ROTATION2 90,270.

Screen-related.

Note: While rotation is supported by the generic Symbian OS, 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.

SCR_WIDTHn 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, SCR_WIDTH2 240 sets a width of 240 pixels for screen mode 2.

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.

Screen-related.

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

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.

Screen-related.

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

Screen-related.

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

Screen-related.

SHELLCMD string

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

Defaults to an empty string.

Not screen-related.

SIZE_MODE

The screen mode enforcement. It is read when the system boots. If it is not set then a value of 0 (ESizeEnforcementNone) is used. The screen mode is the combination of screen rotation and screen size.

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

Screen-related.

STARTUP string

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

Not screen-related.

TRANSPARENCY

When this is specified, all redraw drawing of transparent windows is done using two offscreen bitmaps, both the size of the screen. When the only visible windows are opaque, redraw drawing uses a single offscreen bitmap.

With a single layer of transparency, the transparent window in the foreground is drawn to one bitmap, and the windows behind it are drawn to the other. With multiple layers of transparency, the latter bitmap may be the result of combining the contents of multiple transparent windows. The two bitmaps are combined using the foreground bitmap's alpha channel and the result is applied to the screen in the same way as for flicker free redraw drawing (see FLICKERFREEREDRAW).

The offscreen bitmaps use the highest display mode available and therefore can use a lot of memory. The memory required for them is allocated at system boot time.

See also the notes in the description of FLICKERFREEREDRAW.

Screen-related.

WINDOWMODE COLORvalue

or

WINDOWMODE GRAYvalue

This is used to set the default display mode. On the Emulator, it may be used to reflect the fact that different hardware may require different default display modes.

If it is omitted, or if the requested display mode is not supported by the phone, the machine's lowest display mode is used. An exception to this is that EGray2 will only be used if no other display modes are supported. The lowest display mode is the one which supports the fewest greys/colours. Note that all greyscale display modes are considered to be lower than any colour display mode.

For a colour display mode, value can be one of the following:

• 16 for EColor16,

• 256 for EColor256,

• 4K for EColor4K,

• 64K for EColor64K,

• 16M for EColor16M.

For instance, specifying WINDOWMODE COLOR256 gives a default display mode of 256 colours.

For a greyscale display mode, value can be one of the following:

• 2 for EGray2,

• 4 for EGray4,

• 16 for EGray16,

• 256 for EGray256.

For instance, specifying WINDOWMODE GRAY16 gives a default display mode of 16 greys.

Screen-related.

BLTOFFSCREENBITMAP

If this is specified in addition to FLICKERFREEREDRAW the invalid region of the offscreen bitmap is not set to white or the background colour, 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 OSB 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.

Screen-related.