![[Index]](../../../stock/btn_index.gif){kind=small}
![[Glossary]](../../../stock/btn_glossary.gif){kind=small}
![[Previous]](../../../stock/btn_prev.gif){kind=small}
![[Next]](../../../stock/btn_next.gif){kind=small}
| |
|
| |
Location:
coemain.h
Link against: cone.lib
CCoeEnv
Supported from 5.0
Control environment.
CCoeEnv provides an active environment for creating
controls. It implements active objects and an active scheduler, which provide
access to the window server, simplifying the API for application programs. It
also provides utility functions that are useful to many applications.
When a standard event occurs, the active scheduler calls
CCoeEnv::RunL(). When a redraw event occurs, it calls
CCoeRedrawer::RunL(). Priority key events must be accessed using
the Window Server API directly.
Note:
Standard events are all events except redraw events and priority key events.
|
Defined in CCoeEnv:
AddFepObserverL(), AddFocusObserverL(), AddForegroundObserverL(), AddMessageObserverL(), AddObserverOfLoadedFepL(), AddResourceFileL(), AllocReadResourceAsDes16L(), AllocReadResourceAsDes16LC(), AllocReadResourceAsDes8L(), AllocReadResourceAsDes8LC(), AllocReadResourceL(), AllocReadResourceLC(), AppUi(), BringOwnerToFront(), CCoeEnv(), ConstructL(), CreateDeviceFontL(), CreateGcL(), CreateResourceReaderLC(), CreateScreenFontL(), DeleteResourceFile(), DestroyEnvironment(), DestroyScreen(), DisableExitChecks(), ErrorContextText(), ErrorText(), ExecuteD(), ExecuteFepSettingsDialogL(), Fep(), FepUid(), FileNamesOfAvailableFepsL(), Flush(), ForEachFepObserverCall(), Format128(), Format256(), FsSession(), HandleError(), InitSystemFontsL(), InputCapabilitiesChanged(), InstallFepL(), IsRedrawEventPending(), IsWservEventPending(), LastEvent(), LeaveWithErrorText(), NameOfInstalledFepL(), NormalFont(), PrepareToExit(), ReadDesC16ArrayResourceL(), ReadDesC8ArrayResourceL(), ReadDesCArrayResourceL(), ReadResource(), ReadResourceAsDes16(), ReadResourceAsDes8(), ReleaseScreenFont(), RemoveFepObserver(), RemoveFocusObserver(), RemoveForegroundObserver(), RemoveMessageObserver(), RemoveObserverOfLoadedFep(), ResourceFileVersionNumber(), RootWin(), ScreenDevice(), SetAppUi(), SimulateKeyEventL(), Static(), SuppressNextFlush(), SwapSystemGc(), SystemGc(), Version(), WsSession(), ~CCoeEnv()
Inherited from CActive:
Cancel(),
Deque(),
DoCancel(),
EPriorityHigh,
EPriorityIdle,
EPriorityLow,
EPriorityStandard,
EPriorityUserInput,
IsActive(),
IsAdded(),
Priority(),
RunError(),
RunL(),
SetActive(),
SetPriority(),
TPriority,
iStatus
Inherited from CBase:
operator new()
Standard GUI applications do not generally need to use the
functions in this section, as they are encapsulated within
CEikonEnv.
CCoeEnv();
Default constructor.
Constructs an incomplete CCoeEnv. Construction of
the CCoeEnv is not complete until ConstructL() has
been called.
This function panics with a category name of CONE,
reason number 2 if the application already owns a CCoeEnv.
void ConstructL();
Completes the construction of the CCoeEnv
object.
Until v5.1, the function fully completed the construction of
the CCoeEnv. It creates an active scheduler, and adds active
objects to it for standard and redraw events. The active scheduler is not
started, however, and no events are received, until ExecuteD() is
called. ConstructL() also does the following:
creates a connection to the window server.
creates a connection to the file server so that the control environment can access resource files.
calls InitSystemFontsL()
creates a graphics context (the system GC), a standard font, a screen device and the application's window group.
After v5.1 this function changed behaviour, and completes the
construction by calling the function overload (below) — specifying
ETrue as the initial focus state.
void ConstructL(TBool aInitialFocusState);
Supported from 6.0
Completes the construction of the CCoeEnv.
It is called by the previous constructor
CCoeEnv::ConstructL(), with aInitialFocusState set to
ETrue.
This function creates an active scheduler, and adds active
objects to it for standard and redraw events. The active scheduler is not
started, however, and no events are received, until ExecuteD() is
called. It also does the following:
creates a connection to the window server.
creates a connection to the file server so that the CONE environment can access resource files
creates a screen device, the application's window group, a standard font, and a graphics context (the system GC).
The window group is constructed with the initial focus state
aInitialFocusState, which automatically takes keyboard focus when
it is created.
|
~CCoeEnv();
Destructor.
This function deletes any resources owned by the
CCoeEnv that were not deleted by
DestroyEnvironment().
|
Standard GUI applications do not generally need to use the
functions in this section, as they are encapsulated within
CEikonEnv.
void ExecuteD();
Launches the application.
This function starts the active scheduler owned by the
CCoeEnv, enabling the application to start receiving events from
the window server. It forms the outer loop of all Control Environment
applications.
CCoeAppUiBase* SetAppUi(CCoeAppUiBase* aAppUi);
Sets the application's user interface object.
Standard GUI applications do not need to call this function, as
the framework sets the app UI, during start up, to be the
CEikAppUi-derived object created by the application.
|
|
CCoeAppUiBase* AppUi() const;
Gets the application UI owned by this application.
|
private: virtual void InitSystemFontsL();
Initialises system fonts.
This function is called by ConstructL() during the
construction of a CCoeEnv. The default implementation creates only
the notmal control environment font, but this function may be overridden to
create other fonts.
void PrepareToExit();
Prepares for the exit of the application.
The function is called from ExecuteD() after the
active scheduler's wait loop terminates, but before the environment is
destroyed.
virtual void DestroyEnvironment();
Deletes several resources owned by the CCoeEnv
object.
This includes; the app UI, the system GC, and the active object which receives redraw events. It also closes the window group, the connection to the window server, and the connection to the file server.
The function is called from ExecuteD() when the
active scheduler's wait loop terminates.
|
RWsSession& WsSession() const;
Gets the window server session owned by the application.
This provides access to window server functions not directly accessible via the UI control framework.
|
RWindowGroup& RootWin() const;
Gets the application's window group.
Note:
A window group is an invisible window which acts as the parent window for all other windows in an application. Typically, each application has one window group. In the window server, window groups are also the unit of keyboard focus.
|
void BringOwnerToFront();
Brings the application's owning window group to the front of the screen and gives it keyboard focus.
This is done by giving the owning window group an ordinal position of zero.
void Flush(TTimeIntervalMicroSeconds32 aDelay=0);
Flushes the client-side window server buffer.
The function does this by first calling
RWsSession::Flush(), and then User::After(aDelay) —
which puts the current process in a sleep state for the time interval given by
aDelay.
|
void SuppressNextFlush();
Suppresses the next flush of the active scheduler queue.
It prevents the active scheduler automatically flushing it's
window server session the next time that a non-CCoeEnv object
runs. After the active object has run, the active scheduler reverts back to its
normal behaviour — flushing after each non-CCoeEnv
RunL().
|
CWindowGc& SystemGc() const;
Gets the system graphics context.
This is the graphics contexts typically used for drawing
controls, but an alternative graphics context can be created if required using
CreateGcL().
|
CWindowGc* SwapSystemGc(CWindowGc* aGc);
Sets the new system graphics context.
The function returns a pointer to the old system graphics context.
|
|
CWindowGc* CreateGcL();
Fully constructs a new graphics context.
CCoeEnv calls this function during construction to
create the system graphics context, which can be accessed using
SystemGc(). Hence the system graphics context is always
available.
|
|
RFs& FsSession() const;
Gets the file server session owned by this
CCoeEnv.
This session is normally only used for accessing the application's resource file.
|
|
CWsScreenDevice* ScreenDevice() const;
Gets the default screen device owned by this
CCoeEnv.
This is typically used as the standard screen device for the
CCoeEnv's application.
|
protected: virtual void DestroyScreen();
Destroys screen device.
By default this function simply deletes the screen device owned
by this CCoeEnv. However, this function may also be overridden by
subclasses.
This function is called by
DestroyEnvironment().
|
In addition to the font utilities provided by
CCoeEnv, GUI applications can access many others which are
provided by CEikEnv.
const CFont* NormalFont() const;
Gets the normal environment font.
This is the font created during construction of the control environment.
|
CFbsFont* CreateDeviceFontL(CGraphicsDevice* aDevice,const TFontSpec& aFontSpec);
Creates a font for the specified graphics device.
If you wish to use the default screen device as the graphics
device, use CreateScreenFontL() instead of this function.
This function calls GetNearestFontInTwips() on the
graphics device given by aDevice, passing it the font defined by
aFontSpec.
All fonts should be released, using
MGraphicsDeviceMap::ReleaseFont(), when they are no longer
required.
|
|
CFbsFont* CreateScreenFontL(const TFontSpec& aFontSpec);
Creates a font for the default graphics device, based on the
specified TFontSpec.
This function calls CreateDeviceFontL() passing
the default screen device, owned by this CCoeEnv, as the value for
the graphics device for which to create the font. All fonts created using this
function should be released using ReleaseScreenFont() when they
are no longer required.
|
|
void ReleaseScreenFont(CFont* aFont) const;
Frees all resources used by the font.
This function should be used to release a font when the font is
no longer required. Fonts are created using
CreateScreenFontL().
|
|
This section describes CCoeEnv's utility functions
for reading resource data from resource files.
TInt AddResourceFileL(const TDesC& aFileName);
Adds the specified resource file to the list maintained by
CCoeEnv.
Note:
Resource files are access counted so
AddResourceFileL() can be called several times for the same
resource file. However, care should be taken to call
DeleteResourceFile for each resource file added to the
list.
|
|
|
void DeleteResourceFile(TInt aOffset);
Deletes the specified resource file from the list maintained by
CCoeEnv.
|
|
void ReadResource(TDes& aDes,TInt aResourceId) const;
Reads a resource into a descriptor.
The descriptor must be long enough to contain the entire resource. No memory is allocated by this function.
If the read fails the function sets an error condition and performs any cleanup required. The error condition causes the GUI to launch an alert window.
|
void ReadResourceAsDes16(TDes16& aDes,TInt aResourceId) const;
Reads a resource into a 16 bit descriptor.
The descriptor must be long enough to contain the entire resource. No memory is allocated by this function.
If the read fails the function sets an error condition and performs any cleanup required. The error condition causes the GUI to launch an alert window.
|
void ReadResourceAsDes8(TDes8& aDes,TInt aResourceId) const;
Reads a resource into an 8 bit descriptor.
The descriptor must be long enough to contain the entire resource. No memory is allocated by this function.
If the read fails the function sets an error condition and performs any cleanup required. The error condition causes the GUI to launch an alert window.
|
HBufC* AllocReadResourceL(TInt aResourceId) const;
Reads a specified resource into a heap descriptor, allocating memory for the descriptor.
Note:
The calling program must destroy the heap descriptor when it is no longer needed.
|
|
HBufC* AllocReadResourceLC(TInt aResourceId) const;
Reads a specified resource into a heap descriptor, allocating memory for the descriptor, and pushing the descriptor onto the cleanup stack.
The calling program should pop and destroy the heap descriptor when it is no longer needed.
|
|
HBufC8* AllocReadResourceAsDes8L(TInt aResourceId) const;
Reads a resource into an 8 bit heap buffer — allocating the buffer.
The calling program must destroy the heap descriptor when it is no longer needed.
|
|
HBufC16* AllocReadResourceAsDes16L(TInt aResourceId) const;
Reads a resource into a 16 bit heap buffer — allocating the buffer.
The calling program must destroy the heap descriptor when it is no longer needed.
|
|
HBufC8* AllocReadResourceAsDes8LC(TInt aResourceId) const;
Reads a resource into an 8 bit heap buffer — allocating the buffer and pushing it onto the cleanup stack.
The calling program must destroy the heap descriptor when it is no longer needed.
|
|
HBufC16* AllocReadResourceAsDes16LC(TInt aResourceId) const;
Reads a resource into a 16 bit heap buffer — allocating the buffer and pushing it onto the cleanup stack.
The calling program must destroy the heap descriptor when it is no longer needed.
|
|
CDesCArrayFlat* ReadDesCArrayResourceL(TInt aResourceId);
Reads a resource into a build-independent descriptor array.
Note:
CDesCArrayFlat is a
CDesC8ArrayFlat for ER5, and CDesC16ArrayFlat for
post ER5 builds.
|
|
CDesC8ArrayFlat* ReadDesC8ArrayResourceL(TInt aResourceId);
Reads a resource into an 8 bit descriptor array.
|
|
CDesC16ArrayFlat* ReadDesC16ArrayResourceL(TInt aResourceId);
Reads a resource into a 16 bit descriptor array.
Ownership of the array is transferred to the caller.
|
|
void Format128(TDes& aDes,TInt aResourceId,...);
Reads a 128 byte resource into a formatted string.
The format of the written string is given by the variable
argument list. The unformatted resource data must not be longer than 128 bytes.
If it is, you should use Format256().
|
void Format256(TDes& aDes,TInt aResourceId,...);
Reads a 256 byte resource into a formatted string.
The format of the written string is given by the variable argument list. The unformatted resource data must not be longer than 265 bytes.
|
void CreateResourceReaderLC(TResourceReader& aReader,TInt aResourceId) const;
Reads a resource from a resource file and sets its resource reader.
The resource reader can subsequently be used to read resource data from the resource. The resource reader is also placed on the cleanup stack.
Note:
The GUI framework passes a resource reader as an argument
to CCoeControl::ConstructFromResourceL(), with the resource
reader's buffer already set to contain the relevant resource for that
control.
|
private: virtual TInt ResourceFileVersionNumber() const;
Gets the resource file version number.
The function is intended to be replaced in a derived class — it should return a defined constant which should correspond to the version number of resource files used by the application. It is implemented by the standard GUI framework.
AddResourceFileL() uses this function to verify
that the application is not using an out-of-date resource file. An out-of-date
resource file causes AddResourceFileL() to leave with error code
KErrBaflWrongResourceFileSignature.
|
|
static TVersion Version();
Gets the version number of the UI Control Framework API.
|
|
static CCoeEnv* Static();
Gets a pointer to a CCoeEnv which can be used to
access CCoeEnv's functions.
It allows application code to access CCoeEnv's
functions even where there is no direct access to a CCoeEnv
object.
Example:
CCoeEnv::Static()->CreateResourceReaderLC(aReader, aResourceId);
|
static CCoeStatic* Static(TUid aUid);
Supported from 6.0
Gets a pointer to the specified CCoeStatic derived
class.
If no match is found it will simply return a NULL.
This function might be used to allow a CCoeStatic
derived class to get a handle on itself.
Note:
Ownership of the object remains with CCoeEnv
in all cases.
|
|
|
virtual void HandleError(TInt aError);
Handles an application-defined error message.
This function allows application-defined error messages to be called from functions within the control framework's active scheduler. It has an empty default implementation.
It is called when a leave occurs in
CCoeEnv::RunL(), and also when ReadResource()
fails.
|
void LeaveWithErrorText(const TDesC& aMsg,const TDesC* aContextText=NULL);
Displays an error message and context text and then calls
User::Leave() with a leave code of
KErrExtendedWithText.
|
protected: TDes& ErrorText();
Gets the current error message text.
|
protected: TDes& ErrorContextText();
Gets the current error context text.
|
|
const TWsEvent& LastEvent() const;
Gets the most recent standard event that was received by the application.
Note:
Standard events are all events except redraw events and priority key events.
|
void SimulateKeyEventL(const TKeyEvent& aKeyEvent,TEventCode aType);
Simulates a key event.
This function calls
CCoeAppUiBase::HandleKeyEvent() to process the event
aKeyEvent as if it had arrived from the window server.
|
TBool IsWservEventPending() const;
Tests if there is a standard event waiting to be processed.
Note:
Standard events are all window server events except redraw events and priority key events.
|
TBool IsRedrawEventPending() const;
Tests if there is a redraw event waiting to be processed.
|
|
void AddFepObserverL(MCoeFepObserver& aFepObserver);
Supported from 6.0
Adds the specified MCoeFepObserver to the FEP
observer list.
|
|
void AddFocusObserverL(MCoeFocusObserver& aFocusObserver);
Supported from 6.0
Adds the specified MCoeFocusObserver to the focus
observer list.
|
|
void InputCapabilitiesChanged();
Supported from 6.1
Notifies all focus observers (FEPs) that a change has been made to the input capabilities of the focussed control.
void AddForegroundObserverL(MCoeForegroundObserver& aForegroundObserver);
Supported from 6.0
Adds the specified MCoeForegroundObserver to the
foreground observer list.
|
|
void AddMessageObserverL(MCoeMessageObserver& aMessageObserver);
Supported from 6.0
Adds the specified MCoeMessageObserver to the
message observer list.
|
void RemoveMessageObserver(MCoeMessageObserver& aMessageObserver);
Supported from 6.0
Remove the specified MCoeMessageObserver from the
message observer list.
|
void AddObserverOfLoadedFepL(MCoeObserverOfLoadedFep& aObserverOfLoadedFep);
Supported from 6.0
Adds the specified MCoeObserverOfLoadedFep to the
loaded FEP list.
This enables objects to be notified when a front-end processor is loaded.
|
void DisableExitChecks(TBool aDisable);
Supported from 6.0
Disables exit checks on kernel resources.
After v5.1, CCoeEnv checks for kernel resources on
exit (e.g. open file handles). These checks are too strict for some
applications, such as web, so this function is provided to disable them.
CCoeEnv also checks on heap allocation and window
server resources on exit.
|
void ExecuteFepSettingsDialogL(const TDesC& aFileNameOfFepDll);
Supported from 6.0
Executes the settings dialog of the specified FEP.
The specified FEPdoes not need to be the currently loaded FEP.
|
CCoeFep* Fep() const;
Supported from 6.0
Gets a pointer the currently loaded FEP.
|
TUid FepUid() const;
Supported from 6.0
Gets the UID of the currently loaded FEP.
|
MDesCArray* FileNamesOfAvailableFepsL();
Supported from 6.0
Gets an array of the file-names of all the FEPs that are currently on the machine. Ownership of this array is passed to the caller.
|
void ForEachFepObserverCall(TCoeFepObserverFunction aFepObserverFunction);
Supported from 6.0
Calls specified function for observers.
This function is called for each MCoeFepObserver
object thathas been registered by calling
CCoeEnv::AddFepObserverL().
|
void InstallFepL(const TDesC& aFileNameOfFepDll);
Supported from 6.0
Loads the specified FEP into all running applications.
The currently loaded FEP, if any, will be unloaded.
|
HBufC* NameOfInstalledFepL();
Supported from 6.0
Gets the name of the currently loaded FEP.
Ownership of the named descriptor is passed to the caller.
Note:
The returned name returns as full a path as was passed to
InstallFepL(). If a directory was not specified, \system\fep is
assumed.
|
void RemoveFepObserver(MCoeFepObserver& aFepObserver);
Supported from 6.0
Removes the specified FEP observer.
|
void RemoveFocusObserver(MCoeFocusObserver& aFocusObserver);
Supported from 6.0
Removes the specified focus observer.
|
void RemoveForegroundObserver(MCoeForegroundObserver& aForegroundObserver);
Supported from 6.0
Removes the specified foreground observer.
|
void RemoveObserverOfLoadedFep(MCoeObserverOfLoadedFep& aObserverOfLoadedFep);
Supported from 6.0
Remove the specified loaded FEP observer.
|
Copyright ©2002 Symbian Ltd. 6.1-00174 |
|
![[Top]](../../../stock/arrow_up_2.gif){kind=icon}
![[Top]](../../../stock/arrow_up.gif){kind=icon}