AknIconUtils Class Reference

class AknIconUtils

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().

Public Member Functions
IMPORT_C const TDesC &AvkonIconFileName()
IMPORT_C voidCreateIconL(CFbsBitmap *&, CFbsBitmap *&, const TDesC &, TInt, TInt)
IMPORT_C CFbsBitmap *CreateIconL(const TDesC &, TInt)
IMPORT_C voidCreateIconL(CFbsBitmap *&, CFbsBitmap *&, MAknIconFileProvider &, TInt, TInt)
IMPORT_C CFbsBitmap *CreateIconL(MAknIconFileProvider &, TInt)
IMPORT_C CAknIcon *CreateIconL(CAknIcon *)
IMPORT_C CFbsBitmap *CreateIconL(CFbsBitmap *)
IMPORT_C voidCreateIconLC(CFbsBitmap *&, CFbsBitmap *&, const TDesC &, TInt, TInt)
IMPORT_C voidCreateIconLC(CFbsBitmap *&, CFbsBitmap *&, MAknIconFileProvider &, TInt, TInt)
IMPORT_C voidDestroyIconData(CFbsBitmap *)
IMPORT_C voidDisableCompression(CFbsBitmap *)
TBool DoesScaleBitmapUseFallBack(CFbsBitmap *)
IMPORT_C voidExcludeFromCache(CFbsBitmap *)
IMPORT_C TIntGetContentDimensions(CFbsBitmap *, TSize &)
IMPORT_C TIntGetContentDimensions(CFbsBitmap *, TAknContentDimensions &)
IMPORT_C TBoolIsMifFile(const TDesC &)
IMPORT_C TBoolIsMifIcon(const CFbsBitmap *)
IMPORT_C voidPreserveIconData(CFbsBitmap *)
voidRotateAndScaleBitmapL(const TRect &, CFbsBitmap *, CFbsBitmap *, TInt)
voidScaleBitmapExtL(const TRect &, CFbsBitmap *, CFbsBitmap *, TBool)
IMPORT_C voidScaleBitmapL(const TRect &, CFbsBitmap *, CFbsBitmap *)
IMPORT_C voidSetIconColor(CFbsBitmap *, const TRgb)
IMPORT_C voidSetObserver(CFbsBitmap *, MAknIconObserver *)
IMPORT_C TIntSetSize(CFbsBitmap *, const TSize &, TScaleMode)
IMPORT_C TIntSetSizeAndRotation(CFbsBitmap *, const TSize &, TScaleMode, TInt)
IMPORT_C voidValidateLogicalAppIconId(const TDesC &, TInt &, TInt &)
Private Member Functions
AknIconUtils()
voidCreateIconLC(CFbsBitmap *&, CFbsBitmap *&, const TDesC &, TInt, TInt, MAknIconFileProvider *)
voidCreateIconLC(CFbsBitmap *&, CFbsBitmap *&, const TDesC &, TInt, TInt, RFile &)
TBool IsAknBitmap(const CFbsBitmap *)

Constructor & Destructor Documentation

AknIconUtils()

AknIconUtils()[private]

Member Functions Documentation

AvkonIconFileName()

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.

CreateIconL(CFbsBitmap *&, CFbsBitmap *&, const TDesC &, TInt, TInt)

IMPORT_C voidCreateIconL(CFbsBitmap *&aBitmap,
CFbsBitmap *&aMask,
const TDesC &aFileName,
TIntaBitmapId,
TIntaMaskId
)[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

Parameters

CFbsBitmap *& aBitmapicon bitmap is stored here
CFbsBitmap *& aMaskicon mask is stored here
const TDesC & aFileNameFile name. Can be either MBM or MIF file. Extension is changed based on the given bitmap ID.
TInt aBitmapIdbitmap Id
TInt aMaskIdmask Id

CreateIconL(const TDesC &, TInt)

IMPORT_C CFbsBitmap *CreateIconL(const TDesC &aFileName,
TIntaBitmapId
)[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

Parameters

const TDesC & aFileNameFile name. Can be either MBM or MIF file. Extension is changed based on the given bitmap ID.
TInt aBitmapIdbitmap ID

CreateIconL(CFbsBitmap *&, CFbsBitmap *&, MAknIconFileProvider &, TInt, TInt)

IMPORT_C voidCreateIconL(CFbsBitmap *&aBitmap,
CFbsBitmap *&aMask,
MAknIconFileProvider &aFileProvider,
TIntaBitmapId,
TIntaMaskId
)[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

Parameters

CFbsBitmap *& aBitmapicon bitmap is stored here
CFbsBitmap *& aMaskicon mask is stored here
MAknIconFileProvider & aFileProviderIcon file handle provider.
TInt aBitmapIdbitmap Id
TInt aMaskIdmask Id

CreateIconL(MAknIconFileProvider &, TInt)

IMPORT_C CFbsBitmap *CreateIconL(MAknIconFileProvider &aFileProvider,
TIntaBitmapId
)[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.

Parameters

MAknIconFileProvider & aFileProviderIcon file handle provider.
TInt aBitmapIdbitmap ID

CreateIconL(CAknIcon *)

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.

Parameters

CAknIcon * aSourceIconContains 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.

CreateIconL(CFbsBitmap *)

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.

Parameters

CFbsBitmap * aSourceBitmapSource bitmap. Ownership is transferred from caller. This method takes the responsibility of deleting the object even if the method leaves.

CreateIconLC(CFbsBitmap *&, CFbsBitmap *&, const TDesC &, TInt, TInt)

IMPORT_C voidCreateIconLC(CFbsBitmap *&aBitmap,
CFbsBitmap *&aMask,
const TDesC &aFileName,
TIntaBitmapId,
TIntaMaskId
)[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

Parameters

CFbsBitmap *& aBitmapicon bitmap is stored here
CFbsBitmap *& aMaskicon mask is stored here
const TDesC & aFileNameFile name. Can be either MBM or MIF file. Extension is changed based on the given bitmap ID.
TInt aBitmapIdbitmap ID
TInt aMaskIdmask ID

CreateIconLC(CFbsBitmap *&, CFbsBitmap *&, MAknIconFileProvider &, TInt, TInt)

IMPORT_C voidCreateIconLC(CFbsBitmap *&aBitmap,
CFbsBitmap *&aMask,
MAknIconFileProvider &aFileProvider,
TIntaBitmapId,
TIntaMaskId
)[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

Parameters

CFbsBitmap *& aBitmapicon bitmap is stored here
CFbsBitmap *& aMaskicon mask is stored here
MAknIconFileProvider & aFileProviderIcon file handle provider.
TInt aBitmapIdbitmap Id
TInt aMaskIdmask Id

CreateIconLC(CFbsBitmap *&, CFbsBitmap *&, const TDesC &, TInt, TInt, MAknIconFileProvider *)

voidCreateIconLC(CFbsBitmap *&aBitmap,
CFbsBitmap *&aMask,
const TDesC &aFileName,
TIntaBitmapId,
TIntaMaskId,
MAknIconFileProvider *aFileProvider
)[private, static]

Internal utility.

Parameters

CFbsBitmap *& aBitmap
CFbsBitmap *& aMask
const TDesC & aFileName
TInt aBitmapId
TInt aMaskId
MAknIconFileProvider * aFileProvider

CreateIconLC(CFbsBitmap *&, CFbsBitmap *&, const TDesC &, TInt, TInt, RFile &)

voidCreateIconLC(CFbsBitmap *&aBitmap,
CFbsBitmap *&aMask,
const TDesC &aFileName,
TIntaBitmapId,
TIntaMaskId,
RFile &aFile
)[private, static]

Internal utility.

Parameters

CFbsBitmap *& aBitmap
CFbsBitmap *& aMask
const TDesC & aFileName
TInt aBitmapId
TInt aMaskId
RFile & aFile

DestroyIconData(CFbsBitmap *)

IMPORT_C voidDestroyIconData(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

Parameters

CFbsBitmap * aBitmapbitmap or mask of the icon.

DisableCompression(CFbsBitmap *)

IMPORT_C voidDisableCompression(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

Parameters

CFbsBitmap * aBitmapbitmap

DoesScaleBitmapUseFallBack(CFbsBitmap *)

TBool DoesScaleBitmapUseFallBack(CFbsBitmap *aSrcBitmap)[static]

Parameters

CFbsBitmap * aSrcBitmap

ExcludeFromCache(CFbsBitmap *)

IMPORT_C voidExcludeFromCache(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

Parameters

CFbsBitmap * aBitmapbitmap

GetContentDimensions(CFbsBitmap *, TSize &)

IMPORT_C TIntGetContentDimensions(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.

Parameters

CFbsBitmap * aBitmapbitmap
TSize & aContentDimensionsThe content dimensions are returned here.

GetContentDimensions(CFbsBitmap *, TAknContentDimensions &)

IMPORT_C TIntGetContentDimensions(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.

Parameters

CFbsBitmap * aBitmapbitmap
TAknContentDimensions & aContentDimensionsThe content dimensions are returned here.

IsAknBitmap(const CFbsBitmap *)

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.

Parameters

const CFbsBitmap * aBitmapbitmap ETrue iff the given CFbsBitmap is an CAknBitmap instance.

IsMifFile(const TDesC &)

IMPORT_C TBoolIsMifFile(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.

Parameters

const TDesC & aFileNamefile name

IsMifIcon(const CFbsBitmap *)

IMPORT_C TBoolIsMifIcon(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.

Parameters

const CFbsBitmap * aBitmapbitmap

PreserveIconData(CFbsBitmap *)

IMPORT_C voidPreserveIconData(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

Parameters

CFbsBitmap * aBitmapbitmap or mask of the icon.

RotateAndScaleBitmapL(const TRect &, CFbsBitmap *, CFbsBitmap *, TInt)

voidRotateAndScaleBitmapL(const TRect &aTrgRect,
CFbsBitmap *aTrgBitmap,
CFbsBitmap *aSrcBitmap,
TIntaAngle
)[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

const TRect & aTrgRecttarget rect inside the target bitmap
CFbsBitmap * aTrgBitmapthe target bitmap
CFbsBitmap * aSrcBitmapthe source bitmap
TInt aAnglethe rotation angle in degrees

ScaleBitmapExtL(const TRect &, CFbsBitmap *, CFbsBitmap *, TBool)

voidScaleBitmapExtL(const TRect &aTrgRect,
CFbsBitmap *aTrgBitmap,
CFbsBitmap *aSrcBitmap,
TBoolaForceFallBack
)[static]

Parameters

const TRect & aTrgRect
CFbsBitmap * aTrgBitmap
CFbsBitmap * aSrcBitmap
TBool aForceFallBack

ScaleBitmapL(const TRect &, CFbsBitmap *, CFbsBitmap *)

IMPORT_C voidScaleBitmapL(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.

Parameters

const TRect & aTrgRect
CFbsBitmap * aTrgBitmap
CFbsBitmap * aSrcBitmap

SetIconColor(CFbsBitmap *, const TRgb)

IMPORT_C voidSetIconColor(CFbsBitmap *aBitmap,
const TRgbaColor
)[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

Parameters

CFbsBitmap * aBitmapbitmap
const TRgb aColoricon color

SetObserver(CFbsBitmap *, MAknIconObserver *)

IMPORT_C voidSetObserver(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

Parameters

CFbsBitmap * aBitmapbitmap
MAknIconObserver * aObserverobserver

SetSize(CFbsBitmap *, const TSize &, TScaleMode)

IMPORT_C TIntSetSize(CFbsBitmap *aBitmap,
const TSize &aSize,
TScaleModeaMode = 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.

Parameters

CFbsBitmap * aBitmapbitmap or mask of the icon
const TSize & aSizeicon size
TScaleMode aMode = EAspectRatioPreservedscale mode

SetSizeAndRotation(CFbsBitmap *, const TSize &, TScaleMode, TInt)

IMPORT_C TIntSetSizeAndRotation(CFbsBitmap *aBitmap,
const TSize &aSize,
TScaleModeaMode,
TIntaAngle
)[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.

Parameters

CFbsBitmap * aBitmapbitmap or mask of the icon
const TSize & aSizeicon size
TScaleMode aMode
TInt aAngleRotation angle in degrees.

ValidateLogicalAppIconId(const TDesC &, TInt &, TInt &)

IMPORT_C voidValidateLogicalAppIconId(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

const TDesC & aIconFileNameIcon file name retrieved from AppArc.
TInt & aBitmapId
TInt & aMaskId