williamr@4: /* williamr@4: * Copyright (c) 2002-2004 Nokia Corporation and/or its subsidiary(-ies). williamr@4: * All rights reserved. williamr@4: * This component and the accompanying materials are made available williamr@4: * under the terms of "Eclipse Public License v1.0" williamr@4: * which accompanies this distribution, and is available williamr@4: * at the URL "http://www.eclipse.org/legal/epl-v10.html". williamr@4: * williamr@4: * Initial Contributors: williamr@4: * Nokia Corporation - initial contribution. williamr@4: * williamr@4: * Contributors: williamr@4: * williamr@4: * Description: Defines a public static utility class AknsUtils. williamr@4: * williamr@4: */ williamr@4: williamr@4: williamr@4: #ifndef AKNSUTILS_H williamr@4: #define AKNSUTILS_H williamr@4: williamr@4: // INCLUDES williamr@4: #include williamr@4: #include williamr@4: #include williamr@4: williamr@4: // FORWARD DECLARATIONS williamr@4: class CFbsBitmap; williamr@4: class CAknsItemDef; williamr@4: class CCoeControl; williamr@4: class CGulIcon; williamr@4: williamr@4: // TYPE DEFINITIONS williamr@4: williamr@4: /** williamr@4: * Type of the application icon. williamr@4: * williamr@4: * @since 2.8 williamr@4: */ williamr@4: enum TAknsAppIconType williamr@4: { williamr@4: EAknsAppIconTypeList = 0, williamr@4: EAknsAppIconTypeContext = 1, williamr@4: EAknsAppIconType3D = 2 williamr@4: }; williamr@4: williamr@4: // CLASS DECLARATION williamr@4: williamr@4: /** williamr@4: * Static utility class to support AVKON SKINS common operations. williamr@4: * AknsUtils provides utility method to initialize application skin support, williamr@4: * retrieve current skin instance or data context, retrieve skin data williamr@4: * items and to perform other skin-related tasks. williamr@4: * williamr@4: * This is a public static class with exported functions. williamr@4: * The class is not intended for derivation outside the library. williamr@4: * williamr@4: * @lib AknSkins.lib williamr@4: * williamr@4: * @since 2.0 williamr@4: */ williamr@4: class AknsUtils williamr@4: { williamr@4: williamr@4: public: // New functions - Creators williamr@4: williamr@4: /** williamr@4: * Initializes application skin support. williamr@4: * Creates application skin instance. Method should be called once williamr@4: * in the construction phase of application, before any other williamr@4: * skin-related operations take place. williamr@4: * williamr@4: * @since 2.0 williamr@4: * williamr@4: * @par Notes: williamr@4: * The framework calls this method automatically for each williamr@4: * application. Thus, a normal application does not need to williamr@4: * call this method explicitly. williamr@4: * williamr@4: * @par Exceptions: williamr@4: * - If allocation fails, function leaves with an error code. williamr@4: */ williamr@4: IMPORT_C static void InitSkinSupportL(); williamr@4: williamr@4: /** williamr@4: * Creates data context suitable for a container. williamr@4: * Constructs a new data context suitable for a container. Container williamr@4: * should store the pointer and perform proper destruction when williamr@4: * the lifetime of the container itself ends. williamr@4: * williamr@4: * @since 2.0 williamr@4: * williamr@4: * @return Newly created data context. Ownership of the context object williamr@4: * is transferred to the caller. williamr@4: */ williamr@4: IMPORT_C static MAknsDataContext* CreateDataContextForContainerL(); williamr@4: williamr@4: /** williamr@4: * Constructs a new bitmap item definition object. williamr@4: * williamr@4: * @since 2.0 williamr@4: * williamr@4: * @param aID Item ID of the item definition object to be created: williamr@4: * williamr@4: * @param aFile Filename of the MBM file. williamr@4: * williamr@4: * @param aIndex Index of the bitmap in the file. williamr@4: * williamr@4: * @return Newly constructed item definition object. williamr@4: * williamr@4: * @par Exceptions: williamr@4: * If construction fails, the method leaves with an error code. williamr@4: */ williamr@4: IMPORT_C static CAknsItemDef* CreateBitmapItemDefL( williamr@4: const TAknsItemID& aID, const TDesC& aFilename, williamr@4: const TInt aIndex ); williamr@4: williamr@4: /** williamr@4: * Constructs a new masked bitmap item definition object. williamr@4: * williamr@4: * @since 2.0 williamr@4: * williamr@4: * @param aID Item ID of the item definition object to be created: williamr@4: * williamr@4: * @param aFile Filename of the MBM file. williamr@4: * williamr@4: * @param aIndex Index of the bitmap in the file. williamr@4: * williamr@4: * @param aIndex Index of the bitmap mask in the file. williamr@4: * williamr@4: * @return Newly constructed item definition object. Ownership of the williamr@4: * object is transferred to the caller. williamr@4: * williamr@4: * @par Exceptions: williamr@4: * If construction fails, the method leaves with an error code. williamr@4: */ williamr@4: IMPORT_C static CAknsItemDef* CreateMaskedBitmapItemDefL( williamr@4: const TAknsItemID& aID, const TDesC& aFilename, williamr@4: const TInt aIndex, const TInt aMaskIndex ); williamr@4: williamr@4: public: // New functions - Skin access williamr@4: williamr@4: /** williamr@4: * Returns pointer to current skin instance. williamr@4: * Retrieves pointer to the current application skin instance singleton. williamr@4: * If there is none, @c NULL value is returned. williamr@4: * williamr@4: * @since 2.0 williamr@4: * williamr@4: * @return Pointer to current skin instance, or @c NULL if no skin williamr@4: * support is available. williamr@4: */ williamr@4: IMPORT_C static MAknsSkinInstance* SkinInstance(); williamr@4: williamr@4: /** williamr@4: * Returns pointer to current data context. williamr@4: * If aMop parameter is specified, retrieves the nearest data context williamr@4: * in control hierarchy. If none is found (or @c NULL parameter was williamr@4: * given) returns root data context from skin instance. If there is williamr@4: * no skin instance, @c NULL value is returned. williamr@4: * williamr@4: * @since 2.0 williamr@4: * williamr@4: * @param aMop Object provider to be used to find the nearest data williamr@4: * context. In most cases this should be a pointer to the calling williamr@4: * @c CCoeControl. @c NULL value is also valid. williamr@4: * williamr@4: * @return Pointer to the nearest data context, or @c NULL if no williamr@4: * skin support is available. williamr@4: */ williamr@4: IMPORT_C static MAknsDataContext* DataContext( MObjectProvider* aMop ); williamr@4: williamr@4: public: // New functions - Item access w/ fallback support williamr@4: williamr@4: /** williamr@4: * Constructs an independent masked bitmap with fallback support. williamr@4: * Creates an independent (in terms of instance ownership) copy of a williamr@4: * masked bitmap by the given item ID. williamr@4: * williamr@4: * If no matching item is found in the currently activate skin, williamr@4: * attempts to construct the item using the given file. williamr@4: * williamr@4: * @since 2.6 williamr@4: * williamr@4: * @lib AknSkins.lib williamr@4: * williamr@4: * @param aInstance Pointer to the current skin instance. williamr@4: * Usually retrieved using @c AknsUtils::SkinInstance. williamr@4: * williamr@4: * @param aID Item ID of the masked bitmap to be created. williamr@4: * williamr@4: * @param aBitmap If method succeeds, set to point to the williamr@4: * newly constructed bitmap. Ownership of the bitmap is transferred williamr@4: * to the caller. williamr@4: * williamr@4: * @param aMask If method succeeds, set to point to the newly williamr@4: * constructed mask bitmap. Ownership of the bitmap is transferred williamr@4: * to the caller. williamr@4: * williamr@4: * @param aFilename Filename to be used to construct the item, williamr@4: * if no matching item was found in the currently active skin. williamr@4: * williamr@4: * @param aFileBitmapId ID of the bitmap in the file. williamr@4: * Used only if no matching item was found in the currently williamr@4: * active skin. williamr@4: * williamr@4: * @param aFileMaskId ID of the mask in the file. williamr@4: * Used only if no matching item was found in the currently williamr@4: * active skin. williamr@4: * williamr@4: * @par Exceptions: williamr@4: * If data construction fails or bitmap is not found, the function williamr@4: * leaves with an error code. williamr@4: */ williamr@4: IMPORT_C static void CreateIconL( williamr@4: MAknsSkinInstance* aInstance, const TAknsItemID& aID, williamr@4: CFbsBitmap*& aBitmap, CFbsBitmap*& aMask, williamr@4: const TDesC& aFilename, williamr@4: const TInt aFileBitmapId, const TInt aFileMaskId ); williamr@4: williamr@4: /** williamr@4: * Otherwise identical to CreateIconL, but leaves both the bitmaps williamr@4: * in the cleanup stack. williamr@4: * The order in which they are pushed into the stack and types of williamr@4: * the items in the stack are both undefined. williamr@4: * williamr@4: * @copydoc AknsUtils::CreateIconL(MAknsSkinInstance*,TAknsItemID&,CFbsBitmap*&,CFbsBitmap*&,const TDesC&,const TInt,const TInt) williamr@4: * williamr@4: * @par Note: williamr@4: * Since both the bitmaps are left in the cleanup stack, williamr@4: * call to this method can not be enclosed in an immediate TRAP. williamr@4: */ williamr@4: IMPORT_C static void CreateIconLC( williamr@4: MAknsSkinInstance* aInstance, const TAknsItemID& aID, williamr@4: CFbsBitmap*& aBitmap, CFbsBitmap*& aMask, williamr@4: const TDesC& aFilename, williamr@4: const TInt aFileBitmapId, const TInt aFileMaskId ); williamr@4: williamr@4: /** williamr@4: * Constructs an independent non-masked bitmap with fallback support. williamr@4: * Creates an independent (in terms of instance ownership) copy of a williamr@4: * non-masked bitmap by the given item ID. williamr@4: * williamr@4: * If no matching item is found in the currently activate skin, williamr@4: * attempts to construct the item using the given file. williamr@4: * williamr@4: * @since 2.6 williamr@4: * williamr@4: * @lib AknSkins.lib williamr@4: * williamr@4: * @param aInstance Pointer to the current skin instance. williamr@4: * Usually retrieved using @c AknsUtils::SkinInstance. williamr@4: * williamr@4: * @param aID Item ID of the non-masked bitmap to be created. williamr@4: * williamr@4: * @param aBitmap If method succeeds, set to point to the williamr@4: * newly constructed bitmap. Ownership of the bitmap is transferred williamr@4: * to the caller. williamr@4: * williamr@4: * @param aFilename Filename to be used to construct the item, williamr@4: * if no matching item was found in the currently active skin. williamr@4: * williamr@4: * @param aFileBitmapId ID of the bitmap in the file. williamr@4: * Used only if no matching item was found in the currently williamr@4: * active skin. williamr@4: * williamr@4: * @par Exceptions: williamr@4: * If data construction fails or bitmap is not found, the function williamr@4: * leaves with an error code. williamr@4: */ williamr@4: IMPORT_C static void CreateIconL( williamr@4: MAknsSkinInstance* aInstance, const TAknsItemID& aID, williamr@4: CFbsBitmap*& aBitmap, williamr@4: const TDesC& aFilename, williamr@4: const TInt aFileBitmapId ); williamr@4: williamr@4: /** williamr@4: * Otherwise identical to CreateIconL, but leaves the bitmap williamr@4: * in the cleanup stack. williamr@4: * The type of the item pushed into the stack is undefined. williamr@4: * williamr@4: * @copydoc AknsUtils::CreateIconL(MAknsSkinInstance*,TAknsItemID&,CFbsBitmap*&,const TDesC&,const TInt) williamr@4: * williamr@4: * @par Note: williamr@4: * Since the bitmap is left in the cleanup stack, williamr@4: * call to this method can not be enclosed in an immediate TRAP. williamr@4: */ williamr@4: IMPORT_C static void CreateIconLC( williamr@4: MAknsSkinInstance* aInstance, const TAknsItemID& aID, williamr@4: CFbsBitmap*& aBitmap, williamr@4: const TDesC& aFilename, williamr@4: const TInt aFileBitmapId ); williamr@4: williamr@4: /** williamr@4: * Constructs an independent masked bitmap with fallback support. williamr@4: * Creates an independent (in terms of instance ownership) copy of a williamr@4: * masked bitmap by the given item ID. williamr@4: * williamr@4: * If no matching item is found in the currently activate skin, williamr@4: * attempts to construct the item using the given file. williamr@4: * williamr@4: * @since 2.6 williamr@4: * williamr@4: * @lib AknSkins.lib williamr@4: * williamr@4: * @param aInstance Pointer to the current skin instance. williamr@4: * williamr@4: * @param aID Item ID of the masked bitmap to be created. williamr@4: * williamr@4: * @param aFilename Filename to be used to construct the item, williamr@4: * if no matching item was found in the currently active skin. williamr@4: * williamr@4: * @param aFileIndex Index (for bitmap) in the file. williamr@4: * Used only if no matching item was found in the currently williamr@4: * active skin. williamr@4: * williamr@4: * @param aFileMaskIndex Index (for mask) in the file. williamr@4: * Used only if no matching item was found in the currently williamr@4: * active skin. williamr@4: * williamr@4: * @return Pointer to the newly created CApaMaskedBitmap object. williamr@4: * Ownership of the object is transferred to the caller. williamr@4: * williamr@4: * @par Exceptions: williamr@4: * If data construction fails or bitmap is not found, the function williamr@4: * leaves with an error code. williamr@4: * williamr@4: * @par Note: williamr@4: * Since @c CApaMaskedBitmap can not be used to store scalable williamr@4: * graphics, consider using @c CreateIconLC instead. williamr@4: */ williamr@4: IMPORT_C static CApaMaskedBitmap* CreateMaskedBitmapL( williamr@4: MAknsSkinInstance* aInstance, const TAknsItemID& aID, williamr@4: const TDesC& aFilename, williamr@4: const TInt aFileIndex, const TInt aFileMaskIndex ); williamr@4: williamr@4: /** williamr@4: * Constructs an independent CGulIcon object with fallback support. williamr@4: * Creates an independent (in terms of instance ownership) copy of a williamr@4: * masked bitmap by the given item ID, and returns it as a williamr@4: * newly constructed CGulIcon object. williamr@4: * williamr@4: * If no matching item is found in the currently active skin, williamr@4: * attempts to construct the item using the given file. williamr@4: * williamr@4: * @since 2.6 williamr@4: * williamr@4: * @lib AknSkins.lib williamr@4: * williamr@4: * @param aInstance Pointer to the current skin instance. williamr@4: * williamr@4: * @param aID Item ID of the masked bitmap to be created. williamr@4: * williamr@4: * @param aFilename Filename to be used to construct the item, williamr@4: * if no matching item was found in the currently active skin. williamr@4: * williamr@4: * @param aFileIndex Index (for bitmap) in the file. williamr@4: * Used only if no matching item was found in the currently williamr@4: * active skin. williamr@4: * williamr@4: * @param aFileMaskIndex Index (for mask) in the file. williamr@4: * Used only if no matching item was found in the currently williamr@4: * active skin. williamr@4: * williamr@4: * @return Pointer to the newly created CGulIcon object. williamr@4: * Ownership of the object is transferred to the caller. williamr@4: * williamr@4: * @par Exceptions: williamr@4: * If data construction fails or bitmap is not found, the function williamr@4: * leaves with an error code. williamr@4: */ williamr@4: IMPORT_C static CGulIcon* CreateGulIconL( williamr@4: MAknsSkinInstance* aInstance, const TAknsItemID& aID, williamr@4: const TDesC& aFilename, williamr@4: const TInt aFileIndex, const TInt aFileMaskIndex ); williamr@4: williamr@4: /** williamr@4: * Constructs an application icon supporting scalable graphics. williamr@4: * williamr@4: * This method is fallback-enabled. If no icon is found in the williamr@4: * currently active skin, the application icon is retrieved using williamr@4: * application resource file or AIF. williamr@4: * williamr@4: * After successful completion, the method leaves both the bitmaps williamr@4: * in the cleanup stack. williamr@4: * The order in which they are pushed into the stack and types of williamr@4: * the items in the stack are both undefined. williamr@4: * williamr@4: * The caller must set the size of the returned bitmaps. williamr@4: * See @c AknIconUtils for details. williamr@4: * williamr@4: * @par Note: williamr@4: * Since both the bitmaps are left in the cleanup stack, williamr@4: * call to this method can not be enclosed in an immediate TRAP. williamr@4: * williamr@4: * @since 2.8 williamr@4: * williamr@4: * @lib AknSkins.lib williamr@4: * williamr@4: * @param aInstance Pointer to current skin instance. williamr@4: * williamr@4: * @param aAppUid Application UID. Icon is searched with major IID williamr@4: * ::EAknsIIDMajorAppIcon and minor IID aAppUid. williamr@4: * williamr@4: * @param aType Type of the application icon (list or context). williamr@4: * This parameter is tentative. If no icon of the given type williamr@4: * is found, the other icon is returned. Only the following values williamr@4: * are allowed: EAknsAppIconTypeList and EAknsAppIconTypeContext. williamr@4: * williamr@4: * @param aBitmap If method succeeds, set to point to the williamr@4: * newly constructed bitmap. Ownership of the bitmap is transferred williamr@4: * to the caller. williamr@4: * williamr@4: * @param aMask If method succeeds, set to point to the newly williamr@4: * constructed mask bitmap. Ownership of the bitmap is transferred williamr@4: * to the caller. williamr@4: * williamr@4: * @par Exceptions: williamr@4: * If the method fails, it leaves with a standard error code. williamr@4: */ williamr@4: IMPORT_C static void CreateAppIconLC( williamr@4: MAknsSkinInstance* aInstance, TUid aAppUid, williamr@4: TAknsAppIconType aType, williamr@4: CFbsBitmap*& aBitmap, CFbsBitmap*& aMask ); williamr@4: williamr@4: /** williamr@4: * Opens the file containing application icon data. williamr@4: * williamr@4: * This method first checks whether there is a data file of the given williamr@4: * type associated with the application icon of the given UID. If no williamr@4: * file is found, an error code is returned and the caller should use williamr@4: * @c CreateAppIconLC to construct the icon. Otherwise, one of the williamr@4: * associated files is opened using the given @c RFile object. williamr@4: * williamr@4: * @since 3.0 williamr@4: * williamr@4: * @lib AknSkins.lib williamr@4: * williamr@4: * @param aInstance Pointer to current skin instance. williamr@4: * williamr@4: * @param aAppUid Application UID. Icon is searched with major IID williamr@4: * ::EAknsIIDMajorAppIcon and minor IID aAppUid. williamr@4: * williamr@4: * @param aType Only EAknsAppIconType3D is allowed. williamr@4: * williamr@4: * @param aFile Reference to a @c RFile. If @c KErrNone is returned, williamr@4: * this handle refers to an open file containing the data. williamr@4: * If an error code is returned, the file is not opened. williamr@4: * williamr@4: * @return @c KErrNone if a file was opened, an error code otherwise. williamr@4: */ williamr@4: IMPORT_C TInt OpenAppIconFile( williamr@4: MAknsSkinInstance* aInstance, TUid aAppUid, williamr@4: TAknsAppIconType aType, RFile& aFile ); williamr@4: williamr@4: /** williamr@4: * Constructs an independent masked color-customized icon with williamr@4: * fallback support without setting its size. williamr@4: * williamr@4: * Creates an independent (in terms of instance ownership) copy of a williamr@4: * masked bitmap by the given item ID and applies color-based williamr@4: * skinning to it. williamr@4: * williamr@4: * This method: williamr@4: * - Creates a masked bitmap item from skin, or from the given williamr@4: * MBM or MIF file if no matching item is found in the active skin. williamr@4: * - If the icon can be color-skinned, applies the color retrieved williamr@4: * from the given color table and index. If no color information williamr@4: * is found in the active skin, uses the given fallback color value. williamr@4: * - Returns the resulting bitmaps. If no color skinning was applied, williamr@4: * returns the original bitmaps. williamr@4: * williamr@4: * The method fails only, if the masked bitmap can not be constructed williamr@4: * at all. If the icon can not be color-skinned, it is returned as-is. williamr@4: * williamr@4: * @since 2.6 williamr@4: * williamr@4: * @lib AknSkins.lib williamr@4: * williamr@4: * @param aInstance Pointer to the current skin instance. williamr@4: * Usually retrieved using @c AknsUtils::SkinInstance. williamr@4: * williamr@4: * @param aID Item ID of the masked bitmap to be created. williamr@4: * williamr@4: * @param aColorID Item ID of the color table. williamr@4: * williamr@4: * @param aColorIndex Index in the color table. williamr@4: * williamr@4: * @param aBitmap If method succeeds, set to point to the williamr@4: * newly constructed bitmap. Ownership of the bitmap is transferred williamr@4: * to the caller. williamr@4: * williamr@4: * @param aMask If method succeeds, set to point to the newly williamr@4: * constructed mask bitmap. Ownership of the bitmap is transferred williamr@4: * to the caller. williamr@4: * williamr@4: * @param aFilename Filename to be used to construct the item, williamr@4: * if no matching item was found in the currently active skin. williamr@4: * williamr@4: * @param aFileBitmapId ID of the bitmap in the file. williamr@4: * Used only if no matching item was found in the currently williamr@4: * active skin. williamr@4: * williamr@4: * @param aFileMaskId ID of the mask in the file. williamr@4: * Used only if no matching item was found in the currently williamr@4: * active skin. williamr@4: * williamr@4: * @param aDefaultColor Color RGB value to be used, if no color williamr@4: * is found in the currently active skin. williamr@4: * williamr@4: * @par Exceptions: williamr@4: * If data construction fails or bitmap is not found, the function williamr@4: * leaves with an error code. williamr@4: */ williamr@4: IMPORT_C static void CreateColorIconL( williamr@4: MAknsSkinInstance* aInstance, const TAknsItemID& aID, williamr@4: const TAknsItemID& aColorID, const TInt aColorIndex, williamr@4: CFbsBitmap*& aBitmap, CFbsBitmap*& aMask, williamr@4: const TDesC& aFilename, williamr@4: const TInt aFileBitmapId, const TInt aFileMaskId, williamr@4: const TRgb aDefaultColor ); williamr@4: williamr@4: /** williamr@4: * Otherwise identical to @c CreateColorIconL, but leaves both the williamr@4: * bitmap and the mask in the cleanup stack. williamr@4: * The order in which they are pushed into the stack and types of williamr@4: * the items in the stack are both undefined. williamr@4: * williamr@4: * @since 2.6 williamr@4: * williamr@4: * @lib AknSkins.lib williamr@4: * williamr@4: * @par Note: williamr@4: * Since two bitmaps are left in the cleanup stack, williamr@4: * call to this method can not be enclosed in an immediate TRAP. williamr@4: */ williamr@4: IMPORT_C static void CreateColorIconLC( williamr@4: MAknsSkinInstance* aInstance, const TAknsItemID& aID, williamr@4: const TAknsItemID& aColorID, const TInt aColorIndex, williamr@4: CFbsBitmap*& aBitmap, CFbsBitmap*& aMask, williamr@4: const TDesC& aFilename, williamr@4: const TInt aFileBitmapId, const TInt aFileMaskId, williamr@4: const TRgb aDefaultColor ); williamr@4: williamr@4: /** williamr@4: * Otherwise identical to @c CreateColorIconL without size parameters, williamr@4: * but calls @c SetSize to set the size of the resulting icon. williamr@4: * williamr@4: * @since 2.8 williamr@4: * williamr@4: * @lib AknSkins.lib williamr@4: */ williamr@4: IMPORT_C static void CreateColorIconL( williamr@4: MAknsSkinInstance* aInstance, const TAknsItemID& aID, williamr@4: const TAknsItemID& aColorID, const TInt aColorIndex, williamr@4: CFbsBitmap*& aBitmap, CFbsBitmap*& aMask, williamr@4: const TDesC& aFilename, williamr@4: const TInt aFileBitmapId, const TInt aFileMaskId, williamr@4: const TRgb aDefaultColor, williamr@4: const TSize& aSize, const TScaleMode aScaleMode ); williamr@4: williamr@4: /** williamr@4: * Otherwise identical to @c CreateColorIconL, but leaves both the williamr@4: * bitmap and the mask in the cleanup stack. williamr@4: * The order in which they are pushed into the stack and types of williamr@4: * the items in the stack are both undefined. williamr@4: * williamr@4: * @since 2.8 williamr@4: * williamr@4: * @lib AknSkins.lib williamr@4: * williamr@4: * @par Note: williamr@4: * Since two bitmaps are left in the cleanup stack, williamr@4: * call to this method can not be enclosed in an immediate TRAP. williamr@4: */ williamr@4: IMPORT_C static void CreateColorIconLC( williamr@4: MAknsSkinInstance* aInstance, const TAknsItemID& aID, williamr@4: const TAknsItemID& aColorID, const TInt aColorIndex, williamr@4: CFbsBitmap*& aBitmap, CFbsBitmap*& aMask, williamr@4: const TDesC& aFilename, williamr@4: const TInt aFileBitmapId, const TInt aFileMaskId, williamr@4: const TRgb aDefaultColor, williamr@4: const TSize& aSize, const TScaleMode aScaleMode ); williamr@4: williamr@4: public: // New functions - Item access w/o support for scalable graphics williamr@4: williamr@4: /** williamr@4: * Constructs an application icon. Icon bitmaps are duplicated to the williamr@4: * given CApaMaskedBitmap object. williamr@4: * williamr@4: * Since Series 60 Release 2.6, this method is fallback-enabled. williamr@4: * If no icon is found in the currently active skin, it uses williamr@4: * AppArch to construct the icon. williamr@4: * williamr@4: * @since 2.0 williamr@4: * williamr@4: * @param aInstance Pointer to current skin instance. williamr@4: * williamr@4: * @param aAppUid Application UID. Icon is searched with major IID williamr@4: * ::EAknsIIDMajorAppIcon and minor IID aAppUid. AppArch search williamr@4: * is always performed with UID only. williamr@4: * williamr@4: * @param aSize Maximum size of the icon. williamr@4: * williamr@4: * @param aAppBitmap On return contains the icon. williamr@4: * williamr@4: * @return KErrNone if succeeded, KErrNotFound if no icon was found williamr@4: * or size requirements were not met, other error code if williamr@4: * another error occured. williamr@4: * williamr@4: * @par Note: williamr@4: * This method does not support scalable graphics. williamr@4: * Consider using @c CreateAppIconLC instead. williamr@4: */ williamr@4: IMPORT_C static TInt GetAppIcon( williamr@4: MAknsSkinInstance* aInstance, TUid aAppUid, TSize aSize, williamr@4: CApaMaskedBitmap& aAppBitmap ); williamr@4: williamr@4: public: // New functions - Item access w/ ownership williamr@4: williamr@4: /** williamr@4: * Constructs an independent bitmap. williamr@4: * Creates an independent copy of bitmap (in terms of instance ownership) williamr@4: * by given item ID. williamr@4: * williamr@4: * @since 2.0 williamr@4: * williamr@4: * @param aInstance Pointer to current skin instance. williamr@4: * williamr@4: * @param aID Item ID of the bitmap to be created. williamr@4: * williamr@4: * @return Pointer to the newly created bitmap. Ownership of the object williamr@4: * is transferred to the caller. williamr@4: * williamr@4: * @par Exceptions: williamr@4: * - If data construction fails or bitmap is not found, function williamr@4: * leaves with an error code. williamr@4: */ williamr@4: IMPORT_C static CFbsBitmap* CreateBitmapL( williamr@4: MAknsSkinInstance* aInstance, const TAknsItemID& aID ); williamr@4: williamr@4: /** williamr@4: * Constructs an independent masked bitmap. williamr@4: * Creates an independent (in terms of instance ownership) copy of a williamr@4: * masked bitmap by the given item ID. williamr@4: * williamr@4: * Alternatively, masked bitmaps can be retrieved by using williamr@4: * @c MAknsSkinInstance::GetCachedItemData(TAknsItemID,TAknsItemType) williamr@4: * or williamr@4: * @c MAknsSkinInstance::CreateUncachedItemDataL(TAknsItemID,TAknsItemType) williamr@4: * methods. For these, @c ::EAknsITMaskedBitmap should be given as the williamr@4: * second parameter. Returned @c CAknsItemData pointer can be casted williamr@4: * to a @c CAknsMaskedBitmapItemData pointer in order to get access williamr@4: * to the bitmap objects themselves. williamr@4: * williamr@4: * @par Note: williamr@4: * This method does not have fallback support (to load the bitmap from williamr@4: * the specified file in case it is not available in the current williamr@4: * skin). Consider using one of the fallback-enabled overloads williamr@4: * instead. williamr@4: * williamr@4: * @since 2.0 williamr@4: * williamr@4: * @param aInstance Pointer to the current skin instance. williamr@4: * williamr@4: * @param aID Item ID of the masked bitmap to be created. williamr@4: * williamr@4: * @return Pointer to the newly created CApaMaskedBitmap object. williamr@4: * Ownership of the object is transferred to the caller. williamr@4: * williamr@4: * @par Exceptions: williamr@4: * If data construction fails or bitmap is not found, the function williamr@4: * leaves with an error code. williamr@4: * williamr@4: * @par Note: williamr@4: * Since @c CApaMaskedBitmap can not be used to store scalable williamr@4: * graphics, consider using @c CreateIconLC instead. williamr@4: */ williamr@4: IMPORT_C static CApaMaskedBitmap* CreateMaskedBitmapL( williamr@4: MAknsSkinInstance* aInstance, const TAknsItemID& aID ); williamr@4: williamr@4: /** williamr@4: * Constructs an independent CGulIcon object. williamr@4: * Creates an independent (in terms of instance ownership) copy of a williamr@4: * bitmap or a masked bitmap by the given item ID, and returns it as a williamr@4: * newly constructed CGulIcon object. williamr@4: * williamr@4: * @par Note: williamr@4: * This method does not have fallback support (to load the bitmap from williamr@4: * the specified file in case it is not available in the current williamr@4: * skin). Consider using one of the fallback-enabled overloads williamr@4: * instead. williamr@4: * williamr@4: * @since 2.1 williamr@4: * williamr@4: * @lib AknSkins.lib williamr@4: * williamr@4: * @param aInstance Pointer to the current skin instance. williamr@4: * williamr@4: * @param aID Item ID of the bitmap or masked bitmap to be created. williamr@4: * williamr@4: * @param aRequireMask ETrue if masked bitmap is explicitly required. williamr@4: * EFalse if mask is optional. williamr@4: * williamr@4: * @return Pointer to the newly created CGulIcon object. williamr@4: * Ownership of the object is transferred to the caller. williamr@4: * williamr@4: * @par Exceptions: williamr@4: * If data construction fails or bitmap is not found, the function williamr@4: * leaves with an error code. williamr@4: */ williamr@4: IMPORT_C static CGulIcon* CreateGulIconL( williamr@4: MAknsSkinInstance* aInstance, const TAknsItemID& aID, williamr@4: const TBool aRequireMask ); williamr@4: williamr@4: public: // New functions - Item access w/o ownership williamr@4: williamr@4: /** williamr@4: * Returns pointer to a cached bitmap. williamr@4: * Retrieves (and constructs if necessary) a bitmap in skin instance williamr@4: * cache. Caller can use the bitmap temporarily (e.g. in drawing code), williamr@4: * but should not store pointer to it, since its lifetime is determined williamr@4: * by cache. williamr@4: * williamr@4: * @since 2.0 williamr@4: * williamr@4: * @param aInstance Pointer to current skin instance. If @c NULL value williamr@4: * is specified, method immediately returns with @c NULL return value. williamr@4: * williamr@4: * @param aID Item ID of the bitmap to be retrieved. williamr@4: * williamr@4: * @return Pointer to the bitmap, or @c NULL if no bitmap with given ID williamr@4: * was found or an error occured. williamr@4: * williamr@4: * @par Exceptions: williamr@4: * - Because the method can not leave, error handling procedure williamr@4: * described in williamr@4: * MAknsSkinInstance::GetCachedItemData(const TAknsItemID& aID) is williamr@4: * used if data construction fails. williamr@4: */ williamr@4: IMPORT_C static CFbsBitmap* GetCachedBitmap( williamr@4: MAknsSkinInstance* aInstance, const TAknsItemID& aID ); williamr@4: williamr@4: /** williamr@4: * Retrieves temporary pointers to a cached bitmap and its mask. williamr@4: * Retrieves (and constructs, if necessary) a masked bitmap in the skin williamr@4: * instance cache. Pointers to the bitmap (and its mask) are stored williamr@4: * to the pointers given as parameters. Caller can use the bitmaps williamr@4: * temporarily (e.g. in drawing code), but should not store them, since williamr@4: * their lifetimes are determined by the cache. williamr@4: * williamr@4: * @since 2.1 williamr@4: * williamr@4: * @param aInstance Pointer to the current skin instance. If @c NULL williamr@4: * value is specified, the method assigns @c NULL to both the given williamr@4: * pointers and then returns. williamr@4: * williamr@4: * @param aID Item ID of the bitmap (or masked bitmap) to be retrieved. williamr@4: * williamr@4: * @param aBitmap Reference to the pointer that will receive the bitmap. williamr@4: * @c NULL value is assigned if no bitmap with the given ID was found williamr@4: * or an error occured. williamr@4: * williamr@4: * @param aMask Reference to the pointer that will receive the mask. williamr@4: * @c NULL value is assigned if no bitmap with the given ID was found, williamr@4: * or the bitmap did not have a mask, or an error occured. williamr@4: * williamr@4: * @par Exceptions: williamr@4: * - Because the method can not leave, error handling procedure williamr@4: * described in williamr@4: * MAknsSkinInstance::GetCachedItemData(const TAknsItemID& aID) is williamr@4: * used if data construction fails. williamr@4: */ williamr@4: IMPORT_C static void GetCachedMaskedBitmap( williamr@4: MAknsSkinInstance* aInstance, const TAknsItemID& aID, williamr@4: CFbsBitmap*& aBitmap, CFbsBitmap*& aMask ); williamr@4: williamr@4: /** williamr@4: * Returns a color value from a cached color table. williamr@4: * Retrieves (and constructs if necessary) a color table in williamr@4: * skin instance cache and returns a color value from it. williamr@4: * williamr@4: * Since release 2.8, this method also handles any backward williamr@4: * compatibility operations possibly required. williamr@4: * williamr@4: * @since 2.0 williamr@4: * williamr@4: * @param aInstance Pointer to current skin instance. If @c NULL value williamr@4: * is specified, returns KErrNotSupported. williamr@4: * williamr@4: * @param aRgb Reference to a TRgb that will receive the color. williamr@4: * williamr@4: * @param aID Item ID of the color table. williamr@4: * williamr@4: * @param aIndex Index of the color in the color table. williamr@4: * williamr@4: * @return KErrNone if successful, otherwise an error code is returned. williamr@4: */ williamr@4: IMPORT_C static TInt GetCachedColor( williamr@4: MAknsSkinInstance* aInstance, TRgb& aRgb, const TAknsItemID& aID, williamr@4: const TInt aIndex ); williamr@4: williamr@4: /** williamr@4: * Retrieves the value of the given boolean property skin item. williamr@4: * williamr@4: * @since 2.8 williamr@4: * williamr@4: * @param aInstance Pointer to current skin instance. If @c NULL value williamr@4: * is specified, the method leaves. williamr@4: * williamr@4: * @param aID Item ID of the boolean property. williamr@4: * williamr@4: * @return Value of the boolean property as @c TBool. williamr@4: * williamr@4: * @par Exceptions: williamr@4: * - If the item is not found, leaves with @c KErrNotFound. williamr@4: * - If the item is not a boolean property or another error occures, williamr@4: * leaves with a system-wide error code. williamr@4: */ williamr@4: IMPORT_C static TBool BooleanPropertyL( MAknsSkinInstance* aInstance, williamr@4: const TAknsItemID& aID ); williamr@4: williamr@4: /** williamr@4: * Test whether the given type is derived from the given base type. williamr@4: * williamr@4: * @since 2.0 williamr@4: * williamr@4: * @param aBaseType Base type. williamr@4: * williamr@4: * @param aDerivedType Derived type. williamr@4: * williamr@4: * @return ETrue if the type is derived from the base type, EFalse williamr@4: * otherwise. williamr@4: * williamr@4: * @internal williamr@4: */ williamr@4: static TBool IsDerivedType( const TAknsItemType aBaseType, williamr@4: const TAknsItemType aDerivedType ); williamr@4: williamr@4: public: // New functions - Avkon parameters williamr@4: williamr@4: /** williamr@4: * Sets the flag indicating whether default skin parameters should williamr@4: * be used for newly created Avkon controls in the scope of the williamr@4: * current AppUi. williamr@4: * williamr@4: * @since 2.0 williamr@4: * williamr@4: * @param Value of the flag as TBool. williamr@4: * williamr@4: * @par Exceptions: williamr@4: * If construction of the storage object for the flag fails, williamr@4: * leaves with an error code. williamr@4: */ williamr@4: IMPORT_C static void SetAvkonSkinEnabledL( const TBool aEnabled ); williamr@4: williamr@4: /** williamr@4: * Queries whether default skin parameters should be used for newly williamr@4: * created Avkon controls. Components supporting williamr@4: * SetSkinEnabledL method should also check for this williamr@4: * value upon construction and set their internal state accordingly. williamr@4: * williamr@4: * Note that this flag is intended to be used to determine whether or williamr@4: * not controls should create skin backgrounds for main pane williamr@4: * layouts. Skins are always enabled for e.g. all the popup windows, williamr@4: * even through the flag may be @c EFalse, and therefore the flag williamr@4: * must not be used as a generic "are skins enabled" switch. williamr@4: * williamr@4: * Most controls do not (and should not) query the flag value. If williamr@4: * control just fetches the skin control context with williamr@4: * @c AknsDrawUtils::ControlContext, it will get the proper @c NULL williamr@4: * value if no background has been defined. williamr@4: * williamr@4: * @since 2.0 williamr@4: * williamr@4: * @return ETrue if default skin parameters should be used, williamr@4: * EFalse otherwise. The default value is EFalse. williamr@4: */ williamr@4: IMPORT_C static TBool AvkonSkinEnabled(); williamr@4: williamr@4: /** williamr@4: * Sets the flag indicating whether highlight animations should be used williamr@4: * for Avkon list controls in the scope of the current AppUi. williamr@4: * williamr@4: * @since 3.0 williamr@4: * williamr@4: * @param Value of the flag as TBool. williamr@4: * williamr@4: * @par Exceptions: williamr@4: * If construction of the storage object for the flag fails, williamr@4: * leaves with an error code. williamr@4: */ williamr@4: IMPORT_C static void SetAvkonHighlightAnimationEnabledL( const TBool aEnabled ); williamr@4: williamr@4: /** williamr@4: * Queries whether highlight animation should be used for newly created williamr@4: * Avkon list controls. williamr@4: * williamr@4: * @since 3.0 williamr@4: * williamr@4: * @return ETrue if list highlight animation should be used, EFalse williamr@4: * otherwise. The default value is ETrue. williamr@4: */ williamr@4: IMPORT_C static TBool AvkonHighlightAnimationEnabled(); williamr@4: williamr@4: public: // New functions - Control position list williamr@4: williamr@4: /** williamr@4: * Registers the position of the given control. williamr@4: * The position is stored in the thread-local control position list. williamr@4: * If the control has already been registered, its position is updated. williamr@4: * williamr@4: * Registering the position of the control enables background drawing williamr@4: * methods in AknsDrawUtils to calculate positions in williamr@4: * parent-absolute layouts without causing window server flushes. williamr@4: * williamr@4: * When a registered control goes out of scope, it must call williamr@4: * AknsUtils::DeregisterControlPosition to ensure that it is properly williamr@4: * removed from the list. williamr@4: * williamr@4: * @since 2.0 williamr@4: * williamr@4: * @param aControl Pointer to the control that needs its position williamr@4: * to be updated in the control position list. williamr@4: */ williamr@4: IMPORT_C static void RegisterControlPosition( williamr@4: const CCoeControl* aControl ); williamr@4: williamr@4: /** williamr@4: * Registers the position of the given control with given position. williamr@4: * The position is stored in the thread-local control position list. williamr@4: * If the control has already been registered, its position is updated. williamr@4: * williamr@4: * Registering the position of the control enables background drawing williamr@4: * methods in AknsDrawUtils to calculate positions in williamr@4: * parent-absolute layouts without causing window server flushes. williamr@4: * williamr@4: * When a registered control goes out of scope, it must call williamr@4: * AknsUtils::DeregisterControlPosition to ensure that it is properly williamr@4: * removed from the list. williamr@4: * williamr@4: * @since 2.0 williamr@4: * williamr@4: * @param aControl Pointer to the control that needs its position williamr@4: * to be updated in the control position list. williamr@4: * williamr@4: * @param aPoint The new position to be registered with the given williamr@4: * control (in screen coordinates). williamr@4: */ williamr@4: IMPORT_C static void RegisterControlPosition( williamr@4: const CCoeControl* aControl, const TPoint& aPoint ); williamr@4: williamr@4: /** williamr@4: * Removes the position of the given control from the list. williamr@4: * The position of the given control is removed from the thread-local williamr@4: * control position list. If the control has not been registered, williamr@4: * this method does nothing. williamr@4: * williamr@4: * @since 2.0 williamr@4: * williamr@4: * @param aControl Pointer to the control that needs to be removed williamr@4: * from the control position list. williamr@4: */ williamr@4: IMPORT_C static void DeregisterControlPosition( williamr@4: const CCoeControl* aControl ); williamr@4: williamr@4: /** williamr@4: * Gets the position of the control registered in the control position williamr@4: * list. williamr@4: * williamr@4: * @param aControl Pointer to the control whose position is to be williamr@4: * queried. williamr@4: * williamr@4: * @param aScreenPos Reference to the TPoint that will receive the williamr@4: * position. williamr@4: * williamr@4: * @return KErrNone if successful, KErrNotFound if the control has williamr@4: * not been registered. williamr@4: */ williamr@4: IMPORT_C static TInt GetControlPosition( const CCoeControl* aControl, williamr@4: TPoint& aScreenPos ); williamr@4: williamr@4: private: // Internal methods williamr@4: williamr@4: /** williamr@4: * Gets an application icon from skin. williamr@4: * williamr@4: * @since 2.8 williamr@4: * williamr@4: * @internal williamr@4: */ williamr@4: static TInt GetAppIconFromSkin( williamr@4: MAknsSkinInstance* aInstance, TUid aAppUid, TSize aSize, williamr@4: CFbsBitmap*& aBitmap, CFbsBitmap*& aMask ); williamr@4: williamr@4: /** williamr@4: * Returns the best application icon bitmap IID among the listed icons. williamr@4: * williamr@4: * @since 2.1 williamr@4: * williamr@4: * @param aSize Maximum size. williamr@4: * williamr@4: * @param aSkin Skin instance. williamr@4: * williamr@4: * @param aAppIconIID Item ID of the application icon. williamr@4: * williamr@4: * @return Icon bitmap IID. williamr@4: * williamr@4: * @internal williamr@4: */ williamr@4: static TAknsItemID SelectBestAppIconBitmapL( williamr@4: const TSize& aSize, MAknsSkinInstance* aSkin, williamr@4: const TAknsItemID& aAppIconIID ); williamr@4: williamr@4: private: // Reserved exports williamr@4: williamr@4: /** williamr@4: * Reserved for future use. williamr@4: * williamr@4: * @since 2.0 williamr@4: * williamr@4: * @return Always returns zero. williamr@4: */ williamr@4: IMPORT_C static TInt Reserved(); williamr@4: williamr@4: private: // Prohibited constructors and destructor williamr@4: williamr@4: // Construction prohibited (static class) williamr@4: AknsUtils(); williamr@4: // Destruction prohibited (static class) williamr@4: ~AknsUtils(); williamr@4: }; williamr@4: williamr@4: #endif // AKNSUTILS_H williamr@4: williamr@4: // End of File