![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
This document describes the main changes that have been made to EPOC's graphics-related tools and APIs to provide colour support in EPOC Release 5.
The framework for colour support was built into EPOC from the beginning. For instance, the GDI's TRgb class is used throughout EPOC to represent colour as a 24 bit value. This 24 bit value is mapped down to device-level values by the BITGDI or printer driver. Many of the colour support changes have had no effect on EPOC APIs and are invisible to developers.
The changes include:
bmconv
tool support colour bitmaps.Section Contents
In previous releases of EPOC, a colour scheme suitable for drawing in either four or sixteen shades of grey was provided. In EPOC Release 5, two colour schemes are provided one for drawing using four shades of grey and the other for drawing in sixteen colours. This section explains how to add colour to EIKON applications.
A colour-aware application does not need to know the colour capabilities of the machine on which is is running. The same application should be able to run on an EPOC Release 5 device with a greyscale or colour screen, without modification. EIKON will detect the device's capabilities and set the colour scheme accordingly. Applications can use any TRgb values EPOC will map them to values supported by the device.
Before EPOC Release 5, the colours used in EIKON controls were specified as hardcoded TRgb values. In EPOC Release 5, these colours have been replaced by values read from a resource file.
The colour resource source file, eikcolor.ra
is installed by the C++ SDK in \eikon\group\
. If you open this file, you will see that it contains resource definitions for both colour and greyscale devices. The set of resources used by the application is dependent on the device's colour capability. On the Emulator, the colour capability is specified in the file wsini.ini
. The settings which can be specified in wsini.ini
are described in The wsini.ini file.
The default, system-wide colour settings are read into a colour list, CEikColorList, defined in the new header file, eikcolor.h
. The EIKON environment, CEikonEnv, owns the colour list, which is specific to each application. The application can access and modify its colour list through the EIKON environment. The colour list is initialised in CEikonEnv's ConstructL() function.
The colour list is an array of matching pairs of logical and physical colours. Physical colours are TRgb values, logical colours (defined by the TEikLogicalColor enum in eikcolor.h
) indicate the part of a control to which the physical colour maps. Logical colours are grouped in the TEikLogicalColor enum according to whether they are windows, controls, dialogs, menus, buttons, message windows, scrollbars, labels or toolbars. The colour list provides public, exported functions to give all controls access to its settings.
For example, before drawing a control, rather than setting the pen and brush colour using explicit TRgb values, you could extract the relevant values from the colour list using:
CGraphicsContext& gc=SystemGc(); gc.SetPenColor(iEikonEnv->ControlColor(EEikColorControlText,*this)); gc.SetBrushColor(iEikonEnv->ControlColor(EEikColorControlBackground,*this)); ...
In EPOC Release 5, all EIKON controls have been converted to use this new colour scheme.
It is possible to customise an application's colour list, so that the colours it contains are specific to the application. There are two ways in which this can happen. Individual colours within the colour list may be modified, or a new array of logical and physical colour mappings may be appended to the list.
To change the colour used for a particular UI component, you can use code such as the following:
iEikonEnv->ColorList().SetColor(EEikColorDialogTitle,KRgbDarkCyan);
CEikColorList::SetColor() may be used to change the mapping between a logical and a physical color, in this case setting the colour for dialog titles throughout the application to KRgbDarkCyan.
Note that in general it is not recommended that developers override the default colour scheme settings for their application.
Applications may need to create new, application-specific logical colours. This can be done by appending the new logical colours to the colour list. The following code reads an array of logical colours from a resource file then appends the colour array to the colour list.
TInt numGrays=0; TInt numColors=0; TDisplayMode defaultMode=iEikonEnv->WsSession().GetDefModeMaxNumColors(numColors,numGrays); // Get default display mode - ignore numColors and numGrays const TInt resourceId=(defaultMode>=EColor16? r_myapp_color_color16 : r_myapp_color_gray4); CEikColorArray* colors=EikResourceUtils::CreateColorArrayLC(resourceId,iEikonEnv); iEikonEnv->ColorList().AddColorArrayL(KMyAppUid,colors); // takes ownership CleanupStack::Pop(); // delete colors
r_myapp_color_color16 and r_myapp_color_gray4 are COLORLIST resources, defined in the application's resource file.
COLORLIST is a resource struct, defined in eikcolor.rh
as:
STRUCT COLORLIST
{
LLINK array_id=0;
}
The r_myapp_color_color16 and r_myapp_color_gray4 resources each contain an array of CTRL_COLOR resource structs. CTRL_COLOR resource structs specify logical and physical colour mappings.
To retrieve the number of colours supported by the device, use the new window server function RWsSession::GetDefModeMaxNumColors(). If sixteen colours or more are supported, then the r_myapp_color_color16 resource will be used. Otherwise, the r_myapp_color_gray4 will be used.
EikResourceUtils::CreateColorArrayLC() creates the colour array from the resource file and CEikColorList::AddColorArrayL() appends the colour array to the colour list.
Colour arrays do not have to be read from resource files, but it is recommended that they are.
Some new functions have been added to the CEikonEnv class in EPOC Release 5 to enable custom controls to retrieve colours from the colour list, and to override the system default colour settings. For documentation of these new functions, see CEikonEnv class.
Another feature new to EIKON in EPOC Release 5 is the extension of the existing grey selector and grey palette classes (CEikGraySelector and CEikGrayPalette) to allow the selection of up to 16 colours.
CEikGrayPalette, defined in eikgysel.h
previously provided a palette of grey shades only. Now it supports both greyscale and colour display modes, depending on the device's capabilities.
An instance of CEikGrayPalette may be created by the grey selector and displayed as a popout list. For an example of the grey selector and palette classes in colour display mode, see the screen shot below of the colour tool in the Sketch application.
The display mode for the grey selector and palette depends on the flags specified on construction. The available flags for the grey selector are defined in eikgysel.hrh
. If the grey selector's associated window is using a colour display mode, construct the CEikGraySelector specifying EEikGraySelDisplay16Color, otherwise, use EEikGraySelDisplay4Gray or EEikGraySelDisplay16Gray. Specifying both a colour and a grey mode flag together with the EEikGraySelColorIfAvailable flag ensures that a colour selection will be offered by the CEikGraySelector if the window associated with the selector supports colour.
The API changes to the CEikGrayPalette class are described in CEikGrayPalette class.
The new colour manipulation class EikColorUtils is described in EikColorUtils class.
The GDI is EPOC's common abstract graphics classes component. It enables programs to request any 24 bit RGB value using the TRgb class and it is responsible for performing the mapping between TRgb values and the nearest available colour values in the hardware's colour palette. Although colour support was already built into the GDI, several new functions have been added in EPOC Release 5 to support colour mapping.
In summary, the following changes have been made to the GDI's API:
Section Contents
In EPOC Release 5, the window server has been extended to support colour display modes for windows.
In previous releases of EPOC, a window's display mode (enumerated in the TDisplayMode type) could only be set to EGray2, EGray4 or EGray16. In EPOC Release 5, the window server will accept any display mode, returning the closest match that is available on the hardware.
Typically, EPOC devices will support more than one screen display mode.
When a window is created, its display mode is set to the system's default display mode, (RBackedUpWindows are an exception their display mode is specified upon construction). The window's display mode can be changed after creation. Before EPOC Release 5, the default display mode had a fixed value of EGray4. In EPOC Release 5, the default display mode is specified in the window server configuration file, wsini.ini
. For a description of all the settings which may be specified in wsini.ini
, including the default display mode setting, see The wsini.ini file.
Note also that some arguments which could be specified in wsini.ini
in EPOC Release 3 are no longer recognised in EPOC Release 5. These arguments are:
Support has been added to the RWsSession class to retrieve the default display mode, see the description of RWsSession::GetDefModeMaxColors() in RWsSession class.
The display mode for all window types except backed-up windows can be changed after creation by calling RWindowBase::SetRequiredDisplayMode(). As in previous releases of EPOC, when a visible window's display mode is changed, the window server may carry out display mode switching.
Display mode switching means changing the screen's display mode so that it is optimised for the windows currently visible within it. For example, if the screen's display mode is EColor256, but no visible window has a display mode greater than EColor16, the window server will reduce the screen's display mode to EColor16. This minimises the device's battery usage.
In EPOC Release 5, support has been added to the screen and bitmap specific graphics drawing component (BITGDI) for drawing colour bitmaps. This section describes some issues involved when drawing a colour bitmap to a window.
When drawing a bitmap, the number of colours in which the bitmap can be drawn is limited to the number of colours supported by the window in which it is drawn. If you try to draw a colour bitmap to a window which doesn't support the number of colours used in the bitmap, then the colours used to draw the bitmap will be converted to colours supported by the window.
This colour conversion process is time consuming and causes bitmaps to be drawn slowly. If in addition to this, the screen supports more colours than the window being drawn to, drawing the bitmap may be even slower. This is because in this case, a second conversion may be necessary to upgrade each pixel in the bitmap so that it uses the number of bits supported by the screen's display mode.
For instance, if a 256 colour bitmap is drawn to a 16 colour window when the screen's display mode is true colour (EColor16M), each colour used to draw the bitmap will be converted to a colour which exists in the window's more limited colour palette. Then, each pixel in the bitmap will be converted from using 8 bits to using 24 bits.
In order to minimise the slowness caused by colour conversion, you should try to ensure that the bitmap uses the same display mode as the window. This value should not be hardcoded because the hardware may not support the requested display mode. Instead, you should create the window, retrieve its display mode (using RWindowBase::DisplayMode(), described below), then create the bitmap in the same display mode as the window. Note that in the unusual case that the screen's display mode is greater than the display mode of the window you are drawing to, drawing bitmaps will still be slow. This cannot be avoided.
The functions which are either new to or have been modified in EPOC Release 5 are described in RWindowBase class and in RWsSession class. All are defined in w32std.h
.
Section Contents
bmconv
and FBSERVbmconv
The bmconv
tool is used to convert bitmaps between EPOC and Windows bitmap formats. Before EPOC Release 5, it was limited to creating 2 or 4 bits per pixel bitmaps. In EPOC Release 5, it has been extended to allow conversion in both directions, in any of the available display modes. Additionally, some new arguments may be specified.
For documentation of bmconv
, including descriptions of the pre-existing arguments as well as the new arguments in EPOC Release 5, see the documentation of bmconv
in the EPOC Tools and Utilities documentation (bmconv.exe).
The font and bitmap server (FBSERV), which handles loading and storing bitmaps and fonts has been extended to support loading, saving and reading from bitmaps in all display modes (including EGray256, EColor16, EColor256, EColor4K, EColor64K and EColor16M).
The changes have had no effect on APIs, except that the TBitmapFileCompression enum, defined in bitmap.h
has been extended to support the compression of 12, 16 and 24 bits per pixel bitmaps. For details, see the documentation in TBitmapFileCompression enum.
Some new functions have been added to the CCoeControl class in EPOC Release 5. For details, see CCoeControl class.
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |