diff -r e1b950c65cb4 -r 837f303aceeb epoc32/include/mw/AknIconUtils.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/epoc32/include/mw/AknIconUtils.h Wed Mar 31 12:33:34 2010 +0100 @@ -0,0 +1,781 @@ +/* +* 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 +#include + +// 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. + * + * @since 2.8 + * @param aBitmap bitmap + * + * @return ETrue if the given bitmap is part of a MIF icon, + * EFalse otherwise. + */ + IMPORT_C static TBool IsMifIcon( const CFbsBitmap* aBitmap ); + + /** + * Returns the content dimensions of the given icon. + * In case of MBM icons, this is the original size of the bitmap. + * In case of SVG icons, this is defined in the icon data. + * + * If SetSize or SetSizeAndRotation is going to be called on the same + * icon after this call, the performance can be improved by calling + * PreserveIconData before calling this method. + * + * @deprecated + * @since 2.8 + * @param aBitmap bitmap + * @param aContentDimensions The content dimensions are returned here. + * + * @ret Standard Symbian OS error code. + */ + IMPORT_C static TInt GetContentDimensions( + CFbsBitmap* aBitmap, + TSize& aContentDimensions ); + + /** + * Returns the content dimensions of the given icon. + * In case of MBM icons, this is the original size of the bitmap. + * In case of SVG icons, this is defined in the icon data. + * + * If SetSize or SetSizeAndRotation is going to be called on the same + * icon after this call, the performance can be improved by calling + * PreserveIconData before calling this method. + * + * @since 3.0 + * @param aBitmap bitmap + * @param aContentDimensions The content dimensions are returned here. + * + * @ret Standard Symbian OS error code. + */ + IMPORT_C static TInt GetContentDimensions( + CFbsBitmap* aBitmap, + TAknContentDimensions& aContentDimensions ); + + + /** + * Creates bitmap and mask for an icon. + * Allocates bitmap and mask objects and sets aResultIcon to point at them. + * + * When this method returns, the resulting bitmaps are + * duplicates of the source bitmaps. + * Also the source bitmap instances are preserved in memory. + * + * Ownership of aSourceIcon is transferred from caller. + * This method takes the responsibility of deleting the object + * even if the method leaves. + * + * The returned icon bitmaps are instances of CAknBitmap, + * so AknIconUtils::SetSize is functional for them. + * + * AknIconUtils::SetSize first creates duplicates of the source bitmaps + * and after that, if required, creates new bitmaps and performs scaling. + * + * Note that due to the additional memory consumption caused by the source bitmaps, + * this method should only be used if it is not possible to use the variant of + * CreateIconL that takes icon file name and IDs as parameters. + * + * @since 2.8 + * + * @param aSourceIcon Contains source bitmap and mask. + * Ownership of aSourceIcon is transferred from caller. + * This method takes the responsibility of deleting the object + * even if the method leaves. + * + * @ret Resulting icon. Ownership transferred to the caller. + */ + IMPORT_C static CAknIcon* CreateIconL( CAknIcon* aSourceIcon ); + + /** + * Non-masked variant of CreateIconL. + * + * Ownership of aSourceBitmap is transferred from caller. + * This method takes the responsibility of deleting the object + * even if the method leaves. + * + * @since 2.8 + * @param aSourceBitmap Source bitmap. + * Ownership is transferred from caller. + * This method takes the responsibility of deleting the object + * even if the method leaves. + * + * @ret Resulting icon bitmap. Ownership transferred to the caller. + */ + IMPORT_C static CFbsBitmap* CreateIconL( CFbsBitmap* aSourceBitmap ); + + /** + * Determines the icon color. Only effective if the given bitmap is + * an instance of CAknBitmap. This method only needs to be called either + * for the bitmap or the mask of an icon, but to be effective, it needs + * to be called before calling SetSize or SetSizeAndRotation. + * + * @since 2.8 + * @param aBitmap bitmap + * @param aColor icon color + */ + IMPORT_C static void SetIconColor( CFbsBitmap* aBitmap, const TRgb aColor ); + + + /** + * Excludes the icon form the icon cache. + * Only effective if the given bitmap is an instance of CAknBitmap. This call + * sets the sizes of both bitmap and mask (if it exists), regardless of + * which is given as the parameter. + * This method should be called after calling CreateIconL or CreateIconLC + * and before calling AknIconUtils::SetSize. + * + * By default icons are being put to icon cache after they are no longer used. + * This makes it possible to retrieve recently used icons fast without the need to + * render them again. + * The icon cache has a limited size and when the cache is full to cache new icons + * the oldest icons from the cache will be removed. + * In certain situations it might be feasible to exclude some icons from the + * icon cache (e.g. in case of infrequently used large icons) to prevent some more + * frequently used icon being kicked out from the cache. Excluding infrequently used + * icons from icon cache could improve performance and memory usage of the system. + * + * + * @since 3.1 + * @param aBitmap bitmap + */ + IMPORT_C static void ExcludeFromCache( CFbsBitmap* aBitmap ); + + /** + * Disables bitmap compression for the icon. + * Only effective if the given bitmap is an instance of CAknBitmap. This call + * prevents AknIcon framework from compressing the CFbsBitmap objects + * (bitmap, mask) of the icon. + * This method should be called after calling CreateIconL or CreateIconLC + * and before calling AknIconUtils::SetSize. + * + * @since 3.1 + * @param aBitmap bitmap + */ + IMPORT_C static void DisableCompression( CFbsBitmap* aBitmap ); + + + /** + * Performs bitmap scaling. + * Draws a source bitmap to fit a given rectangle within a target bitmap. + * This is ~15x faster than scaling with Symbian's DrawBitmap. Following + * bitmap modes are supported: EGray256, EColor4K, EColor64K, EColor256, + * EColor16MU. For all other bitmap modes, Symbian's DrawBitmap API will + * be used. Bitmap modes of the source and target bitmap should be the + * same. + * @ since 3.2 + * @ param aTrgRect target rect inside the target bitmap + * @ param aTrgBitmap the target bitmap + * @ param aSrcBitmap the source bitmap + * @leave KErrArgument + * If source bitmap mode is not the same as target bitmap mode. + * @leave Any other Symbian OS specific error codes. + */ + IMPORT_C static void ScaleBitmapL( + const TRect& aTrgRect, + CFbsBitmap* aTrgBitmap, + CFbsBitmap* aSrcBitmap ); + + /** + * Bitmap rotation and scaling. Might be exported later. Scales and + * rotates the given bitmap according to the parameters. Supported + * bitmap modes are EGray2, EGray256, EColor256, EColor4K, EColor64K and + * EColor16MU. All other bitmap depts will cause a leave with + * KErrNotSupported. The only supported scalemode is + * EAspectRatioPreserved. The unused area in the target bitmap is + * filled with black color unless the bitmap depth is EGray8 when the + * area is filled with white. Areas that do not fit to the target area + * after rotation are clipped out + * + * If the bitmap depth is EGray2, the routine will perform noticeably worse. + * + * @param aTrgRect target rect inside the target bitmap + * @param aTrgBitmap the target bitmap + * @param aSrcBitmap the source bitmap + * @param aAngle the rotation angle in degrees + */ + static void RotateAndScaleBitmapL( + const TRect& aTrgRect, + CFbsBitmap* aTrgBitmap, + CFbsBitmap* aSrcBitmap, + TInt aAngle ); + + /** + * @internal + */ + static TBool DoesScaleBitmapUseFallBack( + CFbsBitmap* aSrcBitmap ); + + /** + * @internal + */ + static void ScaleBitmapExtL( + const TRect& aTrgRect, + CFbsBitmap* aTrgBitmap, + CFbsBitmap* aSrcBitmap, + TBool aForceFallBack ); + + private: + + /** + * Utility for down-cast of CFbsBitmap objects. It informs whether + * the given CFbsBitmap is CAknBitmap or not. A list of CAknBitmap + * pointers is managed in TLS for this. + * + * @param aBitmap bitmap + * @ret ETrue iff the given CFbsBitmap is an CAknBitmap instance. + */ + static TBool IsAknBitmap( const CFbsBitmap* aBitmap ); + + /** + * Internal utility. + */ + static void CreateIconLC( + CFbsBitmap*& aBitmap, + CFbsBitmap*& aMask, + const TDesC& aFileName, + TInt aBitmapId, + TInt aMaskId, + MAknIconFileProvider* aFileProvider ); + + /** + * Internal utility. + * @deprecated + */ + static void CreateIconLC( + CFbsBitmap*& aBitmap, + CFbsBitmap*& aMask, + const TDesC& aFileName, + TInt aBitmapId, + TInt aMaskId, + RFile& aFile ); + + private: + + AknIconUtils(); + }; + +#include "AknIconUtils.inl" +#endif // AKN_ICON_UTILS_H + +// End of File