AknsUtils Class Reference

Public Member Functions

Static Public Member Functions

Queries whether highlight animation should be used for newly created Avkon list controls.

Returns:

ETrue if list highlight animation should be used, EFalse otherwise. The default value is ETrue.

Queries whether default skin parameters should be used for newly created Avkon controls.

Components supporting SetSkinEnabledL method should also check for this value upon construction and set their internal state accordingly.

Note that this flag is intended to be used to determine whether or not controls should create skin backgrounds for main pane layouts. Skins are always enabled for e.g. all the popup windows, even through the flag may be EFalse, and therefore the flag must not be used as a generic "are skins enabled" switch.

Most controls do not (and should not) query the flag value. If control just fetches the skin control context with AknsDrawUtils::ControlContext, it will get the proper NULL value if no background has been defined.

Returns:

ETrue if default skin parameters should be used, EFalse otherwise. The default value is EFalse.

Retrieves the value of the given boolean property skin item.

Parameters:

	aInstance	Pointer to current skin instance. If NULL value is specified, the method leaves.
	aID	Item ID of the boolean property.

Returns:

Value of the boolean property as TBool.

Exceptions:

• If the item is not found, leaves with KErrNotFound.
• If the item is not a boolean property or another error occures, leaves with a system-wide error code.

Constructs an application icon supporting scalable graphics.

This method is fallback-enabled. If no icon is found in the currently active skin, the application icon is retrieved using application resource file or AIF.

After successful completion, the method leaves both the bitmaps in the cleanup stack. The order in which they are pushed into the stack and types of the items in the stack are both undefined.

The caller must set the size of the returned bitmaps. See AknIconUtils for details.

Note:

Since both the bitmaps are left in the cleanup stack, call to this method can not be enclosed in an immediate TRAP.

Parameters:

	aInstance	Pointer to current skin instance.
	aAppUid	Application UID. Icon is searched with major IID EAknsIIDMajorAppIcon and minor IID aAppUid.
	aType	Type of the application icon (list or context). This parameter is tentative. If no icon of the given type is found, the other icon is returned. Only the following values are allowed: EAknsAppIconTypeList and EAknsAppIconTypeContext.
	aBitmap	If method succeeds, set to point to the newly constructed bitmap. Ownership of the bitmap is transferred to the caller.
	aMask	If method succeeds, set to point to the newly constructed mask bitmap. Ownership of the bitmap is transferred to the caller.

Exceptions:

If the method fails, it leaves with a standard error code.

Constructs a new bitmap item definition object.

Parameters:

	aID	Item ID of the item definition object to be created:
	aFile	Filename of the MBM file.
	aIndex	Index of the bitmap in the file.

Returns:

Newly constructed item definition object.

Exceptions:

If construction fails, the method leaves with an error code.

Constructs an independent bitmap.

Creates an independent copy of bitmap (in terms of instance ownership) by given item ID.

Parameters:

	aInstance	Pointer to current skin instance.
	aID	Item ID of the bitmap to be created.

Returns:

Pointer to the newly created bitmap. Ownership of the object is transferred to the caller.

Exceptions:

• If data construction fails or bitmap is not found, function leaves with an error code.

Otherwise identical to CreateColorIconL without size parameters, but calls SetSize to set the size of the resulting icon.

Constructs an independent masked color-customized icon with fallback support without setting its size.

Creates an independent (in terms of instance ownership) copy of a masked bitmap by the given item ID and applies color-based skinning to it.

This method:

• Creates a masked bitmap item from skin, or from the given MBM or MIF file if no matching item is found in the active skin.
• If the icon can be color-skinned, applies the color retrieved from the given color table and index. If no color information is found in the active skin, uses the given fallback color value.
• Returns the resulting bitmaps. If no color skinning was applied, returns the original bitmaps.

The method fails only, if the masked bitmap can not be constructed at all. If the icon can not be color-skinned, it is returned as-is.

Parameters:

	aInstance	Pointer to the current skin instance. Usually retrieved using AknsUtils::SkinInstance.
	aID	Item ID of the masked bitmap to be created.
	aColorID	Item ID of the color table.
	aColorIndex	Index in the color table.
	aBitmap	If method succeeds, set to point to the newly constructed bitmap. Ownership of the bitmap is transferred to the caller.
	aMask	If method succeeds, set to point to the newly constructed mask bitmap. Ownership of the bitmap is transferred to the caller.
	aFilename	Filename to be used to construct the item, if no matching item was found in the currently active skin.
	aFileBitmapId	ID of the bitmap in the file. Used only if no matching item was found in the currently active skin.
	aFileMaskId	ID of the mask in the file. Used only if no matching item was found in the currently active skin.
	aDefaultColor	Color RGB value to be used, if no color is found in the currently active skin.

Exceptions:

If data construction fails or bitmap is not found, the function leaves with an error code.

Otherwise identical to CreateColorIconL, but leaves both the bitmap and the mask in the cleanup stack.

The order in which they are pushed into the stack and types of the items in the stack are both undefined.

Note:

Since two bitmaps are left in the cleanup stack, call to this method can not be enclosed in an immediate TRAP.

Otherwise identical to CreateColorIconL, but leaves both the bitmap and the mask in the cleanup stack.

The order in which they are pushed into the stack and types of the items in the stack are both undefined.

Note:

Since two bitmaps are left in the cleanup stack, call to this method can not be enclosed in an immediate TRAP.

Creates data context suitable for a container.

Constructs a new data context suitable for a container. Container should store the pointer and perform proper destruction when the lifetime of the container itself ends.

Returns:

Newly created data context. Ownership of the context object is transferred to the caller.

Constructs an independent CGulIcon object.

Creates an independent (in terms of instance ownership) copy of a bitmap or a masked bitmap by the given item ID, and returns it as a newly constructed CGulIcon object.

Note:

This method does not have fallback support (to load the bitmap from the specified file in case it is not available in the current skin). Consider using one of the fallback-enabled overloads instead.

Parameters:

	aInstance	Pointer to the current skin instance.
	aID	Item ID of the bitmap or masked bitmap to be created.
	aRequireMask	ETrue if masked bitmap is explicitly required. EFalse if mask is optional.

Returns:

Pointer to the newly created CGulIcon object. Ownership of the object is transferred to the caller.

Exceptions:

If data construction fails or bitmap is not found, the function leaves with an error code.

Constructs an independent CGulIcon object with fallback support.

Creates an independent (in terms of instance ownership) copy of a masked bitmap by the given item ID, and returns it as a newly constructed CGulIcon object.

If no matching item is found in the currently active skin, attempts to construct the item using the given file.

Parameters:

	aInstance	Pointer to the current skin instance.
	aID	Item ID of the masked bitmap to be created.
	aFilename	Filename to be used to construct the item, if no matching item was found in the currently active skin.
	aFileIndex	Index (for bitmap) in the file. Used only if no matching item was found in the currently active skin.
	aFileMaskIndex	Index (for mask) in the file. Used only if no matching item was found in the currently active skin.

Returns:

Pointer to the newly created CGulIcon object. Ownership of the object is transferred to the caller.

Exceptions:

If data construction fails or bitmap is not found, the function leaves with an error code.

Constructs an independent non-masked bitmap with fallback support.

Creates an independent (in terms of instance ownership) copy of a non-masked bitmap by the given item ID.

If no matching item is found in the currently activate skin, attempts to construct the item using the given file.

Parameters:

	aInstance	Pointer to the current skin instance. Usually retrieved using AknsUtils::SkinInstance.
	aID	Item ID of the non-masked bitmap to be created.
	aBitmap	If method succeeds, set to point to the newly constructed bitmap. Ownership of the bitmap is transferred to the caller.
	aFilename	Filename to be used to construct the item, if no matching item was found in the currently active skin.
	aFileBitmapId	ID of the bitmap in the file. Used only if no matching item was found in the currently active skin.

Exceptions:

If data construction fails or bitmap is not found, the function leaves with an error code.

Constructs an independent masked bitmap with fallback support.

Creates an independent (in terms of instance ownership) copy of a masked bitmap by the given item ID.

If no matching item is found in the currently activate skin, attempts to construct the item using the given file.

Parameters:

	aInstance	Pointer to the current skin instance. Usually retrieved using AknsUtils::SkinInstance.
	aID	Item ID of the masked bitmap to be created.
	aBitmap	If method succeeds, set to point to the newly constructed bitmap. Ownership of the bitmap is transferred to the caller.
	aMask	If method succeeds, set to point to the newly constructed mask bitmap. Ownership of the bitmap is transferred to the caller.
	aFilename	Filename to be used to construct the item, if no matching item was found in the currently active skin.
	aFileBitmapId	ID of the bitmap in the file. Used only if no matching item was found in the currently active skin.
	aFileMaskId	ID of the mask in the file. Used only if no matching item was found in the currently active skin.

Exceptions:

If data construction fails or bitmap is not found, the function leaves with an error code.

Otherwise identical to CreateIconL, but leaves the bitmap in the cleanup stack.

The type of the item pushed into the stack is undefined.

Note:

Since the bitmap is left in the cleanup stack, call to this method can not be enclosed in an immediate TRAP.

Otherwise identical to CreateIconL, but leaves both the bitmaps in the cleanup stack.

The order in which they are pushed into the stack and types of the items in the stack are both undefined.

Note:

Since both the bitmaps are left in the cleanup stack, call to this method can not be enclosed in an immediate TRAP.

Constructs a new masked bitmap item definition object.

Parameters:

	aID	Item ID of the item definition object to be created:
	aFile	Filename of the MBM file.
	aIndex	Index of the bitmap in the file.
	aIndex	Index of the bitmap mask in the file.

Returns:

Newly constructed item definition object. Ownership of the object is transferred to the caller.

Exceptions:

If construction fails, the method leaves with an error code.

Constructs an independent masked bitmap.

Creates an independent (in terms of instance ownership) copy of a masked bitmap by the given item ID.

Alternatively, masked bitmaps can be retrieved by using MAknsSkinInstance::GetCachedItemData(TAknsItemID,TAknsItemType) or MAknsSkinInstance::CreateUncachedItemDataL(TAknsItemID,TAknsItemType) methods. For these, EAknsITMaskedBitmap should be given as the second parameter. Returned CAknsItemData pointer can be casted to a CAknsMaskedBitmapItemData pointer in order to get access to the bitmap objects themselves.

Note:

This method does not have fallback support (to load the bitmap from the specified file in case it is not available in the current skin). Consider using one of the fallback-enabled overloads instead.

Parameters:

	aInstance	Pointer to the current skin instance.
	aID	Item ID of the masked bitmap to be created.

Returns:

Pointer to the newly created CApaMaskedBitmap object. Ownership of the object is transferred to the caller.

Exceptions:

If data construction fails or bitmap is not found, the function leaves with an error code.

Note:

Since CApaMaskedBitmap can not be used to store scalable graphics, consider using CreateIconLC instead.

Constructs an independent masked bitmap with fallback support.

Creates an independent (in terms of instance ownership) copy of a masked bitmap by the given item ID.

If no matching item is found in the currently activate skin, attempts to construct the item using the given file.

Parameters:

	aInstance	Pointer to the current skin instance.
	aID	Item ID of the masked bitmap to be created.
	aFilename	Filename to be used to construct the item, if no matching item was found in the currently active skin.
	aFileIndex	Index (for bitmap) in the file. Used only if no matching item was found in the currently active skin.
	aFileMaskIndex	Index (for mask) in the file. Used only if no matching item was found in the currently active skin.

Returns:

Pointer to the newly created CApaMaskedBitmap object. Ownership of the object is transferred to the caller.

Exceptions:

If data construction fails or bitmap is not found, the function leaves with an error code.

Note:

Since CApaMaskedBitmap can not be used to store scalable graphics, consider using CreateIconLC instead.

Returns pointer to current data context.

If aMop parameter is specified, retrieves the nearest data context in control hierarchy. If none is found (or NULL parameter was given) returns root data context from skin instance. If there is no skin instance, NULL value is returned.

Parameters:

aMop

Object provider to be used to find the nearest data context. In most cases this should be a pointer to the calling CCoeControl. NULL value is also valid.

Returns:

Pointer to the nearest data context, or NULL if no skin support is available.

Removes the position of the given control from the list.

The position of the given control is removed from the thread-local control position list. If the control has not been registered, this method does nothing.

Parameters:

aControl

Pointer to the control that needs to be removed from the control position list.

Constructs an application icon.

Icon bitmaps are duplicated to the given CApaMaskedBitmap object.

Since Series 60 Release 2.6, this method is fallback-enabled. If no icon is found in the currently active skin, it uses AppArch to construct the icon.

Parameters:

	aInstance	Pointer to current skin instance.
	aAppUid	Application UID. Icon is searched with major IID EAknsIIDMajorAppIcon and minor IID aAppUid. AppArch search is always performed with UID only.
	aSize	Maximum size of the icon.
	aAppBitmap	On return contains the icon.

Returns:

KErrNone if succeeded, KErrNotFound if no icon was found or size requirements were not met, other error code if another error occured.

Note:

This method does not support scalable graphics. Consider using CreateAppIconLC instead.

Returns pointer to a cached bitmap.

Retrieves (and constructs if necessary) a bitmap in skin instance cache. Caller can use the bitmap temporarily (e.g. in drawing code), but should not store pointer to it, since its lifetime is determined by cache.

Parameters:

	aInstance	Pointer to current skin instance. If NULL value is specified, method immediately returns with NULL return value.
	aID	Item ID of the bitmap to be retrieved.

Returns:

Pointer to the bitmap, or NULL if no bitmap with given ID was found or an error occured.

Exceptions:

• Because the method can not leave, error handling procedure described in MAknsSkinInstance::GetCachedItemData(const TAknsItemID& aID) is used if data construction fails.

Returns a color value from a cached color table.

Retrieves (and constructs if necessary) a color table in skin instance cache and returns a color value from it.

Since release 2.8, this method also handles any backward compatibility operations possibly required.

Parameters:

	aInstance	Pointer to current skin instance. If NULL value is specified, returns KErrNotSupported.
	aRgb	Reference to a TRgb that will receive the color.
	aID	Item ID of the color table.
	aIndex	Index of the color in the color table.

Returns:

KErrNone if successful, otherwise an error code is returned.

Retrieves temporary pointers to a cached bitmap and its mask.

Retrieves (and constructs, if necessary) a masked bitmap in the skin instance cache. Pointers to the bitmap (and its mask) are stored to the pointers given as parameters. Caller can use the bitmaps temporarily (e.g. in drawing code), but should not store them, since their lifetimes are determined by the cache.

Parameters:

	aInstance	Pointer to the current skin instance. If NULL value is specified, the method assigns NULL to both the given pointers and then returns.
	aID	Item ID of the bitmap (or masked bitmap) to be retrieved.
	aBitmap	Reference to the pointer that will receive the bitmap. NULL value is assigned if no bitmap with the given ID was found or an error occured.
	aMask	Reference to the pointer that will receive the mask. NULL value is assigned if no bitmap with the given ID was found, or the bitmap did not have a mask, or an error occured.

Exceptions:

• Because the method can not leave, error handling procedure described in MAknsSkinInstance::GetCachedItemData(const TAknsItemID& aID) is used if data construction fails.

Gets the position of the control registered in the control position list.

Parameters:

	aControl	Pointer to the control whose position is to be queried.
	aScreenPos	Reference to the TPoint that will receive the position.

Returns:

KErrNone if successful, KErrNotFound if the control has not been registered.

Initializes application skin support.

Creates application skin instance. Method should be called once in the construction phase of application, before any other skin-related operations take place.

Notes:

The framework calls this method automatically for each application. Thus, a normal application does not need to call this method explicitly.

Exceptions:

• If allocation fails, function leaves with an error code.

Test whether the given type is derived from the given base type.

Parameters:

	aBaseType	Base type.
	aDerivedType	Derived type.

Returns:

ETrue if the type is derived from the base type, EFalse otherwise.

Opens the file containing application icon data.

This method first checks whether there is a data file of the given type associated with the application icon of the given UID. If no file is found, an error code is returned and the caller should use CreateAppIconLC to construct the icon. Otherwise, one of the associated files is opened using the given RFile object.

Parameters:

	aInstance	Pointer to current skin instance.
	aAppUid	Application UID. Icon is searched with major IID EAknsIIDMajorAppIcon and minor IID aAppUid.
	aType	Only EAknsAppIconType3D is allowed.
	aFile	Reference to a RFile. If KErrNone is returned, this handle refers to an open file containing the data. If an error code is returned, the file is not opened.

Returns:

KErrNone if a file was opened, an error code otherwise.

Registers the position of the given control with given position.

The position is stored in the thread-local control position list. If the control has already been registered, its position is updated.

Registering the position of the control enables background drawing methods in AknsDrawUtils to calculate positions in parent-absolute layouts without causing window server flushes.

When a registered control goes out of scope, it must call AknsUtils::DeregisterControlPosition to ensure that it is properly removed from the list.

Parameters:

	aControl	Pointer to the control that needs its position to be updated in the control position list.
	aPoint	The new position to be registered with the given control (in screen coordinates).

Registers the position of the given control.

The position is stored in the thread-local control position list. If the control has already been registered, its position is updated.

Registering the position of the control enables background drawing methods in AknsDrawUtils to calculate positions in parent-absolute layouts without causing window server flushes.

When a registered control goes out of scope, it must call AknsUtils::DeregisterControlPosition to ensure that it is properly removed from the list.

Parameters:

aControl

Pointer to the control that needs its position to be updated in the control position list.

Sets the flag indicating whether highlight animations should be used for Avkon list controls in the scope of the current AppUi.

Parameters:

Value

of the flag as TBool.

Exceptions:

If construction of the storage object for the flag fails, leaves with an error code.

Sets the flag indicating whether default skin parameters should be used for newly created Avkon controls in the scope of the current AppUi.

Parameters:

Value

of the flag as TBool.

Exceptions:

If construction of the storage object for the flag fails, leaves with an error code.

Returns pointer to current skin instance.

Retrieves pointer to the current application skin instance singleton. If there is none, NULL value is returned.

Returns:

Pointer to current skin instance, or NULL if no skin support is available.