AknIconUtils Class Reference

Static Public Member Functions

Returns the file name of Avkon's icon file, containing full path.

Avkon's icon file name, containing full path.

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.

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.

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

Returns:

The icon bitmap.

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

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:

	aBitmap	icon bitmap 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

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

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

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

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.

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

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

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.

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.

Deprecated:

Parameters:

	aBitmap	bitmap
	aContentDimensions	The content dimensions are returned here.

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.

Parameters:

aFileName

file name

Returns:

ETrue if MIF file, EFalse otherwise.

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

Returns:

ETrue if the given bitmap is part of a MIF icon, EFalse otherwise.

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.

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

Bitmap scaling.

Might be exported later. This is ~15x faster than scaling with Symbian's DrawBitmap.

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

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

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

Returns:

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.

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.

Returns:

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.

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.
	aId	Logical bitmap ID used in the app icon file, usually 0.
	aId	Logical mask ID used in the app icon file, usually 1.