williamr@4: /*
williamr@4: * Copyright (c) 2002 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:   Utility functions related to scalable icons.
williamr@4: *
williamr@4: */
williamr@4: 
williamr@4: 
williamr@4: 
williamr@4: 
williamr@4: #ifndef AKN_ICON_UTILS_H
williamr@4: #define AKN_ICON_UTILS_H
williamr@4: 
williamr@4: // INCLUDES
williamr@4: #include <e32std.h>
williamr@4: #include <gdi.h>
williamr@4: 
williamr@4: // FORWARD DECLARATIONS
williamr@4: class CFbsBitmap;
williamr@4: class MAknIconObserver;
williamr@4: 
williamr@4: // ENUMERATIONS
williamr@4: enum TScaleMode
williamr@4:     {
williamr@4:     /*
williamr@4:     * Scales the icon to the maximum size that fits in the given size,
williamr@4:     * whilst preserving the aspect ratio of the icon. The sizes of the resulting
williamr@4:     * bitmaps are exactly of the given size. If the aspect ratio of
williamr@4:     * the given size differs from the aspect ratio of the icon,
williamr@4:     * the resulting bitmaps will contain an unused area.
williamr@4:     */
williamr@4:     EAspectRatioPreserved = 0,
williamr@4: 
williamr@4:     /*
williamr@4:     * Scales the icon to the maximum size that fits in the given size,
williamr@4:     * whilst preserving the aspect ratio of the icon. The resulting bitmaps
williamr@4:     * are resized so that any unused portion of the given size is not
williamr@4:     * present in them.
williamr@4:     *
williamr@4:     * This mode should be used when only the height or the width of the icon
williamr@4:     * is known and the other should be based on the aspect ratio of the icon.
williamr@4:     * The unknown dimension should be defined high enough (e.g. KMaxTInt) so
williamr@4:     * that it does not limit the scaling based on the aspect ratio of the icon.
williamr@4:     */
williamr@4:     EAspectRatioPreservedAndUnusedSpaceRemoved = 1,
williamr@4: 
williamr@4:     /*
williamr@4:     * Scales the icon exactly to the given size. Does not preserve the aspect
williamr@4:     * ratio of the icon.
williamr@4:     */
williamr@4:     EAspectRatioNotPreserved = 2,
williamr@4:         
williamr@4:     /*
williamr@4:     * Scales the icon to the minimum size that covers the given size,
williamr@4:     * whilst preserving the aspect ratio of the icon. The sizes of the resulting
williamr@4:     * bitmaps are exactly of the given size. If the aspect ratio of
williamr@4:     * the given size differs from the aspect ratio of the icon, some parts of the 
williamr@4:     * icon will be sliced from the resulting bitmaps.
williamr@4:     *
williamr@4:     * @since 3.1
williamr@4:     */
williamr@4:     EAspectRatioPreservedSlice = 3
williamr@4:     };
williamr@4: 
williamr@4: // CLASS DECLARATIONS
williamr@4: 
williamr@4: /**
williamr@4: * Class for storing the content dimensions of icons.
williamr@4: */
williamr@4: class TAknContentDimensions
williamr@4: 	{
williamr@4: 	public:
williamr@4: 
williamr@4:         /**
williamr@4:          * C++ default constructor.
williamr@4:          */
williamr@4:         inline TAknContentDimensions();	
williamr@4: 
williamr@4:         /**
williamr@4:          * Constructor.
williamr@4:          *
williamr@4:          * @param aWidth Icons width.
williamr@4:          * @param aHeight Icons height.
williamr@4:          */
williamr@4:         inline TAknContentDimensions(TReal32 aWidth, TReal32 aHeight);
williamr@4: 
williamr@4:         /**
williamr@4:          * Sets the content dimensions.
williamr@4:          *
williamr@4:          * @param aWidth Width of the icon.
williamr@4:          * @param aHeight Height of the icon.
williamr@4:          */
williamr@4:         inline void SetDimensions(TReal32 aWidth, TReal32 aHeight);	
williamr@4:  
williamr@4:         /**
williamr@4:          * Sets the content size of the icon.
williamr@4:          *
williamr@4:          * @param aDimensions Two-dimensional size as a width and a height 
williamr@4:                               value of the icon.
williamr@4:          */
williamr@4:         inline void SetDimensions(const TSize& aDimensions);	
williamr@4: 
williamr@4: 	public:
williamr@4:     
williamr@4:         /** Icons width. */
williamr@4:         TReal32 iWidth;
williamr@4: 
williamr@4:         /** Icons height. */
williamr@4: 		TReal32 iHeight;
williamr@4: 	};
williamr@4: 
williamr@4: /**
williamr@4:  * Cleanup stack helper. Owns the bitmap and the mask.
williamr@4:  */
williamr@4: NONSHARABLE_CLASS(CAknIcon) : public CBase
williamr@4:     {
williamr@4:     public:
williamr@4:     
williamr@4:         /**
williamr@4:          * Two-phased constructor.
williamr@4:          *
williamr@4:          * Creates and returns a pointer to a new @c CAknIcon object.
williamr@4:          *
williamr@4:          * @return New @c CAknIcon.
williamr@4:          */
williamr@4:         IMPORT_C static CAknIcon* NewL();
williamr@4:     
williamr@4:         /**
williamr@4:          * Destructor.
williamr@4:          */
williamr@4:         ~CAknIcon();
williamr@4:     
williamr@4:     public:
williamr@4:     
williamr@4:         /**
williamr@4:          * Gets the bitmap.
williamr@4:          *
williamr@4:          * @return The icon's bitmap.
williamr@4:          */
williamr@4:         IMPORT_C CFbsBitmap* Bitmap() const;
williamr@4:     
williamr@4:         /**
williamr@4:          * Gets the mask.
williamr@4:          *
williamr@4:          * @return The icon's mask.
williamr@4:          */    
williamr@4:         IMPORT_C CFbsBitmap* Mask() const;
williamr@4:     
williamr@4:         /**
williamr@4:          * Sets the bitmap.
williamr@4:          *
williamr@4:          * @param aBitmap The icon's bitmap.
williamr@4:          */    
williamr@4:         IMPORT_C void SetBitmap( CFbsBitmap* aBitmap );
williamr@4:     
williamr@4:         /**
williamr@4:          * Sets the mask.
williamr@4:          *
williamr@4:          * @param aMask The icon's mask.
williamr@4:          */    
williamr@4:         IMPORT_C void SetMask( CFbsBitmap* aMask );
williamr@4:     
williamr@4:     private:
williamr@4:     
williamr@4:         /**
williamr@4:          * Default constructor.
williamr@4:          */
williamr@4:         inline CAknIcon() {}
williamr@4: 
williamr@4:     private:
williamr@4:     
williamr@4:         CFbsBitmap* iBitmap; // owned
williamr@4:         CFbsBitmap* iMask; // owned
williamr@4:     };
williamr@4: 
williamr@4: /**
williamr@4: * The purpose of this class is for clients to provide opened file handles
williamr@4: * to icon files, which reside in private directories,
williamr@4: * where AknIcon server has no access.
williamr@4: *
williamr@4: * MIF file is always generated, when building icons with MifConv tool.
williamr@4: * The corresponding MBM file is generated only if there are bitmap icons
williamr@4: * amongst the source icons.
williamr@4: *
williamr@4: */
williamr@4: class MAknIconFileProvider
williamr@4:     {
williamr@4:     public:
williamr@4: 
williamr@4:         enum TIconFileType
williamr@4:             {
williamr@4:             EMbmFile = 0,
williamr@4:             EMifFile = 1
williamr@4:             };
williamr@4: 
williamr@4:     public:
williamr@4: 
williamr@4:         /**
williamr@4:         * Destructor.
williamr@4:         */
williamr@4:         virtual ~MAknIconFileProvider() {}
williamr@4: 
williamr@4:         /**
williamr@4:         * Returns an open file handle to the icon file.
williamr@4:         * This method should leave if an icon file with specified type does
williamr@4:         * not exist. That may be the case e.g. with MBM file,
williamr@4:         * if there are no bitmap icons.
williamr@4:         *
williamr@4:         * Note! RFs::ShareProtected must be called to the RFs instance used
williamr@4:         * for opening the file.
williamr@4:         *
williamr@4:         * @param aFile Icon file should be opened in this file handle, which
williamr@4:         * is an empty file handle, when the AknIcon framework calls this method.
williamr@4:         * The AknIcon framework takes care of closing the file handle after
williamr@4:         * having used it.
williamr@4:         * @param aType Icon file type.
williamr@4:         */
williamr@4:         virtual void RetrieveIconFileHandleL(
williamr@4:             RFile& aFile, const TIconFileType aType ) = 0;
williamr@4: 
williamr@4:         /**
williamr@4:         * With this method, AknIcon framework informs that it does not use
williamr@4:         * this MAknIconFileProvider instance any more. After this call,
williamr@4:         * it is ok to delete the object. This can be implemented simply
williamr@4:         * e.g. by deleting self in this callback.
williamr@4:         * Normally, this callback is invoked when the icon in question
williamr@4:         * is deleted.
williamr@4:         * Note, however, that if the same MAknIconFileProvider instance is
williamr@4:         * supplied in multiple CreateIcon calls, then it must be accessible
williamr@4:         * by AknIcon framework until it has signalled a matching amount
williamr@4:         * of these callbacks.
williamr@4:         */
williamr@4:         virtual void Finished() = 0;
williamr@4:     };
williamr@4: 
williamr@4: /**
williamr@4: * AknIconUtils
williamr@4: *
williamr@4: * Note: The CFbsBitmap objects for bitmaps and mask returned by this class
williamr@4: * may be compressed in background. 
williamr@4: * Client code directly accessing the bitmap pixel data should not
williamr@4: * assume that the bitmap and mask objects are not compressed. 
williamr@4: *
williamr@4: * Bitmap compression can be disabled for an icon if desired using
williamr@4: * AknIconUtils::DisableCompression().
williamr@4: */
williamr@4: class AknIconUtils
williamr@4:     {
williamr@4:     public:
williamr@4: 
williamr@4:         /**
williamr@4:         * Creates bitmap and mask for an icon.
williamr@4:         * Allocates bitmap and mask objects and sets aBitmap and
williamr@4:         * aMask to point at them. Ownership of those is transferred to the caller.
williamr@4:         * These bitmaps are not ready for drawing until they are initialized with
williamr@4:         * SetSize method. Usually, UI controls do this.
williamr@4:         *
williamr@4:         * Use this method only if aBitmap and aMask are member variables.
williamr@4:         * Otherwise, use method CreateIconLC.
williamr@4:         *
williamr@4:         * @since 2.8
williamr@4:         * @param aBitmap icon bitmap is stored here
williamr@4:         * @param aMask icon mask is stored here
williamr@4:         * @param aFileName File name. Can be either MBM or MIF file.
williamr@4:         * Extension is changed based on the given bitmap ID.
williamr@4:         * @param aBitmapId bitmap Id
williamr@4:         * @param aMaskId mask Id
williamr@4:         */
williamr@4:         IMPORT_C static void CreateIconL(
williamr@4:             CFbsBitmap*& aBitmap,
williamr@4:             CFbsBitmap*& aMask,
williamr@4:             const TDesC& aFileName,
williamr@4:             TInt aBitmapId,
williamr@4:             TInt aMaskId );
williamr@4: 
williamr@4:         /**
williamr@4:         * Creates bitmap and mask for an icon.
williamr@4:         * Allocates bitmap and mask objects and sets aBitmap and
williamr@4:         * aMask to point at them. Ownership of those is transferred to the caller.
williamr@4:         * These bitmaps are not ready for drawing until they are initialized with
williamr@4:         * SetSize method. Usually, UI controls do this.
williamr@4:         *
williamr@4:         * This method puts both aBitmap and aMask in the cleanup stack.
williamr@4:         *
williamr@4:         * @since 2.8
williamr@4:         * @param aBitmap icon bitmap is stored here
williamr@4:         * @param aMask icon mask is stored here
williamr@4:         * @param aFileName File name. Can be either MBM or MIF file.
williamr@4:         * Extension is changed based on the given bitmap ID.
williamr@4:         * @param aBitmapId bitmap ID
williamr@4:         * @param aMaskId mask ID
williamr@4:         */
williamr@4:         IMPORT_C static void CreateIconLC(
williamr@4:             CFbsBitmap*& aBitmap,
williamr@4:             CFbsBitmap*& aMask,
williamr@4:             const TDesC& aFileName,
williamr@4:             TInt aBitmapId,
williamr@4:             TInt aMaskId );
williamr@4: 
williamr@4:         /**
williamr@4:         * Creates the bitmap for an icon.
williamr@4:         * Use this variant when a mask is not needed.
williamr@4:         * Ownership of the returned object is transferred to the caller.
williamr@4:         * The bitmap is not ready for drawing until it is initialized with
williamr@4:         * SetSize method. Usually, UI controls do this.
williamr@4:         *
williamr@4:         * @since 2.8
williamr@4:         * @param aBitmap icon bitmap is stored here
williamr@4:         * @param aFileName File name. Can be either MBM or MIF file.
williamr@4:         * Extension is changed based on the given bitmap ID.
williamr@4:         * @param aBitmapId bitmap ID
williamr@4:         */
williamr@4:         IMPORT_C static CFbsBitmap* CreateIconL(
williamr@4:             const TDesC& aFileName,
williamr@4:             TInt aBitmapId );
williamr@4: 
williamr@4:         /**
williamr@4:         * Creates bitmap and mask for an icon.
williamr@4:         * Allocates bitmap and mask objects and sets aBitmap and
williamr@4:         * aMask to point at them. Ownership of those is transferred to the caller.
williamr@4:         * These bitmaps are not ready for drawing until they are initialized with
williamr@4:         * SetSize method. Usually, UI controls do this.
williamr@4:         *
williamr@4:         * If this method leaves, MAknIconFileProvider::Finished is called for the
williamr@4:         * supplied aFileProvider.
williamr@4:         *
williamr@4:         * Use this method only if aBitmap and aMask are member variables.
williamr@4:         * Otherwise, use method CreateIconLC.
williamr@4:         *
williamr@4:         * @since 3.0
williamr@4:         * @param aBitmap icon bitmap is stored here
williamr@4:         * @param aMask icon mask is stored here
williamr@4:         * @param aFileProvider Icon file handle provider.
williamr@4:         * @param aBitmapId bitmap Id
williamr@4:         * @param aMaskId mask Id
williamr@4:         */
williamr@4:         IMPORT_C static void CreateIconL(
williamr@4:             CFbsBitmap*& aBitmap,
williamr@4:             CFbsBitmap*& aMask,
williamr@4:             MAknIconFileProvider& aFileProvider,
williamr@4:             TInt aBitmapId,
williamr@4:             TInt aMaskId );
williamr@4: 
williamr@4:         /**
williamr@4:         * Creates bitmap and mask for an icon.
williamr@4:         * Allocates bitmap and mask objects and sets aBitmap and
williamr@4:         * aMask to point at them. Ownership of those is transferred to the caller.
williamr@4:         * These bitmaps are not ready for drawing until they are initialized with
williamr@4:         * SetSize method. Usually, UI controls do this.
williamr@4:         *
williamr@4:         * This method puts both aBitmap and aMask in the cleanup stack.
williamr@4:         *
williamr@4:         * If this method leaves, MAknIconFileProvider::Finished is called for the
williamr@4:         * supplied aFileProvider.
williamr@4:         *
williamr@4:         * @since 3.0
williamr@4:         * @param aBitmap icon bitmap is stored here
williamr@4:         * @param aMask icon mask is stored here
williamr@4:         * @param aFileProvider Icon file handle provider.
williamr@4:         * @param aBitmapId bitmap Id
williamr@4:         * @param aMaskId mask Id
williamr@4:         */
williamr@4:         IMPORT_C static void CreateIconLC(
williamr@4:             CFbsBitmap*& aBitmap,
williamr@4:             CFbsBitmap*& aMask,
williamr@4:             MAknIconFileProvider& aFileProvider,
williamr@4:             TInt aBitmapId,
williamr@4:             TInt aMaskId );
williamr@4: 
williamr@4:         /**
williamr@4:         * Creates the bitmap for an icon.
williamr@4:         * Use this variant when a mask is not needed.
williamr@4:         * Ownership of the returned object is transferred to the caller.
williamr@4:         * The bitmap is not ready for drawing until it is initialized with
williamr@4:         * SetSize method. Usually, UI controls do this.
williamr@4:         *
williamr@4:         * If this method leaves, MAknIconFileProvider::Finished is called for the
williamr@4:         * supplied aFileProvider.
williamr@4:         *
williamr@4:         * @since 3.0
williamr@4:         * @param aFileProvider Icon file handle provider.
williamr@4:         * @param aBitmapId bitmap ID
williamr@4:         * @return The icon bitmap.
williamr@4:         */
williamr@4:         IMPORT_C static CFbsBitmap* CreateIconL(
williamr@4:             MAknIconFileProvider& aFileProvider,
williamr@4:             TInt aBitmapId );
williamr@4: 
williamr@4:         /**
williamr@4:         * Preserves the icon data (e.g. SVG-T data) related to the given icon
williamr@4:         * in memory. After this, the icon data is destroyed when either
williamr@4:         * DestroyIconData is explicitly called or the bitmap(s) of the icon are
williamr@4:         * deleted.
williamr@4:         *
williamr@4:         * This method should be called to improve performance if more than one
williamr@4:         * call to methods SetSize, SetSizeAndRotation or GetContentDimensions
williamr@4:         * is made successively on a particular icon. It should be called prior
williamr@4:         * to the above-mentioned calls. Without calling this method,
williamr@4:         * the icon data is destroyed after any of the method calls mentioned
williamr@4:         * above and then loaded from the storage medium and parsed from scratch
williamr@4:         * again in a new operation.
williamr@4:         *
williamr@4:         * Note! Icon data may consume considerable amounts of memory. In order
williamr@4:         * to save memory, any code that calls PreserveIconData should also
williamr@4:         * explicitly call DestroyIconData when the icon data is no longer
williamr@4:         * required.
williamr@4:         *
williamr@4:         * @since 2.8
williamr@4:         * @param aBitmap bitmap or mask of the icon.
williamr@4:         */
williamr@4:         IMPORT_C static void PreserveIconData( CFbsBitmap* aBitmap );
williamr@4: 
williamr@4:         /**
williamr@4:         * Destroys the icon data related to the given icon,
williamr@4:         * if it was preserved in memory. Note that this does not affect
williamr@4:         * the rendered frame buffers (CFbsBitmap objects).
williamr@4:         *
williamr@4:         * @since 2.8
williamr@4:         * @param aBitmap bitmap or mask of the icon.
williamr@4:         */
williamr@4:         IMPORT_C static void DestroyIconData( CFbsBitmap* aBitmap );
williamr@4: 
williamr@4:         /**
williamr@4:         * Initializes the icon to the given size, if the parameter aBitmap is
williamr@4:         * an instance of CAknBitmap, i.e. created with AknIconUtils methods.
williamr@4:         * If it is not CAknBitmap, this method does nothing. Note that this call
williamr@4:         * sets the sizes of both bitmap and mask (if it exists), regardless of
williamr@4:         * which is given as the parameter.
williamr@4:         *
williamr@4:         * @since 2.8
williamr@4:         * @param aBitmap bitmap or mask of the icon
williamr@4:         * @param aSize icon size
williamr@4:         * @param aMode scale mode
williamr@4:         * @return Standard Symbian OS error code. In error cases, it is guaranteed
williamr@4:         * that the returned bitmap is a valid CFbsBitmap, but there is no guarantee
williamr@4:         * of its size, except that it is non-negative.
williamr@4:         */
williamr@4:         IMPORT_C static TInt SetSize(
williamr@4:             CFbsBitmap* aBitmap,
williamr@4:             const TSize& aSize,
williamr@4:             TScaleMode aMode = EAspectRatioPreserved );
williamr@4: 
williamr@4:         /**
williamr@4:         * Initializes the icon to the given size, if the parameter aBitmap is
williamr@4:         * an instance of CAknBitmap, i.e. created with AknIconUtils methods.
williamr@4:         * If it is not CAknBitmap, this method does nothing. Note that this call
williamr@4:         * sets the sizes of both bitmap and mask (if it exists), regardless of
williamr@4:         * which is given as the parameter. Additionally, this method rotates
williamr@4:         * the icon according to the given angle.
williamr@4:         *
williamr@4:         * @since 2.8
williamr@4:         * @param aBitmap bitmap or mask of the icon
williamr@4:         * @param aSize icon size
williamr@4:         * @param aAngle Rotation angle in degrees.
williamr@4:         * @return Standard Symbian OS error code. In error cases, it is guaranteed
williamr@4:         * that the returned bitmap is a valid CFbsBitmap, but there is no guarantee
williamr@4:         * of its size, except that it is non-negative.
williamr@4:         */
williamr@4:         IMPORT_C static TInt SetSizeAndRotation(
williamr@4:             CFbsBitmap* aBitmap,
williamr@4:             const TSize& aSize,
williamr@4:             TScaleMode aMode,
williamr@4:             TInt aAngle );
williamr@4: 
williamr@4:         /**
williamr@4:         * Sets observer for change notification.
williamr@4:         * 
williamr@4:         * The method BitmapChanged() will be called when the contents of the CFbsBitmap
williamr@4:         * are changed. Controls can use this to redraw themselves when icon
williamr@4:         * animation progresses.
williamr@4:         * 
williamr@4:         * @since 2.8
williamr@4:         * @param aBitmap bitmap
williamr@4:         * @param aObserver observer
williamr@4:         */
williamr@4:         IMPORT_C static void SetObserver( CFbsBitmap* aBitmap, MAknIconObserver* aObserver );
williamr@4: 
williamr@4:         /**
williamr@4:         * Returns the file name of Avkon's icon file, containing full path.
williamr@4:         *
williamr@4:         * @since 2.8
williamr@4:         * @ret Avkon's icon file name, containing full path.
williamr@4:         */
williamr@4:         IMPORT_C static const TDesC& AvkonIconFileName();
williamr@4: 
williamr@4:         /**
williamr@4:         * Validates logical app icon ID so that it can be used as a parameter to
williamr@4:         * CreateIconL or CreateIconLC. If the given icon file name is .MBM file,
williamr@4:         * this method does nothing. If it is .MIF file, a predefined offset is
williamr@4:         * added to the given IDs.
williamr@4:         *
williamr@4:         * This method is only intended to be used when loading icons from the
williamr@4:         * icon file retrieved from AppArc.
williamr@4:         *
williamr@4:         * @param aIconFileName Icon file name retrieved from AppArc.
williamr@4:         * @param aId Logical bitmap ID used in the app icon file, usually 0.
williamr@4:         * @param aId Logical mask ID used in the app icon file, usually 1.
williamr@4:         */
williamr@4:         IMPORT_C static void ValidateLogicalAppIconId( 
williamr@4:             const TDesC& aIconFileName,
williamr@4:             TInt& aBitmapId,
williamr@4:             TInt& aMaskId );
williamr@4: 
williamr@4:         /**
williamr@4:         * Tells whether the given file name is recognized as a MIF file or not.
williamr@4:         * Only the file name extension is examined, not the contents of the file.
williamr@4:         *
williamr@4:         * @since 2.8
williamr@4:         * @param aFileName file name
williamr@4:         *
williamr@4:         * @return ETrue if MIF file, EFalse otherwise.
williamr@4:         */
williamr@4:         IMPORT_C static TBool IsMifFile( const TDesC& aFileName );
williamr@4: 
williamr@4:         /**
williamr@4:         * Tells whether the given bitmap is a part of a MIF icon or not.
williamr@4:         * Accepts any pointer (also NULL) as a parameter.
williamr@4:         *
williamr@4:         * @since 2.8
williamr@4:         * @param aBitmap bitmap
williamr@4:         *
williamr@4:         * @return ETrue if the given bitmap is part of a MIF icon,
williamr@4:         * EFalse otherwise.
williamr@4:         */
williamr@4:         IMPORT_C static TBool IsMifIcon( const CFbsBitmap* aBitmap );
williamr@4: 
williamr@4:         /**
williamr@4:         * Returns the content dimensions of the given icon.
williamr@4:         * In case of MBM icons, this is the original size of the bitmap.
williamr@4:         * In case of SVG icons, this is defined in the icon data.
williamr@4:         *
williamr@4:         * If SetSize or SetSizeAndRotation is going to be called on the same
williamr@4:         * icon after this call, the performance can be improved by calling
williamr@4:         * PreserveIconData before calling this method.
williamr@4:         * 
williamr@4:         * @deprecated
williamr@4:         * @since 2.8
williamr@4:         * @param aBitmap bitmap
williamr@4:         * @param aContentDimensions The content dimensions are returned here.
williamr@4:         *
williamr@4:         * @ret Standard Symbian OS error code.
williamr@4:         */
williamr@4:         IMPORT_C static TInt GetContentDimensions(
williamr@4:             CFbsBitmap* aBitmap,
williamr@4:             TSize& aContentDimensions );
williamr@4:             
williamr@4:         /**
williamr@4:         * Returns the content dimensions of the given icon.
williamr@4:         * In case of MBM icons, this is the original size of the bitmap.
williamr@4:         * In case of SVG icons, this is defined in the icon data.
williamr@4:         *
williamr@4:         * If SetSize or SetSizeAndRotation is going to be called on the same
williamr@4:         * icon after this call, the performance can be improved by calling
williamr@4:         * PreserveIconData before calling this method.
williamr@4:         * 
williamr@4:         * @since 3.0
williamr@4:         * @param aBitmap bitmap
williamr@4:         * @param aContentDimensions The content dimensions are returned here.
williamr@4:         *
williamr@4:         * @ret Standard Symbian OS error code.
williamr@4:         */
williamr@4:         IMPORT_C static TInt GetContentDimensions(
williamr@4:             CFbsBitmap* aBitmap,
williamr@4:             TAknContentDimensions& aContentDimensions );
williamr@4:             
williamr@4: 
williamr@4:         /**
williamr@4:         * Creates bitmap and mask for an icon.
williamr@4:         * Allocates bitmap and mask objects and sets aResultIcon to point at them.
williamr@4:         *
williamr@4:         * When this method returns, the resulting bitmaps are
williamr@4:         * duplicates of the source bitmaps.
williamr@4:         * Also the source bitmap instances are preserved in memory.
williamr@4:         *
williamr@4:         * Ownership of aSourceIcon is transferred from caller.
williamr@4:         * This method takes the responsibility of deleting the object
williamr@4:         * even if the method leaves.
williamr@4:         *
williamr@4:         * The returned icon bitmaps are instances of CAknBitmap,
williamr@4:         * so AknIconUtils::SetSize is functional for them.
williamr@4:         *
williamr@4:         * AknIconUtils::SetSize first creates duplicates of the source bitmaps
williamr@4:         * and after that, if required, creates new bitmaps and performs scaling.
williamr@4:         *
williamr@4:         * Note that due to the additional memory consumption caused by the source bitmaps,
williamr@4:         * this method should only be used if it is not possible to use the variant of
williamr@4:         * CreateIconL that takes icon file name and IDs as parameters.
williamr@4:         *
williamr@4:         * @since 2.8
williamr@4:         *
williamr@4:         * @param aSourceIcon Contains source bitmap and mask.
williamr@4:         *   Ownership of aSourceIcon is transferred from caller.
williamr@4:         *   This method takes the responsibility of deleting the object
williamr@4:         *   even if the method leaves.
williamr@4:         *
williamr@4:         * @ret Resulting icon. Ownership transferred to the caller.
williamr@4:         */
williamr@4:         IMPORT_C static CAknIcon* CreateIconL( CAknIcon* aSourceIcon );
williamr@4: 
williamr@4:         /**
williamr@4:         * Non-masked variant of CreateIconL.
williamr@4:         *
williamr@4:         * Ownership of aSourceBitmap is transferred from caller.
williamr@4:         * This method takes the responsibility of deleting the object
williamr@4:         * even if the method leaves.
williamr@4:         * 
williamr@4:         * @since 2.8
williamr@4:         * @param aSourceBitmap Source bitmap.
williamr@4:         *   Ownership is transferred from caller.
williamr@4:         *   This method takes the responsibility of deleting the object
williamr@4:         *   even if the method leaves.
williamr@4:         *
williamr@4:         * @ret Resulting icon bitmap. Ownership transferred to the caller.
williamr@4:         */
williamr@4:         IMPORT_C static CFbsBitmap* CreateIconL( CFbsBitmap* aSourceBitmap );
williamr@4: 
williamr@4:         /**
williamr@4:         * Determines the icon color. Only effective if the given bitmap is
williamr@4:         * an instance of CAknBitmap. This method only needs to be called either
williamr@4:         * for the bitmap or the mask of an icon, but to be effective, it needs
williamr@4:         * to be called before calling SetSize or SetSizeAndRotation.
williamr@4:         *
williamr@4:         * @since 2.8
williamr@4:         * @param aBitmap bitmap
williamr@4:         * @param aColor icon color
williamr@4:         */
williamr@4:         IMPORT_C static void SetIconColor( CFbsBitmap* aBitmap, const TRgb aColor );
williamr@4:         
williamr@4:         
williamr@4:         /**
williamr@4:         * Excludes the icon form the icon cache.
williamr@4:         * Only effective if the given bitmap is an instance of CAknBitmap. This call
williamr@4:         * sets the sizes of both bitmap and mask (if it exists), regardless of
williamr@4:         * which is given as the parameter. 
williamr@4:         * This method should be called after calling CreateIconL or CreateIconLC
williamr@4:         * and before calling AknIconUtils::SetSize.
williamr@4:         * 
williamr@4:         * By default icons are being put to icon cache after they are no longer used. 
williamr@4:         * This makes it possible to retrieve recently used icons fast without the need to
williamr@4:         * render them again.
williamr@4:         * The icon cache has a limited size and when the cache is full to cache new icons
williamr@4:         * the oldest icons from the cache will be removed.
williamr@4:         * In certain situations it might be feasible to exclude some icons from the
williamr@4:         * icon cache (e.g. in case of infrequently used large icons) to prevent some more
williamr@4:         * frequently used icon being kicked out from the cache. Excluding infrequently used
williamr@4:         * icons from icon cache could improve performance and memory usage of the system.
williamr@4:         * 
williamr@4:         * 
williamr@4:         * @since 3.1
williamr@4:         * @param aBitmap bitmap        
williamr@4:         */
williamr@4:         IMPORT_C static void ExcludeFromCache( CFbsBitmap* aBitmap );
williamr@4:         
williamr@4:         /**
williamr@4:         * Disables bitmap compression for the icon.
williamr@4:         * Only effective if the given bitmap is an instance of CAknBitmap. This call
williamr@4:         * prevents AknIcon framework from compressing the CFbsBitmap objects 
williamr@4:         * (bitmap, mask) of the icon.
williamr@4:         * This method should be called after calling CreateIconL or CreateIconLC
williamr@4:         * and before calling AknIconUtils::SetSize.
williamr@4:         * 
williamr@4:         * @since 3.1
williamr@4:         * @param aBitmap bitmap        
williamr@4:         */
williamr@4:         IMPORT_C static void DisableCompression( CFbsBitmap* aBitmap );
williamr@4:         
williamr@4: 
williamr@4:         /**
williamr@4:         * Performs bitmap scaling. 
williamr@4:         * Draws a source bitmap to fit a given rectangle within a target bitmap. 
williamr@4:         * This is ~15x faster than scaling with Symbian's DrawBitmap. Following
williamr@4:         * bitmap modes are supported: EGray256, EColor4K, EColor64K, EColor256,
williamr@4:         * EColor16MU. For all other bitmap modes, Symbian's DrawBitmap API will
williamr@4:         * be used. Bitmap modes of the source and target bitmap should be the 
williamr@4:         * same.
williamr@4:         * @ since 3.2
williamr@4:         * @ param aTrgRect  target rect inside the target bitmap
williamr@4:         * @ param aTrgBitmap the target bitmap 
williamr@4:         * @ param aSrcBitmap the source bitmap 
williamr@4:         * @leave KErrArgument
williamr@4:         *        If source bitmap mode is not the same as target bitmap mode.
williamr@4:         * @leave Any other Symbian OS specific error codes.
williamr@4:         */
williamr@4:         IMPORT_C static void ScaleBitmapL( 
williamr@4:             const TRect& aTrgRect,
williamr@4:             CFbsBitmap* aTrgBitmap,
williamr@4:             CFbsBitmap* aSrcBitmap );
williamr@4: 
williamr@4:         /**
williamr@4:         * Bitmap rotation and scaling. Might be exported later. Scales and
williamr@4:         * rotates the given bitmap according to the parameters. Supported 
williamr@4:         * bitmap modes are EGray2, EGray256, EColor256, EColor4K, EColor64K and 
williamr@4:         * EColor16MU. All other bitmap depts will cause a leave with
williamr@4:         * KErrNotSupported. The only supported scalemode is 
williamr@4:         * EAspectRatioPreserved. The unused area in the target bitmap is
williamr@4:         * filled with black color unless the bitmap depth is EGray8 when the
williamr@4:         * area is filled with white. Areas that do not fit to the target area
williamr@4:         * after rotation are clipped out
williamr@4:         *
williamr@4:         * If the bitmap depth is EGray2, the routine will perform noticeably worse.
williamr@4:         * 
williamr@4:         * @param aTrgRect target rect inside the target bitmap
williamr@4:         * @param aTrgBitmap the target bitmap
williamr@4:         * @param aSrcBitmap the source bitmap
williamr@4:         * @param aAngle the rotation angle in degrees
williamr@4:         */
williamr@4:         static void RotateAndScaleBitmapL(
williamr@4:             const TRect& aTrgRect,
williamr@4:             CFbsBitmap* aTrgBitmap, 
williamr@4:             CFbsBitmap* aSrcBitmap,
williamr@4:             TInt aAngle );
williamr@4: 
williamr@4:         /**
williamr@4:          * @internal
williamr@4:          */
williamr@4:         static TBool DoesScaleBitmapUseFallBack( 
williamr@4:             CFbsBitmap* aSrcBitmap );
williamr@4: 
williamr@4:         /**
williamr@4:          * @internal
williamr@4:          */
williamr@4:         static void ScaleBitmapExtL( 
williamr@4:             const TRect& aTrgRect,
williamr@4:             CFbsBitmap* aTrgBitmap,
williamr@4:             CFbsBitmap* aSrcBitmap,
williamr@4:             TBool aForceFallBack );
williamr@4:             
williamr@4:     private:
williamr@4: 
williamr@4:         /**
williamr@4:         * Utility for down-cast of CFbsBitmap objects. It informs whether
williamr@4:         * the given CFbsBitmap is CAknBitmap or not. A list of CAknBitmap
williamr@4:         * pointers is managed in TLS for this.
williamr@4:         * 
williamr@4:         * @param aBitmap bitmap
williamr@4:         * @ret ETrue iff the given CFbsBitmap is an CAknBitmap instance.
williamr@4:         */
williamr@4:         static TBool IsAknBitmap( const CFbsBitmap* aBitmap );
williamr@4:         
williamr@4:         /**
williamr@4:         * Internal utility.
williamr@4:         */
williamr@4:         static void CreateIconLC(
williamr@4:             CFbsBitmap*& aBitmap,
williamr@4:             CFbsBitmap*& aMask,
williamr@4:             const TDesC& aFileName,
williamr@4:             TInt aBitmapId,
williamr@4:             TInt aMaskId,
williamr@4:             MAknIconFileProvider* aFileProvider );
williamr@4: 
williamr@4:         /**
williamr@4:         * Internal utility.
williamr@4:         * @deprecated
williamr@4:         */
williamr@4:         static void CreateIconLC(
williamr@4:             CFbsBitmap*& aBitmap,
williamr@4:             CFbsBitmap*& aMask,
williamr@4:             const TDesC& aFileName,
williamr@4:             TInt aBitmapId,
williamr@4:             TInt aMaskId,
williamr@4:             RFile& aFile );
williamr@4:         
williamr@4:     private:
williamr@4: 
williamr@4:         AknIconUtils();
williamr@4:     };
williamr@4: 
williamr@4: #include "AknIconUtils.inl"
williamr@4: #endif // AKN_ICON_UTILS_H
williamr@4:             
williamr@4: // End of File