Emulator initialisation file: epoc.ini

The Emulator can be configured using an initialisation file which is located at \epoc32\data\ on the PC file system. By default, the name of the initialisation file is epoc.ini, however this can be changed using the command line option -M.

The following sections provide an exhaustive list of the available configuration options. Note that not all these options will be meaningful in the context of a particular reference design.

Configuration options are specified on separate lines of epoc.ini. The option is specified first, followed by a space, followed by the “amount” of the option. For example, to set the screen width as 640 pixels and the screen height as 240 pixels, the epoc.ini entry would be:

ScreenWidth 640 ScreenHeight 240

Value	Parameters	Definition
`ScreenWidth`	integer	Screen width in pixels
`ScreenHeight`	integer	Screen height in pixels
`PhysicalScreenWidth`	integer	Physical screen width in twips
`PhysicalScreenHeight`	integer	Physical screen height in twips
`ScreenOffsetX`	integer	Symbian machine screen offset from left hand side
`ScreenOffsetY`	integer	Symbian machine screen offset from top

Note

The twips settings allow the GDI’s twips-to-pixels mapping functions to be changed according the size of the physical screen on the emulated model. The default values correspond to 0.21mm pixel size or 121 pixels per inch.

Value	Parameters	Definition
`FasciaBitmap`	bitmap name and path	sets background bitmap

The following keywords are for configuring the digitiser size. The default behaviour is that the digitiser is enabled and is the same size as the fascia bitmap.

Value	Parameters	Definition
`DigitizerOffsetX`	integer	Position of the left of the emulated digitiser relative to the screen (not the fascia bitmap). The offset will generally be a negative number as the digitiser overlaps the screen in all directions — defaults to minus the offset of the screen in the bitmap.
`DigitizerOffsetY`	integer	Position of the top of the emulated digitiser relative to the screen (not the fascia bitmap). The offset will generally be a negative number as the digitiser overlaps the screen in all directions — defaults to minus the offset of the screen in the bitmap.
`DigitizerWidth`	integer	Width of digitiser in pixels.
`DigitizerHeight`	integer	Height of digitiser in pixels
`DisableDigitizer`	integer	Disable digitiser. If this is specified, no mouse events will be generated and buttons on the bitmap which are implemented with an off screen window will not work. The VirtualKey regions defined in the emulator configuration file will still work as they generate key events to the Symbian Platform — not pointer events.

Value	Parameters	Definition
`VirtualKey`	key-code shape params	defines virtual key region

Note:

The syntax will allow different shapes, but the only shape supported is rect which specifies a rectangle. The parameters are the co-ordinates for the top left and bottom right of the rectangle.

Value	Parameters	Definition
`KeyMap`	realkey key-code	maps a real key on the keyboard to a Symbian platform key.

In reference designs which support two hardware LEDs, the following settings determine the appearance of these LEDs.

Value	Parameters	Definition
`LedSize`	integer	Size of LED in pixels.
`LedArrangeVertically`	n/a	arrange the LEDs vertically
`LedArrangeHorizontally`	n/a	arrange the LEDs horizontally
`LedOffsetX`	integer	LED offset from the left of the bitmap
`LedOffsetY`	integer	LED offset from the top of the bitmap
`LedGap`	integer	Gap between the LEDs in pixels

Value

Parameters

Definition

DebugMask

integer

Deprecated keyword — used in kernel tracing. It specifies a value to be passed to User::SetDebugMask() to control the kind of debugging information printed to the debugger's output window.

DebugMask is not useful for most developers since it's related specifically to kernel tracing. Developers are more likely to use debug messages from their own code.

JustInTime

0,1

Calls User::SetJustInTime. Stops the just in time debugging to occur with the debug emulator.

Value	Parameters	Definition
`PointerType`	None, Pen, Mouse, Delta-Mouse	pointer type

The PointerType setting in the emulator configuration file sets the type of pointer device that is available on the target machine. The setting determines the events that the window server makes available to applications.

PEN simulates pen input: events only occur when the pen is touching the digitiser—in the emulator, when the left mouse button is depressed. With MOUSE, an application also gets Move events: that is, an application can detect a mouse moving even while the button is not pressed. NONE is not currently supported.

The standard shell and applications do not respond to Move events, so the setting value does not alter their behaviour.

Value	Parameters	Definition
`MegabytesOfFreeMemory`	integer	Limits amount of RAM available to the Symbian platform.

This option sets the maximum total heap size in megabytes, in order to emulate target machines with different memory capacities. If this parameter is not specified, the amount of free memory defaults to 64MB.

If you wish to limit the heap, it is conventional to allow one megabyte for Symbian system use: for example, specify 7 to simulate a 8MB machine.

Value	Parameters	Definition
`ColorDepth`	`Gray2`, `Gray4`, `Gray16`, `Gray256`, `Color16`, `Color256`, `Color4k`, `Color64k`, `Color16M`	Sets the colour depth for the Symbian platform to simulate various colour devices.

For more than one colour depth, specify the ColorDepth keyword once, and then specify as many of the color depth parameters as you want on the same line, for instance:

ColorDepth Gray256 Color256 Color4k

Emulator initialisation file: `epoc.ini`

Purpose

Syntax

Configuration options

Screen size and position

Note

FasciaBitmap

Digitiser size

VirtualKey

Note:

KeyMap

LEDs

Debugging

Pointer type

Memory capacity

Colour depth

Alias name

Comments