![[Index]](../../../../a_stock/btn_index_wt.gif){kind=small}
![[Spacer]](../../../../a_stock/btn_spacer.gif){kind=small}
![[Previous]](../../../../a_stock/btn_prev_wt.gif){kind=small}
![[Next]](../../../../a_stock/btn_next_wt.gif){kind=small}
|
|
|
|
|
|
||
Location:
coemain.h
Link against: cone.lib
class CCoeEnv : public CActive, public MObjectProvider;
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.
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
Defined in CCoeEnv:
AddFepObserverL(), AddFocusObserverL(), AddForegroundObserverL(), AddMessageMonitorObserverL(), AddMessageObserverL(), AddObserverOfLoadedFepL(), AddResourceChangeObserverL(), AddResourceFileL(), AllocReadResourceAsDes16L(), AllocReadResourceAsDes16LC(), AllocReadResourceAsDes8L(), AllocReadResourceAsDes8LC(), AllocReadResourceL(), AllocReadResourceLC(), AppUi(), AvailableFepsL(), BringOwnerToFront(), CCoeEnv(), ConstructL(), ConstructL(), ConstructL(), ConstructL(), CreateDeviceFontL(), CreateGcL(), CreateResourceReaderLC(), CreateScreenFontL(), DefaultFontProvider(), DefaultTextDrawer(), DeleteResourceFile(), DestroyEnvironment(), DestroyScreen(), DisableExitChecks(), DisableShutdownChecks(), DoCancel(), ErrorContextText(), ErrorText(), Execute(), ExecuteD(), ExecuteFepSettingsDialogL(), Fep(), FepUid(), FindStatic(), Flush(), ForEachFepObserverCall(), Format128(), Format256(), FsSession(), HandleError(), InitSystemFontsL(), InputCapabilitiesChanged(), InstallFepL(), InstallFepL(), IsRedrawEventPending(), IsResourceAvailableL(), IsSchedulerRunning(), IsWservEventPending(), LastEvent(), LeaveWithErrorText(), MopSupplyObject(), NormalFont(), PrepareToExit(), ReadDesC16ArrayResourceL(), ReadDesC8ArrayResourceL(), ReadDesCArrayResourceL(), ReadResource(), ReadResourceAsDes16(), ReadResourceAsDes16L(), ReadResourceAsDes8(), ReadResourceAsDes8L(), ReadResourceL(), ReleaseScreenFont(), RemoveFepObserver(), RemoveFocusObserver(), RemoveForegroundObserver(), RemoveMessageMonitorObserver(), RemoveMessageObserver(), RemoveObserverOfLoadedFep(), RemoveResourceChangeObserver(), Reserved_1(), Reserved_2(), ResourceFileVersionNumber(), RootWin(), RunError(), RunL(), ScreenDevice(), SetAppUi(), SimulateKeyEventL(), Static(), Static(), SuppressNextFlush(), SwapSystemGc(), SyncNotifyFocusObserversOfChangeInFocus(), SystemGc(), Version(), WsSession(), iAppUi, iFsSession, iLastEvent, iNormalFont, iResourceFileArray, iRootWin, iScreen, iSystemGc, iWsSession, ~CCoeEnv()
Inherited from CActive:
Cancel(),
Deque(),
EPriorityHigh,
EPriorityIdle,
EPriorityLow,
EPriorityStandard,
EPriorityUserInput,
Extension_(),
IsActive(),
IsAdded(),
Priority(),
SetActive(),
SetPriority(),
TPriority,
iStatus
Inherited from CBase:
Delete(),
operator new()
Inherited from MObjectProvider:
MObjectProvider_Reserved1(),
MObjectProvider_Reserved2(),
MopGetObject(),
MopGetObjectNoChaining(),
MopNext()
IMPORT_C CCoeEnv();
Default constructor.
Constructs an incomplete CCoeEnv. Construction of the CCoeEnv is not complete until ConstructL() has been called.
This function raises a CONE 2 panic if the application already owns a CCoeEnv.
IMPORT_C ~CCoeEnv();
Destructor.
This function deletes any resources owned by the CCoeEnv that were not deleted by DestroyEnvironment().
IMPORT_C void ConstructL();
Completes construction of the CCoeEnv object.
It calls the other ConstructL() overload specifying ETrue as the initial focus state.
IMPORT_C void ConstructL(TBool aInitialFocusState);
Completes construction of the CCoeEnv.
It is called by the other overload, with aInitialFocusState set to ETrue.
|
IMPORT_C void ConstructL(TBool aInitialFocusState, TInt aDefaultScreenNumber);
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
|
IMPORT_C void ConstructL(TBool aInitialFocusState, TInt aDefaultScreenNumber, TInt aWindowGroupID);
Completes construction of the CCoeEnv.
All of the previous 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 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.
|
|
|
static IMPORT_C TVersion Version();
Gets the version number of the UI Control Framework API.
|
static IMPORT_C 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.
For example:
CCoeEnv::Static()->CreateResourceReaderLC(aReader, aResourceId);
|
IMPORT_C CCoeAppUi *SetAppUi(CCoeAppUi *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.
|
|
IMPORT_C void ExecuteD();
Launches the application and destroys the control environment.
IMPORT_C void Execute();
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.
virtual IMPORT_C void RunL();
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 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)
RunL() runs under a trap harness in the active scheduler. If it leaves, then the active scheduler calls RunError() 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 RunL() or RunError() functions.
virtual IMPORT_C void DoCancel();
Implements cancellation of an outstanding request.
This function is called as part of the active object's 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.
DoCancel() must not wait for event completion; this is handled by Cancel().
IMPORT_C void PrepareToExit();
Prepares for exiting the application.
The function is called from ExecuteD() after the active scheduler's wait loop terminates, but before the environment is destroyed.
virtual IMPORT_C void DestroyEnvironment();
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 ExecuteD() when the active scheduler's wait loop terminates.
IMPORT_C void DisableExitChecks(TBool aDisable);
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.
|
virtual IMPORT_C 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.
|
inline CCoeAppUi *AppUi() const;
Gets the application UI owned by this application.
|
inline 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.
|
inline 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.
|
inline 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.
|
inline 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.
|
inline CWindowGc &SystemGc() const;
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 CreateGcL().
|
inline const CFont *NormalFont() const;
Gets the normal environment font.
This is the font created during construction of the control environment.
|
inline 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.
|
IMPORT_C 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.
|
IMPORT_C CWindowGc *SwapSystemGc(CWindowGc *aGc);
Sets the new system graphics context.
The function returns a pointer to the old system graphics context.
|
|
|
IMPORT_C 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.
|
IMPORT_C void SuppressNextFlush();
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
RunL().
IMPORT_C TBool IsWservEventPending() const;
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.
|
IMPORT_C TBool IsRedrawEventPending() const;
Tests if there is a redraw event waiting to be processed.
|
IMPORT_C 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 GetNearestFontToMaxHeightInTwips() 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.
|
|
IMPORT_C 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.
|
|
IMPORT_C 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().
|
IMPORT_C const CCoeFontProvider &DefaultFontProvider() const;
This function returns the default font provider.
|
IMPORT_C CCoeTextDrawerBase &DefaultTextDrawer() const;
This function returns the default text drawer.
|
IMPORT_C TInt AddResourceFileL(const TDesC &aFileName);
Adds the specified resource file to the list maintained by CCoeEnv.
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.
|
|
|
IMPORT_C void DeleteResourceFile(TInt aOffset);
Deletes the specified resource file from the list maintained by CCoeEnv.
|
|
IMPORT_C TBool IsResourceAvailableL(TInt aResourceId) const;
Checks if the given resource is owned by one of the resource files in the list maintained by CCoeEnv.
|
|
IMPORT_C 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.
|
inline 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.
Deprecated - Use CCoeEnv::ReadResourceL() instead.
|
inline void ReadResourceL(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.
|
inline HBufC *AllocReadResourceL(TInt aResourceId) const;
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.
|
|
inline HBufC *AllocReadResourceLC(TInt aResourceId) const;
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.
|
|
inline CDesCArrayFlat *ReadDesCArrayResourceL(TInt aResourceId);
Reads a resource into a Unicode descriptor array.
|
|
IMPORT_C 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. Deprecated: use CCoeEnv::ReadResourceAsDes8L() instead.
|
IMPORT_C void ReadResourceAsDes8L(TDes8 &aDes, TInt aResourceId) const;
|
IMPORT_C 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.
|
|
IMPORT_C 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.
|
|
IMPORT_C CDesC8ArrayFlat *ReadDesC8ArrayResourceL(TInt aResourceId);
Reads a resource into an 8 bit descriptor array.
|
|
IMPORT_C 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. Deprecated: use CCoeEnv::ReadResourceAsDes16L() instead.
|
IMPORT_C void ReadResourceAsDes16L(TDes16 &aDes, TInt aResourceId) const;
|
IMPORT_C 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.
|
|
IMPORT_C 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.
|
|
IMPORT_C CDesC16ArrayFlat *ReadDesC16ArrayResourceL(TInt aResourceId);
Reads a resource into a 16 bit descriptor array.
Ownership of the array is transferred to the caller.
|
|
IMPORT_C void Format128(TDes &aDes, TInt aResourceId,...);
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 Format256() instead.
|
IMPORT_C void Format256(TDes &aDes, TInt aResourceId,...);
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 265 bytes.
|
IMPORT_C void LeaveWithErrorText(const TDesC &aMsg, const TDesC *aContextText=0);
Triggers a dialog which will display the error message
|
IMPORT_C void SimulateKeyEventL(const TKeyEvent &aKeyEvent, TEventCode aType);
Simulates a key event.
This function calls CCoeAppUi::HandleWsEventL() to process the event as if it had arrived from the window server.
|
IMPORT_C void AddObserverOfLoadedFepL(MCoeObserverOfLoadedFep &aObserverOfLoadedFep);
Adds the specified MCoeObserverOfLoadedFep to the loaded FEP list.
This enables objects to be notified when a front-end processor is loaded.
|
IMPORT_C void RemoveObserverOfLoadedFep(MCoeObserverOfLoadedFep &aObserverOfLoadedFep);
Removes the specified loaded FEP observer.
|
IMPORT_C void AddFepObserverL(MCoeFepObserver &aFepObserver);
Adds the specified MCoeFepObserver to the FEP observer list.
|
|
IMPORT_C void RemoveFepObserver(MCoeFepObserver &aFepObserver);
Removes the specified FEP observer.
|
IMPORT_C void ForEachFepObserverCall(TCoeFepObserverFunction aFepObserverFunction);
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().
|
| Capability: | WriteDeviceData | To protect against installation of insecure FEP. |
IMPORT_C void InstallFepL(TUid aFepUid);
Loads the specified secure FEP into all running applications.
The currently loaded FEP, if any, is unloaded.
|
| Capability: | WriteDeviceData | To protect against installation of insecure FEP. |
IMPORT_C void InstallFepL(TUid aFepUid, const TBool aLeave);
Loads the specified secure FEP into all running applications.
The currently loaded FEP, if any, is unloaded.
|
IMPORT_C void AvailableFepsL(RArray< TUid > &aUids, CDesCArray *aDisplayNames);
Gets the UIDs, and optionally display names, of all the secure FEPs that are available.
|
IMPORT_C void ExecuteFepSettingsDialogL(TUid aFepUid);
Executes the settings dialog for the specified secure FEP.
The specified FEP does not need to be loaded.
|
IMPORT_C CCoeFep *Fep() const;
Gets a pointer to the currently loaded FEP.
|
IMPORT_C TUid FepUid() const;
Gets the UID of the currently loaded FEP.
|
IMPORT_C void InputCapabilitiesChanged();
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);
Adds the specified MCoeFocusObserver to the focus observer list.
|
|
IMPORT_C void RemoveFocusObserver(MCoeFocusObserver &aFocusObserver);
Removes the specified focus observer.
|
IMPORT_C 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.
IMPORT_C void AddForegroundObserverL(MCoeForegroundObserver &aForegroundObserver);
Adds the specified MCoeForegroundObserver to the foreground observer list.
|
|
IMPORT_C void RemoveForegroundObserver(MCoeForegroundObserver &aForegroundObserver);
Removes the specified foreground observer.
|
IMPORT_C void AddResourceChangeObserverL(MCoeResourceChangeObserver &aResourceChangeObserver);
Adds the specified MCoeResourceChangeObserver to the resource change observer list.
|
IMPORT_C void RemoveResourceChangeObserver(MCoeResourceChangeObserver &aResourceChangeObserver);
Removes the specified resource change observer.
|
IMPORT_C void AddMessageObserverL(MCoeMessageObserver &aMessageObserver);
Adds the specified MCoeMessageObserver to the message observer list.
|
IMPORT_C void RemoveMessageObserver(MCoeMessageObserver &aMessageObserver);
Removes the specified MCoeMessageObserver from the message observer list.
|
IMPORT_C void AddMessageMonitorObserverL(MCoeMessageMonitorObserver &aMessageMonitorObserver);
Adds the specified MCoeMessageMonitorObserver to the message observer list
|
IMPORT_C void RemoveMessageMonitorObserver(MCoeMessageMonitorObserver &aMessageMonitorObserver);
Removes the specified MCoeMessageMonitorObserver.
|
static IMPORT_C CCoeStatic *Static(TUid aUid);
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.
|
|
IMPORT_C CCoeStatic *FindStatic(TUid aUid);
|
|
private: virtual IMPORT_C TInt RunError(TInt aError);
|
|
protected: virtual IMPORT_C TTypeUid::Ptr MopSupplyObject(TTypeUid aId);
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.
|
|
protected: virtual IMPORT_C void DestroyScreen();
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 DestroyEnvironment().
protected: inline TDes &ErrorText();
Gets the current error message text.
|
protected: inline TDes &ErrorContextText();
Gets the current error context text.
|
private: virtual IMPORT_C void InitSystemFontsL();
Initialises the system fonts.
This function is called by 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: virtual IMPORT_C 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.
|
|
|
protected: CArrayFix< RResourceFile > * iResourceFileArray;
|
Copyright ©2008 Symbian Software Ltd. |
|
![[Top]](../../../../a_stock/arrow_up_2.gif){kind=icon}
![[Previous]](../../../../a_stock/btn_prev.gif){kind=small}
![[Top]](../../../../a_stock/btn_top.gif)
![[Next]](../../../../a_stock/btn_next.gif){kind=small}