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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
5 // which accompanies this distribution, and is available
6 // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
35 #include <babitflags.h>
36 #include <eikpicturefactory.h>
42 class CEikHotKeyTable;
44 class CParaFormatLayer;
45 class CCharFormatLayer;
46 class CCoeBrushAndPenContext;
47 class CEikCommandButton;
49 class CDictionaryStore;
50 class CApaWindowGroupName;
52 class CEikApplication;
58 class MEikAppUiFactory;
61 class CApaMaskedBitmap;
62 class CEikLogicalBorderProxy;
65 class CEikPictureFactory;
67 class TApaApplicationFactory;
76 typedef void (*TRequestDialogFunc)();
81 const TUid KUikonLibraryUid = {KUidUikonLibraryValue};
84 Creates the CEikLibrary interface object by calling the first ordinal function which is mapped to NewL method.
86 The function leaves with KErrBadLibraryEntryPoint if the ordinal 1 function
92 typedef CEikLibrary* (*EikLibraryEntryPoint)();
95 /** An environment for creating controls and utility functions for manipulating
98 Every GUI application is provided with an instance of CEikonEnv
99 by the framework, which can be accessed through either CEikonEnv::Static()
100 or the iEikonEnv macro of CEikApplication.
104 class CEikonEnv : public CCoeEnv
108 { EErrorNumValid, EErrorNumInvalid };
111 IMPORT_C static TVersion Version();
112 inline static CEikonEnv* Static();
113 // Construction and destruction
114 IMPORT_C ~CEikonEnv();
115 IMPORT_C CEikonEnv();
116 IMPORT_C void ConstructL();
117 IMPORT_C void ConstructL(TBool aInitialFocusState);
118 IMPORT_C void ConstructL(TBool aInitialFocusState, TInt aWindowGroupID);
119 IMPORT_C void ConstructAppFromCommandLineL(const TApaApplicationFactory& aApplicationFactory, const CApaCommandLine& aCommandLine);
120 IMPORT_C void ControlStackReadyL();
121 IMPORT_C void DestroyEnvironment();
123 inline CEikAppUi* EikAppUi() const;
124 inline CEikProcess* Process() const;
125 // Legacy font support (see new TCoeFont and CCoeControl::ScreenFont())
126 IMPORT_C const CFont* AnnotationFont() const;
127 IMPORT_C const CFont* TitleFont() const;
128 IMPORT_C const CFont* LegendFont() const;
129 IMPORT_C const CFont* SymbolFont() const;
130 IMPORT_C const CFont* DenseFont() const;
131 IMPORT_C const CFont* Font(const TLogicalFont& aLogicalFont) const;
132 IMPORT_C void UpdateSystemFontsL();
134 IMPORT_C const CFbsBitmap* TexturedBitmap() const; // deprecated
135 IMPORT_C const CFbsBitmap* GrayBitmap() const; // deprecated
136 IMPORT_C const CFbsBitmap* OptionBitmap() const; // deprecated
137 IMPORT_C const CFbsBitmap* HighlightedOptionBitmap() const;
138 IMPORT_C const CFbsBitmap* OptionMaskBitmap() const; // deprecated
139 IMPORT_C const CFbsBitmap* Bitmap(TUid aUidBmp) const;
141 IMPORT_C TBool ConfirmLossOfAllChangesL() const;
143 IMPORT_C MPictureFactory* PictureFactory() const;
144 IMPORT_C MEikPictureFactory* ExtendedPictureFactory(TUid aPictureType) const;
145 IMPORT_C void AddPictureFactoryL(MEikPictureFactory& aFactory);
146 IMPORT_C void RemovePictureFactory(TUid aFactoryId);
148 IMPORT_C void AlertWin(const TDesC& aMsg);
149 IMPORT_C void AlertWin(const TDesC& aMsg1, const TDesC& aMsg2);
150 inline const MEikAlertWin* Alert() const;
151 IMPORT_C void SetAlertWin(MEikAlertWin* aAlertWin);
153 IMPORT_C void LeaveWithInfoMsg(TInt aResourceId,...);
154 IMPORT_C void LeaveWithErrorContext(TInt aError, const TDesC& aContextText); // deprecated
155 IMPORT_C void GetErrorText(TDes& aDes,TInt aError) const;
156 IMPORT_C TErrorValidity GetErrorText(TDes& aErrorText, TInt aError, TUid aAppUid) const;
157 IMPORT_C TErrorValidity GetErrorTextAndTitle(TDes& aErrorText, TInt aError, TDes& aTitleText) const;
158 IMPORT_C void ResolveError(TInt aError, TUid aAppUid = KNullUid) const;
159 IMPORT_C void NotifyIdleErrorWhileRedrawing(TInt aError);
160 IMPORT_C void NotifyIdleError(TInt aError, TInt aContextResourceId);
161 IMPORT_C void HandleErrorWithContext(TInt aError,TInt aContextResourceId);
163 IMPORT_C void InfoMsg(const TDesC& aDes);
164 IMPORT_C void InfoMsgWithAlignment(TGulAlignment aCorner,const TDesC& aDes);
165 IMPORT_C void InfoMsg(TInt aResourceId, ...);
166 IMPORT_C void InfoMsg(TInt aResourceId, VA_LIST aList);
167 IMPORT_C void InfoMsgWithAlignment(TGulAlignment aCorner, TInt aResourceId,...);
168 IMPORT_C void InfoMsgWithAlignment(TGulAlignment aCorner, TInt aResourceId, VA_LIST aList);
169 IMPORT_C void InfoMsgWithDuration(const TDesC& aDes, TTimeIntervalMicroSeconds32 aDuration);
170 IMPORT_C void InfoMsgWithDuration(TInt aResourceId, TTimeIntervalMicroSeconds32 aDuration, ...);
171 IMPORT_C void InfoMsgWithDuration(TInt aResourceId, TTimeIntervalMicroSeconds32 aDuration, VA_LIST aList);
172 IMPORT_C void InfoMsgWithAlignmentAndDuration(TGulAlignment aCorner, const TDesC& aDes, TTimeIntervalMicroSeconds32 aDuration);
173 IMPORT_C void InfoMsgWithAlignmentAndDuration(TGulAlignment aCorner, TInt aResourceId, TTimeIntervalMicroSeconds32 aDuration, ...);
174 IMPORT_C void InfoMsgWithAlignmentAndDuration(TGulAlignment aCorner, TInt aResourceId, TTimeIntervalMicroSeconds32 aDuration, VA_LIST aList);
175 IMPORT_C void InfoMsgCancel();
176 IMPORT_C void VerboseInfoMsg(const TDesC& aDes);
177 IMPORT_C void SetVerboseInfoReporting(TBool aVerbose); // deprecated
179 IMPORT_C void BusyMsgL(const TDesC& aDes);
180 IMPORT_C void BusyMsgL(const TDesC& aDes, TGulAlignment aCorner);
181 IMPORT_C void BusyMsgL(TInt aResourceId);
182 IMPORT_C void BusyMsgL(const TDesC& aDes, TTimeIntervalMicroSeconds32 aInitialDelay);
183 IMPORT_C void BusyMsgL(const TDesC& aDes, TGulAlignment aCorner, TTimeIntervalMicroSeconds32 aInitialDelay);
184 IMPORT_C void BusyMsgL(TInt aResourceId, TTimeIntervalMicroSeconds32 aInitialDelay);
185 IMPORT_C void BusyMsgCancel();
187 IMPORT_C static TBool QueryWinL(const TDesC& aFirstLine, const TDesC& aSecondLine);
188 IMPORT_C TBool QueryWinL(TInt aFirstLineId, TInt aSecondLineId = 0) const;
189 IMPORT_C void SetQueryDialog(MEikInfoDialog* aQueryDialog);
190 IMPORT_C void SetRequestQueryDialogFunc(TRequestDialogFunc aQueryDialogFunc);
192 IMPORT_C static void InfoWinL(const TDesC& aFirstLine, const TDesC& aSecondLine);
193 IMPORT_C void InfoWinL(TInt aFirstLineId, TInt aSecondLineId = 0) const;
194 IMPORT_C void SetInfoDialog(MEikInfoDialog* aInfoDialog);
195 IMPORT_C void SetRequestInfoDialogFunc(TRequestDialogFunc aInfoDialogFunc);
196 IMPORT_C void AllocInfoMsg();
197 IMPORT_C void WservAllocInfoMsg();
198 IMPORT_C void FservAllocInfoMsg();
199 // Sound notificatons
200 IMPORT_C static void Beep(); // deprecated
202 IMPORT_C CWsBitmap* CreateBitmapL(const TDesC& aFileName, TInt aId);
203 IMPORT_C CWsBitmap* CreateBitmapL(const TDesC& aFileName, TInt aId, TBool aShowDlgIfErr);
204 IMPORT_C CGulIcon* CreateIconL(const TDesC& aFileName, TInt aBitmapId, TInt aMaskId = KErrNotFound);
205 IMPORT_C static CGulIcon* CreateIconFromMaskedBitmapL(const CApaMaskedBitmap& aApaMaskedBitmap);
207 IMPORT_C void SetDebugKeys(MEikDebugKeys* aDebugKeys);
209 IMPORT_C void LaunchPopupMenuL(TInt aResourceId, const TPoint& aTargetPos, TPopupTargetPosType aTargetType = EPopupTargetTopLeft, const CEikHotKeyTable* aHotKeyTable = NULL);
211 IMPORT_C static void AddWindowShadow(CCoeControl* aWinArea);
212 IMPORT_C RAnimDll& ClockDllL();
213 // Text formatting parameters
214 IMPORT_C CParaFormatLayer* SystemSingleLineParaFormatLayerL();
215 IMPORT_C CParaFormatLayer* SystemParaFormatLayerL();
216 IMPORT_C CCharFormatLayer* SystemCharFormatLayerL();
217 IMPORT_C static CParaFormatLayer* NewDefaultSingleLineParaFormatLayerL();
218 IMPORT_C static CParaFormatLayer* NewDefaultParaFormatLayerL();
219 IMPORT_C static CCharFormatLayer* NewDefaultCharFormatLayerL();
220 // Control stack utilities
221 IMPORT_C void AddDialogLikeControlToStackL(CCoeControl* aControl);
222 IMPORT_C void AddAlertDialogLikeControlToStackL(CCoeControl* aControl);
223 IMPORT_C void RemoveFromStack(CCoeControl* aControl);
224 IMPORT_C void AddSleepingDialogToStackL(CCoeControl* aControl);
225 IMPORT_C void AddSleepingAlertDialogToStackL(CCoeControl* aControl);
226 IMPORT_C void RouseSleepingDialog(CCoeControl* aControl, TBool aRoused);
228 IMPORT_C void DrawCursor(const CCoeControl* aControl, const TPoint& aPosition, TInt aWidth);
229 IMPORT_C void DrawCursor(const CCoeControl* aControl, const TPoint& aPosition, TInt aWidth, TInt aAscent, TInt aHeight);
230 IMPORT_C void HideCursor(const CCoeControl* aControl);
231 // Virtual pointer device cursor
232 IMPORT_C TEikVirtualCursor& VirtualCursor();
233 // Control of the application's ordinal position
234 IMPORT_C void BringForwards(TBool aForwards, TInt aPriority = ECoeWinPriorityAlwaysAtFront);
235 IMPORT_C void SetAutoForwarding(TBool aAutoBringToForeground);
237 IMPORT_C TPtrC KeyPressLabel(TInt aIndex) const; // deprecated
239 IMPORT_C CPrintSetup* NewDefaultPrintSetupL();
240 IMPORT_C static void GetPrinterNamesL(CPrinterModelList* aModelNameList, CDesCArray& aPrinterNameList);
241 // Application properties
242 IMPORT_C void UpdateTaskNameL();
243 IMPORT_C void SetBusy(TBool aBusy);
244 IMPORT_C TBool IsBusy() const;
245 IMPORT_C void SetSystem(TBool aSystem);
246 IMPORT_C TBool IsSystem() const;
247 IMPORT_C void SetDocNameIsAFile(TBool aDocNameIsAFile);
248 IMPORT_C TBool DocNameIsAFile() const;
249 IMPORT_C void SetRespondsToShutdownEvent(TBool aRespondsToShutdownEvent);
250 IMPORT_C TBool RespondsToShutdownEvent() const;
251 IMPORT_C void SetRespondsToSwitchFilesEvent(TBool aRespondsToSwitchFilesEvent);
252 IMPORT_C TBool RespondsToSwitchFilesEvent() const;
254 IMPORT_C void DisplayTaskList();
255 IMPORT_C void DismissTaskList();
256 public: // Internal (for Symbian and partners only)
258 inline MEikCDlgDialogFactory* CDlgDialogFactory() const;
259 inline MEikPrintDialogFactory* PrintDialogFactory() const;
260 inline MEikFileDialogFactory* FileDialogFactory() const;
261 inline MEikIrFactory* IrFactory() const;
262 inline void SetCDlgDialogFactory(MEikCDlgDialogFactory* aDialogFactory);
263 inline void SetPrintDialogFactory(MEikPrintDialogFactory* aDialogFactory);
264 inline void SetFileDialogFactory(MEikFileDialogFactory* aDialogFactory);
265 inline void SetIrFactory(MEikIrFactory* aIrFactory);
266 CArrayFix<TCreateByTypeFunction>* ControlFactoryFuncArray() const;
268 inline CColorList& ColorList() const;
269 inline TRgb Color(TLogicalColor aLogicalColor) const;
270 inline void SetColor(TLogicalColor aLogicalColor, TRgb aColor);
271 IMPORT_C TRgb ControlColor(TLogicalColor aLogicalColor,const CCoeControl& aControl) const;
272 inline CColorArray& CustomColorArray() const;
273 IMPORT_C CColorList* CreateSystemColorListL();
274 IMPORT_C CColorList* CreateSystemColorListL(const CColorList& aColorList);
275 IMPORT_C void UpdateSystemColorListL(const CColorList& aColorList);
276 IMPORT_C CColorList* PopulateColorArrayL();
277 // Library loading and unloading
278 IMPORT_C TInt AddLibraryL(TCreateByTypeFunction aControlFactory, TFileName* aResourceFile);
279 inline TInt AddLibraryL(TCreateByTypeFunction aControlFactory);
280 inline TInt AddLibraryL(TFileName* aResourceFile);
281 IMPORT_C void RemoveLibrary(TCreateByTypeFunction aControlFactory, TInt aResourceFileOffset);
282 inline void RemoveLibrary(TCreateByTypeFunction aControlFactory);
283 inline void RemoveLibrary(TInt aResourceFileOffset);
284 // Legacy UI utilities
285 inline TChar NudgeCharMinus() const;
286 inline TChar NudgeCharPlus() const;
288 inline TInt StatusPaneCoreResId() const;
289 inline void SetStatusPaneCoreResId(TInt aStatusPaneCoreResId);
291 IMPORT_C void AddAutoMenuTitleL(CEikAutoMenuTitle* aTitle);
292 inline CEikAutoMenuTitleArray* AutoMenuTitleArray() const;
294 IMPORT_C TDisplayMode DefaultDisplayMode() const;
296 IMPORT_C MLafEnv& LafEnv() const; // deprecated
297 inline TInt EditableControlStandardHeight() const;
298 IMPORT_C void SendEventToEikonServer(TInt aEvent,const TAny* aPtr,TInt aLength);
300 IMPORT_C MEikAppUiFactory* AppUiFactory() const;
301 IMPORT_C MEikAppUiFactory* AppUiFactory(const CEikAppUi& aAppUi) const;
302 IMPORT_C void SetAppUiFactoryL(MEikAppUiFactory* aAppUiFactory);
303 IMPORT_C void AddAppUiFactoryL(MEikAppUiFactory* aAppUiFactory);
304 IMPORT_C void RemoveAppUiFactory();
305 public: // Internal. Do not use!
306 IMPORT_C void SetExtension(CBase* aExtension); // deprecated
307 inline CBase* Extension() const; // deprecated
308 IMPORT_C void HandleError(TInt aError);
309 IMPORT_C void WriteInternalStateOfStackedControlsL();
310 IMPORT_C void DoGetErrorText(TDes& aDes,TInt aError) const;
311 IMPORT_C TErrorValidity DoGetErrorTextAndTitle(TDes& aErrorText, TInt aError, TInt& aTextId, TUint& aFlags, TDes& aTitleText, TBool aIsMemoryAllocatedByErrResolver = EFalse) const;
312 void InitSystemBitmapsL();
313 void UpdateColorListL();
314 void PostAppUiInitializeL();
315 TLanguage ApplicationLanguage() const;
316 void PostAppUiDestroy();
318 IMPORT_C virtual void CEikonEnv_Reserved_1();
319 IMPORT_C virtual void CEikonEnv_Reserved_2();
320 IMPORT_C virtual void CEikonEnv_Reserved_3();
321 IMPORT_C virtual void CEikonEnv_Reserved_4();
322 IMPORT_C virtual void CEikonEnv_Reserved_5();
323 private: // framework functions
324 IMPORT_C void DestroyScreen();
325 IMPORT_C void InitSystemFontsL();
326 IMPORT_C TInt ResourceFileVersionNumber() const;
328 IMPORT_C MEikInfoDialog* QueryDialog() const;
329 IMPORT_C MEikInfoDialog* InfoDialog() const;
331 IMPORT_C CEikAppServer* AppServer() const;
332 IMPORT_C TBool StartedAsServerApp() const;
334 friend class CEikServAppUi;
336 void InitSystemResourceFileL();
337 void InitPrivateResourceFileL();
339 void PrepareBusyMsgL();
340 void InitAlertWinL();
341 void InitDebugKeysL();
342 TErrorHandlerResponse PrepareToHandleError(TInt aError);
343 void DoHandleError(TErrorHandlerResponse aType);
344 static TInt IdleErrorCallBack(TAny* aThis);
345 void InitColorSchemeL();
346 void LoadParserListL();
347 void LoadLibrariesL();
348 void CloseLibraries();
349 TRequestDialogFunc RequestQueryDialogFunc();
350 TRequestDialogFunc RequestInfoDialogFunc();
353 TBool IsEiksrvThread() const;
355 TBool InfoWinOrQueryWinL(TInt aFirstLineId,TInt aSecondLineId,TBool aIsQueryWin=EFalse) const;
356 void SetCommandLineDebugMemFailL(const CApaCommandLine& aCommandLine);
357 void StoreAppLanguageL(const RApaLsSession& aLsSession);
358 void ErrorContextL(TInt aError,const TDesC& aContextText);
360 IMPORT_C virtual void CEikonEnv_Reserved_6();
361 IMPORT_C virtual void CEikonEnv_Reserved_7();
362 IMPORT_C virtual void CEikonEnv_Reserved_8();
363 IMPORT_C virtual void CEikonEnv_Reserved_9();
364 IMPORT_C virtual void CEikonEnv_Reserved_10();
366 NONSHARABLE_CLASS(TEikAppUiFactory)
369 MEikAppUiFactory* iFactory;
373 TBitFlags iEikonEnvFlags;
376 CEikProcess* iProcess;
378 CArrayPtr<CLafSystemFont>* iFontArray;
379 MEikInfoMsgWin* iInfoMsgWin;
380 MEikBusyMsgWin* iBusyMsgWin;
381 MEikAlertWin* iAlertWin;
382 TInt iSystemResourceFileOffset;
383 HBufC8* iKeyPressLabels;
384 CParaFormatLayer* iSingleLineParaFormatLayer;
385 CParaFormatLayer* iParaFormatLayer;
386 CCharFormatLayer* iCharFormatLayer;
387 const CCoeControl* iCursorWindow;
388 TInt iEditableControlStandardHeight;
389 CApaWindowGroupName* iWgName;
390 CEikErrorIdler* iErrorIdler;
391 TInt iPrivateResourceFileOffset;
392 CColorList* iColorList;
393 CEikPictureFactory* iPictureFactory;
395 MEikInfoDialog* iQueryDialog;
396 MEikInfoDialog* iInfoDialog;
397 TRequestDialogFunc iQueryDialogFunc;
398 TRequestDialogFunc iInfoDialogFunc;
399 CArrayFix<TCreateByTypeFunction>* iControlFactoryFuncArray;
400 CArrayFix<TInt>* iResourceFileOffsetArray;
401 TBool iAlertWinInitialized;
402 MEikDebugKeys* iDebugKeys;
403 MEikCDlgDialogFactory* iCDlgDialogFactory;
404 MEikPrintDialogFactory* iPrintDialogFactory;
405 MEikFileDialogFactory* iFileDialogFactory;
406 CArrayFix<TEikAppUiFactory>* iAppUiFactoryArray;
407 MEikIrFactory* iIrFactory;
408 CArrayPtr<CEikLibrary>* iLibraries;
409 TInt iEmbeddedAppLevel;
410 TInt iAutoLoadedResourceFiles;
411 TInt iAutoLoadedControlFactories;
413 TInt iStatusPaneCoreResId;
414 CEikAutoMenuTitleArray* iAutoMenuTitleArray;
415 TEikVirtualCursor iVirtualCursor;
416 CEikLogicalBorderProxy* iLogicalBorderProxy;
418 CArrayPtrFlat<CFbsBitmap>* iBitmapArray;
419 CEikEnvExtra* iEikEnvExtra; // used to be TInt iSpare1;
420 HBufC* iOOMErrorText; // used to be TInt iSpare2;
425 /** Interface for launching a dialog with a title and a message, for instance a
428 Dialogs implementing this interface can be passed to CEikonEnv::SetQueryDialog()
429 or CEikonEnv::SetInfoDialog().
436 /** Initialises and executes the dialog.
438 @param aResource The ID of the DIALOG resource that identifies the dialog's
439 type. For instance, a query dialog (with Yes/No buttons) or an info dialog
440 (with a Continue button).
441 @param aTitle The dialog's title.
442 @param aMsg The message to display in the dialog.
443 @return True if the Confirm button (or equivalent) was pressed, false if the
444 dialog was cancelled. */
445 virtual TBool RunDlgLD(TInt aResource, const TDesC& aTitle, const TDesC& aMsg) = 0;
456 virtual void ConstructL() = 0;
457 virtual void RunAlert(const TDesC& aTitle, const TDesC& aMsg) = 0;
458 virtual void Release() = 0;
459 virtual CEikDialog* AsEikDialog() = 0;
460 inline const CEikDialog* AsEikDialog() const;
461 IMPORT_C virtual CCoeControl* AsCoeControl();
462 inline const CCoeControl* AsCoeControl() const;
464 IMPORT_C virtual void MEikAlertWin_Reserved2();
465 IMPORT_C virtual void MEikAlertWin_Reserved3();
476 virtual void ConstructL() = 0;
477 virtual void Release() = 0;
479 IMPORT_C virtual void MEikDebugKeys_Reserved1();
480 IMPORT_C virtual void MEikDebugKeys_Reserved2();
481 IMPORT_C virtual void MEikDebugKeys_Reserved3();
485 IMPORT_C void InternalizeL(TEikPortFlag& aThing,RReadStream& aStream);
486 inline RWriteStream& operator<<(RWriteStream& aStream,const TEikPortFlag& aThing)
487 {aStream.WriteUint8L(aThing);return aStream;}
488 inline RReadStream& operator>>(RReadStream& aStream,TEikPortFlag& aThing)
489 {InternalizeL(aThing,aStream);return aStream;}
491 #include <eikenv.inl>
493 #endif // __EIKENV_H__