|
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". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // |
|
15 |
|
16 #ifndef __LAFENV_H__ |
|
17 #define __LAFENV_H__ |
|
18 |
|
19 #include <e32std.h> |
|
20 #include <e32base.h> |
|
21 #include <gulbordr.h> |
|
22 #include <gulalign.h> |
|
23 #include <lafmain.h> |
|
24 #include <apgcli.h> |
|
25 #ifndef SYMBIAN_ENABLE_SPLIT_HEADERS |
|
26 #include <eikinfomsgwin.h> |
|
27 #include <eikbusymsgwin.h> |
|
28 #endif //SYMBIAN_ENABLE_SPLIT_HEADERS |
|
29 #include <eikmsg.h> |
|
30 |
|
31 class MParser; |
|
32 class CCoeEnv; |
|
33 class CFont; |
|
34 class TLogicalFont; |
|
35 class CLafSystemFont; |
|
36 class MEikInfoMsgWin; |
|
37 class MEikBusyMsgWin; |
|
38 |
|
39 class LafEnv |
|
40 /** Application environment level LAF functions. |
|
41 |
|
42 @publishedPartner |
|
43 @released */ |
|
44 { |
|
45 public: |
|
46 /** Creates an EText parser. |
|
47 |
|
48 @param aIndex Index of parser to retrieve. A LAF can supply multiple parsers, |
|
49 indexed from 0. |
|
50 @return EText parser */ |
|
51 IMPORT_C static MParser* CreateTextParserL(TInt aIndex); |
|
52 /** Draws a logical border. |
|
53 |
|
54 @param aBorder Border specification to draw |
|
55 @param aGc Graphics context to which to draw |
|
56 @param aRect Drawing rectangle |
|
57 @param aBorderColors Colours with which to draw */ |
|
58 IMPORT_C static void DrawLogicalBorder(const TGulBorder& aBorder,CGraphicsContext& aGc,const TRect& aRect,const TGulBorder::TColors& aBorderColors); |
|
59 /** Gets the margins of a specified logical border. |
|
60 |
|
61 @param aBorder Border specification |
|
62 @return Border's margins */ |
|
63 IMPORT_C static TMargins LogicalBorderMargins(const TGulBorder& aBorder); |
|
64 /** Populates an array with a set of system bitmaps. |
|
65 |
|
66 CEikonEnv calls this to get system bitmaps, and uses the array in subsequent |
|
67 calls to MatchBitmap(). |
|
68 |
|
69 @param aEnv Application's control environment |
|
70 @param aBitmaps On return, array of system bitmaps */ |
|
71 IMPORT_C static void CreateSystemBitmapsL(CCoeEnv& aEnv, CArrayPtrFlat<CFbsBitmap>& aBitmaps); |
|
72 /** Populates an array with a set of system fonts. |
|
73 |
|
74 CEikonEnv calls this to get system fonts, and uses the array in subsequent |
|
75 calls to MatchFont(). |
|
76 |
|
77 A minimum of one font must be created. |
|
78 |
|
79 @param aEnv Application's control environment |
|
80 @param aFonts On return, array of system fonts */ |
|
81 IMPORT_C static void CreateSystemFontsL(CCoeEnv& aEnv,CArrayPtr<CLafSystemFont>& aFonts); |
|
82 /** Gets the nearest match in the specified fonts for a specified logical system |
|
83 font. |
|
84 |
|
85 The return value must be non-NULL. |
|
86 |
|
87 @param aFonts Fonts from which to select the match |
|
88 @param aLogicalFont The logical font to match |
|
89 @return Font that is the best match to aLogicalFont */ |
|
90 IMPORT_C static const CFont* MatchFont(CArrayPtr<CLafSystemFont>& aFonts,const TLogicalFont& aLogicalFont); |
|
91 /** Gets the nearest match in the specified bitmaps for a specified system bitmap |
|
92 type. |
|
93 |
|
94 The desired bitmap is specified by the identifer aBmpUid: for possible UIDs, |
|
95 see KLafUidEikonTexturedVal etc. |
|
96 |
|
97 The return value must be non-NULL. |
|
98 |
|
99 @param aSystemBmps Bitmaps from which to select the match |
|
100 @param aBmpUid The bitmap type to match |
|
101 @return Bitmap that is the best match to aBmpUid */ |
|
102 IMPORT_C static CFbsBitmap* MatchBitmap(const CArrayPtrFlat<CFbsBitmap>& aSystemBmps, TUid aBmpUid); |
|
103 /** Gets the corner of the screen which the busy message should appear in by default |
|
104 on the device. |
|
105 |
|
106 @return Default corner |
|
107 @see CEikonEnv::BusyMsgL() */ |
|
108 IMPORT_C static TGulAlignment DefaultBusyMsgCorner(); |
|
109 /** Tests if the specified key corresponds to the hardware default key. |
|
110 |
|
111 @param aCharCode Key to test |
|
112 @return True if the key is the default */ |
|
113 IMPORT_C static TBool IsDefaultKey(TUint aCharCode); |
|
114 /** Gets the default line spacing used to format text paragraphs. |
|
115 |
|
116 @return Default line spacing in twips */ |
|
117 IMPORT_C static TInt DefaultLineSpacingInTwips(); |
|
118 /** Gets the height of single-line edit control for the system normal font. |
|
119 |
|
120 @param aLafEnv Environment access |
|
121 @return Height of single-line edit control */ |
|
122 IMPORT_C static TInt EditableControlStandardHeight(const MLafEnv& aLafEnv); |
|
123 /** Sets any device-specific font attributes to be applied to the system character |
|
124 formatting layer. |
|
125 |
|
126 Applications can access the format layer through CEikonEnv::SystemCharFormatLayerL(). |
|
127 This format layer is also used in Edwins. |
|
128 |
|
129 @param aCharFormat On return, the character formatting to apply |
|
130 @param aCharFormatMask On return, the character formatting mask to apply */ |
|
131 IMPORT_C static void PrepareCharFormatAndMask(TCharFormat& aCharFormat,TCharFormatMask& aCharFormatMask); |
|
132 /** Specifies (and creates if necessary) a default directory for documents. |
|
133 |
|
134 The function is called on application startup. The parameters provided are |
|
135 to allow an implementation to generate a document directory based on the application |
|
136 being launched. |
|
137 |
|
138 @param aFilePath On return, the default / generated directory path |
|
139 @param aAppUid UID of application being launched |
|
140 @param aLs Application's session with the Application Architecture server |
|
141 @param aEnv Thread's control environment */ |
|
142 IMPORT_C static void GetDefaultPath(TDes& aFilePath,TUid aAppUid,RApaLsSession& aLs,CCoeEnv& aEnv); |
|
143 /** Loads the system resource file. |
|
144 |
|
145 The system resource file defines resources required by the system environment, |
|
146 and which can also be used by applications. The function is called by CCoeEnv's |
|
147 construction function. |
|
148 |
|
149 @param aEnv Thread's control environment |
|
150 @return System wide error code */ |
|
151 IMPORT_C static TInt LoadCoreResFileL(CCoeEnv& aEnv); |
|
152 /** Loads the private resource file. |
|
153 |
|
154 The private resource file defines resources required by the system environment, |
|
155 but not intended for application use. The function is called by CCoeEnv's |
|
156 construction function. |
|
157 |
|
158 @param aEnv Thread's control environment |
|
159 @return System wide error code */ |
|
160 IMPORT_C static TInt LoadPrivResFileL(CCoeEnv& aEnv); |
|
161 /** Gets the name of the resource file that contains resources for the EIKCOCTL |
|
162 component. |
|
163 |
|
164 @return Resource file for the EIKCOCTL component */ |
|
165 IMPORT_C static const TDesC& CoctlResourceFile(); |
|
166 /** Allows the LAF to update the list of system bitmaps, in response to a colour |
|
167 settings change. |
|
168 |
|
169 @param aEnv Thread's control environment |
|
170 @param aBitmaps On return, updated array of system bitmaps |
|
171 @param aColorList New colour settings */ |
|
172 IMPORT_C static void UpdateSystemBitmapsL(CCoeEnv& aEnv, CArrayPtrFlat<CFbsBitmap>& aBitmaps, const CColorList& aColorList); |
|
173 |
|
174 /** Performs the releasing of the fonts but doesn't delete the array itself |
|
175 |
|
176 @param aSystemFontArray array of fonts to release |
|
177 */ |
|
178 IMPORT_C static void ReleaseSystemFonts( CArrayPtr<CLafSystemFont>& aSystemFontArray); |
|
179 |
|
180 /** Creates busy message window. |
|
181 |
|
182 @param aEnv Thread's control environment |
|
183 @return Busy message window */ |
|
184 IMPORT_C static MEikBusyMsgWin* NewBusyMsgWinL(CCoeEnv& aEnv); |
|
185 /** Creates info message window. |
|
186 |
|
187 @param aEnv Thread's control environment |
|
188 @return Info message window */ |
|
189 IMPORT_C static MEikInfoMsgWin* NewInfoMsgWinL(CCoeEnv& aEnv); |
|
190 |
|
191 /** Creates info message window, overridden function to allow another RWindowGroup to be |
|
192 used rather the the the CCoeEnv's RootWin() function. |
|
193 |
|
194 @param aEnv Thread's control environment |
|
195 @param aWinGroup window group for displaying the Info Msg |
|
196 @return Info message window */ |
|
197 IMPORT_C static MEikInfoMsgWin* NewInfoMsgWinL(CCoeEnv& aEnv, RWindowGroup& aWinGroup); |
|
198 /** Asks if display of the task list is disabled during initialization |
|
199 |
|
200 @return ETrue if task list is disabled, otherwise EFalse */ |
|
201 IMPORT_C static TBool IsTaskListDisabledAtInitialization(); |
|
202 /** Displays a one or two line alert as a notifier window customisable by the system GUI. |
|
203 |
|
204 @param aMsg1 Line one of the message to be displayed. |
|
205 @param aMsg2 Line two of the message to be displayed */ |
|
206 IMPORT_C static void DisplayAlertAsNotifier(const TDesC& aMsg1, const TDesC& aMsg2); |
|
207 |
|
208 /** Updates an existing color list |
|
209 |
|
210 @param aColorList The color list to be updated. */ |
|
211 IMPORT_C static void UpdateColorListL(CColorList* aColorList); |
|
212 |
|
213 /** Plays an audible alert, if supported by the system GUI. */ |
|
214 IMPORT_C static void Beep(); |
|
215 |
|
216 /** Updates an existing array of system fonts. |
|
217 |
|
218 @param aEnv Thread's control environment |
|
219 @param aSystemFontArray The array of fonts to be updated */ |
|
220 IMPORT_C static void UpdateSystemFontsL(CCoeEnv* aEnv, CArrayPtr<CLafSystemFont>& aSystemFontArray); |
|
221 |
|
222 /** A list of events that are handled by the HandleExtensionEventL() function.*/ |
|
223 enum TLafEnvExtensionEvent |
|
224 { |
|
225 /** Event sent in CEikonEnv::ConstructL right before CCoeEnv::ConstructL() */ |
|
226 ELafEnvPreCoeEnvConstructL, |
|
227 /** Event sent in CEikonEnv::ConstructL right after CCoeEnv::ConstructL() */ |
|
228 ELafEnvPostCoeEnvConstructL |
|
229 }; |
|
230 |
|
231 /** Handles events listed by TLafEnvExtensionEvent |
|
232 @param aEnv The instance of CEikonEnv from which this function has been called |
|
233 @param aEvent The event |
|
234 */ |
|
235 IMPORT_C static void HandleExtensionEventL(CEikonEnv& aEnv, TLafEnvExtensionEvent aEvent); |
|
236 |
|
237 /** Allows debug keys to display output. |
|
238 @param aResourceId The resource to use for the note |
|
239 */ |
|
240 IMPORT_C static void InfoNote(TInt aResourceId,...); |
|
241 |
|
242 /** Creates a default system colour list. |
|
243 @param aEnv The instance of CEikonEnv from which this function has been called |
|
244 @return A list of colours |
|
245 */ |
|
246 IMPORT_C static CColorList* CreateColorListL(CEikonEnv& aEnv); |
|
247 |
|
248 /** Gets the name of the clock DLL |
|
249 @return The name of the clock DLL |
|
250 */ |
|
251 IMPORT_C static const TDesC& ClockDllName(); |
|
252 |
|
253 /** The behaviour of CEikonEnv can be customized. This enum lists |
|
254 the things that can be customized. */ |
|
255 enum TLafEnvPolicyItem |
|
256 { |
|
257 /** The action to take when there is an error during startup. */ |
|
258 ELafEnvPolicyExitIfErrorDuringStartup, |
|
259 /** The action to take when the document is corrupt. */ |
|
260 ELafEnvPolicyDeleteCorruptDocumentAndContinue, |
|
261 /** This affects the way the environment is deleted. */ |
|
262 ELAfEnvPolicyDeferredEnvironmentDeletion, |
|
263 }; |
|
264 |
|
265 /** CEikonEnv will use this function to find out how it should behave. |
|
266 The list of things that can be customized this way are listed by |
|
267 TLafEnvPolicyItem. |
|
268 @param aItem The policy item. |
|
269 @return An integer that indicates what the action should be. |
|
270 */ |
|
271 IMPORT_C static TInt PolicyItem(TLafEnvPolicyItem aItem); |
|
272 |
|
273 public: |
|
274 inline static TInt ShadowHeight(); |
|
275 private: |
|
276 /** Defines types of constant setting relevant to LAFs. */ |
|
277 enum TConstantType |
|
278 { |
|
279 /** Window shadow height. */ |
|
280 EShadowHeight |
|
281 }; |
|
282 private: |
|
283 /** Gets the value for a specified constant setting. |
|
284 |
|
285 @param aConstant Type of constant setting to get |
|
286 @return Value for the constant setting */ |
|
287 IMPORT_C static TInt Constant(TConstantType aConstant); |
|
288 }; |
|
289 |
|
290 // identifiers for legacy system fonts |
|
291 |
|
292 /** UID for the system "normal" font. |
|
293 |
|
294 @see TLogicalFont::iFontId |
|
295 @publishedPartner |
|
296 @released */ |
|
297 #define KLafUidNormalFontVal 0x10005F02 |
|
298 |
|
299 /** UID for the system "title" font. |
|
300 |
|
301 @see TLogicalFont::iFontId |
|
302 @publishedPartner |
|
303 @released */ |
|
304 #define KLafUidTitleFontVal 0x10005F03 |
|
305 |
|
306 /** UID for the system "annotation" font. |
|
307 |
|
308 @see TLogicalFont::iFontId |
|
309 @publishedPartner |
|
310 @released */ |
|
311 #define KLafUidAnnotationFontVal 0x10005F04 |
|
312 |
|
313 /** UID for the system "legend" font. |
|
314 |
|
315 @see TLogicalFont::iFontId |
|
316 @publishedPartner |
|
317 @released */ |
|
318 #define KLafUidLegendFontVal 0x10005F05 |
|
319 |
|
320 /** UID for the system "symbol" font. |
|
321 |
|
322 @see TLogicalFont::iFontId |
|
323 @publishedPartner |
|
324 @released */ |
|
325 #define KLafUidSymbolFontVal 0x10005F06 |
|
326 |
|
327 /** UID for the system "dense" font. |
|
328 |
|
329 @see TLogicalFont::iFontId |
|
330 @publishedPartner |
|
331 @released */ |
|
332 #define KLafUidDenseFontVal 0x10005F07 |
|
333 |
|
334 // identifiers for legacy system bitmaps |
|
335 /** UID for a textured block system bitmap. |
|
336 |
|
337 @see LafEnv::MatchBitmap() |
|
338 @publishedPartner |
|
339 @released */ |
|
340 #define KLafUidEikonTexturedVal 0x100048F4 |
|
341 |
|
342 /** UID for a gray block system bitmap. |
|
343 |
|
344 @see LafEnv::MatchBitmap() |
|
345 @publishedPartner |
|
346 @released */ |
|
347 #define KLafUidEikonGrayVal 0x100048F5 |
|
348 |
|
349 /** UID for a horizontal option button system bitmap. |
|
350 |
|
351 @see LafEnv::MatchBitmap() |
|
352 @publishedPartner |
|
353 @released */ |
|
354 #define KLafUidEikonOptiVal 0x100048F6 |
|
355 |
|
356 /** UID for a highlighted horizontal option button system bitmap. |
|
357 |
|
358 @see LafEnv::MatchBitmap() |
|
359 @publishedPartner |
|
360 @released */ |
|
361 #define KLafUidEikonOptihVal 0x100048F7 |
|
362 |
|
363 /** UID for a horizontal option button mask system bitmap. |
|
364 |
|
365 @see LafEnv::MatchBitmap() |
|
366 @publishedPartner |
|
367 @released */ |
|
368 #define KLafUidEikonOptimVal 0x100048F8 |
|
369 |
|
370 // Inlines |
|
371 |
|
372 inline TInt LafEnv::ShadowHeight() |
|
373 /** Gets the height of shadows to apply to windows. |
|
374 |
|
375 @return Shadow height. */ |
|
376 {//static |
|
377 return Constant(EShadowHeight); |
|
378 } |
|
379 |
|
380 #endif |