| class AknIconUtils |
Note: The CFbsBitmap objects for bitmaps and mask returned by this class may be compressed in background. Client code directly accessing the bitmap pixel data should not assume that the bitmap and mask objects are not compressed.
Bitmap compression can be disabled for an icon if desired using AknIconUtils::DisableCompression().
| Private Member Functions | |
|---|---|
| AknIconUtils() | |
| void | CreateIconLC(CFbsBitmap *&, CFbsBitmap *&, const TDesC &, TInt, TInt, MAknIconFileProvider *) |
| void | CreateIconLC(CFbsBitmap *&, CFbsBitmap *&, const TDesC &, TInt, TInt, RFile &) |
| TBool | IsAknBitmap(const CFbsBitmap *) |
| IMPORT_C const TDesC & | AvkonIconFileName | ( | ) | [static] |
Returns the file name of Avkon's icon file, containing full path.
2.8 Avkon's icon file name, containing full path.
| IMPORT_C void | CreateIconL | ( | CFbsBitmap *& | aBitmap, |
| CFbsBitmap *& | aMask, | |||
| const TDesC & | aFileName, | |||
| TInt | aBitmapId, | |||
| TInt | aMaskId | |||
| ) | [static] | |||
Creates bitmap and mask for an icon. Allocates bitmap and mask objects and sets aBitmap and aMask to point at them. Ownership of those is transferred to the caller. These bitmaps are not ready for drawing until they are initialized with SetSize method. Usually, UI controls do this.
Use this method only if aBitmap and aMask are member variables. Otherwise, use method CreateIconLC.
2.8
| CFbsBitmap *& aBitmap | icon bitmap is stored here |
| CFbsBitmap *& aMask | icon mask is stored here |
| const TDesC & aFileName | File name. Can be either MBM or MIF file. Extension is changed based on the given bitmap ID. |
| TInt aBitmapId | bitmap Id |
| TInt aMaskId | mask Id |
| IMPORT_C CFbsBitmap * | CreateIconL | ( | const TDesC & | aFileName, |
| TInt | aBitmapId | |||
| ) | [static] | |||
Creates the bitmap for an icon. Use this variant when a mask is not needed. Ownership of the returned object is transferred to the caller. The bitmap is not ready for drawing until it is initialized with SetSize method. Usually, UI controls do this.
2.8
| IMPORT_C void | CreateIconL | ( | CFbsBitmap *& | aBitmap, |
| CFbsBitmap *& | aMask, | |||
| MAknIconFileProvider & | aFileProvider, | |||
| TInt | aBitmapId, | |||
| TInt | aMaskId | |||
| ) | [static] | |||
Creates bitmap and mask for an icon. Allocates bitmap and mask objects and sets aBitmap and aMask to point at them. Ownership of those is transferred to the caller. These bitmaps are not ready for drawing until they are initialized with SetSize method. Usually, UI controls do this.
If this method leaves, MAknIconFileProvider::Finished is called for the supplied aFileProvider.
Use this method only if aBitmap and aMask are member variables. Otherwise, use method CreateIconLC.
3.0
| CFbsBitmap *& aBitmap | icon bitmap is stored here |
| CFbsBitmap *& aMask | icon mask is stored here |
| MAknIconFileProvider & aFileProvider | Icon file handle provider. |
| TInt aBitmapId | bitmap Id |
| TInt aMaskId | mask Id |
| IMPORT_C CFbsBitmap * | CreateIconL | ( | MAknIconFileProvider & | aFileProvider, |
| TInt | aBitmapId | |||
| ) | [static] | |||
Creates the bitmap for an icon. Use this variant when a mask is not needed. Ownership of the returned object is transferred to the caller. The bitmap is not ready for drawing until it is initialized with SetSize method. Usually, UI controls do this.
If this method leaves, MAknIconFileProvider::Finished is called for the supplied aFileProvider.
3.0
The icon bitmap.
| MAknIconFileProvider & aFileProvider | Icon file handle provider. |
| TInt aBitmapId | bitmap ID |
| IMPORT_C CAknIcon * | CreateIconL | ( | CAknIcon * | aSourceIcon | ) | [static] |
Creates bitmap and mask for an icon. Allocates bitmap and mask objects and sets aResultIcon to point at them.
When this method returns, the resulting bitmaps are duplicates of the source bitmaps. Also the source bitmap instances are preserved in memory.
Ownership of aSourceIcon is transferred from caller. This method takes the responsibility of deleting the object even if the method leaves.
The returned icon bitmaps are instances of CAknBitmap, so AknIconUtils::SetSize is functional for them.
AknIconUtils::SetSize first creates duplicates of the source bitmaps and after that, if required, creates new bitmaps and performs scaling.
Note that due to the additional memory consumption caused by the source bitmaps, this method should only be used if it is not possible to use the variant of CreateIconL that takes icon file name and IDs as parameters.
2.8
Resulting icon. Ownership transferred to the caller.
| CAknIcon * aSourceIcon | Contains source bitmap and mask. Ownership of aSourceIcon is transferred from caller. This method takes the responsibility of deleting the object even if the method leaves. |
| IMPORT_C CFbsBitmap * | CreateIconL | ( | CFbsBitmap * | aSourceBitmap | ) | [static] |
Non-masked variant of CreateIconL.
Ownership of aSourceBitmap is transferred from caller. This method takes the responsibility of deleting the object even if the method leaves.
2.8
Resulting icon bitmap. Ownership transferred to the caller.
| CFbsBitmap * aSourceBitmap | Source bitmap. Ownership is transferred from caller. This method takes the responsibility of deleting the object even if the method leaves. |
| IMPORT_C void | CreateIconLC | ( | CFbsBitmap *& | aBitmap, |
| CFbsBitmap *& | aMask, | |||
| const TDesC & | aFileName, | |||
| TInt | aBitmapId, | |||
| TInt | aMaskId | |||
| ) | [static] | |||
Creates bitmap and mask for an icon. Allocates bitmap and mask objects and sets aBitmap and aMask to point at them. Ownership of those is transferred to the caller. These bitmaps are not ready for drawing until they are initialized with SetSize method. Usually, UI controls do this.
This method puts both aBitmap and aMask in the cleanup stack.
2.8
| CFbsBitmap *& aBitmap | icon bitmap is stored here |
| CFbsBitmap *& aMask | icon mask is stored here |
| const TDesC & aFileName | File name. Can be either MBM or MIF file. Extension is changed based on the given bitmap ID. |
| TInt aBitmapId | bitmap ID |
| TInt aMaskId | mask ID |
| IMPORT_C void | CreateIconLC | ( | CFbsBitmap *& | aBitmap, |
| CFbsBitmap *& | aMask, | |||
| MAknIconFileProvider & | aFileProvider, | |||
| TInt | aBitmapId, | |||
| TInt | aMaskId | |||
| ) | [static] | |||
Creates bitmap and mask for an icon. Allocates bitmap and mask objects and sets aBitmap and aMask to point at them. Ownership of those is transferred to the caller. These bitmaps are not ready for drawing until they are initialized with SetSize method. Usually, UI controls do this.
This method puts both aBitmap and aMask in the cleanup stack.
If this method leaves, MAknIconFileProvider::Finished is called for the supplied aFileProvider.
3.0
| CFbsBitmap *& aBitmap | icon bitmap is stored here |
| CFbsBitmap *& aMask | icon mask is stored here |
| MAknIconFileProvider & aFileProvider | Icon file handle provider. |
| TInt aBitmapId | bitmap Id |
| TInt aMaskId | mask Id |
| void | CreateIconLC | ( | CFbsBitmap *& | aBitmap, |
| CFbsBitmap *& | aMask, | |||
| const TDesC & | aFileName, | |||
| TInt | aBitmapId, | |||
| TInt | aMaskId, | |||
| MAknIconFileProvider * | aFileProvider | |||
| ) | [private, static] | |||
Internal utility.
| CFbsBitmap *& aBitmap | |
| CFbsBitmap *& aMask | |
| const TDesC & aFileName | |
| TInt aBitmapId | |
| TInt aMaskId | |
| MAknIconFileProvider * aFileProvider |
| void | CreateIconLC | ( | CFbsBitmap *& | aBitmap, |
| CFbsBitmap *& | aMask, | |||
| const TDesC & | aFileName, | |||
| TInt | aBitmapId, | |||
| TInt | aMaskId, | |||
| RFile & | aFile | |||
| ) | [private, static] | |||
Internal utility.
| CFbsBitmap *& aBitmap | |
| CFbsBitmap *& aMask | |
| const TDesC & aFileName | |
| TInt aBitmapId | |
| TInt aMaskId | |
| RFile & aFile |
| IMPORT_C void | DestroyIconData | ( | CFbsBitmap * | aBitmap | ) | [static] |
Destroys the icon data related to the given icon, if it was preserved in memory. Note that this does not affect the rendered frame buffers (CFbsBitmap objects).
2.8
| CFbsBitmap * aBitmap | bitmap or mask of the icon. |
| IMPORT_C void | DisableCompression | ( | CFbsBitmap * | aBitmap | ) | [static] |
Disables bitmap compression for the icon. Only effective if the given bitmap is an instance of CAknBitmap. This call prevents AknIcon framework from compressing the CFbsBitmap objects (bitmap, mask) of the icon. This method should be called after calling CreateIconL or CreateIconLC and before calling AknIconUtils::SetSize.
3.1
| CFbsBitmap * aBitmap | bitmap |
| TBool | DoesScaleBitmapUseFallBack | ( | CFbsBitmap * | aSrcBitmap | ) | [static] |
| CFbsBitmap * aSrcBitmap |
| IMPORT_C void | ExcludeFromCache | ( | CFbsBitmap * | aBitmap | ) | [static] |
Excludes the icon form the icon cache. Only effective if the given bitmap is an instance of CAknBitmap. This call sets the sizes of both bitmap and mask (if it exists), regardless of which is given as the parameter. This method should be called after calling CreateIconL or CreateIconLC and before calling AknIconUtils::SetSize.
By default icons are being put to icon cache after they are no longer used. This makes it possible to retrieve recently used icons fast without the need to render them again. The icon cache has a limited size and when the cache is full to cache new icons the oldest icons from the cache will be removed. In certain situations it might be feasible to exclude some icons from the icon cache (e.g. in case of infrequently used large icons) to prevent some more frequently used icon being kicked out from the cache. Excluding infrequently used icons from icon cache could improve performance and memory usage of the system.
3.1
| CFbsBitmap * aBitmap | bitmap |
| IMPORT_C TInt | GetContentDimensions | ( | CFbsBitmap * | aBitmap, |
| TSize & | aContentDimensions | |||
| ) | [static] | |||
Returns the content dimensions of the given icon. In case of MBM icons, this is the original size of the bitmap. In case of SVG icons, this is defined in the icon data.
If SetSize or SetSizeAndRotation is going to be called on the same icon after this call, the performance can be improved by calling PreserveIconData before calling this method.
2.8
Standard Symbian OS error code.
| CFbsBitmap * aBitmap | bitmap |
| TSize & aContentDimensions | The content dimensions are returned here. |
| IMPORT_C TInt | GetContentDimensions | ( | CFbsBitmap * | aBitmap, |
| TAknContentDimensions & | aContentDimensions | |||
| ) | [static] | |||
Returns the content dimensions of the given icon. In case of MBM icons, this is the original size of the bitmap. In case of SVG icons, this is defined in the icon data.
If SetSize or SetSizeAndRotation is going to be called on the same icon after this call, the performance can be improved by calling PreserveIconData before calling this method.
3.0
Standard Symbian OS error code.
| CFbsBitmap * aBitmap | bitmap |
| TAknContentDimensions & aContentDimensions | The content dimensions are returned here. |
| TBool | IsAknBitmap | ( | const CFbsBitmap * | aBitmap | ) | [private, static] |
Utility for down-cast of CFbsBitmap objects. It informs whether the given CFbsBitmap is CAknBitmap or not. A list of CAknBitmap pointers is managed in TLS for this.
| const CFbsBitmap * aBitmap | bitmap ETrue iff the given CFbsBitmap is an CAknBitmap instance. |
| IMPORT_C TBool | IsMifFile | ( | const TDesC & | aFileName | ) | [static] |
Tells whether the given file name is recognized as a MIF file or not. Only the file name extension is examined, not the contents of the file.
2.8
ETrue if MIF file, EFalse otherwise.
| const TDesC & aFileName | file name |
| IMPORT_C TBool | IsMifIcon | ( | const CFbsBitmap * | aBitmap | ) | [static] |
Tells whether the given bitmap is a part of a MIF icon or not. Accepts any pointer (also NULL) as a parameter.
2.8
ETrue if the given bitmap is part of a MIF icon, EFalse otherwise.
| const CFbsBitmap * aBitmap | bitmap |
| IMPORT_C void | PreserveIconData | ( | CFbsBitmap * | aBitmap | ) | [static] |
Preserves the icon data (e.g. SVG-T data) related to the given icon in memory. After this, the icon data is destroyed when either DestroyIconData is explicitly called or the bitmap(s) of the icon are deleted.
This method should be called to improve performance if more than one call to methods SetSize, SetSizeAndRotation or GetContentDimensions is made successively on a particular icon. It should be called prior to the above-mentioned calls. Without calling this method, the icon data is destroyed after any of the method calls mentioned above and then loaded from the storage medium and parsed from scratch again in a new operation.
Note! Icon data may consume considerable amounts of memory. In order to save memory, any code that calls PreserveIconData should also explicitly call DestroyIconData when the icon data is no longer required.
2.8
| CFbsBitmap * aBitmap | bitmap or mask of the icon. |
| void | RotateAndScaleBitmapL | ( | const TRect & | aTrgRect, |
| CFbsBitmap * | aTrgBitmap, | |||
| CFbsBitmap * | aSrcBitmap, | |||
| TInt | aAngle | |||
| ) | [static] | |||
Bitmap rotation and scaling. Might be exported later. Scales and rotates the given bitmap according to the parameters. Supported bitmap modes are EGray2, EGray256, EColor256, EColor4K, EColor64K and EColor16MU. All other bitmap depts will cause a leave with KErrNotSupported. The only supported scalemode is EAspectRatioPreserved. The unused area in the target bitmap is filled with black color unless the bitmap depth is EGray8 when the area is filled with white. Areas that do not fit to the target area after rotation are clipped out
If the bitmap depth is EGray2, the routine will perform noticeably worse.
| const TRect & aTrgRect | target rect inside the target bitmap |
| CFbsBitmap * aTrgBitmap | the target bitmap |
| CFbsBitmap * aSrcBitmap | the source bitmap |
| TInt aAngle | the rotation angle in degrees |
| void | ScaleBitmapExtL | ( | const TRect & | aTrgRect, |
| CFbsBitmap * | aTrgBitmap, | |||
| CFbsBitmap * | aSrcBitmap, | |||
| TBool | aForceFallBack | |||
| ) | [static] | |||
| const TRect & aTrgRect | |
| CFbsBitmap * aTrgBitmap | |
| CFbsBitmap * aSrcBitmap | |
| TBool aForceFallBack |
| IMPORT_C void | ScaleBitmapL | ( | const TRect & | aTrgRect, |
| CFbsBitmap * | aTrgBitmap, | |||
| CFbsBitmap * | aSrcBitmap | |||
| ) | [static] | |||
Performs bitmap scaling. Draws a source bitmap to fit a given rectangle within a target bitmap. This is ~15x faster than scaling with Symbian's DrawBitmap. Following bitmap modes are supported: EGray256, EColor4K, EColor64K, EColor256, EColor16MU. For all other bitmap modes, Symbian's DrawBitmap API will be used. Bitmap modes of the source and target bitmap should be the same. @ since 3.2 @ param aTrgRect target rect inside the target bitmap @ param aTrgBitmap the target bitmap @ param aSrcBitmap the source bitmap leave
KErrArgument If source bitmap mode is not the same as target bitmap mode.
leave
Any other Symbian OS specific error codes.
| const TRect & aTrgRect | |
| CFbsBitmap * aTrgBitmap | |
| CFbsBitmap * aSrcBitmap |
| IMPORT_C void | SetIconColor | ( | CFbsBitmap * | aBitmap, |
| const TRgb | aColor | |||
| ) | [static] | |||
Determines the icon color. Only effective if the given bitmap is an instance of CAknBitmap. This method only needs to be called either for the bitmap or the mask of an icon, but to be effective, it needs to be called before calling SetSize or SetSizeAndRotation.
2.8
| CFbsBitmap * aBitmap | bitmap |
| const TRgb aColor | icon color |
| IMPORT_C void | SetObserver | ( | CFbsBitmap * | aBitmap, |
| MAknIconObserver * | aObserver | |||
| ) | [static] | |||
Sets observer for change notification.
The method BitmapChanged() will be called when the contents of the CFbsBitmap are changed. Controls can use this to redraw themselves when icon animation progresses.
2.8
| CFbsBitmap * aBitmap | bitmap |
| MAknIconObserver * aObserver | observer |
| IMPORT_C TInt | SetSize | ( | CFbsBitmap * | aBitmap, |
| const TSize & | aSize, | |||
| TScaleMode | aMode = EAspectRatioPreserved | |||
| ) | [static] | |||
Initializes the icon to the given size, if the parameter aBitmap is an instance of CAknBitmap, i.e. created with AknIconUtils methods. If it is not CAknBitmap, this method does nothing. Note that this call sets the sizes of both bitmap and mask (if it exists), regardless of which is given as the parameter.
2.8
Standard Symbian OS error code. In error cases, it is guaranteed that the returned bitmap is a valid CFbsBitmap, but there is no guarantee of its size, except that it is non-negative.
| CFbsBitmap * aBitmap | bitmap or mask of the icon |
| const TSize & aSize | icon size |
| TScaleMode aMode = EAspectRatioPreserved | scale mode |
| IMPORT_C TInt | SetSizeAndRotation | ( | CFbsBitmap * | aBitmap, |
| const TSize & | aSize, | |||
| TScaleMode | aMode, | |||
| TInt | aAngle | |||
| ) | [static] | |||
Initializes the icon to the given size, if the parameter aBitmap is an instance of CAknBitmap, i.e. created with AknIconUtils methods. If it is not CAknBitmap, this method does nothing. Note that this call sets the sizes of both bitmap and mask (if it exists), regardless of which is given as the parameter. Additionally, this method rotates the icon according to the given angle.
2.8
Standard Symbian OS error code. In error cases, it is guaranteed that the returned bitmap is a valid CFbsBitmap, but there is no guarantee of its size, except that it is non-negative.
| CFbsBitmap * aBitmap | bitmap or mask of the icon |
| const TSize & aSize | icon size |
| TScaleMode aMode | |
| TInt aAngle | Rotation angle in degrees. |
| IMPORT_C void | ValidateLogicalAppIconId | ( | const TDesC & | aIconFileName, |
| TInt & | aBitmapId, | |||
| TInt & | aMaskId | |||
| ) | [static] | |||
Validates logical app icon ID so that it can be used as a parameter to CreateIconL or CreateIconLC. If the given icon file name is .MBM file, this method does nothing. If it is .MIF file, a predefined offset is added to the given IDs.
This method is only intended to be used when loading icons from the icon file retrieved from AppArc.