|
1 /* |
|
2 * Copyright (c) 2002 Nokia Corporation and/or its subsidiary(-ies). |
|
3 * All rights reserved. |
|
4 * This component and the accompanying materials are made available |
|
5 * under the terms of "Eclipse Public License v1.0" |
|
6 * which accompanies this distribution, and is available |
|
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
8 * |
|
9 * Initial Contributors: |
|
10 * Nokia Corporation - initial contribution. |
|
11 * |
|
12 * Contributors: |
|
13 * |
|
14 * Description: Utility functions related to scalable icons. |
|
15 * |
|
16 */ |
|
17 |
|
18 |
|
19 |
|
20 |
|
21 #ifndef AKN_ICON_UTILS_H |
|
22 #define AKN_ICON_UTILS_H |
|
23 |
|
24 // INCLUDES |
|
25 #include <e32std.h> |
|
26 #include <gdi.h> |
|
27 |
|
28 // FORWARD DECLARATIONS |
|
29 class CFbsBitmap; |
|
30 class MAknIconObserver; |
|
31 |
|
32 // ENUMERATIONS |
|
33 enum TScaleMode |
|
34 { |
|
35 /* |
|
36 * Scales the icon to the maximum size that fits in the given size, |
|
37 * whilst preserving the aspect ratio of the icon. The sizes of the resulting |
|
38 * bitmaps are exactly of the given size. If the aspect ratio of |
|
39 * the given size differs from the aspect ratio of the icon, |
|
40 * the resulting bitmaps will contain an unused area. |
|
41 */ |
|
42 EAspectRatioPreserved = 0, |
|
43 |
|
44 /* |
|
45 * Scales the icon to the maximum size that fits in the given size, |
|
46 * whilst preserving the aspect ratio of the icon. The resulting bitmaps |
|
47 * are resized so that any unused portion of the given size is not |
|
48 * present in them. |
|
49 * |
|
50 * This mode should be used when only the height or the width of the icon |
|
51 * is known and the other should be based on the aspect ratio of the icon. |
|
52 * The unknown dimension should be defined high enough (e.g. KMaxTInt) so |
|
53 * that it does not limit the scaling based on the aspect ratio of the icon. |
|
54 */ |
|
55 EAspectRatioPreservedAndUnusedSpaceRemoved = 1, |
|
56 |
|
57 /* |
|
58 * Scales the icon exactly to the given size. Does not preserve the aspect |
|
59 * ratio of the icon. |
|
60 */ |
|
61 EAspectRatioNotPreserved = 2, |
|
62 |
|
63 /* |
|
64 * Scales the icon to the minimum size that covers the given size, |
|
65 * whilst preserving the aspect ratio of the icon. The sizes of the resulting |
|
66 * bitmaps are exactly of the given size. If the aspect ratio of |
|
67 * the given size differs from the aspect ratio of the icon, some parts of the |
|
68 * icon will be sliced from the resulting bitmaps. |
|
69 * |
|
70 * @since 3.1 |
|
71 */ |
|
72 EAspectRatioPreservedSlice = 3 |
|
73 }; |
|
74 |
|
75 // CLASS DECLARATIONS |
|
76 |
|
77 /** |
|
78 * Class for storing the content dimensions of icons. |
|
79 */ |
|
80 class TAknContentDimensions |
|
81 { |
|
82 public: |
|
83 |
|
84 /** |
|
85 * C++ default constructor. |
|
86 */ |
|
87 inline TAknContentDimensions(); |
|
88 |
|
89 /** |
|
90 * Constructor. |
|
91 * |
|
92 * @param aWidth Icons width. |
|
93 * @param aHeight Icons height. |
|
94 */ |
|
95 inline TAknContentDimensions(TReal32 aWidth, TReal32 aHeight); |
|
96 |
|
97 /** |
|
98 * Sets the content dimensions. |
|
99 * |
|
100 * @param aWidth Width of the icon. |
|
101 * @param aHeight Height of the icon. |
|
102 */ |
|
103 inline void SetDimensions(TReal32 aWidth, TReal32 aHeight); |
|
104 |
|
105 /** |
|
106 * Sets the content size of the icon. |
|
107 * |
|
108 * @param aDimensions Two-dimensional size as a width and a height |
|
109 value of the icon. |
|
110 */ |
|
111 inline void SetDimensions(const TSize& aDimensions); |
|
112 |
|
113 public: |
|
114 |
|
115 /** Icons width. */ |
|
116 TReal32 iWidth; |
|
117 |
|
118 /** Icons height. */ |
|
119 TReal32 iHeight; |
|
120 }; |
|
121 |
|
122 /** |
|
123 * Cleanup stack helper. Owns the bitmap and the mask. |
|
124 */ |
|
125 NONSHARABLE_CLASS(CAknIcon) : public CBase |
|
126 { |
|
127 public: |
|
128 |
|
129 /** |
|
130 * Two-phased constructor. |
|
131 * |
|
132 * Creates and returns a pointer to a new @c CAknIcon object. |
|
133 * |
|
134 * @return New @c CAknIcon. |
|
135 */ |
|
136 IMPORT_C static CAknIcon* NewL(); |
|
137 |
|
138 /** |
|
139 * Destructor. |
|
140 */ |
|
141 ~CAknIcon(); |
|
142 |
|
143 public: |
|
144 |
|
145 /** |
|
146 * Gets the bitmap. |
|
147 * |
|
148 * @return The icon's bitmap. |
|
149 */ |
|
150 IMPORT_C CFbsBitmap* Bitmap() const; |
|
151 |
|
152 /** |
|
153 * Gets the mask. |
|
154 * |
|
155 * @return The icon's mask. |
|
156 */ |
|
157 IMPORT_C CFbsBitmap* Mask() const; |
|
158 |
|
159 /** |
|
160 * Sets the bitmap. |
|
161 * |
|
162 * @param aBitmap The icon's bitmap. |
|
163 */ |
|
164 IMPORT_C void SetBitmap( CFbsBitmap* aBitmap ); |
|
165 |
|
166 /** |
|
167 * Sets the mask. |
|
168 * |
|
169 * @param aMask The icon's mask. |
|
170 */ |
|
171 IMPORT_C void SetMask( CFbsBitmap* aMask ); |
|
172 |
|
173 private: |
|
174 |
|
175 /** |
|
176 * Default constructor. |
|
177 */ |
|
178 inline CAknIcon() {} |
|
179 |
|
180 private: |
|
181 |
|
182 CFbsBitmap* iBitmap; // owned |
|
183 CFbsBitmap* iMask; // owned |
|
184 }; |
|
185 |
|
186 /** |
|
187 * The purpose of this class is for clients to provide opened file handles |
|
188 * to icon files, which reside in private directories, |
|
189 * where AknIcon server has no access. |
|
190 * |
|
191 * MIF file is always generated, when building icons with MifConv tool. |
|
192 * The corresponding MBM file is generated only if there are bitmap icons |
|
193 * amongst the source icons. |
|
194 * |
|
195 */ |
|
196 class MAknIconFileProvider |
|
197 { |
|
198 public: |
|
199 |
|
200 enum TIconFileType |
|
201 { |
|
202 EMbmFile = 0, |
|
203 EMifFile = 1 |
|
204 }; |
|
205 |
|
206 public: |
|
207 |
|
208 /** |
|
209 * Destructor. |
|
210 */ |
|
211 virtual ~MAknIconFileProvider() {} |
|
212 |
|
213 /** |
|
214 * Returns an open file handle to the icon file. |
|
215 * This method should leave if an icon file with specified type does |
|
216 * not exist. That may be the case e.g. with MBM file, |
|
217 * if there are no bitmap icons. |
|
218 * |
|
219 * Note! RFs::ShareProtected must be called to the RFs instance used |
|
220 * for opening the file. |
|
221 * |
|
222 * @param aFile Icon file should be opened in this file handle, which |
|
223 * is an empty file handle, when the AknIcon framework calls this method. |
|
224 * The AknIcon framework takes care of closing the file handle after |
|
225 * having used it. |
|
226 * @param aType Icon file type. |
|
227 */ |
|
228 virtual void RetrieveIconFileHandleL( |
|
229 RFile& aFile, const TIconFileType aType ) = 0; |
|
230 |
|
231 /** |
|
232 * With this method, AknIcon framework informs that it does not use |
|
233 * this MAknIconFileProvider instance any more. After this call, |
|
234 * it is ok to delete the object. This can be implemented simply |
|
235 * e.g. by deleting self in this callback. |
|
236 * Normally, this callback is invoked when the icon in question |
|
237 * is deleted. |
|
238 * Note, however, that if the same MAknIconFileProvider instance is |
|
239 * supplied in multiple CreateIcon calls, then it must be accessible |
|
240 * by AknIcon framework until it has signalled a matching amount |
|
241 * of these callbacks. |
|
242 */ |
|
243 virtual void Finished() = 0; |
|
244 }; |
|
245 |
|
246 /** |
|
247 * AknIconUtils |
|
248 * |
|
249 * Note: The CFbsBitmap objects for bitmaps and mask returned by this class |
|
250 * may be compressed in background. |
|
251 * Client code directly accessing the bitmap pixel data should not |
|
252 * assume that the bitmap and mask objects are not compressed. |
|
253 * |
|
254 * Bitmap compression can be disabled for an icon if desired using |
|
255 * AknIconUtils::DisableCompression(). |
|
256 */ |
|
257 class AknIconUtils |
|
258 { |
|
259 public: |
|
260 |
|
261 /** |
|
262 * Creates bitmap and mask for an icon. |
|
263 * Allocates bitmap and mask objects and sets aBitmap and |
|
264 * aMask to point at them. Ownership of those is transferred to the caller. |
|
265 * These bitmaps are not ready for drawing until they are initialized with |
|
266 * SetSize method. Usually, UI controls do this. |
|
267 * |
|
268 * Use this method only if aBitmap and aMask are member variables. |
|
269 * Otherwise, use method CreateIconLC. |
|
270 * |
|
271 * @since 2.8 |
|
272 * @param aBitmap icon bitmap is stored here |
|
273 * @param aMask icon mask is stored here |
|
274 * @param aFileName File name. Can be either MBM or MIF file. |
|
275 * Extension is changed based on the given bitmap ID. |
|
276 * @param aBitmapId bitmap Id |
|
277 * @param aMaskId mask Id |
|
278 */ |
|
279 IMPORT_C static void CreateIconL( |
|
280 CFbsBitmap*& aBitmap, |
|
281 CFbsBitmap*& aMask, |
|
282 const TDesC& aFileName, |
|
283 TInt aBitmapId, |
|
284 TInt aMaskId ); |
|
285 |
|
286 /** |
|
287 * Creates bitmap and mask for an icon. |
|
288 * Allocates bitmap and mask objects and sets aBitmap and |
|
289 * aMask to point at them. Ownership of those is transferred to the caller. |
|
290 * These bitmaps are not ready for drawing until they are initialized with |
|
291 * SetSize method. Usually, UI controls do this. |
|
292 * |
|
293 * This method puts both aBitmap and aMask in the cleanup stack. |
|
294 * |
|
295 * @since 2.8 |
|
296 * @param aBitmap icon bitmap is stored here |
|
297 * @param aMask icon mask is stored here |
|
298 * @param aFileName File name. Can be either MBM or MIF file. |
|
299 * Extension is changed based on the given bitmap ID. |
|
300 * @param aBitmapId bitmap ID |
|
301 * @param aMaskId mask ID |
|
302 */ |
|
303 IMPORT_C static void CreateIconLC( |
|
304 CFbsBitmap*& aBitmap, |
|
305 CFbsBitmap*& aMask, |
|
306 const TDesC& aFileName, |
|
307 TInt aBitmapId, |
|
308 TInt aMaskId ); |
|
309 |
|
310 /** |
|
311 * Creates the bitmap for an icon. |
|
312 * Use this variant when a mask is not needed. |
|
313 * Ownership of the returned object is transferred to the caller. |
|
314 * The bitmap is not ready for drawing until it is initialized with |
|
315 * SetSize method. Usually, UI controls do this. |
|
316 * |
|
317 * @since 2.8 |
|
318 * @param aBitmap icon bitmap is stored here |
|
319 * @param aFileName File name. Can be either MBM or MIF file. |
|
320 * Extension is changed based on the given bitmap ID. |
|
321 * @param aBitmapId bitmap ID |
|
322 */ |
|
323 IMPORT_C static CFbsBitmap* CreateIconL( |
|
324 const TDesC& aFileName, |
|
325 TInt aBitmapId ); |
|
326 |
|
327 /** |
|
328 * Creates bitmap and mask for an icon. |
|
329 * Allocates bitmap and mask objects and sets aBitmap and |
|
330 * aMask to point at them. Ownership of those is transferred to the caller. |
|
331 * These bitmaps are not ready for drawing until they are initialized with |
|
332 * SetSize method. Usually, UI controls do this. |
|
333 * |
|
334 * If this method leaves, MAknIconFileProvider::Finished is called for the |
|
335 * supplied aFileProvider. |
|
336 * |
|
337 * Use this method only if aBitmap and aMask are member variables. |
|
338 * Otherwise, use method CreateIconLC. |
|
339 * |
|
340 * @since 3.0 |
|
341 * @param aBitmap icon bitmap is stored here |
|
342 * @param aMask icon mask is stored here |
|
343 * @param aFileProvider Icon file handle provider. |
|
344 * @param aBitmapId bitmap Id |
|
345 * @param aMaskId mask Id |
|
346 */ |
|
347 IMPORT_C static void CreateIconL( |
|
348 CFbsBitmap*& aBitmap, |
|
349 CFbsBitmap*& aMask, |
|
350 MAknIconFileProvider& aFileProvider, |
|
351 TInt aBitmapId, |
|
352 TInt aMaskId ); |
|
353 |
|
354 /** |
|
355 * Creates bitmap and mask for an icon. |
|
356 * Allocates bitmap and mask objects and sets aBitmap and |
|
357 * aMask to point at them. Ownership of those is transferred to the caller. |
|
358 * These bitmaps are not ready for drawing until they are initialized with |
|
359 * SetSize method. Usually, UI controls do this. |
|
360 * |
|
361 * This method puts both aBitmap and aMask in the cleanup stack. |
|
362 * |
|
363 * If this method leaves, MAknIconFileProvider::Finished is called for the |
|
364 * supplied aFileProvider. |
|
365 * |
|
366 * @since 3.0 |
|
367 * @param aBitmap icon bitmap is stored here |
|
368 * @param aMask icon mask is stored here |
|
369 * @param aFileProvider Icon file handle provider. |
|
370 * @param aBitmapId bitmap Id |
|
371 * @param aMaskId mask Id |
|
372 */ |
|
373 IMPORT_C static void CreateIconLC( |
|
374 CFbsBitmap*& aBitmap, |
|
375 CFbsBitmap*& aMask, |
|
376 MAknIconFileProvider& aFileProvider, |
|
377 TInt aBitmapId, |
|
378 TInt aMaskId ); |
|
379 |
|
380 /** |
|
381 * Creates the bitmap for an icon. |
|
382 * Use this variant when a mask is not needed. |
|
383 * Ownership of the returned object is transferred to the caller. |
|
384 * The bitmap is not ready for drawing until it is initialized with |
|
385 * SetSize method. Usually, UI controls do this. |
|
386 * |
|
387 * If this method leaves, MAknIconFileProvider::Finished is called for the |
|
388 * supplied aFileProvider. |
|
389 * |
|
390 * @since 3.0 |
|
391 * @param aFileProvider Icon file handle provider. |
|
392 * @param aBitmapId bitmap ID |
|
393 * @return The icon bitmap. |
|
394 */ |
|
395 IMPORT_C static CFbsBitmap* CreateIconL( |
|
396 MAknIconFileProvider& aFileProvider, |
|
397 TInt aBitmapId ); |
|
398 |
|
399 /** |
|
400 * Preserves the icon data (e.g. SVG-T data) related to the given icon |
|
401 * in memory. After this, the icon data is destroyed when either |
|
402 * DestroyIconData is explicitly called or the bitmap(s) of the icon are |
|
403 * deleted. |
|
404 * |
|
405 * This method should be called to improve performance if more than one |
|
406 * call to methods SetSize, SetSizeAndRotation or GetContentDimensions |
|
407 * is made successively on a particular icon. It should be called prior |
|
408 * to the above-mentioned calls. Without calling this method, |
|
409 * the icon data is destroyed after any of the method calls mentioned |
|
410 * above and then loaded from the storage medium and parsed from scratch |
|
411 * again in a new operation. |
|
412 * |
|
413 * Note! Icon data may consume considerable amounts of memory. In order |
|
414 * to save memory, any code that calls PreserveIconData should also |
|
415 * explicitly call DestroyIconData when the icon data is no longer |
|
416 * required. |
|
417 * |
|
418 * @since 2.8 |
|
419 * @param aBitmap bitmap or mask of the icon. |
|
420 */ |
|
421 IMPORT_C static void PreserveIconData( CFbsBitmap* aBitmap ); |
|
422 |
|
423 /** |
|
424 * Destroys the icon data related to the given icon, |
|
425 * if it was preserved in memory. Note that this does not affect |
|
426 * the rendered frame buffers (CFbsBitmap objects). |
|
427 * |
|
428 * @since 2.8 |
|
429 * @param aBitmap bitmap or mask of the icon. |
|
430 */ |
|
431 IMPORT_C static void DestroyIconData( CFbsBitmap* aBitmap ); |
|
432 |
|
433 /** |
|
434 * Initializes the icon to the given size, if the parameter aBitmap is |
|
435 * an instance of CAknBitmap, i.e. created with AknIconUtils methods. |
|
436 * If it is not CAknBitmap, this method does nothing. Note that this call |
|
437 * sets the sizes of both bitmap and mask (if it exists), regardless of |
|
438 * which is given as the parameter. |
|
439 * |
|
440 * @since 2.8 |
|
441 * @param aBitmap bitmap or mask of the icon |
|
442 * @param aSize icon size |
|
443 * @param aMode scale mode |
|
444 * @return Standard Symbian OS error code. In error cases, it is guaranteed |
|
445 * that the returned bitmap is a valid CFbsBitmap, but there is no guarantee |
|
446 * of its size, except that it is non-negative. |
|
447 */ |
|
448 IMPORT_C static TInt SetSize( |
|
449 CFbsBitmap* aBitmap, |
|
450 const TSize& aSize, |
|
451 TScaleMode aMode = EAspectRatioPreserved ); |
|
452 |
|
453 /** |
|
454 * Initializes the icon to the given size, if the parameter aBitmap is |
|
455 * an instance of CAknBitmap, i.e. created with AknIconUtils methods. |
|
456 * If it is not CAknBitmap, this method does nothing. Note that this call |
|
457 * sets the sizes of both bitmap and mask (if it exists), regardless of |
|
458 * which is given as the parameter. Additionally, this method rotates |
|
459 * the icon according to the given angle. |
|
460 * |
|
461 * @since 2.8 |
|
462 * @param aBitmap bitmap or mask of the icon |
|
463 * @param aSize icon size |
|
464 * @param aAngle Rotation angle in degrees. |
|
465 * @return Standard Symbian OS error code. In error cases, it is guaranteed |
|
466 * that the returned bitmap is a valid CFbsBitmap, but there is no guarantee |
|
467 * of its size, except that it is non-negative. |
|
468 */ |
|
469 IMPORT_C static TInt SetSizeAndRotation( |
|
470 CFbsBitmap* aBitmap, |
|
471 const TSize& aSize, |
|
472 TScaleMode aMode, |
|
473 TInt aAngle ); |
|
474 |
|
475 /** |
|
476 * Sets observer for change notification. |
|
477 * |
|
478 * The method BitmapChanged() will be called when the contents of the CFbsBitmap |
|
479 * are changed. Controls can use this to redraw themselves when icon |
|
480 * animation progresses. |
|
481 * |
|
482 * @since 2.8 |
|
483 * @param aBitmap bitmap |
|
484 * @param aObserver observer |
|
485 */ |
|
486 IMPORT_C static void SetObserver( CFbsBitmap* aBitmap, MAknIconObserver* aObserver ); |
|
487 |
|
488 /** |
|
489 * Returns the file name of Avkon's icon file, containing full path. |
|
490 * |
|
491 * @since 2.8 |
|
492 * @ret Avkon's icon file name, containing full path. |
|
493 */ |
|
494 IMPORT_C static const TDesC& AvkonIconFileName(); |
|
495 |
|
496 /** |
|
497 * Validates logical app icon ID so that it can be used as a parameter to |
|
498 * CreateIconL or CreateIconLC. If the given icon file name is .MBM file, |
|
499 * this method does nothing. If it is .MIF file, a predefined offset is |
|
500 * added to the given IDs. |
|
501 * |
|
502 * This method is only intended to be used when loading icons from the |
|
503 * icon file retrieved from AppArc. |
|
504 * |
|
505 * @param aIconFileName Icon file name retrieved from AppArc. |
|
506 * @param aId Logical bitmap ID used in the app icon file, usually 0. |
|
507 * @param aId Logical mask ID used in the app icon file, usually 1. |
|
508 */ |
|
509 IMPORT_C static void ValidateLogicalAppIconId( |
|
510 const TDesC& aIconFileName, |
|
511 TInt& aBitmapId, |
|
512 TInt& aMaskId ); |
|
513 |
|
514 /** |
|
515 * Tells whether the given file name is recognized as a MIF file or not. |
|
516 * Only the file name extension is examined, not the contents of the file. |
|
517 * |
|
518 * @since 2.8 |
|
519 * @param aFileName file name |
|
520 * |
|
521 * @return ETrue if MIF file, EFalse otherwise. |
|
522 */ |
|
523 IMPORT_C static TBool IsMifFile( const TDesC& aFileName ); |
|
524 |
|
525 /** |
|
526 * Tells whether the given bitmap is a part of a MIF icon or not. |
|
527 * Accepts any pointer (also NULL) as a parameter. |
|
528 * |
|
529 * @since 2.8 |
|
530 * @param aBitmap bitmap |
|
531 * |
|
532 * @return ETrue if the given bitmap is part of a MIF icon, |
|
533 * EFalse otherwise. |
|
534 */ |
|
535 IMPORT_C static TBool IsMifIcon( const CFbsBitmap* aBitmap ); |
|
536 |
|
537 /** |
|
538 * Returns the content dimensions of the given icon. |
|
539 * In case of MBM icons, this is the original size of the bitmap. |
|
540 * In case of SVG icons, this is defined in the icon data. |
|
541 * |
|
542 * If SetSize or SetSizeAndRotation is going to be called on the same |
|
543 * icon after this call, the performance can be improved by calling |
|
544 * PreserveIconData before calling this method. |
|
545 * |
|
546 * @deprecated |
|
547 * @since 2.8 |
|
548 * @param aBitmap bitmap |
|
549 * @param aContentDimensions The content dimensions are returned here. |
|
550 * |
|
551 * @ret Standard Symbian OS error code. |
|
552 */ |
|
553 IMPORT_C static TInt GetContentDimensions( |
|
554 CFbsBitmap* aBitmap, |
|
555 TSize& aContentDimensions ); |
|
556 |
|
557 /** |
|
558 * Returns the content dimensions of the given icon. |
|
559 * In case of MBM icons, this is the original size of the bitmap. |
|
560 * In case of SVG icons, this is defined in the icon data. |
|
561 * |
|
562 * If SetSize or SetSizeAndRotation is going to be called on the same |
|
563 * icon after this call, the performance can be improved by calling |
|
564 * PreserveIconData before calling this method. |
|
565 * |
|
566 * @since 3.0 |
|
567 * @param aBitmap bitmap |
|
568 * @param aContentDimensions The content dimensions are returned here. |
|
569 * |
|
570 * @ret Standard Symbian OS error code. |
|
571 */ |
|
572 IMPORT_C static TInt GetContentDimensions( |
|
573 CFbsBitmap* aBitmap, |
|
574 TAknContentDimensions& aContentDimensions ); |
|
575 |
|
576 |
|
577 /** |
|
578 * Creates bitmap and mask for an icon. |
|
579 * Allocates bitmap and mask objects and sets aResultIcon to point at them. |
|
580 * |
|
581 * When this method returns, the resulting bitmaps are |
|
582 * duplicates of the source bitmaps. |
|
583 * Also the source bitmap instances are preserved in memory. |
|
584 * |
|
585 * Ownership of aSourceIcon is transferred from caller. |
|
586 * This method takes the responsibility of deleting the object |
|
587 * even if the method leaves. |
|
588 * |
|
589 * The returned icon bitmaps are instances of CAknBitmap, |
|
590 * so AknIconUtils::SetSize is functional for them. |
|
591 * |
|
592 * AknIconUtils::SetSize first creates duplicates of the source bitmaps |
|
593 * and after that, if required, creates new bitmaps and performs scaling. |
|
594 * |
|
595 * Note that due to the additional memory consumption caused by the source bitmaps, |
|
596 * this method should only be used if it is not possible to use the variant of |
|
597 * CreateIconL that takes icon file name and IDs as parameters. |
|
598 * |
|
599 * @since 2.8 |
|
600 * |
|
601 * @param aSourceIcon Contains source bitmap and mask. |
|
602 * Ownership of aSourceIcon is transferred from caller. |
|
603 * This method takes the responsibility of deleting the object |
|
604 * even if the method leaves. |
|
605 * |
|
606 * @ret Resulting icon. Ownership transferred to the caller. |
|
607 */ |
|
608 IMPORT_C static CAknIcon* CreateIconL( CAknIcon* aSourceIcon ); |
|
609 |
|
610 /** |
|
611 * Non-masked variant of CreateIconL. |
|
612 * |
|
613 * Ownership of aSourceBitmap is transferred from caller. |
|
614 * This method takes the responsibility of deleting the object |
|
615 * even if the method leaves. |
|
616 * |
|
617 * @since 2.8 |
|
618 * @param aSourceBitmap Source bitmap. |
|
619 * Ownership is transferred from caller. |
|
620 * This method takes the responsibility of deleting the object |
|
621 * even if the method leaves. |
|
622 * |
|
623 * @ret Resulting icon bitmap. Ownership transferred to the caller. |
|
624 */ |
|
625 IMPORT_C static CFbsBitmap* CreateIconL( CFbsBitmap* aSourceBitmap ); |
|
626 |
|
627 /** |
|
628 * Determines the icon color. Only effective if the given bitmap is |
|
629 * an instance of CAknBitmap. This method only needs to be called either |
|
630 * for the bitmap or the mask of an icon, but to be effective, it needs |
|
631 * to be called before calling SetSize or SetSizeAndRotation. |
|
632 * |
|
633 * @since 2.8 |
|
634 * @param aBitmap bitmap |
|
635 * @param aColor icon color |
|
636 */ |
|
637 IMPORT_C static void SetIconColor( CFbsBitmap* aBitmap, const TRgb aColor ); |
|
638 |
|
639 |
|
640 /** |
|
641 * Excludes the icon form the icon cache. |
|
642 * Only effective if the given bitmap is an instance of CAknBitmap. This call |
|
643 * sets the sizes of both bitmap and mask (if it exists), regardless of |
|
644 * which is given as the parameter. |
|
645 * This method should be called after calling CreateIconL or CreateIconLC |
|
646 * and before calling AknIconUtils::SetSize. |
|
647 * |
|
648 * By default icons are being put to icon cache after they are no longer used. |
|
649 * This makes it possible to retrieve recently used icons fast without the need to |
|
650 * render them again. |
|
651 * The icon cache has a limited size and when the cache is full to cache new icons |
|
652 * the oldest icons from the cache will be removed. |
|
653 * In certain situations it might be feasible to exclude some icons from the |
|
654 * icon cache (e.g. in case of infrequently used large icons) to prevent some more |
|
655 * frequently used icon being kicked out from the cache. Excluding infrequently used |
|
656 * icons from icon cache could improve performance and memory usage of the system. |
|
657 * |
|
658 * |
|
659 * @since 3.1 |
|
660 * @param aBitmap bitmap |
|
661 */ |
|
662 IMPORT_C static void ExcludeFromCache( CFbsBitmap* aBitmap ); |
|
663 |
|
664 /** |
|
665 * Disables bitmap compression for the icon. |
|
666 * Only effective if the given bitmap is an instance of CAknBitmap. This call |
|
667 * prevents AknIcon framework from compressing the CFbsBitmap objects |
|
668 * (bitmap, mask) of the icon. |
|
669 * This method should be called after calling CreateIconL or CreateIconLC |
|
670 * and before calling AknIconUtils::SetSize. |
|
671 * |
|
672 * @since 3.1 |
|
673 * @param aBitmap bitmap |
|
674 */ |
|
675 IMPORT_C static void DisableCompression( CFbsBitmap* aBitmap ); |
|
676 |
|
677 |
|
678 /** |
|
679 * Performs bitmap scaling. |
|
680 * Draws a source bitmap to fit a given rectangle within a target bitmap. |
|
681 * This is ~15x faster than scaling with Symbian's DrawBitmap. Following |
|
682 * bitmap modes are supported: EGray256, EColor4K, EColor64K, EColor256, |
|
683 * EColor16MU. For all other bitmap modes, Symbian's DrawBitmap API will |
|
684 * be used. Bitmap modes of the source and target bitmap should be the |
|
685 * same. |
|
686 * @ since 3.2 |
|
687 * @ param aTrgRect target rect inside the target bitmap |
|
688 * @ param aTrgBitmap the target bitmap |
|
689 * @ param aSrcBitmap the source bitmap |
|
690 * @leave KErrArgument |
|
691 * If source bitmap mode is not the same as target bitmap mode. |
|
692 * @leave Any other Symbian OS specific error codes. |
|
693 */ |
|
694 IMPORT_C static void ScaleBitmapL( |
|
695 const TRect& aTrgRect, |
|
696 CFbsBitmap* aTrgBitmap, |
|
697 CFbsBitmap* aSrcBitmap ); |
|
698 |
|
699 /** |
|
700 * Bitmap rotation and scaling. Might be exported later. Scales and |
|
701 * rotates the given bitmap according to the parameters. Supported |
|
702 * bitmap modes are EGray2, EGray256, EColor256, EColor4K, EColor64K and |
|
703 * EColor16MU. All other bitmap depts will cause a leave with |
|
704 * KErrNotSupported. The only supported scalemode is |
|
705 * EAspectRatioPreserved. The unused area in the target bitmap is |
|
706 * filled with black color unless the bitmap depth is EGray8 when the |
|
707 * area is filled with white. Areas that do not fit to the target area |
|
708 * after rotation are clipped out |
|
709 * |
|
710 * If the bitmap depth is EGray2, the routine will perform noticeably worse. |
|
711 * |
|
712 * @param aTrgRect target rect inside the target bitmap |
|
713 * @param aTrgBitmap the target bitmap |
|
714 * @param aSrcBitmap the source bitmap |
|
715 * @param aAngle the rotation angle in degrees |
|
716 */ |
|
717 static void RotateAndScaleBitmapL( |
|
718 const TRect& aTrgRect, |
|
719 CFbsBitmap* aTrgBitmap, |
|
720 CFbsBitmap* aSrcBitmap, |
|
721 TInt aAngle ); |
|
722 |
|
723 /** |
|
724 * @internal |
|
725 */ |
|
726 static TBool DoesScaleBitmapUseFallBack( |
|
727 CFbsBitmap* aSrcBitmap ); |
|
728 |
|
729 /** |
|
730 * @internal |
|
731 */ |
|
732 static void ScaleBitmapExtL( |
|
733 const TRect& aTrgRect, |
|
734 CFbsBitmap* aTrgBitmap, |
|
735 CFbsBitmap* aSrcBitmap, |
|
736 TBool aForceFallBack ); |
|
737 |
|
738 private: |
|
739 |
|
740 /** |
|
741 * Utility for down-cast of CFbsBitmap objects. It informs whether |
|
742 * the given CFbsBitmap is CAknBitmap or not. A list of CAknBitmap |
|
743 * pointers is managed in TLS for this. |
|
744 * |
|
745 * @param aBitmap bitmap |
|
746 * @ret ETrue iff the given CFbsBitmap is an CAknBitmap instance. |
|
747 */ |
|
748 static TBool IsAknBitmap( const CFbsBitmap* aBitmap ); |
|
749 |
|
750 /** |
|
751 * Internal utility. |
|
752 */ |
|
753 static void CreateIconLC( |
|
754 CFbsBitmap*& aBitmap, |
|
755 CFbsBitmap*& aMask, |
|
756 const TDesC& aFileName, |
|
757 TInt aBitmapId, |
|
758 TInt aMaskId, |
|
759 MAknIconFileProvider* aFileProvider ); |
|
760 |
|
761 /** |
|
762 * Internal utility. |
|
763 * @deprecated |
|
764 */ |
|
765 static void CreateIconLC( |
|
766 CFbsBitmap*& aBitmap, |
|
767 CFbsBitmap*& aMask, |
|
768 const TDesC& aFileName, |
|
769 TInt aBitmapId, |
|
770 TInt aMaskId, |
|
771 RFile& aFile ); |
|
772 |
|
773 private: |
|
774 |
|
775 AknIconUtils(); |
|
776 }; |
|
777 |
|
778 #include "AknIconUtils.inl" |
|
779 #endif // AKN_ICON_UTILS_H |
|
780 |
|
781 // End of File |