diff -r 2fe1408b6811 -r e1b950c65cb4 epoc32/include/mw/coemain.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/epoc32/include/mw/coemain.h Wed Mar 31 12:27:01 2010 +0100 @@ -0,0 +1,558 @@ +// Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies). +// All rights reserved. +// This component and the accompanying materials are made available +// under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members +// which accompanies this distribution, and is available +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". +// +// Initial Contributors: +// Nokia Corporation - initial contribution. +// +// Contributors: +// +// Description: +// + +#ifndef __COEMAIN_H__ +#define __COEMAIN_H__ + +#include +#include +#include +#include +#include +#include +#include + +#if defined(USE_IH_RAISE_EVENT) +#include +#include +#endif + +class CVwsSessionWrapper; +class MVwsSessionWrapperObserver; +class TCoeInputCapabilities; // forward declaration of class defined in COEINPUT.H +class CCoeAppUi; +class CCoeEnv; +class TResourceReader; +class RGenericPointerArray; +class CCoeFep; // must derive from CBase +class CCoeFontProvider; +class CCoeEnvExtra; +class CCoeStatic; + + +/** UI Control framework active object priorities. +These are in addition to the values contained in the TPriority enum in class CActive. + +@publishedAll +@released */ +enum TActivePriority + { + /** 300 */ + EActivePriorityClockTimer=300, + /** 200 */ + EActivePriorityIpcEventsHigh=200, + /** 150 */ + EActivePriorityFepLoader=150, + /** 100 */ + EActivePriorityWsEvents=100, + /** 50 */ + EActivePriorityRedrawEvents=50, + /** 0 */ + EActivePriorityDefault=0, + /** 10 */ + EActivePriorityLogonA=-10 + }; + + +/** Interface providing notification when there is a change in the currently +loaded FEP. + +This happens either on application start-up, or as a result of a different +front end processor having been installed. + +Anyone requiring this notification should derive from this class and implement +its pure virtual function. Derived classes also need to call CCoeEnv::AddObserverOfLoadedFepL() +during construction, and CCoeEnv::RemoveObserverOfLoadedFep() in their destructor. + +@publishedAll +@released */ +class MCoeObserverOfLoadedFep + { +public: + /** Handles a change in the loaded FEP. + + The function is called if a new FEP is loaded, or if the current one is unloaded. */ + virtual void HandleChangeInLoadedFep()=0; +protected: + IMPORT_C MCoeObserverOfLoadedFep(); + +private: + IMPORT_C virtual void MCoeObserverOfLoadedFep_Reserved_1(); + IMPORT_C virtual void MCoeObserverOfLoadedFep_Reserved_2(); +private: + TInt iMCoeObserverOfLoadedFep_Reserved1; + }; + + +/** Interface providing notification if any control gains or loses focus or is +destroyed. + +The FEP framework uses this class to observe when a target control changes +for reasons unrelated to the FEP. + +Anything that needs such notification should derive from this class and implement +its two pure virtual functions. + +In addition, derived classes need to call CCoeEnv::AddFocusObserverL() during +construction, and CCoeEnv::RemoveFocusObserver() in their destructors. + +@publishedAll +@released +@see CCoeFep */ +class MCoeFocusObserver + { +public: + /** Handles changes in focus. The function is called if any control gains or loses + focus. */ + virtual void HandleChangeInFocus()=0; + /** Handles the destruction of any control. It is called by the framework if any + control is destroyed. */ + virtual void HandleDestructionOfFocusedItem()=0; +protected: + IMPORT_C MCoeFocusObserver(); +private: + IMPORT_C virtual void MCoeFocusObserver_Reserved_1(); + IMPORT_C virtual void MCoeFocusObserver_Reserved_2(); +private: + TInt iMCoeFocusObserver_Reserved1; + }; + +/** An interface which enables message windows to observe resource changes. + +Resource change observers should be added to the control environment using +CCoeEnv::AddResourceChangeObserverL(). + +@publishedAll +@released */ +class MCoeResourceChangeObserver + { +public: + /** Handles a change to the application's resources. */ + virtual void HandleResourceChange()=0; +protected: + IMPORT_C MCoeResourceChangeObserver(); +private: + IMPORT_C virtual void MCoeResourceChangeObserver_Reserved_1(); + IMPORT_C virtual void MCoeResourceChangeObserver_Reserved_2(); +private: + TInt iMCoeResourceChangeObserver_Reserved1; + }; + +/** Interface providing notification of foreground/background changes. + +The FEP framework class, CCoeFep, derives from MCoeForegroundObserver, which +enables FEPs to receive notification when the target application (which receives +the FEP's output) goes into the foreground or background. + +Anything that needs this notification should derive from this class and override +its two pure virtual functions. + +In addition, derived classes also need to call CCoeEnv::AddForegroundObserverL() +during construction, and CCoeEnv::RemoveForegroundObserver() in their destructors. + +@publishedAll +@released +@see CCoeFep */ +class MCoeForegroundObserver + { +public: + /** Handles the application coming to the foreground. */ + virtual void HandleGainingForeground()=0; + /** Handles the application going into the background. */ + virtual void HandleLosingForeground()=0; +protected: + IMPORT_C MCoeForegroundObserver(); +private: + IMPORT_C virtual void MCoeForegroundObserver_Reserved_1(); + IMPORT_C virtual void MCoeForegroundObserver_Reserved_2(); +private: + TInt iMCoeForegroundObserver_Reserved1; + }; + + +/** Interface for handling incoming window server messages. + +This interface is used to enable FEPs to keep their settings synchronised +across all running instances. + +Anything that needs to be notified of messages that get sent by the window server's +message-sending service should derive from this class and override its pure +virtual function. + +In addition, derived classes also need to call CCoeEnv::AddMessageObserverL() +during construction and CCoeEnv::RemoveMessageObserver() in their destructors. + +@publishedAll +@released */ +class MCoeMessageObserver + { +public: + /** Message response flags. */ + enum TMessageResponse + { + /** Message not handled. */ + EMessageNotHandled, + /** Message handled. */ + EMessageHandled + }; +public: + /** Handles window server messages. + + Implementations should return EMessageHandled if they are able to handle the + message, or EMessageNotHandled if the message is not appropriate to this observer. + + @param aClientHandleOfTargetWindowGroup The window group that the message + was sent to. Many implementations will not need this information. + @param aMessageUid The message UID. + @param aMessageParameters The message parameters. + @return Indicates whether the message was handled or not handled + by the function. */ + virtual TMessageResponse HandleMessageL(TUint32 aClientHandleOfTargetWindowGroup, TUid aMessageUid, const TDesC8& aMessageParameters)=0; +protected: + IMPORT_C MCoeMessageObserver(); +private: + IMPORT_C virtual void MCoeMessageObserver_Reserved_1(); + IMPORT_C virtual void MCoeMessageObserver_Reserved_2(); + }; + +/** Mix-in interface for handling window visibility messages. + +@publishedAll +@released */ +class MCoeMessageMonitorObserver + { +public: + /** Received windows messages for monitoring. + @param aEvent The windows server event data.*/ + virtual void MonitorWsMessage(const TWsEvent& aEvent)=0; +private: + IMPORT_C virtual void MCoeMessageMonitorObserver_Reserved_1(); + IMPORT_C virtual void MCoeMessageMonitorObserver_Reserved_2(); + }; + +// classes defined in FEPBASE, declared here +class MCoeFepObserver; + +/** +@publishedAll +@released +*/ +typedef void (*TCoeFepObserverFunction)(MCoeFepObserver& aFepObserver); + +/** +@publishedAll +@released +*/ +class CCoeFepParameters : public CBase + { +public: + static CCoeFepParameters* NewLC(); +private: + inline CCoeFepParameters() {} + }; + + +/** Implements the active scheduler presupposed by the control environment. + +@publishedPartner +@deprecated +*/ +class CCoeScheduler : public CBaActiveScheduler + { +public: + IMPORT_C CCoeScheduler(CCoeEnv* aCoeEnv); + IMPORT_C virtual void WaitForAnyRequest(); + IMPORT_C virtual void DisplayError(TInt aError) const; + /** Gets the control environment. + + @return A pointer to the control environment. */ + inline CCoeEnv* CoeEnv() {return iCoeEnv;} + TBool Flush() const; // not to be called from outside CONE + void SetFlush(TBool aFlush); // not to be called from outside CONE +private: + // from CBaActiveScheduler + IMPORT_C virtual void Reserved_1(); + IMPORT_C virtual void Reserved_2(); +private: + CCoeEnv* iCoeEnv; + TBool iFlush; + }; + + + +/** 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. + +@publishedAll +@released */ +class CCoeEnv : public CActive, public MObjectProvider + { +public: + // Properties + IMPORT_C static TVersion Version(); + IMPORT_C static CCoeEnv* Static(); + // Construction and destruction + IMPORT_C CCoeEnv(); + IMPORT_C ~CCoeEnv(); + IMPORT_C void ConstructL(); + IMPORT_C void ConstructL(TBool aInitialFocusState); + IMPORT_C void ConstructL(TBool aInitialFocusState, TInt aDefaultScreenNumber); + IMPORT_C void ConstructL(TBool aInitialFocusState, TInt aDefaultScreenNumber, TInt aWindowGroupID); + IMPORT_C CCoeAppUi* SetAppUi(CCoeAppUi* aAppUi); + IMPORT_C void ExecuteD(); + IMPORT_C void Execute(); + IMPORT_C void RunL(); + IMPORT_C void DoCancel(); + IMPORT_C void PrepareToExit(); + IMPORT_C virtual void DestroyEnvironment(); + IMPORT_C void DisableExitChecks(TBool aDisable); + IMPORT_C virtual void HandleError(TInt aError); + // System resources + inline CCoeAppUi* AppUi() const; + inline RFs& FsSession() const; + inline RWsSession& WsSession() const; + inline RWindowGroup& RootWin() const; + inline CWsScreenDevice* ScreenDevice() const; + inline CWindowGc& SystemGc() const; + inline const CFont* NormalFont() const; + inline const TWsEvent& LastEvent() const; + inline TBool IsSchedulerRunning() const; + // Graphics + IMPORT_C CWindowGc* CreateGcL(); + IMPORT_C CWindowGc* SwapSystemGc(CWindowGc* aGc); + IMPORT_C void Flush(TTimeIntervalMicroSeconds32 aDelay=0); + IMPORT_C void SuppressNextFlush(); + IMPORT_C TBool IsWservEventPending() const; + IMPORT_C TBool IsRedrawEventPending() const; + // Fonts (legacy API) + IMPORT_C CFbsFont* CreateDeviceFontL(CGraphicsDevice* aDevice,const TFontSpec& aFontSpec); + IMPORT_C CFbsFont* CreateScreenFontL(const TFontSpec& aFontSpec); + IMPORT_C void ReleaseScreenFont(CFont* aFont) const; + // Font provider + IMPORT_C const CCoeFontProvider& DefaultFontProvider() const; + // Text drawer + IMPORT_C CCoeTextDrawerBase& DefaultTextDrawer() const; + // Zooming + IMPORT_C TZoomFactor ZoomFactor() const; + IMPORT_C void SetZoomFactor(const TZoomFactor& aZoomFactor); + // Resource reading + IMPORT_C TInt AddResourceFileL(const TDesC& aFileName); + IMPORT_C void DeleteResourceFile(TInt aOffset); + IMPORT_C TBool IsResourceAvailableL(TInt aResourceId) const; + IMPORT_C void CreateResourceReaderLC(TResourceReader& aReader,TInt aResourceId) const; + inline void ReadResource(TDes& aDes,TInt aResourceId) const; + inline void ReadResourceL(TDes& aDes,TInt aResourceId) const; + inline HBufC* AllocReadResourceL(TInt aResourceId) const; + inline HBufC* AllocReadResourceLC(TInt aResourceId) const; + inline CDesCArrayFlat* ReadDesCArrayResourceL(TInt aResourceId); + IMPORT_C void ReadResourceAsDes8(TDes8& aDes,TInt aResourceId) const; /** @deprecated 7.0*/ + IMPORT_C void ReadResourceAsDes8L(TDes8& aDes,TInt aResourceId) const; + IMPORT_C HBufC8* AllocReadResourceAsDes8L(TInt aResourceId) const; + IMPORT_C HBufC8* AllocReadResourceAsDes8LC(TInt aResourceId) const; + IMPORT_C CDesC8ArrayFlat* ReadDesC8ArrayResourceL(TInt aResourceId); + IMPORT_C void ReadResourceAsDes16(TDes16& aDes,TInt aResourceId) const; /** @deprecated 7.0*/ + IMPORT_C void ReadResourceAsDes16L(TDes16& aDes,TInt aResourceId) const; + IMPORT_C HBufC16* AllocReadResourceAsDes16L(TInt aResourceId) const; + IMPORT_C HBufC16* AllocReadResourceAsDes16LC(TInt aResourceId) const; + IMPORT_C CDesC16ArrayFlat* ReadDesC16ArrayResourceL(TInt aResourceId); + IMPORT_C void Format128(TDes& aDes,TInt aResourceId,...); + IMPORT_C void Format256(TDes& aDes,TInt aResourceId,...); + // Error handling + IMPORT_C void LeaveWithErrorText(const TDesC& aMsg,const TDesC* aContextText=NULL); + // Key handling + IMPORT_C void SimulateKeyEventL(const TKeyEvent& aKeyEvent,TEventCode aType); + // FEP handling + IMPORT_C void AddObserverOfLoadedFepL(MCoeObserverOfLoadedFep& aObserverOfLoadedFep); + IMPORT_C void RemoveObserverOfLoadedFep(MCoeObserverOfLoadedFep& aObserverOfLoadedFep); + IMPORT_C void AddFepObserverL(MCoeFepObserver& aFepObserver); + IMPORT_C void RemoveFepObserver(MCoeFepObserver& aFepObserver); + IMPORT_C void ForEachFepObserverCall(TCoeFepObserverFunction aFepObserverFunction); + void EnsureCorrectFepIsLoadedL(); + void EnsureSpecifiedFepIsLoadedL(TUid aFepUid); + IMPORT_C void InstallFepL(TUid aFepUid); + IMPORT_C void InstallFepL(TUid aFepUid, const TBool aLeave); + IMPORT_C void AvailableFepsL(RArray& aUids, CDesCArray* aDisplayNames); + IMPORT_C void ExecuteFepSettingsDialogL(TUid aFepUid); + IMPORT_C CCoeFep* Fep() const; + IMPORT_C TUid FepUid() const; + IMPORT_C void InputCapabilitiesChanged(); + // Control focus handling + IMPORT_C void AddFocusObserverL(MCoeFocusObserver& aFocusObserver); + IMPORT_C void RemoveFocusObserver(MCoeFocusObserver& aFocusObserver); + IMPORT_C void SyncNotifyFocusObserversOfChangeInFocus(); + void NotifyFocusObserversOfDestructionOfFocusedItem(); + // Application focus (foreground) handling + IMPORT_C void BringOwnerToFront(); + IMPORT_C void AddForegroundObserverL(MCoeForegroundObserver& aForegroundObserver); + IMPORT_C void RemoveForegroundObserver(MCoeForegroundObserver& aForegroundObserver); + void NotifyForegroundObserversOfGainingForeground(); + void NotifyForegroundObserversOfLosingForeground(); + // Resource change handling + IMPORT_C void AddResourceChangeObserverL(MCoeResourceChangeObserver& aResourceChangeObserver); + IMPORT_C void RemoveResourceChangeObserver(MCoeResourceChangeObserver& aResourceChangeObserver); + void NotifyResourceObserversOfChangeInResource(); + // Window server message handling + IMPORT_C void AddMessageObserverL(MCoeMessageObserver& aMessageObserver); + IMPORT_C void RemoveMessageObserver(MCoeMessageObserver& aMessageObserver); + IMPORT_C void AddMessageMonitorObserverL(MCoeMessageMonitorObserver& aMessageMonitorObserver); + IMPORT_C void RemoveMessageMonitorObserver(MCoeMessageMonitorObserver& aMessageMonitorObserver); + void NotifyMessageMonitorObserversOfEvent(const TWsEvent& aEvent); + // Singleton access + IMPORT_C static CCoeStatic* Static(TUid aUid); + IMPORT_C CCoeStatic* FindStatic(TUid aUid); +#if defined(SYMBIAN_WSERV_AND_CONE_MULTIPLE_SCREENS) + //multiple screens + IMPORT_C CWsScreenDevice* ScreenDevice(TInt aScreenNumber) const; + IMPORT_C RWindowGroup* RootWin(TInt aScreenNumber) const; +#endif +public: // *** Do not use! API liable to change *** + TInt AppStartupInstrumentationEventIdBase(); +public: // Internal to Symbian + IMPORT_C void GetMessageNotifyingObserversLC(TUint32 aClientHandleOfTargetWindowGroup, TUid& aMessageUid, TPtr8& aMessageParameters, const TWsEvent& aMessageEvent); + IMPORT_C TBool DisableShutdownChecks() const; +protected: // Internal to Symbian + IMPORT_C void SetAppStartupInstrumentationEventIdBaseL(TInt aAppStartupInstrumentationEventIdBase); + IMPORT_C void DestroyEnvironmentStatic(); + IMPORT_C void DestroyEnvironmentEnd(); + IMPORT_C TInt CoeEnvConstructorError() const; +private: // reserved virtual function space + IMPORT_C virtual void Reserved_1(); + IMPORT_C virtual void Reserved_2(); +private: // from CActive + IMPORT_C TInt RunError(TInt aError); +protected: // from MObjectProvider + IMPORT_C TTypeUid::Ptr MopSupplyObject(TTypeUid aId); +protected: + IMPORT_C virtual void DestroyScreen(); + inline TDes& ErrorText(); + inline TDes& ErrorContextText(); +public: // but not exported + void ReadEvent(); + CVwsSessionWrapper* InitViewServerSessionL(MVwsSessionWrapperObserver& aObserver); + void AddStatic(CCoeStatic* aStatic); + void QueueNotificationToFocusObserversOfChangeInFocus(); + TInt FocusObserverNotificationIdentifier() const; + TBool FocusObserverNotificationIsStillPending(TInt aFocusObserverNotificationIdentifier) const; + void RefetchPixelMappingL(); + TBool ControlStateChange(); +private: + void CreateActiveSchedulerL(); + void ConnectToFileServerL(); + void ConnectToWindowServerL(); + void InitScreenL( TInt aDefaultScreenNumber ); + void InitRootWindowL(TBool aInitialFocusState, TInt aWindowGroupID=0); + void InitSystemGcL(); + IMPORT_C virtual void InitSystemFontsL(); + IMPORT_C virtual TInt ResourceFileVersionNumber() const; + RResourceFile& ResourceFileForId(TInt aResourceId) const; + void DestroyAllResourceFiles(); + void AddObserverL(TAny* aObserver, RGenericPointerArray& aArray); + void RemoveObserver(TAny* aObserver, RGenericPointerArray& aArray); + void UpdateStatic(CCoeAppUi* aNewAppUi); + void SetInitialHandleCount(); + TUint InitialHandleCount() const; + RResourceFile* DoResourceFileForIdL(TInt aResourceId) const; +#if defined(SYMBIAN_WSERV_AND_CONE_MULTIPLE_SCREENS) + void PopulateArrayOfScreenItemsL(); + void DeleteArrayOfScreensItems(); +#endif +protected: + CCoeAppUi* iAppUi; + RFs iFsSession; + RWsSession iWsSession; + RWindowGroup iRootWin; + CWindowGc* iSystemGc; + const CFont* iNormalFont; + CWsScreenDevice* iScreen; + TWsEvent iLastEvent; + CArrayFix* iResourceFileArray; +private: + enum TFlags // used in the bottom 16 bits only of iEnvFlags + { + ENoShutdownChecks =0x0001, + EExtraPointerIsErrorCode =0x0002, + ESchedulerIsRunning =0x0004 + }; +private: + TDes* iErrorText; + TDes* iErrorContextText; + CCoeEnvExtra* iExtra; + CTrapCleanup* iCleanup; + TUint iEnvFlags; + }; + +/** Base class for creating singleton objects that will be stored by CCoeEnv. + +Each object must have a unique TUid. + +Symbian OS does not provide writeable global static data. Singleton objects +provide its equivalent in thread local storage, which is supported. + +This behaviour is useful for objects in which only one copy is ever needed +in the thread or application, e.g. in alert windows. + +@publishedAll +@released */ +class CCoeStatic : public CBase + { +public: + /** Scope of access to the singleton object. */ + enum TScope + { + /** Access from the entire thread. */ + EThread, + /** Access from an appUi in that thread. */ + EApp, + }; + /** The default destruction priority if none is specified in the constructor */ + enum {EDefaultDestructionPriority=100}; +public: + IMPORT_C ~CCoeStatic(); +protected: + IMPORT_C CCoeStatic(); + IMPORT_C CCoeStatic(TUid aUid,TScope=EThread); + IMPORT_C CCoeStatic(TUid aUid,TInt aDestructionPriority,TScope aScope=EThread); +private: + IMPORT_C virtual void CCoeStatic_Reserved1(); + IMPORT_C virtual void CCoeStatic_Reserved2(); +private: + void DoConstruction(const TUid& aUid,TInt aDestructionPriority,TScope aScope); + void SetCsAppUi(CCoeAppUi* aAppUi); + CCoeAppUi* CsAppUi() const; + TScope CsScope() const; + inline TInt DestructionPriority() const {return iCsLink.iPriority;} +private: + TPriQueLink iCsLink; + TUid iCsUid; + TUint iCsAppUiAndScope; + TInt iCCoeStatic_Reserved1; +private: + friend class CCoeEnv; + friend class CCoeEnvExtra; + }; + +#include + +#endif // __COEMAIN_H__