Class CCoeEnv

class CCoeEnv : public CActive, public MObjectProvider;

Description

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.

Derivation

• MObjectProvider - An interface that allows an object to be part of a network of object providers.

• CBase - Base class for all classes to be instantiated on the heap.

• CActive - The core class of the active object abstraction.

• CCoeEnv - Control environment.

Members

Defined in CCoeEnv:

• AddFepObserverL(MCoeFepObserver &)Adds the specified MCoeFepObserver to the FEP observer list.
• AddFocusObserverL(MCoeFocusObserver &)Adds the specified MCoeFocusObserver to the focus observer list.
• AddForegroundObserverL(MCoeForegroundObserver &)Adds the specified MCoeForegroundObserver to the foreground observer list.
• AddMessageMonitorObserverL(MCoeMessageMonitorObserver &)Adds the specified MCoeMessageMonitorObserver to the message observer list
• AddMessageObserverL(MCoeMessageObserver &)Adds the specified MCoeMessageObserver to the message observer list.
• AddObserverOfLoadedFepL(MCoeObserverOfLoadedFep &)Adds the specified MCoeObserverOfLoadedFep to the loaded FEP list.
• AddResourceChangeObserverL(MCoeResourceChangeObserver &)Adds the specified MCoeResourceChangeObserver to the resource change observer li...
• AddResourceFileL(const TDesC &)Adds the specified resource file to the list maintained by CCoeEnv.
• AllocReadResourceAsDes16L(TInt)constReads a resource into a 16 bit heap buffer, allocating the buffer.
• AllocReadResourceAsDes16LC(TInt)constReads a resource into a 16 bit heap buffer, allocating the buffer and pushing it...
• AllocReadResourceAsDes8L(TInt)constReads a resource into an 8 bit heap buffer, allocating the buffer.
• AllocReadResourceAsDes8LC(TInt)constReads a resource into an 8 bit heap buffer, allocating the buffer and pushing it...
• AllocReadResourceL(TInt)constReads a resource into a heap descriptor, allocating memory for it.
• AllocReadResourceLC(TInt)constReads a specified resource into a heap descriptor, allocating memory for it, and...
• AppUi()constGets the application UI owned by this application.
• AvailableFepsL(RArray< TUid > &,CDesCArray *)Gets the UIDs, and optionally display names, of all the secure FEPs that are ava...
• BringOwnerToFront()Brings the application's owning window group to the front of the screen and give...
• CCoeEnv()Default constructor.
• ConstructL()Completes construction of the CCoeEnv object.
• ConstructL(TBool)Completes construction of the CCoeEnv.
• ConstructL(TBool,TInt)Completes construction of the CCoeEnv. It can be called by the previous overload...
• ConstructL(TBool,TInt,TInt)Completes construction of the CCoeEnv.
• CreateDeviceFontL(CGraphicsDevice *,const TFontSpec &)Creates a font for the specified graphics device.
• CreateGcL()Fully constructs a new graphics context.
• CreateResourceReaderLC(TResourceReader &,TInt)constReads a resource from a resource file and sets its resource reader.
• CreateScreenFontL(const TFontSpec &)Creates a font for the default graphics device, based on the specified TFontSpec...
• DefaultFontProvider()constThis function returns the default font provider.
• DefaultTextDrawer()constThis function returns the default text drawer.
• DeleteResourceFile(TInt)Deletes the specified resource file from the list maintained by CCoeEnv.
• DestroyEnvironment()Deletes several resources owned by the CCoeEnv object.
• DestroyScreen()Destroys the screen device.
• DisableExitChecks(TBool)Disables exit checks on kernel resources.
• DisableShutdownChecks()const
• DoCancel()Implements cancellation of an outstanding request.
• ErrorContextText()Gets the current error context text.
• ErrorText()Gets the current error message text.
• Execute()Launches the application without destroying the control environment.
• ExecuteD()Launches the application and destroys the control environment.
• ExecuteFepSettingsDialogL(TUid)Executes the settings dialog for the specified secure FEP.
• Fep()constGets a pointer to the currently loaded FEP.
• FepUid()constGets the UID of the currently loaded FEP.
• FindStatic(TUid)
• Flush(TTimeIntervalMicroSeconds32)Flushes the client-side window server buffer.
• ForEachFepObserverCall(TCoeFepObserverFunction)Calls the specified function for each FEP observer.
• Format128(TDes &,TInt,...)Reads a 128 byte resource into a formatted string.
• Format256(TDes &,TInt,...)Reads a 256 byte resource into a formatted string.
• FsSession()constGets the file server session owned by this CCoeEnv.
• HandleError(TInt)Handles an application-defined error message.
• InitSystemFontsL()Initialises the system fonts.
• InputCapabilitiesChanged()Notifies all focus observers (FEPs) that a change has been made to the input cap...
• InstallFepL(TUid)Loads the specified secure FEP into all running applications.
• InstallFepL(TUid,const TBool)Loads the specified secure FEP into all running applications.
• IsRedrawEventPending()constTests if there is a redraw event waiting to be processed.
• IsResourceAvailableL(TInt)constChecks if the given resource is owned by one of the resource files in the list m...
• IsSchedulerRunning()const
• IsWservEventPending()constTests if there is a standard event waiting to be processed.
• LastEvent()constGets the most recent standard event that was received by the application.
• LeaveWithErrorText(const TDesC &,const TDesC *)Triggers a dialog which will display the error message
• MopSupplyObject(TTypeUid)Retrieves an object of the same type as that encapsulated in aId.
• NormalFont()constGets the normal environment font.
• PrepareToExit()Prepares for exiting the application.
• ReadDesC16ArrayResourceL(TInt)Reads a resource into a 16 bit descriptor array.
• ReadDesC8ArrayResourceL(TInt)Reads a resource into an 8 bit descriptor array.
• ReadDesCArrayResourceL(TInt)Reads a resource into a Unicode descriptor array.
• ReadResource(TDes &,TInt)constReads a resource into a descriptor.
• ReadResourceAsDes16(TDes16 &,TInt)constReads a resource into a 16 bit descriptor.
• ReadResourceAsDes16L(TDes16 &,TInt)const
• ReadResourceAsDes8(TDes8 &,TInt)constReads a resource into an 8 bit descriptor.
• ReadResourceAsDes8L(TDes8 &,TInt)const
• ReadResourceL(TDes &,TInt)constReads a resource into a descriptor.
• ReleaseScreenFont(CFont *)constFrees all resources used by the font.
• RemoveFepObserver(MCoeFepObserver &)Removes the specified FEP observer.
• RemoveFocusObserver(MCoeFocusObserver &)Removes the specified focus observer.
• RemoveForegroundObserver(MCoeForegroundObserver &)Removes the specified foreground observer.
• RemoveMessageMonitorObserver(MCoeMessageMonitorObserver &)Removes the specified MCoeMessageMonitorObserver.
• RemoveMessageObserver(MCoeMessageObserver &)Removes the specified MCoeMessageObserver from the message observer list.
• RemoveObserverOfLoadedFep(MCoeObserverOfLoadedFep &)Removes the specified loaded FEP observer.
• RemoveResourceChangeObserver(MCoeResourceChangeObserver &)Removes the specified resource change observer.
• Reserved_1()
• Reserved_2()
• ResourceFileVersionNumber()constGets the resource file version number.
• RootWin()constGets the application's window group.
• RunError(TInt)
• RunL()Handles an active object's request completion event.
• ScreenDevice()constGets the default screen device owned by this CCoeEnv.
• SetAppUi(CCoeAppUi *)Sets the application's user interface object.
• SimulateKeyEventL(const TKeyEvent &,TEventCode)Simulates a key event.
• Static()Gets a pointer to a CCoeEnv which can be used to access CCoeEnv's functions.
• Static(TUid)Gets a pointer to the specified CCoeStatic derived class.
• SuppressNextFlush()Suppresses the next flush of the active scheduler queue.
• SwapSystemGc(CWindowGc *)Sets the new system graphics context.
• SyncNotifyFocusObserversOfChangeInFocus()
• SystemGc()constGets the system graphics context.
• Version()Gets the version number of the UI Control Framework API.
• WsSession()constGets the window server session owned by the application.
• iAppUi
• iFsSession
• iLastEvent
• iNormalFont
• iResourceFileArray
• iRootWin
• iScreen
• iSystemGc
• iWsSession
• ~CCoeEnv()Destructor.

Inherited from CActive:

• CActive(TInt)Constructs the active object with the specified priority.
• Cancel()Cancels the wait for completion of an outstanding request.
• Deque()Removes the active object from the active scheduler's list of active objects.
• EPriorityHighA priority higher than EPriorityUserInput.
• EPriorityIdleA low priority, useful for active objects representing background processing.
• EPriorityLowA priority higher than EPriorityIdle but lower than EPriorityStandard.
• EPriorityStandardMost active objects will have this priority.
• EPriorityUserInputA priority higher than EPriorityStandard; useful for active objects handling use...
• Extension_(TUint,TAny *&,TAny *)Extension function
• IsActive()constDetermines whether the active object has a request outstanding.
• IsAdded()constDetermines whether the active object has been added to the active scheduler's li...
• Priority()constGets the priority of the active object.
• SetActive()Indicates that the active object has issued a request and that it is now outstan...
• SetPriority(TInt)Sets the priority of the active object.
• TPriorityDefines standard priorities for active objects.
• iStatusThe request status associated with an asynchronous request.

Inherited from CBase:

• Delete(CBase *)Deletes the specified object.
• operator new(TUint)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TAny *)Initialises the object to binary zeroes.
• operator new(TUint,TLeave)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TLeave,TUint)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TUint)Allocates the object from the heap and then initialises its contents to binary z...

Inherited from MObjectProvider:

• MopGetObject(T *&)Gets an object of the type defined by the template parameter.
• MopGetObjectNoChaining(T *&)Gets an object of the type defined by the template parameter.

IMPORT_C CCoeEnv();

Description

Default constructor.

Note - Construction of the CCoeEnv is not complete until CCoeEnv::ConstructL() has been called.

This function raises a CONE 2 panic if the application already owns a CCoeEnv.

IMPORT_C ~CCoeEnv();

Description

Destructor.

This function deletes any resources owned by the CCoeEnv that were not deleted by CCoeEnv::DestroyEnvironment().

IMPORT_C void ConstructL();

Description

Completes construction of the CCoeEnv object.

It calls the other CCoeEnv::ConstructL() overload specifying ETrue as the initial focus state.

IMPORT_C void ConstructL(TBool aInitialFocusState);

Description

Completes construction of the CCoeEnv.

It is called by the other overload, with aInitialFocusState set to ETrue.

Parameters

IMPORT_C void ConstructL(TBool aInitialFocusState, TInt aDefaultScreenNumber);

Description

Completes construction of the CCoeEnv. It can be called by the previous overload. It calls the next overload, setting the default window group ID to 0 which is not a valid ID

Parameters

IMPORT_C void ConstructL(TBool aInitialFocusState, TInt aDefaultScreenNumber, TInt aWindowGroupID);

Description

Completes construction of the CCoeEnv.

All of the previous CCoeEnv::ConstructL() overloads end up at this method.

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 CCoeEnv::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 control 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.

Parameters

IMPORT_C static TVersion Version();

Description

Gets the version number of the UI Control Framework API.

Return value

IMPORT_C static CCoeEnv* Static();

Description

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.

For example:

CCoeEnv::Static()->CreateResourceReaderLC(aReader, aResourceId);

Return value

IMPORT_C CCoeAppUi* SetAppUi(CCoeAppUi *aAppUi);

Description

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.

Parameters

Return value

IMPORT_C void ExecuteD();

Description

Launches the application and destroys the control environment.

IMPORT_C void Execute();

Description

Launches the application without destroying the control environment.

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.

IMPORT_C virtual void RunL();

Description

Handles an active object's request completion event.

A derived class must provide an implementation to handle the completed request. If appropriate, it may issue another request.

The function is called by the active scheduler when a request completion event occurs, i.e. after the active scheduler's WaitForAnyRequest() function completes.

Before calling this active object's CCoeEnv::RunL() function, the active scheduler has:

1. decided that this is the highest priority active object with a completed request

2. marked this active object's request as complete (i.e. the request is no longer outstanding)

CCoeEnv::RunL() runs under a trap harness in the active scheduler. If it leaves, then the active scheduler calls CCoeEnv::RunError(TInt) to handle the leave.

Note that once the active scheduler's Start() function has been called, all user code is run under one of the program's active object's CCoeEnv::RunL() or CCoeEnv::RunError(TInt) functions.

See also:

• CActiveScheduler::Start()Starts a new wait loop under the control of the current active scheduler.
• CActiveScheduler::Error(TInt)constHandles the result of a leave occurring in an active object’s RunL() function.
• CActiveScheduler::WaitForAnyRequest()Wait for an asynchronous request to complete.

IMPORT_C virtual void DoCancel();

Description

Implements cancellation of an outstanding request.

This function is called as part of the active object's CActive::Cancel().

It must call the appropriate cancel function offered by the active object's asynchronous service provider. The asynchronous service provider's cancel is expected to act immediately.

CCoeEnv::DoCancel() must not wait for event completion; this is handled by CActive::Cancel().

See also:

• CActive::Cancel()Cancels the wait for completion of an outstanding request.

IMPORT_C void PrepareToExit();

Description

Prepares for exiting the application.

The function is called from CCoeEnv::ExecuteD() after the active scheduler's wait loop terminates, but before the environment is destroyed.

IMPORT_C virtual void DestroyEnvironment();

Description

Deletes several resources owned by the CCoeEnv object.

This includes; the app UI, the system graphics context, 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 CCoeEnv::ExecuteD() when the active scheduler's wait loop terminates.

IMPORT_C void DisableExitChecks(TBool aDisable);

Description

Disables exit checks on kernel resources.

CCoeEnv checks for kernel resources on exit (e.g. open file handles). These checks may be too strict for some applications, such as a web browser, so this function is provided to disable them.

CCoeEnv also checks on heap allocation and window server resources on exit.

Parameters

IMPORT_C virtual void HandleError(TInt aError);

Description

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 CCoeEnv::ReadResource(TDes &,TInt)const fails.

Parameters

inline CCoeAppUi* AppUi() const;

Description

Gets the application UI owned by this application.

Return value

inline RFs& FsSession() const;

Description

Gets the file server session owned by this CCoeEnv.

This session is normally only used for accessing the application's resource file.

Return value

inline RWsSession& WsSession() const;

Description

Gets the window server session owned by the application.

This provides access to window server functions not directly accessible via the UI control framework.

Return value

inline RWindowGroup& RootWin() const;

Description

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.

Return value

inline CWsScreenDevice* ScreenDevice() const;

Description

Gets the default screen device owned by this CCoeEnv.

This is typically used as the standard screen device for the CCoeEnv's application.

Return value

inline CWindowGc& SystemGc() const;

Description

Gets the system graphics context.

This is the graphics context typically used for drawing controls, but an alternative graphics context can be created if required using CCoeEnv::CreateGcL().

Return value

inline const CFont* NormalFont() const;

Description

Gets the normal environment font.

This is the font created during construction of the control environment.

Return value

See also:

• CCoeEnv::InitSystemFontsL()Initialises the system fonts.

inline const TWsEvent& LastEvent() const;

Description

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.

Return value

inline TBool IsSchedulerRunning() const;

Description

Return value

IMPORT_C CWindowGc* CreateGcL();

Description

Fully constructs a new graphics context.

CCoeEnv calls this function during construction to create the system graphics context, which can be accessed using CCoeEnv::SystemGc()const. Hence the system graphics context is always available.

Return value

See also:

• CCoeEnv::SystemGc()constGets the system graphics context.

IMPORT_C CWindowGc* SwapSystemGc(CWindowGc *aGc);

Description

Sets the new system graphics context.

The function returns a pointer to the old system graphics context.

Parameters

Return value

Panic codes

IMPORT_C void Flush(TTimeIntervalMicroSeconds32 aDelay=0);

Description

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.

Parameters

IMPORT_C void SuppressNextFlush();

Description

Suppresses the next flush of the active scheduler queue.

It prevents the active scheduler automatically flushing its 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 CCoeEnv::RunL().

IMPORT_C TBool IsWservEventPending() const;

Description

Tests if there is a standard event waiting to be processed.

Note: standard events are all window server events except redraw and priority key events.

Return value

IMPORT_C TBool IsRedrawEventPending() const;

Description

Tests if there is a redraw event waiting to be processed.

Return value

IMPORT_C CFbsFont* CreateDeviceFontL(CGraphicsDevice *aDevice, const TFontSpec &aFontSpec);

Description

Creates a font for the specified graphics device.

If you wish to use the default screen device as the graphics device, use CCoeEnv::CreateScreenFontL(const TFontSpec &) instead of this function.

This function calls GetNearestFontToMaxHeightInTwips() on the graphics device given by aDevice, passing it the font defined by aFontSpec.

All fonts should be released, using MGraphicsDeviceMap::ReleaseFont(CFont *), when they are no longer required.

Parameters

Return value

IMPORT_C CFbsFont* CreateScreenFontL(const TFontSpec &aFontSpec);

Description

Creates a font for the default graphics device, based on the specified TFontSpec.

This function calls CCoeEnv::CreateDeviceFontL(CGraphicsDevice *,const TFontSpec &) 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 CCoeEnv::ReleaseScreenFont(CFont *)const when they are no longer required.

Parameters

Return value

IMPORT_C void ReleaseScreenFont(CFont *aFont) const;

Description

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 CCoeEnv::CreateScreenFontL(const TFontSpec &).

Parameters

IMPORT_C const CCoeFontProvider& DefaultFontProvider() const;

Description

This function returns the default font provider.

Return value

IMPORT_C CCoeTextDrawerBase& DefaultTextDrawer() const;

Description

This function returns the default text drawer.

Return value

IMPORT_C TInt AddResourceFileL(const TDesC &aFileName);

Description

Adds the specified resource file to the list maintained by CCoeEnv.

Resource files are access counted so CCoeEnv::AddResourceFileL(const TDesC &) can be called several times for the same resource file. However, care should be taken to call CCoeEnv::DeleteResourceFile(TInt) for each resource file added to the list.

Parameters

Return value

Panic codes

See also:

• RResourceFile::Offset()constReturns the offset value defined for this resource file.
• CCoeEnv::ResourceFileVersionNumber()constGets the resource file version number.

IMPORT_C void DeleteResourceFile(TInt aOffset);

Description

Deletes the specified resource file from the list maintained by CCoeEnv.

Parameters

Panic codes

IMPORT_C TBool IsResourceAvailableL(TInt aResourceId) const;

Description

Checks if the given resource is owned by one of the resource files in the list maintained by CCoeEnv.

Parameters

Return value

IMPORT_C void CreateResourceReaderLC(TResourceReader &aReader, TInt aResourceId) const;

Description

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(TResourceReader &), with the resource reader's buffer already set to contain the relevant resource for that control.

Parameters

inline void ReadResource(TDes &aDes, TInt aResourceId) const;

Description

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.

Deprecated - Use CCoeEnv::ReadResourceL(TDes &,TInt)const instead.

Parameters

See also:

• RResourceFile::ReadL(TDes8 &,TInt)constReads a resource specified by resource id into the specified descriptor.
• KErrCoeFailedToReadFromProgDiskRead fail. CCoeEnv::ReadResource(TDes &,TInt)const sets this as the active s...

inline void ReadResourceL(TDes &aDes, TInt aResourceId) const;

Description

Reads a resource into a descriptor.

The descriptor must be long enough to contain the entire resource. No memory is allocated by this function.

Parameters

inline HBufC* AllocReadResourceL(TInt aResourceId) const;

Description

Reads a resource into a heap descriptor, allocating memory for it.

Note: the calling program must destroy the heap descriptor when it is no longer needed.

Parameters

Return value

See also:

• RResourceFile::AllocReadL(TInt)constReads a resource into a heap descriptor and returns a pointer to that descriptor...

inline HBufC* AllocReadResourceLC(TInt aResourceId) const;

Description

Reads a specified resource into a heap descriptor, allocating memory for it, and pushing the descriptor onto the cleanup stack.

The calling program should pop and destroy the heap descriptor when it is no longer needed.

Parameters

Return value

See also:

• RResourceFile::AllocReadLC(TInt)constReads a resource into a heap descriptor, returns a pointer to that descriptor an...

inline CDesCArrayFlat* ReadDesCArrayResourceL(TInt aResourceId);

Description

Reads a resource into a Unicode descriptor array.

Parameters

Return value

See also:

• TResourceReader::ReadDesCArrayL()Interprets the data at the current buffer position as an array of leading byte c...

IMPORT_C void ReadResourceAsDes8(TDes8 &aDes, TInt aResourceId) const;

Description

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. Deprecated: use CCoeEnv::ReadResourceAsDes8L(TDes8 &,TInt)const instead.

Parameters

See also:

• RResourceFile::ReadL(TDes8 &,TInt)constReads a resource specified by resource id into the specified descriptor.
• KErrCoeFailedToReadFromProgDiskRead fail. CCoeEnv::ReadResource(TDes &,TInt)const sets this as the active s...

IMPORT_C void ReadResourceAsDes8L(TDes8 &aDes, TInt aResourceId) const;

Description

Parameters

IMPORT_C HBufC8* AllocReadResourceAsDes8L(TInt aResourceId) const;

Description

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.

Parameters

Return value

See also:

• RResourceFile::AllocReadL(TInt)constReads a resource into a heap descriptor and returns a pointer to that descriptor...

IMPORT_C HBufC8* AllocReadResourceAsDes8LC(TInt aResourceId) const;

Description

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.

Parameters

Return value

See also:

• RResourceFile::AllocReadL(TInt)constReads a resource into a heap descriptor and returns a pointer to that descriptor...

IMPORT_C CDesC8ArrayFlat* ReadDesC8ArrayResourceL(TInt aResourceId);

Description

Reads a resource into an 8 bit descriptor array.

Parameters

Return value

See also:

• TResourceReader::ReadDesC8ArrayL()Interprets the data at the current buffer position as an array of leading byte c...

IMPORT_C void ReadResourceAsDes16(TDes16 &aDes, TInt aResourceId) const;

Description

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. Deprecated: use CCoeEnv::ReadResourceAsDes16L(TDes16 &,TInt)const instead.

Parameters

See also:

• RResourceFile::ReadL(TDes8 &,TInt)constReads a resource specified by resource id into the specified descriptor.
• KErrCoeFailedToReadFromProgDiskRead fail. CCoeEnv::ReadResource(TDes &,TInt)const sets this as the active s...

IMPORT_C void ReadResourceAsDes16L(TDes16 &aDes, TInt aResourceId) const;

Description

Parameters

IMPORT_C HBufC16* AllocReadResourceAsDes16L(TInt aResourceId) const;

Description

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.

Parameters

Return value

IMPORT_C HBufC16* AllocReadResourceAsDes16LC(TInt aResourceId) const;

Description

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.

Parameters

Return value

See also:

• RResourceFile::AllocReadL(TInt)constReads a resource into a heap descriptor and returns a pointer to that descriptor...

IMPORT_C CDesC16ArrayFlat* ReadDesC16ArrayResourceL(TInt aResourceId);

Description

Reads a resource into a 16 bit descriptor array.

Ownership of the array is transferred to the caller.

Parameters

Return value

See also:

• TResourceReader::ReadDesC16ArrayL()Interprets the data at the current buffer position as an array of leading byte c...

IMPORT_C void Format128(TDes &aDes, TInt aResourceId,...);

Description

Reads a 128 byte resource into a formatted string.

The format of the 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 CCoeEnv::Format256(TDes &,TInt,...) instead.

Parameters

IMPORT_C void Format256(TDes &aDes, TInt aResourceId,...);

Description

Reads a 256 byte resource into a formatted string.

The format of the string is given by the variable argument list. The unformatted resource data must not be longer than 256 bytes.

Parameters

IMPORT_C void LeaveWithErrorText(const TDesC &aMsg, const TDesC *aContextText=0);

Description

Triggers a dialog which will display the error message

Parameters

IMPORT_C void SimulateKeyEventL(const TKeyEvent &aKeyEvent, TEventCode aType);

Description

Simulates a key event.

This function calls CCoeAppUi::HandleWsEventL(const TWsEvent &,CCoeControl *) to process the event as if it had arrived from the window server.

Parameters

IMPORT_C void AddObserverOfLoadedFepL(MCoeObserverOfLoadedFep &aObserverOfLoadedFep);

Description

Adds the specified MCoeObserverOfLoadedFep to the loaded FEP list.

This enables objects to be notified when a front-end processor is loaded.

Parameters

IMPORT_C void RemoveObserverOfLoadedFep(MCoeObserverOfLoadedFep &aObserverOfLoadedFep);

Description

Removes the specified loaded FEP observer.

Parameters

IMPORT_C void AddFepObserverL(MCoeFepObserver &aFepObserver);

Description

Adds the specified MCoeFepObserver to the FEP observer list.

Parameters

Panic codes

IMPORT_C void RemoveFepObserver(MCoeFepObserver &aFepObserver);

Description

Removes the specified FEP observer.

Parameters

See also:

• CCoeEnv::AddFepObserverL(MCoeFepObserver &)Adds the specified MCoeFepObserver to the FEP observer list.

IMPORT_C void ForEachFepObserverCall(TCoeFepObserverFunction aFepObserverFunction);

Description

Calls the specified function for each FEP observer.

This function is called for each MCoeFepObserver object that has been registered. FEP observers are registered by calling CCoeEnv::AddFepObserverL(MCoeFepObserver &).

Parameters

IMPORT_C void InstallFepL(TUid aFepUid);

Description

Loads the specified secure FEP into all running applications.

The currently loaded FEP, if any, is unloaded.

Parameters

IMPORT_C void InstallFepL(TUid aFepUid, const TBool aLeave);

Description

Loads the specified secure FEP into all running applications.

The currently loaded FEP, if any, is unloaded.

Parameters

IMPORT_C void AvailableFepsL(RArray< TUid > &aUids, CDesCArray *aDisplayNames);

Description

Gets the UIDs, and optionally display names, of all the secure FEPs that are available.

Parameters

IMPORT_C void ExecuteFepSettingsDialogL(TUid aFepUid);

Description

Executes the settings dialog for the specified secure FEP.

The specified FEP does not need to be loaded.

Parameters

IMPORT_C CCoeFep* Fep() const;

Description

Gets a pointer to the currently loaded FEP.

Return value

IMPORT_C TUid FepUid() const;

Description

Gets the UID of the currently loaded FEP.

Return value

IMPORT_C void InputCapabilitiesChanged();

Description

Notifies all focus observers (FEPs) that a change has been made to the input capabilities of the focused control.

IMPORT_C void AddFocusObserverL(MCoeFocusObserver &aFocusObserver);

Description

Adds the specified MCoeFocusObserver to the focus observer list.

Parameters

Panic codes

IMPORT_C void RemoveFocusObserver(MCoeFocusObserver &aFocusObserver);

Description

Removes the specified focus observer.

Parameters

See also:

• CCoeEnv::AddFocusObserverL(MCoeFocusObserver &)Adds the specified MCoeFocusObserver to the focus observer list.

IMPORT_C void SyncNotifyFocusObserversOfChangeInFocus();

Description

IMPORT_C void BringOwnerToFront();

Description

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.

IMPORT_C void AddForegroundObserverL(MCoeForegroundObserver &aForegroundObserver);

Description

Adds the specified MCoeForegroundObserver to the foreground observer list.

Parameters

Panic codes

IMPORT_C void RemoveForegroundObserver(MCoeForegroundObserver &aForegroundObserver);

Description

Removes the specified foreground observer.

Parameters

See also:

• CCoeEnv::AddForegroundObserverL(MCoeForegroundObserver &)Adds the specified MCoeForegroundObserver to the foreground observer list.

IMPORT_C void AddResourceChangeObserverL(MCoeResourceChangeObserver &aResourceChangeObserver);

Description

Adds the specified MCoeResourceChangeObserver to the resource change observer list.

Parameters

IMPORT_C void RemoveResourceChangeObserver(MCoeResourceChangeObserver &aResourceChangeObserver);

Description

Removes the specified resource change observer.

Parameters

IMPORT_C void AddMessageObserverL(MCoeMessageObserver &aMessageObserver);

Description

Adds the specified MCoeMessageObserver to the message observer list.

Parameters

See also:

• CCoeEnv::RemoveMessageObserver(MCoeMessageObserver &)Removes the specified MCoeMessageObserver from the message observer list.

IMPORT_C void RemoveMessageObserver(MCoeMessageObserver &aMessageObserver);

Description

Removes the specified MCoeMessageObserver from the message observer list.

Parameters

See also:

• CCoeEnv::AddMessageObserverL(MCoeMessageObserver &)Adds the specified MCoeMessageObserver to the message observer list.

IMPORT_C void AddMessageMonitorObserverL(MCoeMessageMonitorObserver &aMessageMonitorObserver);

Description

Adds the specified MCoeMessageMonitorObserver to the message observer list

Parameters

IMPORT_C void RemoveMessageMonitorObserver(MCoeMessageMonitorObserver &aMessageMonitorObserver);

Description

Removes the specified MCoeMessageMonitorObserver.

Parameters

IMPORT_C static CCoeStatic* Static(TUid aUid);

Description

Gets a pointer to the specified CCoeStatic derived class.

If no match is found it will return 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.

Parameters

Return value

IMPORT_C CCoeStatic* FindStatic(TUid aUid);

Description

Parameters

Return value

IMPORT_C TBool DisableShutdownChecks() const;

Description

Return value

private: IMPORT_C virtual void Reserved_1();

Description

private: IMPORT_C virtual void Reserved_2();

Description

private: IMPORT_C virtual TInt RunError(TInt aError);

Description

Parameters

Return value

protected: IMPORT_C virtual TTypeUid::Ptr MopSupplyObject(TTypeUid aId);

Description

Retrieves an object of the same type as that encapsulated in aId.

This function is used to allow to ask owners for access to other objects that they own.

Other than in the case where NULL is returned, the object returned must be of the same object type - that is, the ETypeId member of the object pointed to by the pointer returned by this function must be equal to the iUid member of aId.

Parameters

Return value

protected: IMPORT_C virtual void DestroyScreen();

Description

Destroys the screen device.

By default this function simply deletes the screen device owned by this CCoeEnv. However, this function may be overridden by subclasses.

This function is called by CCoeEnv::DestroyEnvironment().

protected: inline TDes& ErrorText();

Description

Gets the current error message text.

Return value

protected: inline TDes& ErrorContextText();

Description

Gets the current error context text.

Return value

private: IMPORT_C virtual void InitSystemFontsL();

Description

Initialises the system fonts.

This function is called by CCoeEnv::ConstructL() during the construction of a CCoeEnv. The default implementation creates only the normal control environment font, but this function may be overridden to create other fonts.

private: IMPORT_C virtual TInt ResourceFileVersionNumber() const;

Description

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.

CCoeEnv::AddResourceFileL(const TDesC &) uses this function to verify that the application is not using an out of date resource file. An out of date resource file causes CCoeEnv::AddResourceFileL(const TDesC &) to leave with error code KErrBaflWrongResourceFileSignature.

Return value

protected: CCoeAppUi * iAppUi;

Description

protected: RFs iFsSession;

Description

protected: RWsSession iWsSession;

Description

protected: RWindowGroup iRootWin;

Description

protected: CWindowGc * iSystemGc;

Description

protected: const CFont * iNormalFont;

Description

protected: CWsScreenDevice * iScreen;

Description

protected: TWsEvent iLastEvent;

Description

protected: CArrayFix< RResourceFile > * iResourceFileArray;

Description