/*

* 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