/*
* Copyright (c) 2002-2004 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description: Defines a public static utility class AknsUtils.
*
*/
#ifndef AKNSUTILS_H
#define AKNSUTILS_H
// INCLUDES
#include <AknsSkinInstance.h>
#include <apgicnfl.h>
#include <AknIconUtils.h>
// FORWARD DECLARATIONS
class CFbsBitmap;
class CAknsItemDef;
class CCoeControl;
class CGulIcon;
// TYPE DEFINITIONS
/**
* Type of the application icon.
*
* @since 2.8
*/
enum TAknsAppIconType
{
EAknsAppIconTypeList = 0,
EAknsAppIconTypeContext = 1,
EAknsAppIconType3D = 2
};
// CLASS DECLARATION
/**
* 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.
*
* @lib AknSkins.lib
*
* @since 2.0
*/
class AknsUtils
{
public: // New functions - Creators
/**
* 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.
*
* @since 2.0
*
* @par Notes:
* The framework calls this method automatically for each
* application. Thus, a normal application does not need to
* call this method explicitly.
*
* @par Exceptions:
* - If allocation fails, function leaves with an error code.
*/
IMPORT_C static void InitSkinSupportL();
/**
* 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.
*
* @since 2.0
*
* @return Newly created data context. Ownership of the context object
* is transferred to the caller.
*/
IMPORT_C static MAknsDataContext* CreateDataContextForContainerL();
/**
* Constructs a new bitmap item definition object.
*
* @since 2.0
*
* @param aID Item ID of the item definition object to be created:
*
* @param aFile Filename of the MBM file.
*
* @param aIndex Index of the bitmap in the file.
*
* @return Newly constructed item definition object.
*
* @par Exceptions:
* If construction fails, the method leaves with an error code.
*/
IMPORT_C static CAknsItemDef* CreateBitmapItemDefL(
const TAknsItemID& aID, const TDesC& aFilename,
const TInt aIndex );
/**
* Constructs a new masked bitmap item definition object.
*
* @since 2.0
*
* @param aID Item ID of the item definition object to be created:
*
* @param aFile Filename of the MBM file.
*
* @param aIndex Index of the bitmap in the file.
*
* @param aIndex Index of the bitmap mask in the file.
*
* @return Newly constructed item definition object. Ownership of the
* object is transferred to the caller.
*
* @par Exceptions:
* If construction fails, the method leaves with an error code.
*/
IMPORT_C static CAknsItemDef* CreateMaskedBitmapItemDefL(
const TAknsItemID& aID, const TDesC& aFilename,
const TInt aIndex, const TInt aMaskIndex );
public: // New functions - Skin access
/**
* Returns pointer to current skin instance.
* Retrieves pointer to the current application skin instance singleton.
* If there is none, @c NULL value is returned.
*
* @since 2.0
*
* @return Pointer to current skin instance, or @c NULL if no skin
* support is available.
*/
IMPORT_C static MAknsSkinInstance* SkinInstance();
/**
* Returns pointer to current data context.
* If aMop parameter is specified, retrieves the nearest data context
* in control hierarchy. If none is found (or @c NULL parameter was
* given) returns root data context from skin instance. If there is
* no skin instance, @c NULL value is returned.
*
* @since 2.0
*
* @param aMop Object provider to be used to find the nearest data
* context. In most cases this should be a pointer to the calling
* @c CCoeControl. @c NULL value is also valid.
*
* @return Pointer to the nearest data context, or @c NULL if no
* skin support is available.
*/
IMPORT_C static MAknsDataContext* DataContext( MObjectProvider* aMop );
public: // New functions - Item access w/ fallback support
/**
* 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.
*
* @since 2.6
*
* @lib AknSkins.lib
*
* @param aInstance Pointer to the current skin instance.
* Usually retrieved using @c AknsUtils::SkinInstance.
*
* @param aID Item ID of the masked bitmap to be created.
*
* @param aBitmap If method succeeds, set to point to the
* newly constructed bitmap. Ownership of the bitmap is transferred
* to the caller.
*
* @param aMask If method succeeds, set to point to the newly
* constructed mask bitmap. Ownership of the bitmap is transferred
* to the caller.
*
* @param aFilename Filename to be used to construct the item,
* if no matching item was found in the currently active skin.
*
* @param aFileBitmapId ID of the bitmap in the file.
* Used only if no matching item was found in the currently
* active skin.
*
* @param aFileMaskId ID of the mask in the file.
* Used only if no matching item was found in the currently
* active skin.
*
* @par Exceptions:
* If data construction fails or bitmap is not found, the function
* leaves with an error code.
*/
IMPORT_C static void CreateIconL(
MAknsSkinInstance* aInstance, const TAknsItemID& aID,
CFbsBitmap*& aBitmap, CFbsBitmap*& aMask,
const TDesC& aFilename,
const TInt aFileBitmapId, const TInt aFileMaskId );
/**
* 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.
*
* @copydoc AknsUtils::CreateIconL(MAknsSkinInstance*,TAknsItemID&,CFbsBitmap*&,CFbsBitmap*&,const TDesC&,const TInt,const TInt)
*
* @par Note:
* Since both the bitmaps are left in the cleanup stack,
* call to this method can not be enclosed in an immediate TRAP.
*/
IMPORT_C static void CreateIconLC(
MAknsSkinInstance* aInstance, const TAknsItemID& aID,
CFbsBitmap*& aBitmap, CFbsBitmap*& aMask,
const TDesC& aFilename,
const TInt aFileBitmapId, const TInt aFileMaskId );
/**
* 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.
*
* @since 2.6
*
* @lib AknSkins.lib
*
* @param aInstance Pointer to the current skin instance.
* Usually retrieved using @c AknsUtils::SkinInstance.
*
* @param aID Item ID of the non-masked bitmap to be created.
*
* @param aBitmap If method succeeds, set to point to the
* newly constructed bitmap. Ownership of the bitmap is transferred
* to the caller.
*
* @param aFilename Filename to be used to construct the item,
* if no matching item was found in the currently active skin.
*
* @param aFileBitmapId ID of the bitmap in the file.
* Used only if no matching item was found in the currently
* active skin.
*
* @par Exceptions:
* If data construction fails or bitmap is not found, the function
* leaves with an error code.
*/
IMPORT_C static void CreateIconL(
MAknsSkinInstance* aInstance, const TAknsItemID& aID,
CFbsBitmap*& aBitmap,
const TDesC& aFilename,
const TInt aFileBitmapId );
/**
* Otherwise identical to CreateIconL, but leaves the bitmap
* in the cleanup stack.
* The type of the item pushed into the stack is undefined.
*
* @copydoc AknsUtils::CreateIconL(MAknsSkinInstance*,TAknsItemID&,CFbsBitmap*&,const TDesC&,const TInt)
*
* @par Note:
* Since the bitmap is left in the cleanup stack,
* call to this method can not be enclosed in an immediate TRAP.
*/
IMPORT_C static void CreateIconLC(
MAknsSkinInstance* aInstance, const TAknsItemID& aID,
CFbsBitmap*& aBitmap,
const TDesC& aFilename,
const TInt aFileBitmapId );
/**
* 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.
*
* @since 2.6
*
* @lib AknSkins.lib
*
* @param aInstance Pointer to the current skin instance.
*
* @param aID Item ID of the masked bitmap to be created.
*
* @param aFilename Filename to be used to construct the item,
* if no matching item was found in the currently active skin.
*
* @param aFileIndex Index (for bitmap) in the file.
* Used only if no matching item was found in the currently
* active skin.
*
* @param aFileMaskIndex Index (for mask) in the file.
* Used only if no matching item was found in the currently
* active skin.
*
* @return Pointer to the newly created CApaMaskedBitmap object.
* Ownership of the object is transferred to the caller.
*
* @par Exceptions:
* If data construction fails or bitmap is not found, the function
* leaves with an error code.
*
* @par Note:
* Since @c CApaMaskedBitmap can not be used to store scalable
* graphics, consider using @c CreateIconLC instead.
*/
IMPORT_C static CApaMaskedBitmap* CreateMaskedBitmapL(
MAknsSkinInstance* aInstance, const TAknsItemID& aID,
const TDesC& aFilename,
const TInt aFileIndex, const TInt aFileMaskIndex );
/**
* 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.
*
* @since 2.6
*
* @lib AknSkins.lib
*
* @param aInstance Pointer to the current skin instance.
*
* @param aID Item ID of the masked bitmap to be created.
*
* @param aFilename Filename to be used to construct the item,
* if no matching item was found in the currently active skin.
*
* @param aFileIndex Index (for bitmap) in the file.
* Used only if no matching item was found in the currently
* active skin.
*
* @param aFileMaskIndex Index (for mask) in the file.
* Used only if no matching item was found in the currently
* active skin.
*
* @return Pointer to the newly created CGulIcon object.
* Ownership of the object is transferred to the caller.
*
* @par Exceptions:
* If data construction fails or bitmap is not found, the function
* leaves with an error code.
*/
IMPORT_C static CGulIcon* CreateGulIconL(
MAknsSkinInstance* aInstance, const TAknsItemID& aID,
const TDesC& aFilename,
const TInt aFileIndex, const TInt aFileMaskIndex );
/**
* 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 @c AknIconUtils for details.
*
* @par Note:
* Since both the bitmaps are left in the cleanup stack,
* call to this method can not be enclosed in an immediate TRAP.
*
* @since 2.8
*
* @lib AknSkins.lib
*
* @param aInstance Pointer to current skin instance.
*
* @param aAppUid Application UID. Icon is searched with major IID
* ::EAknsIIDMajorAppIcon and minor IID aAppUid.
*
* @param 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.
*
* @param aBitmap If method succeeds, set to point to the
* newly constructed bitmap. Ownership of the bitmap is transferred
* to the caller.
*
* @param aMask If method succeeds, set to point to the newly
* constructed mask bitmap. Ownership of the bitmap is transferred
* to the caller.
*
* @par Exceptions:
* If the method fails, it leaves with a standard error code.
*/
IMPORT_C static void CreateAppIconLC(
MAknsSkinInstance* aInstance, TUid aAppUid,
TAknsAppIconType aType,
CFbsBitmap*& aBitmap, CFbsBitmap*& aMask );
/**
* 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
* @c CreateAppIconLC to construct the icon. Otherwise, one of the
* associated files is opened using the given @c RFile object.
*
* @since 3.0
*
* @lib AknSkins.lib
*
* @param aInstance Pointer to current skin instance.
*
* @param aAppUid Application UID. Icon is searched with major IID
* ::EAknsIIDMajorAppIcon and minor IID aAppUid.
*
* @param aType Only EAknsAppIconType3D is allowed.
*
* @param aFile Reference to a @c RFile. If @c KErrNone is returned,
* this handle refers to an open file containing the data.
* If an error code is returned, the file is not opened.
*
* @return @c KErrNone if a file was opened, an error code otherwise.
*/
IMPORT_C TInt OpenAppIconFile(
MAknsSkinInstance* aInstance, TUid aAppUid,
TAknsAppIconType aType, RFile& aFile );
/**
* 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.
*
* @since 2.6
*
* @lib AknSkins.lib
*
* @param aInstance Pointer to the current skin instance.
* Usually retrieved using @c AknsUtils::SkinInstance.
*
* @param aID Item ID of the masked bitmap to be created.
*
* @param aColorID Item ID of the color table.
*
* @param aColorIndex Index in the color table.
*
* @param aBitmap If method succeeds, set to point to the
* newly constructed bitmap. Ownership of the bitmap is transferred
* to the caller.
*
* @param aMask If method succeeds, set to point to the newly
* constructed mask bitmap. Ownership of the bitmap is transferred
* to the caller.
*
* @param aFilename Filename to be used to construct the item,
* if no matching item was found in the currently active skin.
*
* @param aFileBitmapId ID of the bitmap in the file.
* Used only if no matching item was found in the currently
* active skin.
*
* @param aFileMaskId ID of the mask in the file.
* Used only if no matching item was found in the currently
* active skin.
*
* @param aDefaultColor Color RGB value to be used, if no color
* is found in the currently active skin.
*
* @par Exceptions:
* If data construction fails or bitmap is not found, the function
* leaves with an error code.
*/
IMPORT_C static 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 );
/**
* Otherwise identical to @c 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.
*
* @since 2.6
*
* @lib AknSkins.lib
*
* @par Note:
* Since two bitmaps are left in the cleanup stack,
* call to this method can not be enclosed in an immediate TRAP.
*/
IMPORT_C static 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 );
/**
* Otherwise identical to @c CreateColorIconL without size parameters,
* but calls @c SetSize to set the size of the resulting icon.
*
* @since 2.8
*
* @lib AknSkins.lib
*/
IMPORT_C static 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 );
/**
* Otherwise identical to @c 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.
*
* @since 2.8
*
* @lib AknSkins.lib
*
* @par Note:
* Since two bitmaps are left in the cleanup stack,
* call to this method can not be enclosed in an immediate TRAP.
*/
IMPORT_C static 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 );
public: // New functions - Item access w/o support for scalable graphics
/**
* 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.
*
* @since 2.0
*
* @param aInstance Pointer to current skin instance.
*
* @param aAppUid Application UID. Icon is searched with major IID
* ::EAknsIIDMajorAppIcon and minor IID aAppUid. AppArch search
* is always performed with UID only.
*
* @param aSize Maximum size of the icon.
*
* @param aAppBitmap On return contains the icon.
*
* @return KErrNone if succeeded, KErrNotFound if no icon was found
* or size requirements were not met, other error code if
* another error occured.
*
* @par Note:
* This method does not support scalable graphics.
* Consider using @c CreateAppIconLC instead.
*/
IMPORT_C static TInt GetAppIcon(
MAknsSkinInstance* aInstance, TUid aAppUid, TSize aSize,
CApaMaskedBitmap& aAppBitmap );
public: // New functions - Item access w/ ownership
/**
* Constructs an independent bitmap.
* Creates an independent copy of bitmap (in terms of instance ownership)
* by given item ID.
*
* @since 2.0
*
* @param aInstance Pointer to current skin instance.
*
* @param aID Item ID of the bitmap to be created.
*
* @return Pointer to the newly created bitmap. Ownership of the object
* is transferred to the caller.
*
* @par Exceptions:
* - If data construction fails or bitmap is not found, function
* leaves with an error code.
*/
IMPORT_C static CFbsBitmap* CreateBitmapL(
MAknsSkinInstance* aInstance, const TAknsItemID& aID );
/**
* 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
* @c MAknsSkinInstance::GetCachedItemData(TAknsItemID,TAknsItemType)
* or
* @c MAknsSkinInstance::CreateUncachedItemDataL(TAknsItemID,TAknsItemType)
* methods. For these, @c ::EAknsITMaskedBitmap should be given as the
* second parameter. Returned @c CAknsItemData pointer can be casted
* to a @c CAknsMaskedBitmapItemData pointer in order to get access
* to the bitmap objects themselves.
*
* @par 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.
*
* @since 2.0
*
* @param aInstance Pointer to the current skin instance.
*
* @param aID Item ID of the masked bitmap to be created.
*
* @return Pointer to the newly created CApaMaskedBitmap object.
* Ownership of the object is transferred to the caller.
*
* @par Exceptions:
* If data construction fails or bitmap is not found, the function
* leaves with an error code.
*
* @par Note:
* Since @c CApaMaskedBitmap can not be used to store scalable
* graphics, consider using @c CreateIconLC instead.
*/
IMPORT_C static CApaMaskedBitmap* CreateMaskedBitmapL(
MAknsSkinInstance* aInstance, const TAknsItemID& aID );
/**
* 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.
*
* @par 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.
*
* @since 2.1
*
* @lib AknSkins.lib
*
* @param aInstance Pointer to the current skin instance.
*
* @param aID Item ID of the bitmap or masked bitmap to be created.
*
* @param aRequireMask ETrue if masked bitmap is explicitly required.
* EFalse if mask is optional.
*
* @return Pointer to the newly created CGulIcon object.
* Ownership of the object is transferred to the caller.
*
* @par Exceptions:
* If data construction fails or bitmap is not found, the function
* leaves with an error code.
*/
IMPORT_C static CGulIcon* CreateGulIconL(
MAknsSkinInstance* aInstance, const TAknsItemID& aID,
const TBool aRequireMask );
public: // New functions - Item access w/o ownership
/**
* 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.
*
* @since 2.0
*
* @param aInstance Pointer to current skin instance. If @c NULL value
* is specified, method immediately returns with @c NULL return value.
*
* @param aID Item ID of the bitmap to be retrieved.
*
* @return Pointer to the bitmap, or @c NULL if no bitmap with given ID
* was found or an error occured.
*
* @par Exceptions:
* - Because the method can not leave, error handling procedure
* described in
* MAknsSkinInstance::GetCachedItemData(const TAknsItemID& aID) is
* used if data construction fails.
*/
IMPORT_C static CFbsBitmap* GetCachedBitmap(
MAknsSkinInstance* aInstance, const TAknsItemID& aID );
/**
* 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.
*
* @since 2.1
*
* @param aInstance Pointer to the current skin instance. If @c NULL
* value is specified, the method assigns @c NULL to both the given
* pointers and then returns.
*
* @param aID Item ID of the bitmap (or masked bitmap) to be retrieved.
*
* @param aBitmap Reference to the pointer that will receive the bitmap.
* @c NULL value is assigned if no bitmap with the given ID was found
* or an error occured.
*
* @param aMask Reference to the pointer that will receive the mask.
* @c 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.
*
* @par Exceptions:
* - Because the method can not leave, error handling procedure
* described in
* MAknsSkinInstance::GetCachedItemData(const TAknsItemID& aID) is
* used if data construction fails.
*/
IMPORT_C static void GetCachedMaskedBitmap(
MAknsSkinInstance* aInstance, const TAknsItemID& aID,
CFbsBitmap*& aBitmap, CFbsBitmap*& aMask );
/**
* 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.
*
* @since 2.0
*
* @param aInstance Pointer to current skin instance. If @c NULL value
* is specified, returns KErrNotSupported.
*
* @param aRgb Reference to a TRgb that will receive the color.
*
* @param aID Item ID of the color table.
*
* @param aIndex Index of the color in the color table.
*
* @return KErrNone if successful, otherwise an error code is returned.
*/
IMPORT_C static TInt GetCachedColor(
MAknsSkinInstance* aInstance, TRgb& aRgb, const TAknsItemID& aID,
const TInt aIndex );
/**
* Retrieves the value of the given boolean property skin item.
*
* @since 2.8
*
* @param aInstance Pointer to current skin instance. If @c NULL value
* is specified, the method leaves.
*
* @param aID Item ID of the boolean property.
*
* @return Value of the boolean property as @c TBool.
*
* @par Exceptions:
* - If the item is not found, leaves with @c KErrNotFound.
* - If the item is not a boolean property or another error occures,
* leaves with a system-wide error code.
*/
IMPORT_C static TBool BooleanPropertyL( MAknsSkinInstance* aInstance,
const TAknsItemID& aID );
/**
* Test whether the given type is derived from the given base type.
*
* @since 2.0
*
* @param aBaseType Base type.
*
* @param aDerivedType Derived type.
*
* @return ETrue if the type is derived from the base type, EFalse
* otherwise.
*
* @internal
*/
static TBool IsDerivedType( const TAknsItemType aBaseType,
const TAknsItemType aDerivedType );
public: // New functions - Avkon parameters
/**
* Sets the flag indicating whether default skin parameters should
* be used for newly created Avkon controls in the scope of the
* current AppUi.
*
* @since 2.0
*
* @param Value of the flag as TBool.
*
* @par Exceptions:
* If construction of the storage object for the flag fails,
* leaves with an error code.
*/
IMPORT_C static void SetAvkonSkinEnabledL( const TBool aEnabled );
/**
* Queries whether default skin parameters should be used for newly
* created Avkon controls. Components supporting
* <code>SetSkinEnabledL</code> 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 @c 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
* @c AknsDrawUtils::ControlContext, it will get the proper @c NULL
* value if no background has been defined.
*
* @since 2.0
*
* @return ETrue if default skin parameters should be used,
* EFalse otherwise. The default value is EFalse.
*/
IMPORT_C static TBool AvkonSkinEnabled();
/**
* Sets the flag indicating whether highlight animations should be used
* for Avkon list controls in the scope of the current AppUi.
*
* @since 3.0
*
* @param Value of the flag as TBool.
*
* @par Exceptions:
* If construction of the storage object for the flag fails,
* leaves with an error code.
*/
IMPORT_C static void SetAvkonHighlightAnimationEnabledL( const TBool aEnabled );
/**
* Queries whether highlight animation should be used for newly created
* Avkon list controls.
*
* @since 3.0
*
* @return ETrue if list highlight animation should be used, EFalse
* otherwise. The default value is ETrue.
*/
IMPORT_C static TBool AvkonHighlightAnimationEnabled();
/**
* Sets the flag indicating whether animation background should be used
* in the scope of the current AppUi.
*
* @since 5.2
*
* @param Value of the flag as TBool.
*/
IMPORT_C static void SetAnimationBackgroundDisabledL( TBool aDisabled );
/**
* Queries whether animation background should be used for newly created
* current AppUi.
*
* @since 5.2
*
* @return ETrue if animation background is disabled, EFalse
* otherwise. The default value is EFalse.
*/
IMPORT_C static TBool AnimationBackgroundDisabled();
public: // New functions - Control position list
/**
* 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.
*
* @since 2.0
*
* @param aControl Pointer to the control that needs its position
* to be updated in the control position list.
*/
IMPORT_C static void RegisterControlPosition(
const CCoeControl* aControl );
/**
* 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.
*
* @since 2.0
*
* @param aControl Pointer to the control that needs its position
* to be updated in the control position list.
*
* @param aPoint The new position to be registered with the given
* control (in screen coordinates).
*/
IMPORT_C static void RegisterControlPosition(
const CCoeControl* aControl, const TPoint& aPoint );
/**
* 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.
*
* @since 2.0
*
* @param aControl Pointer to the control that needs to be removed
* from the control position list.
*/
IMPORT_C static void DeregisterControlPosition(
const CCoeControl* aControl );
/**
* Gets the position of the control registered in the control position
* list.
*
* @param aControl Pointer to the control whose position is to be
* queried.
*
* @param aScreenPos Reference to the TPoint that will receive the
* position.
*
* @return KErrNone if successful, KErrNotFound if the control has
* not been registered.
*/
IMPORT_C static TInt GetControlPosition( const CCoeControl* aControl,
TPoint& aScreenPos );
private: // Internal methods
/**
* Gets an application icon from skin.
*
* @since 2.8
*
* @internal
*/
static TInt GetAppIconFromSkin(
MAknsSkinInstance* aInstance, TUid aAppUid, TSize aSize,
CFbsBitmap*& aBitmap, CFbsBitmap*& aMask );
/**
* Returns the best application icon bitmap IID among the listed icons.
*
* @since 2.1
*
* @param aSize Maximum size.
*
* @param aSkin Skin instance.
*
* @param aAppIconIID Item ID of the application icon.
*
* @return Icon bitmap IID.
*
* @internal
*/
static TAknsItemID SelectBestAppIconBitmapL(
const TSize& aSize, MAknsSkinInstance* aSkin,
const TAknsItemID& aAppIconIID );
private: // Reserved exports
/**
* Reserved for future use.
*
* @since 2.0
*
* @return Always returns zero.
*/
IMPORT_C static TInt Reserved();
private: // Prohibited constructors and destructor
// Construction prohibited (static class)
AknsUtils();
// Destruction prohibited (static class)
~AknsUtils();
};
#endif // AKNSUTILS_H
// End of File