--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/epoc32/include/mw/AknsUtils.h Wed Mar 31 12:33:34 2010 +0100
@@ -0,0 +1,1036 @@
+/*
+* 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();
+
+ 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