/*

* Copyright (c) 2002 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:   Utility functions related to scalable icons.

*

*/

#ifndef AKN_ICON_UTILS_H

#define AKN_ICON_UTILS_H

// INCLUDES

#include <e32std.h>

#include <gdi.h>

// FORWARD DECLARATIONS

class CFbsBitmap;

class MAknIconObserver;

// ENUMERATIONS

enum TScaleMode

    {

    /*

    * Scales the icon to the maximum size that fits in the given size,

    * whilst preserving the aspect ratio of the icon. The sizes of the resulting

    * bitmaps are exactly of the given size. If the aspect ratio of

    * the given size differs from the aspect ratio of the icon,

    * the resulting bitmaps will contain an unused area.

    */

    EAspectRatioPreserved = 0,

    /*

    * Scales the icon to the maximum size that fits in the given size,

    * whilst preserving the aspect ratio of the icon. The resulting bitmaps

    * are resized so that any unused portion of the given size is not

    * present in them.

    *

    * This mode should be used when only the height or the width of the icon

    * is known and the other should be based on the aspect ratio of the icon.

    * The unknown dimension should be defined high enough (e.g. KMaxTInt) so

    * that it does not limit the scaling based on the aspect ratio of the icon.

    */

    EAspectRatioPreservedAndUnusedSpaceRemoved = 1,

    /*

    * Scales the icon exactly to the given size. Does not preserve the aspect

    * ratio of the icon.

    */

    EAspectRatioNotPreserved = 2,

    /*

    * Scales the icon to the minimum size that covers the given size,

    * whilst preserving the aspect ratio of the icon. The sizes of the resulting

    * bitmaps are exactly of the given size. If the aspect ratio of

    * the given size differs from the aspect ratio of the icon, some parts of the 

    * icon will be sliced from the resulting bitmaps.

    *

    * @since 3.1

    */

    EAspectRatioPreservedSlice = 3

    };

// CLASS DECLARATIONS

/**

* Class for storing the content dimensions of icons.

*/

class TAknContentDimensions

	{

	public:

        /**

         * C++ default constructor.

         */

        inline TAknContentDimensions();	

        /**

         * Constructor.

         *

         * @param aWidth Icons width.

         * @param aHeight Icons height.

         */

        inline TAknContentDimensions(TReal32 aWidth, TReal32 aHeight);

        /**

         * Sets the content dimensions.

         *

         * @param aWidth Width of the icon.

         * @param aHeight Height of the icon.

         */

        inline void SetDimensions(TReal32 aWidth, TReal32 aHeight);	

        /**

         * Sets the content size of the icon.

         *

         * @param aDimensions Two-dimensional size as a width and a height 

                              value of the icon.

         */

        inline void SetDimensions(const TSize& aDimensions);	

	public:

        /** Icons width. */

        TReal32 iWidth;

        /** Icons height. */

		TReal32 iHeight;

	};

/**

 * Cleanup stack helper. Owns the bitmap and the mask.

 */

NONSHARABLE_CLASS(CAknIcon) : public CBase

    {

    public:

        /**

         * Two-phased constructor.

         *

         * Creates and returns a pointer to a new @c CAknIcon object.

         *

         * @return New @c CAknIcon.

         */

        IMPORT_C static CAknIcon* NewL();

        /**

         * Destructor.

         */

        ~CAknIcon();

    public:

        /**

         * Gets the bitmap.

         *

         * @return The icon's bitmap.

         */

        IMPORT_C CFbsBitmap* Bitmap() const;

        /**

         * Gets the mask.

         *

         * @return The icon's mask.

         */    

        IMPORT_C CFbsBitmap* Mask() const;

        /**

         * Sets the bitmap.

         *

         * @param aBitmap The icon's bitmap.

         */    

        IMPORT_C void SetBitmap( CFbsBitmap* aBitmap );

        /**

         * Sets the mask.

         *

         * @param aMask The icon's mask.

         */    

        IMPORT_C void SetMask( CFbsBitmap* aMask );

    private:

        /**

         * Default constructor.

         */

        inline CAknIcon() {}

    private:

        CFbsBitmap* iBitmap; // owned

        CFbsBitmap* iMask; // owned

    };

/**

* The purpose of this class is for clients to provide opened file handles

* to icon files, which reside in private directories,

* where AknIcon server has no access.

*

* MIF file is always generated, when building icons with MifConv tool.

* The corresponding MBM file is generated only if there are bitmap icons

* amongst the source icons.

*

*/

class MAknIconFileProvider

    {

    public:

        enum TIconFileType

            {

            EMbmFile = 0,

            EMifFile = 1

            };

    public:

        /**

        * Destructor.

        */

        virtual ~MAknIconFileProvider() {}

        /**

        * Returns an open file handle to the icon file.

        * This method should leave if an icon file with specified type does

        * not exist. That may be the case e.g. with MBM file,

        * if there are no bitmap icons.

        *

        * Note! RFs::ShareProtected must be called to the RFs instance used

        * for opening the file.

        *

        * @param aFile Icon file should be opened in this file handle, which

        * is an empty file handle, when the AknIcon framework calls this method.

        * The AknIcon framework takes care of closing the file handle after

        * having used it.

        * @param aType Icon file type.

        */

        virtual void RetrieveIconFileHandleL(

            RFile& aFile, const TIconFileType aType ) = 0;

        /**

        * With this method, AknIcon framework informs that it does not use

        * this MAknIconFileProvider instance any more. After this call,

        * it is ok to delete the object. This can be implemented simply

        * e.g. by deleting self in this callback.

        * Normally, this callback is invoked when the icon in question

        * is deleted.

        * Note, however, that if the same MAknIconFileProvider instance is

        * supplied in multiple CreateIcon calls, then it must be accessible

        * by AknIcon framework until it has signalled a matching amount

        * of these callbacks.

        */

        virtual void Finished() = 0;

    };

/**

* AknIconUtils

*

* Note: The CFbsBitmap objects for bitmaps and mask returned by this class

* may be compressed in background. 

* Client code directly accessing the bitmap pixel data should not

* assume that the bitmap and mask objects are not compressed. 

*

* Bitmap compression can be disabled for an icon if desired using

* AknIconUtils::DisableCompression().

*/

class AknIconUtils

    {

    public:

        /**

        * Creates bitmap and mask for an icon.

        * Allocates bitmap and mask objects and sets aBitmap and

        * aMask to point at them. Ownership of those is transferred to the caller.

        * These bitmaps are not ready for drawing until they are initialized with

        * SetSize method. Usually, UI controls do this.

        *

        * Use this method only if aBitmap and aMask are member variables.

        * Otherwise, use method CreateIconLC.

        *

        * @since 2.8

        * @param aBitmap icon bitmap is stored here

        * @param aMask icon mask is stored here

        * @param aFileName File name. Can be either MBM or MIF file.

        * Extension is changed based on the given bitmap ID.

        * @param aBitmapId bitmap Id

        * @param aMaskId mask Id

        */

        IMPORT_C static void CreateIconL(

            CFbsBitmap*& aBitmap,

            CFbsBitmap*& aMask,

            const TDesC& aFileName,

            TInt aBitmapId,

            TInt aMaskId );

        /**

        * Creates bitmap and mask for an icon.

        * Allocates bitmap and mask objects and sets aBitmap and

        * aMask to point at them. Ownership of those is transferred to the caller.

        * These bitmaps are not ready for drawing until they are initialized with

        * SetSize method. Usually, UI controls do this.

        *

        * This method puts both aBitmap and aMask in the cleanup stack.

        *

        * @since 2.8

        * @param aBitmap icon bitmap is stored here

        * @param aMask icon mask is stored here

        * @param aFileName File name. Can be either MBM or MIF file.

        * Extension is changed based on the given bitmap ID.

        * @param aBitmapId bitmap ID

        * @param aMaskId mask ID

        */

        IMPORT_C static void CreateIconLC(

            CFbsBitmap*& aBitmap,

            CFbsBitmap*& aMask,

            const TDesC& aFileName,

            TInt aBitmapId,

            TInt aMaskId );

        /**

        * Creates the bitmap for an icon.

        * Use this variant when a mask is not needed.

        * Ownership of the returned object is transferred to the caller.

        * The bitmap is not ready for drawing until it is initialized with

        * SetSize method. Usually, UI controls do this.

        *

        * @since 2.8

        * @param aBitmap icon bitmap is stored here

        * @param aFileName File name. Can be either MBM or MIF file.

        * Extension is changed based on the given bitmap ID.

        * @param aBitmapId bitmap ID

        */

        IMPORT_C static CFbsBitmap* CreateIconL(

            const TDesC& aFileName,

            TInt aBitmapId );

        /**

        * Creates bitmap and mask for an icon.

        * Allocates bitmap and mask objects and sets aBitmap and

        * aMask to point at them. Ownership of those is transferred to the caller.

        * These bitmaps are not ready for drawing until they are initialized with

        * SetSize method. Usually, UI controls do this.

        *

        * If this method leaves, MAknIconFileProvider::Finished is called for the

        * supplied aFileProvider.

        *

        * Use this method only if aBitmap and aMask are member variables.

        * Otherwise, use method CreateIconLC.

        *

        * @since 3.0

        * @param aBitmap icon bitmap is stored here

        * @param aMask icon mask is stored here

        * @param aFileProvider Icon file handle provider.

        * @param aBitmapId bitmap Id

        * @param aMaskId mask Id

        */

        IMPORT_C static void CreateIconL(

            CFbsBitmap*& aBitmap,

            CFbsBitmap*& aMask,

            MAknIconFileProvider& aFileProvider,

            TInt aBitmapId,

            TInt aMaskId );

        /**

        * Creates bitmap and mask for an icon.

        * Allocates bitmap and mask objects and sets aBitmap and

        * aMask to point at them. Ownership of those is transferred to the caller.

        * These bitmaps are not ready for drawing until they are initialized with

        * SetSize method. Usually, UI controls do this.

        *

        * This method puts both aBitmap and aMask in the cleanup stack.

        *

        * If this method leaves, MAknIconFileProvider::Finished is called for the

        * supplied aFileProvider.

        *

        * @since 3.0

        * @param aBitmap icon bitmap is stored here

        * @param aMask icon mask is stored here

        * @param aFileProvider Icon file handle provider.

        * @param aBitmapId bitmap Id

        * @param aMaskId mask Id

        */

        IMPORT_C static void CreateIconLC(

            CFbsBitmap*& aBitmap,

            CFbsBitmap*& aMask,

            MAknIconFileProvider& aFileProvider,

            TInt aBitmapId,

            TInt aMaskId );

        /**

        * Creates the bitmap for an icon.

        * Use this variant when a mask is not needed.

        * Ownership of the returned object is transferred to the caller.

        * The bitmap is not ready for drawing until it is initialized with

        * SetSize method. Usually, UI controls do this.

        *

        * If this method leaves, MAknIconFileProvider::Finished is called for the

        * supplied aFileProvider.

        *

        * @since 3.0

        * @param aFileProvider Icon file handle provider.

        * @param aBitmapId bitmap ID

        * @return The icon bitmap.

        */

        IMPORT_C static CFbsBitmap* CreateIconL(

            MAknIconFileProvider& aFileProvider,

            TInt aBitmapId );

        /**

        * Preserves the icon data (e.g. SVG-T data) related to the given icon

        * in memory. After this, the icon data is destroyed when either

        * DestroyIconData is explicitly called or the bitmap(s) of the icon are

        * deleted.

        *

        * This method should be called to improve performance if more than one

        * call to methods SetSize, SetSizeAndRotation or GetContentDimensions

        * is made successively on a particular icon. It should be called prior

        * to the above-mentioned calls. Without calling this method,

        * the icon data is destroyed after any of the method calls mentioned

        * above and then loaded from the storage medium and parsed from scratch

        * again in a new operation.

        *

        * Note! Icon data may consume considerable amounts of memory. In order

        * to save memory, any code that calls PreserveIconData should also

        * explicitly call DestroyIconData when the icon data is no longer

        * required.

        *

        * @since 2.8

        * @param aBitmap bitmap or mask of the icon.

        */

        IMPORT_C static void PreserveIconData( CFbsBitmap* aBitmap );

        /**

        * Destroys the icon data related to the given icon,

        * if it was preserved in memory. Note that this does not affect

        * the rendered frame buffers (CFbsBitmap objects).

        *

        * @since 2.8

        * @param aBitmap bitmap or mask of the icon.

        */

        IMPORT_C static void DestroyIconData( CFbsBitmap* aBitmap );

        /**

        * Initializes the icon to the given size, if the parameter aBitmap is

        * an instance of CAknBitmap, i.e. created with AknIconUtils methods.

        * If it is not CAknBitmap, this method does nothing. Note that this call

        * sets the sizes of both bitmap and mask (if it exists), regardless of

        * which is given as the parameter.

        *

        * @since 2.8

        * @param aBitmap bitmap or mask of the icon

        * @param aSize icon size

        * @param aMode scale mode

        * @return Standard Symbian OS error code. In error cases, it is guaranteed

        * that the returned bitmap is a valid CFbsBitmap, but there is no guarantee

        * of its size, except that it is non-negative.

        */

        IMPORT_C static TInt SetSize(

            CFbsBitmap* aBitmap,

            const TSize& aSize,

            TScaleMode aMode = EAspectRatioPreserved );

        /**

        * Initializes the icon to the given size, if the parameter aBitmap is

        * an instance of CAknBitmap, i.e. created with AknIconUtils methods.

        * If it is not CAknBitmap, this method does nothing. Note that this call

        * sets the sizes of both bitmap and mask (if it exists), regardless of

        * which is given as the parameter. Additionally, this method rotates

        * the icon according to the given angle.

        *

        * @since 2.8

        * @param aBitmap bitmap or mask of the icon

        * @param aSize icon size

        * @param aAngle Rotation angle in degrees.

        * @return Standard Symbian OS error code. In error cases, it is guaranteed

        * that the returned bitmap is a valid CFbsBitmap, but there is no guarantee

        * of its size, except that it is non-negative.

        */

        IMPORT_C static TInt SetSizeAndRotation(

            CFbsBitmap* aBitmap,

            const TSize& aSize,

            TScaleMode aMode,

            TInt aAngle );

        /**

        * Sets observer for change notification.

        * 

        * The method BitmapChanged() will be called when the contents of the CFbsBitmap

        * are changed. Controls can use this to redraw themselves when icon

        * animation progresses.

        * 

        * @since 2.8

        * @param aBitmap bitmap

        * @param aObserver observer

        */

        IMPORT_C static void SetObserver( CFbsBitmap* aBitmap, MAknIconObserver* aObserver );

        /**

        * Returns the file name of Avkon's icon file, containing full path.

        *

        * @since 2.8

        * @ret Avkon's icon file name, containing full path.

        */

        IMPORT_C static const TDesC& AvkonIconFileName();

        /**

        * Validates logical app icon ID so that it can be used as a parameter to

        * CreateIconL or CreateIconLC. If the given icon file name is .MBM file,

        * this method does nothing. If it is .MIF file, a predefined offset is

        * added to the given IDs.

        *

        * This method is only intended to be used when loading icons from the

        * icon file retrieved from AppArc.

        *

        * @param aIconFileName Icon file name retrieved from AppArc.

        * @param aId Logical bitmap ID used in the app icon file, usually 0.

        * @param aId Logical mask ID used in the app icon file, usually 1.

        */

        IMPORT_C static void ValidateLogicalAppIconId( 

            const TDesC& aIconFileName,

            TInt& aBitmapId,

            TInt& aMaskId );

        /**

        * Tells whether the given file name is recognized as a MIF file or not.

        * Only the file name extension is examined, not the contents of the file.

        *

        * @since 2.8

        * @param aFileName file name

        *

        * @return ETrue if MIF file, EFalse otherwise.

        */

        IMPORT_C static TBool IsMifFile( const TDesC& aFileName );

        /**

        * Tells whether the given bitmap is a part of a MIF icon or not.

        * Accepts any pointer (also NULL) as a parameter.

        *