The control environment

The control environment packages the interface to the window server and provides an environment for creating controls. It is implemented in a single class, CCoeEnv, which encapsulates active objects and an active scheduler for receiving events from the window server. Each application has exactly one CCoeEnv object which is stored in Thread Local Storage (TLS).

CCoeEnv also provides a number of utilities which are useful to most applications. These utilities include:

• creating a graphics context, the system graphics context. This is the standard graphics context which is normally used for drawing controls. It may be accessed using CCoeEnv::SystemGc() but controls should get their graphics context using CCoeControl::SystemGc() rather than directly from the environment.

• access to the window server session

• utilities for using fonts

• utilities for reading resource values from resource files

• Support for singleton (static) objects

CCoeEnv maintains a list of the resource files used by the application. Files may be added to the list using AddResourceFileL() and removed using DeleteResourceFile().

The utility functions provided by the control environment read resources and resource data from the resource files in its list.

A resource file consists of a list of resources, each identified by a resource ID. Each resource consists of a list of resource values in the form of binary data. The order and lengths of the values for each resource type are defined in a resource definition (generally stored in a file with an .rh extension).

Reading data from a resource file requires two stages:

• read a resource from the resource file into a buffer

• read values from the resource using a resource reader

CCoeEnv provides utility functions to perform the first of these stages and functions to create resource readers.

An application's default resource file, one which has the same name as the application, is loaded automatically.

It should be noted that stage two can be omitted if the resource contains only one value, or if it is read into a formatted buffer. In both of these cases the resource data can be read straight from the buffer.

The CCoeStatic base class is closely associated with CCoeEnv. Between them they allow singleton objects to be created and stored in Thread Local Storage (TLS). By doing so they provide an equivalent to writeable global static data.

Classes derived from CCoeStatic are automatically added to the environment when they are instantiated for the first time. Subsequent attempts to instantiate an object of the same type will result in a panic (with error code ECoePanicDuplicateObjectUid).

Each singleton requires a UID and may be given a destruction priority (relative to other singletons and the AppUi) and a scope (EThread or EApp).

Once a singleton has been created it may be accessed through the CCoeEnv API.

// Singleton access
IMPORT_C static CCoeStatic* Static( TUid aUid ) ;
IMPORT_C CCoeStatic* FindStatic( TUid aUid ) ;

CCoeStatic has no public functions.

How to create a Singleton