#include <mw/AknsUtils.h>
Link against: AknSkins.lib
| class AknsUtils |
Static utility class to support AVKON SKINS common operations. AknsUtils provides utility method to initialize application skin support, retrieve current skin instance or data context, retrieve skin data items and to perform other skin-related tasks.
This is a public static class with exported functions. The class is not intended for derivation outside the library.
| IMPORT_C TBool | AnimationBackgroundDisabled | ( | ) | [static] |
Queries whether animation background should be used for newly created current AppUi.
| IMPORT_C TBool | AvkonHighlightAnimationEnabled | ( | ) | [static] |
Queries whether highlight animation should be used for newly created Avkon list controls.
| IMPORT_C TBool | AvkonSkinEnabled | ( | ) | [static] |
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.
| IMPORT_C TBool | BooleanPropertyL | ( | MAknsSkinInstance * | aInstance, |
| const TAknsItemID & | aID | |||
| ) | [static] | |||
Retrieves the value of the given boolean property skin item.
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.
| Parameters | |
|---|---|
| aInstance | Pointer to current skin instance. If NULL value is specified, the method leaves. |
| aID | Item ID of the boolean property. |
| IMPORT_C void | CreateAppIconLC | ( | MAknsSkinInstance * | aInstance, |
| TUid | aAppUid, | |||
| TAknsAppIconType | aType, | |||
| CFbsBitmap *& | aBitmap, | |||
| CFbsBitmap *& | aMask | |||
| ) | [static] | |||
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.
| 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. |
| IMPORT_C CAknsItemDef * | CreateBitmapItemDefL | ( | const TAknsItemID & | aID, |
| const TDesC & | aFilename, | |||
| const TInt | aIndex | |||
| ) | [static] | |||
Constructs a new bitmap item definition object.
| Parameters | |
|---|---|
| aID | Item ID of the item definition object to be created: |
| aIndex | Index of the bitmap in the file. |
| IMPORT_C CFbsBitmap * | CreateBitmapL | ( | MAknsSkinInstance * | aInstance, |
| const TAknsItemID & | aID | |||
| ) | [static] | |||
Constructs an independent bitmap. Creates an independent copy of bitmap (in terms of instance ownership) by given item ID.
If data construction fails or bitmap is not found, function leaves with an error code.
| Parameters | |
|---|---|
| aInstance | Pointer to current skin instance. |
| aID | Item ID of the bitmap to be created. |
| IMPORT_C void | CreateColorIconL | ( | MAknsSkinInstance * | aInstance, |
| const TAknsItemID & | aID, | |||
| const TAknsItemID & | aColorID, | |||
| const TInt | aColorIndex, | |||
| CFbsBitmap *& | aBitmap, | |||
| CFbsBitmap *& | aMask, | |||
| const TDesC & | aFilename, | |||
| const TInt | aFileBitmapId, | |||
| const TInt | aFileMaskId, | |||
| const TRgb | aDefaultColor | |||
| ) | [static] | |||
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.
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. |
| IMPORT_C void | CreateColorIconL | ( | MAknsSkinInstance * | aInstance, |
| const TAknsItemID & | aID, | |||
| const TAknsItemID & | aColorID, | |||
| const TInt | aColorIndex, | |||
| CFbsBitmap *& | aBitmap, | |||
| CFbsBitmap *& | aMask, | |||
| const TDesC & | aFilename, | |||
| const TInt | aFileBitmapId, | |||
| const TInt | aFileMaskId, | |||
| const TRgb | aDefaultColor, | |||
| const TSize & | aSize, | |||
| const TScaleMode | aScaleMode | |||
| ) | [static] | |||
Otherwise identical to CreateColorIconL without size parameters, but calls SetSize to set the size of the resulting icon.
| IMPORT_C void | CreateColorIconLC | ( | MAknsSkinInstance * | aInstance, |
| const TAknsItemID & | aID, | |||
| const TAknsItemID & | aColorID, | |||
| const TInt | aColorIndex, | |||
| CFbsBitmap *& | aBitmap, | |||
| CFbsBitmap *& | aMask, | |||
| const TDesC & | aFilename, | |||
| const TInt | aFileBitmapId, | |||
| const TInt | aFileMaskId, | |||
| const TRgb | aDefaultColor | |||
| ) | [static] | |||
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.
| IMPORT_C void | CreateColorIconLC | ( | MAknsSkinInstance * | aInstance, |
| const TAknsItemID & | aID, | |||
| const TAknsItemID & | aColorID, | |||
| const TInt | aColorIndex, | |||
| CFbsBitmap *& | aBitmap, | |||
| CFbsBitmap *& | aMask, | |||
| const TDesC & | aFilename, | |||
| const TInt | aFileBitmapId, | |||
| const TInt | aFileMaskId, | |||
| const TRgb | aDefaultColor, | |||
| const TSize & | aSize, | |||
| const TScaleMode | aScaleMode | |||
| ) | [static] | |||
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.
| IMPORT_C MAknsDataContext * | CreateDataContextForContainerL | ( | ) | [static] |
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.
| IMPORT_C CGulIcon * | CreateGulIconL | ( | MAknsSkinInstance * | aInstance, |
| const TAknsItemID & | aID, | |||
| const TDesC & | aFilename, | |||
| const TInt | aFileIndex, | |||
| const TInt | aFileMaskIndex | |||
| ) | [static] | |||
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. |
| IMPORT_C CGulIcon * | CreateGulIconL | ( | MAknsSkinInstance * | aInstance, |
| const TAknsItemID & | aID, | |||
| const TBool | aRequireMask | |||
| ) | [static] | |||
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.
| 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. |
| IMPORT_C void | CreateIconL | ( | MAknsSkinInstance * | aInstance, |
| const TAknsItemID & | aID, | |||
| CFbsBitmap *& | aBitmap, | |||
| CFbsBitmap *& | aMask, | |||
| const TDesC & | aFilename, | |||
| const TInt | aFileBitmapId, | |||
| const TInt | aFileMaskId | |||
| ) | [static] | |||
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. |
| IMPORT_C void | CreateIconL | ( | MAknsSkinInstance * | aInstance, |
| const TAknsItemID & | aID, | |||
| CFbsBitmap *& | aBitmap, | |||
| const TDesC & | aFilename, | |||
| const TInt | aFileBitmapId | |||
| ) | [static] | |||
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. |
| IMPORT_C void | CreateIconLC | ( | MAknsSkinInstance * | aInstance, |
| const TAknsItemID & | aID, | |||
| CFbsBitmap *& | aBitmap, | |||
| CFbsBitmap *& | aMask, | |||
| const TDesC & | aFilename, | |||
| const TInt | aFileBitmapId, | |||
| const TInt | aFileMaskId | |||
| ) | [static] | |||
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.
| IMPORT_C void | CreateIconLC | ( | MAknsSkinInstance * | aInstance, |
| const TAknsItemID & | aID, | |||
| CFbsBitmap *& | aBitmap, | |||
| const TDesC & | aFilename, | |||
| const TInt | aFileBitmapId | |||
| ) | [static] | |||
Otherwise identical to CreateIconL, but leaves the bitmap in the cleanup stack. The type of the item pushed into the stack is undefined.
| IMPORT_C CAknsItemDef * | CreateMaskedBitmapItemDefL | ( | const TAknsItemID & | aID, |
| const TDesC & | aFilename, | |||
| const TInt | aIndex, | |||
| const TInt | aMaskIndex | |||
| ) | [static] | |||
Constructs a new masked bitmap item definition object.
| Parameters | |
|---|---|
| aID | Item ID of the item definition object to be created: |
| aIndex | Index of the bitmap mask in the file. |
| IMPORT_C CApaMaskedBitmap * | CreateMaskedBitmapL | ( | MAknsSkinInstance * | aInstance, |
| const TAknsItemID & | aID, | |||
| const TDesC & | aFilename, | |||
| const TInt | aFileIndex, | |||
| const TInt | aFileMaskIndex | |||
| ) | [static] | |||
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. |
| IMPORT_C CApaMaskedBitmap * | CreateMaskedBitmapL | ( | MAknsSkinInstance * | aInstance, |
| const TAknsItemID & | aID | |||
| ) | [static] | |||
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.
| Parameters | |
|---|---|
| aInstance | Pointer to the current skin instance. |
| aID | Item ID of the masked bitmap to be created. |
| IMPORT_C MAknsDataContext * | DataContext | ( | MObjectProvider * | aMop | ) | [static] |
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. |
| IMPORT_C void | DeregisterControlPosition | ( | const CCoeControl * | aControl | ) | [static] |
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. |
| IMPORT_C TInt | GetAppIcon | ( | MAknsSkinInstance * | aInstance, |
| TUid | aAppUid, | |||
| TSize | aSize, | |||
| CApaMaskedBitmap & | aAppBitmap | |||
| ) | [static] | |||
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. |
| IMPORT_C CFbsBitmap * | GetCachedBitmap | ( | MAknsSkinInstance * | aInstance, |
| const TAknsItemID & | aID | |||
| ) | [static] | |||
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.
Because the method can not leave, error handling procedure described in MAknsSkinInstance::GetCachedItemData(const TAknsItemID& aID) is used if data construction fails.
| 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. |
| IMPORT_C TInt | GetCachedColor | ( | MAknsSkinInstance * | aInstance, |
| TRgb & | aRgb, | |||
| const TAknsItemID & | aID, | |||
| const TInt | aIndex | |||
| ) | [static] | |||
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. |
| IMPORT_C void | GetCachedMaskedBitmap | ( | MAknsSkinInstance * | aInstance, |
| const TAknsItemID & | aID, | |||
| CFbsBitmap *& | aBitmap, | |||
| CFbsBitmap *& | aMask | |||
| ) | [static] | |||
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.
Because the method can not leave, error handling procedure described in MAknsSkinInstance::GetCachedItemData(const TAknsItemID& aID) is used if data construction fails.
| 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. |
| IMPORT_C TInt | GetControlPosition | ( | const CCoeControl * | aControl, |
| TPoint & | aScreenPos | |||
| ) | [static] | |||
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. |
| IMPORT_C void | InitSkinSupportL | ( | ) | [static] |
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.
If allocation fails, function leaves with an error code.
| TBool | IsDerivedType | ( | const TAknsItemType | aBaseType, |
| const TAknsItemType | aDerivedType | |||
| ) | [static] | |||
Test whether the given type is derived from the given base type.
| Parameters | |
|---|---|
| aBaseType | Base type. |
| aDerivedType | Derived type. |
| IMPORT_C TInt | OpenAppIconFile | ( | MAknsSkinInstance * | aInstance, |
| TUid | aAppUid, | |||
| TAknsAppIconType | aType, | |||
| RFile & | aFile | |||
| ) | ||||
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. |
| IMPORT_C void | RegisterControlPosition | ( | const CCoeControl * | aControl | ) | [static] |
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. |
| IMPORT_C void | RegisterControlPosition | ( | const CCoeControl * | aControl, |
| const TPoint & | aPoint | |||
| ) | [static] | |||
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). |
| IMPORT_C void | SetAnimationBackgroundDisabledL | ( | TBool | aDisabled | ) | [static] |
Sets the flag indicating whether animation background should be used in the scope of the current AppUi.
| IMPORT_C void | SetAvkonHighlightAnimationEnabledL | ( | const TBool | aEnabled | ) | [static] |
Sets the flag indicating whether highlight animations should be used for Avkon list controls in the scope of the current AppUi.
| IMPORT_C void | SetAvkonSkinEnabledL | ( | const TBool | aEnabled | ) | [static] |
Sets the flag indicating whether default skin parameters should be used for newly created Avkon controls in the scope of the current AppUi.
| IMPORT_C MAknsSkinInstance * | SkinInstance | ( | ) | [static] |
Returns pointer to current skin instance. Retrieves pointer to the current application skin instance singleton. If there is none, NULL value is returned.