#include <mw/AknIconUtils.h>
| 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().
| IMPORT_C const TDesC & | AvkonIconFileName | ( | ) | [static] |
Returns the file name of Avkon's icon file, 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.
| Parameters | |
|---|---|
| aBitmap | icon bitmap is stored here |
| aMask | icon mask is stored here |
| aFileName | File name. Can be either MBM or MIF file. Extension is changed based on the given bitmap ID. |
| aBitmapId | bitmap Id |
| 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.
| Parameters | |
|---|---|
| aFileName | File name. Can be either MBM or MIF file. Extension is changed based on the given bitmap ID. |
| aBitmapId | bitmap ID |
| 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.
| Parameters | |
|---|---|
| aBitmap | icon bitmap is stored here |
| aMask | icon mask is stored here |
| aFileProvider | Icon file handle provider. |
| aBitmapId | bitmap Id |
| 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.
| Parameters | |
|---|---|
| aFileProvider | Icon file handle provider. |
| 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.
| Parameters | |
|---|---|
| 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.
| Parameters | |
|---|---|
| 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.
| Parameters | |
|---|---|
| aBitmap | icon bitmap is stored here |
| aMask | icon mask is stored here |
| aFileName | File name. Can be either MBM or MIF file. Extension is changed based on the given bitmap ID. |
| aBitmapId | bitmap ID |
| 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.
| Parameters | |
|---|---|
| aBitmap | icon bitmap is stored here |
| aMask | icon mask is stored here |
| aFileProvider | Icon file handle provider. |
| aBitmapId | bitmap Id |
| aMaskId | mask Id |
| 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).
| Parameters | |
|---|---|
| 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.
| Parameters | |
|---|---|
| aBitmap | bitmap |
| TBool | DoesScaleBitmapUseFallBack | ( | CFbsBitmap * | aSrcBitmap | ) | [static] |
| 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.
| Parameters | |
|---|---|
| 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.
| Parameters | |
|---|---|
| aBitmap | bitmap |
| 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.
| Parameters | |
|---|---|
| aBitmap | bitmap |
| aContentDimensions | The content dimensions are returned here. |
| 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.
| Parameters | |
|---|---|
| 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.
| Parameters | |
|---|---|
| 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.
| Parameters | |
|---|---|
| aTrgRect | target rect inside the target bitmap |
| aTrgBitmap | the target bitmap |
| aSrcBitmap | the source bitmap |
| aAngle | the rotation angle in degrees |
| void | ScaleBitmapExtL | ( | const TRect & | aTrgRect, |
| CFbsBitmap * | aTrgBitmap, | |||
| CFbsBitmap * | aSrcBitmap, | |||
| TBool | aForceFallBack | |||
| ) | [static] | |||
| IMPORT_C void | ScaleBitmapL | ( | const TRect & | aTrgRect, |
| CFbsBitmap * | aTrgBitmap, | |||
| CFbsBitmap * | aSrcBitmap | |||
| ) | [static] | |||
| Leave Codes | |
|---|---|
| KErrArgument | If source bitmap mode is not the same as target bitmap mode. |
| Any | other Symbian OS specific error codes. |
| 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.
| Parameters | |
|---|---|
| aBitmap | bitmap |
| 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.
| Parameters | |
|---|---|
| aBitmap | bitmap |
| 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.
| Parameters | |
|---|---|
| aBitmap | bitmap or mask of the icon |
| aSize | icon size |
| aMode | 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.
| Parameters | |
|---|---|
| aBitmap | bitmap or mask of the icon |
| aSize | icon size |
| 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.
| Parameters | |
|---|---|
| aIconFileName | Icon file name retrieved from AppArc. |