epoc32/include/mw/AknIconUtils.h
branchSymbian3
changeset 4 837f303aceeb
equal deleted inserted replaced
3:e1b950c65cb4 4:837f303aceeb
       
     1 /*
       
     2 * Copyright (c) 2002 Nokia Corporation and/or its subsidiary(-ies).
       
     3 * All rights reserved.
       
     4 * This component and the accompanying materials are made available
       
     5 * under the terms of "Eclipse Public License v1.0"
       
     6 * which accompanies this distribution, and is available
       
     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".
       
     8 *
       
     9 * Initial Contributors:
       
    10 * Nokia Corporation - initial contribution.
       
    11 *
       
    12 * Contributors:
       
    13 *
       
    14 * Description:   Utility functions related to scalable icons.
       
    15 *
       
    16 */
       
    17 
       
    18 
       
    19 
       
    20 
       
    21 #ifndef AKN_ICON_UTILS_H
       
    22 #define AKN_ICON_UTILS_H
       
    23 
       
    24 // INCLUDES
       
    25 #include <e32std.h>
       
    26 #include <gdi.h>
       
    27 
       
    28 // FORWARD DECLARATIONS
       
    29 class CFbsBitmap;
       
    30 class MAknIconObserver;
       
    31 
       
    32 // ENUMERATIONS
       
    33 enum TScaleMode
       
    34     {
       
    35     /*
       
    36     * Scales the icon to the maximum size that fits in the given size,
       
    37     * whilst preserving the aspect ratio of the icon. The sizes of the resulting
       
    38     * bitmaps are exactly of the given size. If the aspect ratio of
       
    39     * the given size differs from the aspect ratio of the icon,
       
    40     * the resulting bitmaps will contain an unused area.
       
    41     */
       
    42     EAspectRatioPreserved = 0,
       
    43 
       
    44     /*
       
    45     * Scales the icon to the maximum size that fits in the given size,
       
    46     * whilst preserving the aspect ratio of the icon. The resulting bitmaps
       
    47     * are resized so that any unused portion of the given size is not
       
    48     * present in them.
       
    49     *
       
    50     * This mode should be used when only the height or the width of the icon
       
    51     * is known and the other should be based on the aspect ratio of the icon.
       
    52     * The unknown dimension should be defined high enough (e.g. KMaxTInt) so
       
    53     * that it does not limit the scaling based on the aspect ratio of the icon.
       
    54     */
       
    55     EAspectRatioPreservedAndUnusedSpaceRemoved = 1,
       
    56 
       
    57     /*
       
    58     * Scales the icon exactly to the given size. Does not preserve the aspect
       
    59     * ratio of the icon.
       
    60     */
       
    61     EAspectRatioNotPreserved = 2,
       
    62         
       
    63     /*
       
    64     * Scales the icon to the minimum size that covers the given size,
       
    65     * whilst preserving the aspect ratio of the icon. The sizes of the resulting
       
    66     * bitmaps are exactly of the given size. If the aspect ratio of
       
    67     * the given size differs from the aspect ratio of the icon, some parts of the 
       
    68     * icon will be sliced from the resulting bitmaps.
       
    69     *
       
    70     * @since 3.1
       
    71     */
       
    72     EAspectRatioPreservedSlice = 3
       
    73     };
       
    74 
       
    75 // CLASS DECLARATIONS
       
    76 
       
    77 /**
       
    78 * Class for storing the content dimensions of icons.
       
    79 */
       
    80 class TAknContentDimensions
       
    81 	{
       
    82 	public:
       
    83 
       
    84         /**
       
    85          * C++ default constructor.
       
    86          */
       
    87         inline TAknContentDimensions();	
       
    88 
       
    89         /**
       
    90          * Constructor.
       
    91          *
       
    92          * @param aWidth Icons width.
       
    93          * @param aHeight Icons height.
       
    94          */
       
    95         inline TAknContentDimensions(TReal32 aWidth, TReal32 aHeight);
       
    96 
       
    97         /**
       
    98          * Sets the content dimensions.
       
    99          *
       
   100          * @param aWidth Width of the icon.
       
   101          * @param aHeight Height of the icon.
       
   102          */
       
   103         inline void SetDimensions(TReal32 aWidth, TReal32 aHeight);	
       
   104  
       
   105         /**
       
   106          * Sets the content size of the icon.
       
   107          *
       
   108          * @param aDimensions Two-dimensional size as a width and a height 
       
   109                               value of the icon.
       
   110          */
       
   111         inline void SetDimensions(const TSize& aDimensions);	
       
   112 
       
   113 	public:
       
   114     
       
   115         /** Icons width. */
       
   116         TReal32 iWidth;
       
   117 
       
   118         /** Icons height. */
       
   119 		TReal32 iHeight;
       
   120 	};
       
   121 
       
   122 /**
       
   123  * Cleanup stack helper. Owns the bitmap and the mask.
       
   124  */
       
   125 NONSHARABLE_CLASS(CAknIcon) : public CBase
       
   126     {
       
   127     public:
       
   128     
       
   129         /**
       
   130          * Two-phased constructor.
       
   131          *
       
   132          * Creates and returns a pointer to a new @c CAknIcon object.
       
   133          *
       
   134          * @return New @c CAknIcon.
       
   135          */
       
   136         IMPORT_C static CAknIcon* NewL();
       
   137     
       
   138         /**
       
   139          * Destructor.
       
   140          */
       
   141         ~CAknIcon();
       
   142     
       
   143     public:
       
   144     
       
   145         /**
       
   146          * Gets the bitmap.
       
   147          *
       
   148          * @return The icon's bitmap.
       
   149          */
       
   150         IMPORT_C CFbsBitmap* Bitmap() const;
       
   151     
       
   152         /**
       
   153          * Gets the mask.
       
   154          *
       
   155          * @return The icon's mask.
       
   156          */    
       
   157         IMPORT_C CFbsBitmap* Mask() const;
       
   158     
       
   159         /**
       
   160          * Sets the bitmap.
       
   161          *
       
   162          * @param aBitmap The icon's bitmap.
       
   163          */    
       
   164         IMPORT_C void SetBitmap( CFbsBitmap* aBitmap );
       
   165     
       
   166         /**
       
   167          * Sets the mask.
       
   168          *
       
   169          * @param aMask The icon's mask.
       
   170          */    
       
   171         IMPORT_C void SetMask( CFbsBitmap* aMask );
       
   172     
       
   173     private:
       
   174     
       
   175         /**
       
   176          * Default constructor.
       
   177          */
       
   178         inline CAknIcon() {}
       
   179 
       
   180     private:
       
   181     
       
   182         CFbsBitmap* iBitmap; // owned
       
   183         CFbsBitmap* iMask; // owned
       
   184     };
       
   185 
       
   186 /**
       
   187 * The purpose of this class is for clients to provide opened file handles
       
   188 * to icon files, which reside in private directories,
       
   189 * where AknIcon server has no access.
       
   190 *
       
   191 * MIF file is always generated, when building icons with MifConv tool.
       
   192 * The corresponding MBM file is generated only if there are bitmap icons
       
   193 * amongst the source icons.
       
   194 *
       
   195 */
       
   196 class MAknIconFileProvider
       
   197     {
       
   198     public:
       
   199 
       
   200         enum TIconFileType
       
   201             {
       
   202             EMbmFile = 0,
       
   203             EMifFile = 1
       
   204             };
       
   205 
       
   206     public:
       
   207 
       
   208         /**
       
   209         * Destructor.
       
   210         */
       
   211         virtual ~MAknIconFileProvider() {}
       
   212 
       
   213         /**
       
   214         * Returns an open file handle to the icon file.
       
   215         * This method should leave if an icon file with specified type does
       
   216         * not exist. That may be the case e.g. with MBM file,
       
   217         * if there are no bitmap icons.
       
   218         *
       
   219         * Note! RFs::ShareProtected must be called to the RFs instance used
       
   220         * for opening the file.
       
   221         *
       
   222         * @param aFile Icon file should be opened in this file handle, which
       
   223         * is an empty file handle, when the AknIcon framework calls this method.
       
   224         * The AknIcon framework takes care of closing the file handle after
       
   225         * having used it.
       
   226         * @param aType Icon file type.
       
   227         */
       
   228         virtual void RetrieveIconFileHandleL(
       
   229             RFile& aFile, const TIconFileType aType ) = 0;
       
   230 
       
   231         /**
       
   232         * With this method, AknIcon framework informs that it does not use
       
   233         * this MAknIconFileProvider instance any more. After this call,
       
   234         * it is ok to delete the object. This can be implemented simply
       
   235         * e.g. by deleting self in this callback.
       
   236         * Normally, this callback is invoked when the icon in question
       
   237         * is deleted.
       
   238         * Note, however, that if the same MAknIconFileProvider instance is
       
   239         * supplied in multiple CreateIcon calls, then it must be accessible
       
   240         * by AknIcon framework until it has signalled a matching amount
       
   241         * of these callbacks.
       
   242         */
       
   243         virtual void Finished() = 0;
       
   244     };
       
   245 
       
   246 /**
       
   247 * AknIconUtils
       
   248 *
       
   249 * Note: The CFbsBitmap objects for bitmaps and mask returned by this class
       
   250 * may be compressed in background. 
       
   251 * Client code directly accessing the bitmap pixel data should not
       
   252 * assume that the bitmap and mask objects are not compressed. 
       
   253 *
       
   254 * Bitmap compression can be disabled for an icon if desired using
       
   255 * AknIconUtils::DisableCompression().
       
   256 */
       
   257 class AknIconUtils
       
   258     {
       
   259     public:
       
   260 
       
   261         /**
       
   262         * Creates bitmap and mask for an icon.
       
   263         * Allocates bitmap and mask objects and sets aBitmap and
       
   264         * aMask to point at them. Ownership of those is transferred to the caller.
       
   265         * These bitmaps are not ready for drawing until they are initialized with
       
   266         * SetSize method. Usually, UI controls do this.
       
   267         *
       
   268         * Use this method only if aBitmap and aMask are member variables.
       
   269         * Otherwise, use method CreateIconLC.
       
   270         *
       
   271         * @since 2.8
       
   272         * @param aBitmap icon bitmap is stored here
       
   273         * @param aMask icon mask is stored here
       
   274         * @param aFileName File name. Can be either MBM or MIF file.
       
   275         * Extension is changed based on the given bitmap ID.
       
   276         * @param aBitmapId bitmap Id
       
   277         * @param aMaskId mask Id
       
   278         */
       
   279         IMPORT_C static void CreateIconL(
       
   280             CFbsBitmap*& aBitmap,
       
   281             CFbsBitmap*& aMask,
       
   282             const TDesC& aFileName,
       
   283             TInt aBitmapId,
       
   284             TInt aMaskId );
       
   285 
       
   286         /**
       
   287         * Creates bitmap and mask for an icon.
       
   288         * Allocates bitmap and mask objects and sets aBitmap and
       
   289         * aMask to point at them. Ownership of those is transferred to the caller.
       
   290         * These bitmaps are not ready for drawing until they are initialized with
       
   291         * SetSize method. Usually, UI controls do this.
       
   292         *
       
   293         * This method puts both aBitmap and aMask in the cleanup stack.
       
   294         *
       
   295         * @since 2.8
       
   296         * @param aBitmap icon bitmap is stored here
       
   297         * @param aMask icon mask is stored here
       
   298         * @param aFileName File name. Can be either MBM or MIF file.
       
   299         * Extension is changed based on the given bitmap ID.
       
   300         * @param aBitmapId bitmap ID
       
   301         * @param aMaskId mask ID
       
   302         */
       
   303         IMPORT_C static void CreateIconLC(
       
   304             CFbsBitmap*& aBitmap,
       
   305             CFbsBitmap*& aMask,
       
   306             const TDesC& aFileName,
       
   307             TInt aBitmapId,
       
   308             TInt aMaskId );
       
   309 
       
   310         /**
       
   311         * Creates the bitmap for an icon.
       
   312         * Use this variant when a mask is not needed.
       
   313         * Ownership of the returned object is transferred to the caller.
       
   314         * The bitmap is not ready for drawing until it is initialized with
       
   315         * SetSize method. Usually, UI controls do this.
       
   316         *
       
   317         * @since 2.8
       
   318         * @param aBitmap icon bitmap is stored here
       
   319         * @param aFileName File name. Can be either MBM or MIF file.
       
   320         * Extension is changed based on the given bitmap ID.
       
   321         * @param aBitmapId bitmap ID
       
   322         */
       
   323         IMPORT_C static CFbsBitmap* CreateIconL(
       
   324             const TDesC& aFileName,
       
   325             TInt aBitmapId );
       
   326 
       
   327         /**
       
   328         * Creates bitmap and mask for an icon.
       
   329         * Allocates bitmap and mask objects and sets aBitmap and
       
   330         * aMask to point at them. Ownership of those is transferred to the caller.
       
   331         * These bitmaps are not ready for drawing until they are initialized with
       
   332         * SetSize method. Usually, UI controls do this.
       
   333         *
       
   334         * If this method leaves, MAknIconFileProvider::Finished is called for the
       
   335         * supplied aFileProvider.
       
   336         *
       
   337         * Use this method only if aBitmap and aMask are member variables.
       
   338         * Otherwise, use method CreateIconLC.
       
   339         *
       
   340         * @since 3.0
       
   341         * @param aBitmap icon bitmap is stored here
       
   342         * @param aMask icon mask is stored here
       
   343         * @param aFileProvider Icon file handle provider.
       
   344         * @param aBitmapId bitmap Id
       
   345         * @param aMaskId mask Id
       
   346         */
       
   347         IMPORT_C static void CreateIconL(
       
   348             CFbsBitmap*& aBitmap,
       
   349             CFbsBitmap*& aMask,
       
   350             MAknIconFileProvider& aFileProvider,
       
   351             TInt aBitmapId,
       
   352             TInt aMaskId );
       
   353 
       
   354         /**
       
   355         * Creates bitmap and mask for an icon.
       
   356         * Allocates bitmap and mask objects and sets aBitmap and
       
   357         * aMask to point at them. Ownership of those is transferred to the caller.
       
   358         * These bitmaps are not ready for drawing until they are initialized with
       
   359         * SetSize method. Usually, UI controls do this.
       
   360         *
       
   361         * This method puts both aBitmap and aMask in the cleanup stack.
       
   362         *
       
   363         * If this method leaves, MAknIconFileProvider::Finished is called for the
       
   364         * supplied aFileProvider.
       
   365         *
       
   366         * @since 3.0
       
   367         * @param aBitmap icon bitmap is stored here
       
   368         * @param aMask icon mask is stored here
       
   369         * @param aFileProvider Icon file handle provider.
       
   370         * @param aBitmapId bitmap Id
       
   371         * @param aMaskId mask Id
       
   372         */
       
   373         IMPORT_C static void CreateIconLC(
       
   374             CFbsBitmap*& aBitmap,
       
   375             CFbsBitmap*& aMask,
       
   376             MAknIconFileProvider& aFileProvider,
       
   377             TInt aBitmapId,
       
   378             TInt aMaskId );
       
   379 
       
   380         /**
       
   381         * Creates the bitmap for an icon.
       
   382         * Use this variant when a mask is not needed.
       
   383         * Ownership of the returned object is transferred to the caller.
       
   384         * The bitmap is not ready for drawing until it is initialized with
       
   385         * SetSize method. Usually, UI controls do this.
       
   386         *
       
   387         * If this method leaves, MAknIconFileProvider::Finished is called for the
       
   388         * supplied aFileProvider.
       
   389         *
       
   390         * @since 3.0
       
   391         * @param aFileProvider Icon file handle provider.
       
   392         * @param aBitmapId bitmap ID
       
   393         * @return The icon bitmap.
       
   394         */
       
   395         IMPORT_C static CFbsBitmap* CreateIconL(
       
   396             MAknIconFileProvider& aFileProvider,
       
   397             TInt aBitmapId );
       
   398 
       
   399         /**
       
   400         * Preserves the icon data (e.g. SVG-T data) related to the given icon
       
   401         * in memory. After this, the icon data is destroyed when either
       
   402         * DestroyIconData is explicitly called or the bitmap(s) of the icon are
       
   403         * deleted.
       
   404         *
       
   405         * This method should be called to improve performance if more than one
       
   406         * call to methods SetSize, SetSizeAndRotation or GetContentDimensions
       
   407         * is made successively on a particular icon. It should be called prior
       
   408         * to the above-mentioned calls. Without calling this method,
       
   409         * the icon data is destroyed after any of the method calls mentioned
       
   410         * above and then loaded from the storage medium and parsed from scratch
       
   411         * again in a new operation.
       
   412         *
       
   413         * Note! Icon data may consume considerable amounts of memory. In order
       
   414         * to save memory, any code that calls PreserveIconData should also
       
   415         * explicitly call DestroyIconData when the icon data is no longer
       
   416         * required.
       
   417         *
       
   418         * @since 2.8
       
   419         * @param aBitmap bitmap or mask of the icon.
       
   420         */
       
   421         IMPORT_C static void PreserveIconData( CFbsBitmap* aBitmap );
       
   422 
       
   423         /**
       
   424         * Destroys the icon data related to the given icon,
       
   425         * if it was preserved in memory. Note that this does not affect
       
   426         * the rendered frame buffers (CFbsBitmap objects).
       
   427         *
       
   428         * @since 2.8
       
   429         * @param aBitmap bitmap or mask of the icon.
       
   430         */
       
   431         IMPORT_C static void DestroyIconData( CFbsBitmap* aBitmap );
       
   432 
       
   433         /**
       
   434         * Initializes the icon to the given size, if the parameter aBitmap is
       
   435         * an instance of CAknBitmap, i.e. created with AknIconUtils methods.
       
   436         * If it is not CAknBitmap, this method does nothing. Note that this call
       
   437         * sets the sizes of both bitmap and mask (if it exists), regardless of
       
   438         * which is given as the parameter.
       
   439         *
       
   440         * @since 2.8
       
   441         * @param aBitmap bitmap or mask of the icon
       
   442         * @param aSize icon size
       
   443         * @param aMode scale mode
       
   444         * @return Standard Symbian OS error code. In error cases, it is guaranteed
       
   445         * that the returned bitmap is a valid CFbsBitmap, but there is no guarantee
       
   446         * of its size, except that it is non-negative.
       
   447         */
       
   448         IMPORT_C static TInt SetSize(
       
   449             CFbsBitmap* aBitmap,
       
   450             const TSize& aSize,
       
   451             TScaleMode aMode = EAspectRatioPreserved );
       
   452 
       
   453         /**
       
   454         * Initializes the icon to the given size, if the parameter aBitmap is
       
   455         * an instance of CAknBitmap, i.e. created with AknIconUtils methods.
       
   456         * If it is not CAknBitmap, this method does nothing. Note that this call
       
   457         * sets the sizes of both bitmap and mask (if it exists), regardless of
       
   458         * which is given as the parameter. Additionally, this method rotates
       
   459         * the icon according to the given angle.
       
   460         *
       
   461         * @since 2.8
       
   462         * @param aBitmap bitmap or mask of the icon
       
   463         * @param aSize icon size
       
   464         * @param aAngle Rotation angle in degrees.
       
   465         * @return Standard Symbian OS error code. In error cases, it is guaranteed
       
   466         * that the returned bitmap is a valid CFbsBitmap, but there is no guarantee
       
   467         * of its size, except that it is non-negative.
       
   468         */
       
   469         IMPORT_C static TInt SetSizeAndRotation(
       
   470             CFbsBitmap* aBitmap,
       
   471             const TSize& aSize,
       
   472             TScaleMode aMode,
       
   473             TInt aAngle );
       
   474 
       
   475         /**
       
   476         * Sets observer for change notification.
       
   477         * 
       
   478         * The method BitmapChanged() will be called when the contents of the CFbsBitmap
       
   479         * are changed. Controls can use this to redraw themselves when icon
       
   480         * animation progresses.
       
   481         * 
       
   482         * @since 2.8
       
   483         * @param aBitmap bitmap
       
   484         * @param aObserver observer
       
   485         */
       
   486         IMPORT_C static void SetObserver( CFbsBitmap* aBitmap, MAknIconObserver* aObserver );
       
   487 
       
   488         /**
       
   489         * Returns the file name of Avkon's icon file, containing full path.
       
   490         *
       
   491         * @since 2.8
       
   492         * @ret Avkon's icon file name, containing full path.
       
   493         */
       
   494         IMPORT_C static const TDesC& AvkonIconFileName();
       
   495 
       
   496         /**
       
   497         * Validates logical app icon ID so that it can be used as a parameter to
       
   498         * CreateIconL or CreateIconLC. If the given icon file name is .MBM file,
       
   499         * this method does nothing. If it is .MIF file, a predefined offset is
       
   500         * added to the given IDs.
       
   501         *
       
   502         * This method is only intended to be used when loading icons from the
       
   503         * icon file retrieved from AppArc.
       
   504         *
       
   505         * @param aIconFileName Icon file name retrieved from AppArc.
       
   506         * @param aId Logical bitmap ID used in the app icon file, usually 0.
       
   507         * @param aId Logical mask ID used in the app icon file, usually 1.
       
   508         */
       
   509         IMPORT_C static void ValidateLogicalAppIconId( 
       
   510             const TDesC& aIconFileName,
       
   511             TInt& aBitmapId,
       
   512             TInt& aMaskId );
       
   513 
       
   514         /**
       
   515         * Tells whether the given file name is recognized as a MIF file or not.
       
   516         * Only the file name extension is examined, not the contents of the file.
       
   517         *
       
   518         * @since 2.8
       
   519         * @param aFileName file name
       
   520         *
       
   521         * @return ETrue if MIF file, EFalse otherwise.
       
   522         */
       
   523         IMPORT_C static TBool IsMifFile( const TDesC& aFileName );
       
   524 
       
   525         /**
       
   526         * Tells whether the given bitmap is a part of a MIF icon or not.
       
   527         * Accepts any pointer (also NULL) as a parameter.
       
   528         *
       
   529         * @since 2.8
       
   530         * @param aBitmap bitmap
       
   531         *
       
   532         * @return ETrue if the given bitmap is part of a MIF icon,
       
   533         * EFalse otherwise.
       
   534         */
       
   535         IMPORT_C static TBool IsMifIcon( const CFbsBitmap* aBitmap );
       
   536 
       
   537         /**
       
   538         * Returns the content dimensions of the given icon.
       
   539         * In case of MBM icons, this is the original size of the bitmap.
       
   540         * In case of SVG icons, this is defined in the icon data.
       
   541         *
       
   542         * If SetSize or SetSizeAndRotation is going to be called on the same
       
   543         * icon after this call, the performance can be improved by calling
       
   544         * PreserveIconData before calling this method.
       
   545         * 
       
   546         * @deprecated
       
   547         * @since 2.8
       
   548         * @param aBitmap bitmap
       
   549         * @param aContentDimensions The content dimensions are returned here.
       
   550         *
       
   551         * @ret Standard Symbian OS error code.
       
   552         */
       
   553         IMPORT_C static TInt GetContentDimensions(
       
   554             CFbsBitmap* aBitmap,
       
   555             TSize& aContentDimensions );
       
   556             
       
   557         /**
       
   558         * Returns the content dimensions of the given icon.
       
   559         * In case of MBM icons, this is the original size of the bitmap.
       
   560         * In case of SVG icons, this is defined in the icon data.
       
   561         *
       
   562         * If SetSize or SetSizeAndRotation is going to be called on the same
       
   563         * icon after this call, the performance can be improved by calling
       
   564         * PreserveIconData before calling this method.
       
   565         * 
       
   566         * @since 3.0
       
   567         * @param aBitmap bitmap
       
   568         * @param aContentDimensions The content dimensions are returned here.
       
   569         *
       
   570         * @ret Standard Symbian OS error code.
       
   571         */
       
   572         IMPORT_C static TInt GetContentDimensions(
       
   573             CFbsBitmap* aBitmap,
       
   574             TAknContentDimensions& aContentDimensions );
       
   575             
       
   576 
       
   577         /**
       
   578         * Creates bitmap and mask for an icon.
       
   579         * Allocates bitmap and mask objects and sets aResultIcon to point at them.
       
   580         *
       
   581         * When this method returns, the resulting bitmaps are
       
   582         * duplicates of the source bitmaps.
       
   583         * Also the source bitmap instances are preserved in memory.
       
   584         *
       
   585         * Ownership of aSourceIcon is transferred from caller.
       
   586         * This method takes the responsibility of deleting the object
       
   587         * even if the method leaves.
       
   588         *
       
   589         * The returned icon bitmaps are instances of CAknBitmap,
       
   590         * so AknIconUtils::SetSize is functional for them.
       
   591         *
       
   592         * AknIconUtils::SetSize first creates duplicates of the source bitmaps
       
   593         * and after that, if required, creates new bitmaps and performs scaling.
       
   594         *
       
   595         * Note that due to the additional memory consumption caused by the source bitmaps,
       
   596         * this method should only be used if it is not possible to use the variant of
       
   597         * CreateIconL that takes icon file name and IDs as parameters.
       
   598         *
       
   599         * @since 2.8
       
   600         *
       
   601         * @param aSourceIcon Contains source bitmap and mask.
       
   602         *   Ownership of aSourceIcon is transferred from caller.
       
   603         *   This method takes the responsibility of deleting the object
       
   604         *   even if the method leaves.
       
   605         *
       
   606         * @ret Resulting icon. Ownership transferred to the caller.
       
   607         */
       
   608         IMPORT_C static CAknIcon* CreateIconL( CAknIcon* aSourceIcon );
       
   609 
       
   610         /**
       
   611         * Non-masked variant of CreateIconL.
       
   612         *
       
   613         * Ownership of aSourceBitmap is transferred from caller.
       
   614         * This method takes the responsibility of deleting the object
       
   615         * even if the method leaves.
       
   616         * 
       
   617         * @since 2.8
       
   618         * @param aSourceBitmap Source bitmap.
       
   619         *   Ownership is transferred from caller.
       
   620         *   This method takes the responsibility of deleting the object
       
   621         *   even if the method leaves.
       
   622         *
       
   623         * @ret Resulting icon bitmap. Ownership transferred to the caller.
       
   624         */
       
   625         IMPORT_C static CFbsBitmap* CreateIconL( CFbsBitmap* aSourceBitmap );
       
   626 
       
   627         /**
       
   628         * Determines the icon color. Only effective if the given bitmap is
       
   629         * an instance of CAknBitmap. This method only needs to be called either
       
   630         * for the bitmap or the mask of an icon, but to be effective, it needs
       
   631         * to be called before calling SetSize or SetSizeAndRotation.
       
   632         *
       
   633         * @since 2.8
       
   634         * @param aBitmap bitmap
       
   635         * @param aColor icon color
       
   636         */
       
   637         IMPORT_C static void SetIconColor( CFbsBitmap* aBitmap, const TRgb aColor );
       
   638         
       
   639         
       
   640         /**
       
   641         * Excludes the icon form the icon cache.
       
   642         * Only effective if the given bitmap is an instance of CAknBitmap. This call
       
   643         * sets the sizes of both bitmap and mask (if it exists), regardless of
       
   644         * which is given as the parameter. 
       
   645         * This method should be called after calling CreateIconL or CreateIconLC
       
   646         * and before calling AknIconUtils::SetSize.
       
   647         * 
       
   648         * By default icons are being put to icon cache after they are no longer used. 
       
   649         * This makes it possible to retrieve recently used icons fast without the need to
       
   650         * render them again.
       
   651         * The icon cache has a limited size and when the cache is full to cache new icons
       
   652         * the oldest icons from the cache will be removed.
       
   653         * In certain situations it might be feasible to exclude some icons from the
       
   654         * icon cache (e.g. in case of infrequently used large icons) to prevent some more
       
   655         * frequently used icon being kicked out from the cache. Excluding infrequently used
       
   656         * icons from icon cache could improve performance and memory usage of the system.
       
   657         * 
       
   658         * 
       
   659         * @since 3.1
       
   660         * @param aBitmap bitmap        
       
   661         */
       
   662         IMPORT_C static void ExcludeFromCache( CFbsBitmap* aBitmap );
       
   663         
       
   664         /**
       
   665         * Disables bitmap compression for the icon.
       
   666         * Only effective if the given bitmap is an instance of CAknBitmap. This call
       
   667         * prevents AknIcon framework from compressing the CFbsBitmap objects 
       
   668         * (bitmap, mask) of the icon.
       
   669         * This method should be called after calling CreateIconL or CreateIconLC
       
   670         * and before calling AknIconUtils::SetSize.
       
   671         * 
       
   672         * @since 3.1
       
   673         * @param aBitmap bitmap        
       
   674         */
       
   675         IMPORT_C static void DisableCompression( CFbsBitmap* aBitmap );
       
   676         
       
   677 
       
   678         /**
       
   679         * Performs bitmap scaling. 
       
   680         * Draws a source bitmap to fit a given rectangle within a target bitmap. 
       
   681         * This is ~15x faster than scaling with Symbian's DrawBitmap. Following
       
   682         * bitmap modes are supported: EGray256, EColor4K, EColor64K, EColor256,
       
   683         * EColor16MU. For all other bitmap modes, Symbian's DrawBitmap API will
       
   684         * be used. Bitmap modes of the source and target bitmap should be the 
       
   685         * same.
       
   686         * @ since 3.2
       
   687         * @ param aTrgRect  target rect inside the target bitmap
       
   688         * @ param aTrgBitmap the target bitmap 
       
   689         * @ param aSrcBitmap the source bitmap 
       
   690         * @leave KErrArgument
       
   691         *        If source bitmap mode is not the same as target bitmap mode.
       
   692         * @leave Any other Symbian OS specific error codes.
       
   693         */
       
   694         IMPORT_C static void ScaleBitmapL( 
       
   695             const TRect& aTrgRect,
       
   696             CFbsBitmap* aTrgBitmap,
       
   697             CFbsBitmap* aSrcBitmap );
       
   698 
       
   699         /**
       
   700         * Bitmap rotation and scaling. Might be exported later. Scales and
       
   701         * rotates the given bitmap according to the parameters. Supported 
       
   702         * bitmap modes are EGray2, EGray256, EColor256, EColor4K, EColor64K and 
       
   703         * EColor16MU. All other bitmap depts will cause a leave with
       
   704         * KErrNotSupported. The only supported scalemode is 
       
   705         * EAspectRatioPreserved. The unused area in the target bitmap is
       
   706         * filled with black color unless the bitmap depth is EGray8 when the
       
   707         * area is filled with white. Areas that do not fit to the target area
       
   708         * after rotation are clipped out
       
   709         *
       
   710         * If the bitmap depth is EGray2, the routine will perform noticeably worse.
       
   711         * 
       
   712         * @param aTrgRect target rect inside the target bitmap
       
   713         * @param aTrgBitmap the target bitmap
       
   714         * @param aSrcBitmap the source bitmap
       
   715         * @param aAngle the rotation angle in degrees
       
   716         */
       
   717         static void RotateAndScaleBitmapL(
       
   718             const TRect& aTrgRect,
       
   719             CFbsBitmap* aTrgBitmap, 
       
   720             CFbsBitmap* aSrcBitmap,
       
   721             TInt aAngle );
       
   722 
       
   723         /**
       
   724          * @internal
       
   725          */
       
   726         static TBool DoesScaleBitmapUseFallBack( 
       
   727             CFbsBitmap* aSrcBitmap );
       
   728 
       
   729         /**
       
   730          * @internal
       
   731          */
       
   732         static void ScaleBitmapExtL( 
       
   733             const TRect& aTrgRect,
       
   734             CFbsBitmap* aTrgBitmap,
       
   735             CFbsBitmap* aSrcBitmap,
       
   736             TBool aForceFallBack );
       
   737             
       
   738     private:
       
   739 
       
   740         /**
       
   741         * Utility for down-cast of CFbsBitmap objects. It informs whether
       
   742         * the given CFbsBitmap is CAknBitmap or not. A list of CAknBitmap
       
   743         * pointers is managed in TLS for this.
       
   744         * 
       
   745         * @param aBitmap bitmap
       
   746         * @ret ETrue iff the given CFbsBitmap is an CAknBitmap instance.
       
   747         */
       
   748         static TBool IsAknBitmap( const CFbsBitmap* aBitmap );
       
   749         
       
   750         /**
       
   751         * Internal utility.
       
   752         */
       
   753         static void CreateIconLC(
       
   754             CFbsBitmap*& aBitmap,
       
   755             CFbsBitmap*& aMask,
       
   756             const TDesC& aFileName,
       
   757             TInt aBitmapId,
       
   758             TInt aMaskId,
       
   759             MAknIconFileProvider* aFileProvider );
       
   760 
       
   761         /**
       
   762         * Internal utility.
       
   763         * @deprecated
       
   764         */
       
   765         static void CreateIconLC(
       
   766             CFbsBitmap*& aBitmap,
       
   767             CFbsBitmap*& aMask,
       
   768             const TDesC& aFileName,
       
   769             TInt aBitmapId,
       
   770             TInt aMaskId,
       
   771             RFile& aFile );
       
   772         
       
   773     private:
       
   774 
       
   775         AknIconUtils();
       
   776     };
       
   777 
       
   778 #include "AknIconUtils.inl"
       
   779 #endif // AKN_ICON_UTILS_H
       
   780             
       
   781 // End of File