1 // Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).
2 // All rights reserved.
3 // This component and the accompanying materials are made available
4 // under the terms of "Eclipse Public License v1.0"
5 // which accompanies this distribution, and is available
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
16 #ifndef __EIKAPPUI_H__
17 #define __EIKAPPUI_H__
30 class CEikApplication;
32 class MApaEmbeddedDocObserver;
33 struct SExtendedError;
34 class CApaCommandLine;
36 /** Handles application-wide aspects of the application's user interface such
37 as the menu bar, toolbar pop-up menus, opening and closing files and exiting the
40 Every GUI application should use its own class derived from CEikAppUi.
42 An app UI's main role is to handle commands, in its HandleCommandL() function.
43 These may be invoked using the menu bar, toolbar, or hotkeys; the commands
44 that an app UI handles are specified in the application's resource file.
46 In addition, the app UI normally needs to respond to other kinds of events, by
47 providing suitable implementations of the following virtual functions, all
48 inherited from CCoeAppUi:
50 - HandleKeyEventL(): Key events.
52 - HandleForegroundEventL(): Application switched to foreground.
54 - HandleSwitchOnEventL(): Machine switched on.
56 - HandleSystemEventL(): System events.
58 - HandleApplicationSpecificEventL(): Application-specific events.
62 class CEikAppUi : public CCoeAppUi, public MEikMenuObserver, public MCoeMessageObserver, public MObjectProvider
65 IMPORT_C ~CEikAppUi();
67 public: // new functions
68 IMPORT_C virtual void ConstructL();
69 IMPORT_C virtual void HandleModelChangeL();
70 IMPORT_C TLanguage ApplicationLanguageL() const;
71 IMPORT_C CEikApplication* Application() const;
72 IMPORT_C CEikDocument* Document() const;
73 IMPORT_C void SetDocument(CEikDocument* aDocument);
74 inline CEikAppUi* ContainerAppUi() const;
75 IMPORT_C void SetEmbeddedDocInfo(MApaEmbeddedDocObserver* aObserver, TBool aReadOnly);
76 IMPORT_C virtual TBool ProcessCommandParametersL(TApaCommand aCommand, TFileName& aDocumentName, const TDesC8& aTail);
77 IMPORT_C virtual TBool ProcessCommandParametersL(CApaCommandLine& aCommandLine);
78 // Application screen extent
79 IMPORT_C TRect ClientRect() const;
80 IMPORT_C virtual TRect ApplicationRect() const;
82 IMPORT_C void LaunchPopupMenuL(TInt aResourceId, const TPoint& aTargetPos, TPopupTargetPosType aTargetType, const CEikHotKeyTable* aHotKeyTable = NULL);
83 IMPORT_C virtual void StopDisplayingMenuBar();
85 IMPORT_C TBool FadeWhenInBackground();
86 IMPORT_C virtual void SetFadedL(TBool aFaded);
87 inline void SetFaded(TBool aFaded); //mm: has no implementation
88 public: // new function
89 IMPORT_C virtual void ReportResourceChangedToAppL(TInt aType);
90 IMPORT_C virtual void HandleCommandL(TInt aCommand);
91 IMPORT_C virtual void ProcessMessageL(TUid aUid, const TDesC8& aParams);
92 IMPORT_C virtual void OpenFileL(const TDesC& aFileName);
93 IMPORT_C virtual void CreateFileL(const TDesC& aFileName);
94 IMPORT_C virtual TErrorHandlerResponse HandleError(TInt aError, const SExtendedError& aExtErr, TDes& aErrorText, TDes& aContextText);
95 IMPORT_C virtual void HandleResourceChangeL(TInt aType);
96 public: // from CCoeAppUi
97 IMPORT_C void PrepareToExit();
98 protected: // new functions
100 IMPORT_C void BaseConstructL(TInt aAppUiFlags = 0);
101 IMPORT_C void ReadAppInfoResourceL(TInt aResourceFileOffset = 0);
102 IMPORT_C void CreateHotKeyControlL(TInt aResourceId);
103 IMPORT_C TBool ProcessCommandParametersL(TApaCommand aCommand, TFileName& aDocumentName);
104 // User data change management
105 IMPORT_C void SetDocChanged();
106 IMPORT_C void SaveAnyChangesL();
107 IMPORT_C void SaveL();
108 IMPORT_C virtual void Exit();
110 IMPORT_C void ClosePopup(); //mm: deprecate?
111 protected: // from MEikMenuObserver
112 IMPORT_C void HandleSideBarMenuL(TInt aResourceId,const TPoint& aPos,TInt aModifiers,const CEikHotKeyTable* aTable);
113 protected: // from CCoeAppUi
114 IMPORT_C void HandleApplicationSpecificEventL(TInt aType,const TWsEvent& aEvent);
115 IMPORT_C void HandleForegroundEventL(TBool aForeground);
116 IMPORT_C void HandleWsEventL(const TWsEvent& aEvent, CCoeControl* aDestination);
117 IMPORT_C void HandleSystemEventL(const TWsEvent& aEvent);
118 IMPORT_C void HandleScreenDeviceChangedL();
119 protected: // from MEikCommandObserver
120 IMPORT_C void ProcessCommandL(TInt aCommand);
121 private: // from MEikMenuObserver
122 IMPORT_C void SetEmphasis(CCoeControl* aMenuWindow,TBool aEmphasis);
123 protected: // from MCoeMessageObserver
124 IMPORT_C MCoeMessageObserver::TMessageResponse HandleMessageL(TUint32 aClientHandleOfTargetWindowGroup, TUid aMessageUid, const TDesC8& aMessageParameters);
125 protected: // from MObjectProvider
126 IMPORT_C virtual TTypeUid::Ptr MopSupplyObject(TTypeUid aId);
127 IMPORT_C virtual MObjectProvider* MopNext();
129 // Validate document file type
130 IMPORT_C virtual TBool ValidFileType(TUid aFileUid) const;
131 private: // spare virtuals
132 IMPORT_C virtual void Reserved_3();
133 IMPORT_C virtual void Reserved_4();
135 /** Application resource file and screen furniture flags, passed to BaseConstructL(). */
138 /** Application uses a standard resource file. */
140 /** Application has no resource file. */
141 ENoAppResourceFile = 0x01,
142 /** Application uses a different resource file from the standard. */
143 ENonStandardResourceFile= 0x02,
144 /** Application uses no screen furniture. */
145 ENoScreenFurniture = 0x04,
146 /** Indicates the last value in the enum. */
147 ELastReservedEikAppUiFlag = 0x8000
150 IMPORT_C void ReportResourceChangedToAppStackL(CEikAppUi* aTopApp, TInt aEventId);
151 CEikAppUiExtra* AppUiExtra();
153 void CreateResourceIndependentFurnitureL();
154 TBool ValidFileExistsL(const TDesC& aFileName);
156 /** A pointer to the application's document. */
157 CEikDocument* iDocument;
158 /** A pointer to the containing app UI. This is NULL for non-embedded
160 CEikAppUi* iContainerAppUi;
161 /** Embedded document observer. */
162 MApaEmbeddedDocObserver* iDoorObserver;
163 /** Indicates whether or not this is the app UI for an embedded,
164 read-only document. */
165 TBool iEmbeddedAndReadOnly;
173 CEikAppUiExtra* iAppUiExtra;
178 /** Returns the app UI inside which this app UI is embedded.
179 Embedded app UIs are used for editing embedded documents.
181 @return A pointer to this object's container app UI. NULL if this app
182 UI is not embedded */
183 inline CEikAppUi* CEikAppUi::ContainerAppUi() const
184 { return iContainerAppUi; }
186 #endif // __EIKAPPUI_H__