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