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.