1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/mw/AknIconUtils.h Wed Mar 31 12:33:34 2010 +0100
1.3 @@ -0,0 +1,781 @@
1.4 +/*
1.5 +* Copyright (c) 2002 Nokia Corporation and/or its subsidiary(-ies).
1.6 +* All rights reserved.
1.7 +* This component and the accompanying materials are made available
1.8 +* under the terms of "Eclipse Public License v1.0"
1.9 +* which accompanies this distribution, and is available
1.10 +* at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.11 +*
1.12 +* Initial Contributors:
1.13 +* Nokia Corporation - initial contribution.
1.14 +*
1.15 +* Contributors:
1.16 +*
1.17 +* Description: Utility functions related to scalable icons.
1.18 +*
1.19 +*/
1.20 +
1.21 +
1.22 +
1.23 +
1.24 +#ifndef AKN_ICON_UTILS_H
1.25 +#define AKN_ICON_UTILS_H
1.26 +
1.27 +// INCLUDES
1.28 +#include <e32std.h>
1.29 +#include <gdi.h>
1.30 +
1.31 +// FORWARD DECLARATIONS
1.32 +class CFbsBitmap;
1.33 +class MAknIconObserver;
1.34 +
1.35 +// ENUMERATIONS
1.36 +enum TScaleMode
1.37 + {
1.38 + /*
1.39 + * Scales the icon to the maximum size that fits in the given size,
1.40 + * whilst preserving the aspect ratio of the icon. The sizes of the resulting
1.41 + * bitmaps are exactly of the given size. If the aspect ratio of
1.42 + * the given size differs from the aspect ratio of the icon,
1.43 + * the resulting bitmaps will contain an unused area.
1.44 + */
1.45 + EAspectRatioPreserved = 0,
1.46 +
1.47 + /*
1.48 + * Scales the icon to the maximum size that fits in the given size,
1.49 + * whilst preserving the aspect ratio of the icon. The resulting bitmaps
1.50 + * are resized so that any unused portion of the given size is not
1.51 + * present in them.
1.52 + *
1.53 + * This mode should be used when only the height or the width of the icon
1.54 + * is known and the other should be based on the aspect ratio of the icon.
1.55 + * The unknown dimension should be defined high enough (e.g. KMaxTInt) so
1.56 + * that it does not limit the scaling based on the aspect ratio of the icon.
1.57 + */
1.58 + EAspectRatioPreservedAndUnusedSpaceRemoved = 1,
1.59 +
1.60 + /*
1.61 + * Scales the icon exactly to the given size. Does not preserve the aspect
1.62 + * ratio of the icon.
1.63 + */
1.64 + EAspectRatioNotPreserved = 2,
1.65 +
1.66 + /*
1.67 + * Scales the icon to the minimum size that covers the given size,
1.68 + * whilst preserving the aspect ratio of the icon. The sizes of the resulting
1.69 + * bitmaps are exactly of the given size. If the aspect ratio of
1.70 + * the given size differs from the aspect ratio of the icon, some parts of the
1.71 + * icon will be sliced from the resulting bitmaps.
1.72 + *
1.73 + * @since 3.1
1.74 + */
1.75 + EAspectRatioPreservedSlice = 3
1.76 + };
1.77 +
1.78 +// CLASS DECLARATIONS
1.79 +
1.80 +/**
1.81 +* Class for storing the content dimensions of icons.
1.82 +*/
1.83 +class TAknContentDimensions
1.84 + {
1.85 + public:
1.86 +
1.87 + /**
1.88 + * C++ default constructor.
1.89 + */
1.90 + inline TAknContentDimensions();
1.91 +
1.92 + /**
1.93 + * Constructor.
1.94 + *
1.95 + * @param aWidth Icons width.
1.96 + * @param aHeight Icons height.
1.97 + */
1.98 + inline TAknContentDimensions(TReal32 aWidth, TReal32 aHeight);
1.99 +
1.100 + /**
1.101 + * Sets the content dimensions.
1.102 + *
1.103 + * @param aWidth Width of the icon.
1.104 + * @param aHeight Height of the icon.
1.105 + */
1.106 + inline void SetDimensions(TReal32 aWidth, TReal32 aHeight);
1.107 +
1.108 + /**
1.109 + * Sets the content size of the icon.
1.110 + *
1.111 + * @param aDimensions Two-dimensional size as a width and a height
1.112 + value of the icon.
1.113 + */
1.114 + inline void SetDimensions(const TSize& aDimensions);
1.115 +
1.116 + public:
1.117 +
1.118 + /** Icons width. */
1.119 + TReal32 iWidth;
1.120 +
1.121 + /** Icons height. */
1.122 + TReal32 iHeight;
1.123 + };
1.124 +
1.125 +/**
1.126 + * Cleanup stack helper. Owns the bitmap and the mask.
1.127 + */
1.128 +NONSHARABLE_CLASS(CAknIcon) : public CBase
1.129 + {
1.130 + public:
1.131 +
1.132 + /**
1.133 + * Two-phased constructor.
1.134 + *
1.135 + * Creates and returns a pointer to a new @c CAknIcon object.
1.136 + *
1.137 + * @return New @c CAknIcon.
1.138 + */
1.139 + IMPORT_C static CAknIcon* NewL();
1.140 +
1.141 + /**
1.142 + * Destructor.
1.143 + */
1.144 + ~CAknIcon();
1.145 +
1.146 + public:
1.147 +
1.148 + /**
1.149 + * Gets the bitmap.
1.150 + *
1.151 + * @return The icon's bitmap.
1.152 + */
1.153 + IMPORT_C CFbsBitmap* Bitmap() const;
1.154 +
1.155 + /**
1.156 + * Gets the mask.
1.157 + *
1.158 + * @return The icon's mask.
1.159 + */
1.160 + IMPORT_C CFbsBitmap* Mask() const;
1.161 +
1.162 + /**
1.163 + * Sets the bitmap.
1.164 + *
1.165 + * @param aBitmap The icon's bitmap.
1.166 + */
1.167 + IMPORT_C void SetBitmap( CFbsBitmap* aBitmap );
1.168 +
1.169 + /**
1.170 + * Sets the mask.
1.171 + *
1.172 + * @param aMask The icon's mask.
1.173 + */
1.174 + IMPORT_C void SetMask( CFbsBitmap* aMask );
1.175 +
1.176 + private:
1.177 +
1.178 + /**
1.179 + * Default constructor.
1.180 + */
1.181 + inline CAknIcon() {}
1.182 +
1.183 + private:
1.184 +
1.185 + CFbsBitmap* iBitmap; // owned
1.186 + CFbsBitmap* iMask; // owned
1.187 + };
1.188 +
1.189 +/**
1.190 +* The purpose of this class is for clients to provide opened file handles
1.191 +* to icon files, which reside in private directories,
1.192 +* where AknIcon server has no access.
1.193 +*
1.194 +* MIF file is always generated, when building icons with MifConv tool.
1.195 +* The corresponding MBM file is generated only if there are bitmap icons
1.196 +* amongst the source icons.
1.197 +*
1.198 +*/
1.199 +class MAknIconFileProvider
1.200 + {
1.201 + public:
1.202 +
1.203 + enum TIconFileType
1.204 + {
1.205 + EMbmFile = 0,
1.206 + EMifFile = 1
1.207 + };
1.208 +
1.209 + public:
1.210 +
1.211 + /**
1.212 + * Destructor.
1.213 + */
1.214 + virtual ~MAknIconFileProvider() {}
1.215 +
1.216 + /**
1.217 + * Returns an open file handle to the icon file.
1.218 + * This method should leave if an icon file with specified type does
1.219 + * not exist. That may be the case e.g. with MBM file,
1.220 + * if there are no bitmap icons.
1.221 + *
1.222 + * Note! RFs::ShareProtected must be called to the RFs instance used
1.223 + * for opening the file.
1.224 + *
1.225 + * @param aFile Icon file should be opened in this file handle, which
1.226 + * is an empty file handle, when the AknIcon framework calls this method.
1.227 + * The AknIcon framework takes care of closing the file handle after
1.228 + * having used it.
1.229 + * @param aType Icon file type.
1.230 + */
1.231 + virtual void RetrieveIconFileHandleL(
1.232 + RFile& aFile, const TIconFileType aType ) = 0;
1.233 +
1.234 + /**
1.235 + * With this method, AknIcon framework informs that it does not use
1.236 + * this MAknIconFileProvider instance any more. After this call,
1.237 + * it is ok to delete the object. This can be implemented simply
1.238 + * e.g. by deleting self in this callback.
1.239 + * Normally, this callback is invoked when the icon in question
1.240 + * is deleted.
1.241 + * Note, however, that if the same MAknIconFileProvider instance is
1.242 + * supplied in multiple CreateIcon calls, then it must be accessible
1.243 + * by AknIcon framework until it has signalled a matching amount
1.244 + * of these callbacks.
1.245 + */
1.246 + virtual void Finished() = 0;
1.247 + };
1.248 +
1.249 +/**
1.250 +* AknIconUtils
1.251 +*
1.252 +* Note: The CFbsBitmap objects for bitmaps and mask returned by this class
1.253 +* may be compressed in background.
1.254 +* Client code directly accessing the bitmap pixel data should not
1.255 +* assume that the bitmap and mask objects are not compressed.
1.256 +*
1.257 +* Bitmap compression can be disabled for an icon if desired using
1.258 +* AknIconUtils::DisableCompression().
1.259 +*/
1.260 +class AknIconUtils
1.261 + {
1.262 + public:
1.263 +
1.264 + /**
1.265 + * Creates bitmap and mask for an icon.
1.266 + * Allocates bitmap and mask objects and sets aBitmap and
1.267 + * aMask to point at them. Ownership of those is transferred to the caller.
1.268 + * These bitmaps are not ready for drawing until they are initialized with
1.269 + * SetSize method. Usually, UI controls do this.
1.270 + *
1.271 + * Use this method only if aBitmap and aMask are member variables.
1.272 + * Otherwise, use method CreateIconLC.
1.273 + *
1.274 + * @since 2.8
1.275 + * @param aBitmap icon bitmap is stored here
1.276 + * @param aMask icon mask is stored here
1.277 + * @param aFileName File name. Can be either MBM or MIF file.
1.278 + * Extension is changed based on the given bitmap ID.
1.279 + * @param aBitmapId bitmap Id
1.280 + * @param aMaskId mask Id
1.281 + */
1.282 + IMPORT_C static void CreateIconL(
1.283 + CFbsBitmap*& aBitmap,
1.284 + CFbsBitmap*& aMask,
1.285 + const TDesC& aFileName,
1.286 + TInt aBitmapId,
1.287 + TInt aMaskId );
1.288 +
1.289 + /**
1.290 + * Creates bitmap and mask for an icon.
1.291 + * Allocates bitmap and mask objects and sets aBitmap and
1.292 + * aMask to point at them. Ownership of those is transferred to the caller.
1.293 + * These bitmaps are not ready for drawing until they are initialized with
1.294 + * SetSize method. Usually, UI controls do this.
1.295 + *
1.296 + * This method puts both aBitmap and aMask in the cleanup stack.
1.297 + *
1.298 + * @since 2.8
1.299 + * @param aBitmap icon bitmap is stored here
1.300 + * @param aMask icon mask is stored here
1.301 + * @param aFileName File name. Can be either MBM or MIF file.
1.302 + * Extension is changed based on the given bitmap ID.
1.303 + * @param aBitmapId bitmap ID
1.304 + * @param aMaskId mask ID
1.305 + */
1.306 + IMPORT_C static void CreateIconLC(
1.307 + CFbsBitmap*& aBitmap,
1.308 + CFbsBitmap*& aMask,
1.309 + const TDesC& aFileName,
1.310 + TInt aBitmapId,
1.311 + TInt aMaskId );
1.312 +
1.313 + /**
1.314 + * Creates the bitmap for an icon.
1.315 + * Use this variant when a mask is not needed.
1.316 + * Ownership of the returned object is transferred to the caller.
1.317 + * The bitmap is not ready for drawing until it is initialized with
1.318 + * SetSize method. Usually, UI controls do this.
1.319 + *
1.320 + * @since 2.8
1.321 + * @param aBitmap icon bitmap is stored here
1.322 + * @param aFileName File name. Can be either MBM or MIF file.
1.323 + * Extension is changed based on the given bitmap ID.
1.324 + * @param aBitmapId bitmap ID
1.325 + */
1.326 + IMPORT_C static CFbsBitmap* CreateIconL(
1.327 + const TDesC& aFileName,
1.328 + TInt aBitmapId );
1.329 +
1.330 + /**
1.331 + * Creates bitmap and mask for an icon.
1.332 + * Allocates bitmap and mask objects and sets aBitmap and
1.333 + * aMask to point at them. Ownership of those is transferred to the caller.
1.334 + * These bitmaps are not ready for drawing until they are initialized with
1.335 + * SetSize method. Usually, UI controls do this.
1.336 + *
1.337 + * If this method leaves, MAknIconFileProvider::Finished is called for the
1.338 + * supplied aFileProvider.
1.339 + *
1.340 + * Use this method only if aBitmap and aMask are member variables.
1.341 + * Otherwise, use method CreateIconLC.
1.342 + *
1.343 + * @since 3.0
1.344 + * @param aBitmap icon bitmap is stored here
1.345 + * @param aMask icon mask is stored here
1.346 + * @param aFileProvider Icon file handle provider.
1.347 + * @param aBitmapId bitmap Id
1.348 + * @param aMaskId mask Id
1.349 + */
1.350 + IMPORT_C static void CreateIconL(
1.351 + CFbsBitmap*& aBitmap,
1.352 + CFbsBitmap*& aMask,
1.353 + MAknIconFileProvider& aFileProvider,
1.354 + TInt aBitmapId,
1.355 + TInt aMaskId );
1.356 +
1.357 + /**
1.358 + * Creates bitmap and mask for an icon.
1.359 + * Allocates bitmap and mask objects and sets aBitmap and
1.360 + * aMask to point at them. Ownership of those is transferred to the caller.
1.361 + * These bitmaps are not ready for drawing until they are initialized with
1.362 + * SetSize method. Usually, UI controls do this.
1.363 + *
1.364 + * This method puts both aBitmap and aMask in the cleanup stack.
1.365 + *
1.366 + * If this method leaves, MAknIconFileProvider::Finished is called for the
1.367 + * supplied aFileProvider.
1.368 + *
1.369 + * @since 3.0
1.370 + * @param aBitmap icon bitmap is stored here
1.371 + * @param aMask icon mask is stored here
1.372 + * @param aFileProvider Icon file handle provider.
1.373 + * @param aBitmapId bitmap Id
1.374 + * @param aMaskId mask Id
1.375 + */
1.376 + IMPORT_C static void CreateIconLC(
1.377 + CFbsBitmap*& aBitmap,
1.378 + CFbsBitmap*& aMask,
1.379 + MAknIconFileProvider& aFileProvider,
1.380 + TInt aBitmapId,
1.381 + TInt aMaskId );
1.382 +
1.383 + /**
1.384 + * Creates the bitmap for an icon.
1.385 + * Use this variant when a mask is not needed.
1.386 + * Ownership of the returned object is transferred to the caller.
1.387 + * The bitmap is not ready for drawing until it is initialized with
1.388 + * SetSize method. Usually, UI controls do this.
1.389 + *
1.390 + * If this method leaves, MAknIconFileProvider::Finished is called for the
1.391 + * supplied aFileProvider.
1.392 + *
1.393 + * @since 3.0
1.394 + * @param aFileProvider Icon file handle provider.
1.395 + * @param aBitmapId bitmap ID
1.396 + * @return The icon bitmap.
1.397 + */
1.398 + IMPORT_C static CFbsBitmap* CreateIconL(
1.399 + MAknIconFileProvider& aFileProvider,
1.400 + TInt aBitmapId );
1.401 +
1.402 + /**
1.403 + * Preserves the icon data (e.g. SVG-T data) related to the given icon
1.404 + * in memory. After this, the icon data is destroyed when either
1.405 + * DestroyIconData is explicitly called or the bitmap(s) of the icon are
1.406 + * deleted.
1.407 + *
1.408 + * This method should be called to improve performance if more than one
1.409 + * call to methods SetSize, SetSizeAndRotation or GetContentDimensions
1.410 + * is made successively on a particular icon. It should be called prior
1.411 + * to the above-mentioned calls. Without calling this method,
1.412 + * the icon data is destroyed after any of the method calls mentioned
1.413 + * above and then loaded from the storage medium and parsed from scratch
1.414 + * again in a new operation.
1.415 + *
1.416 + * Note! Icon data may consume considerable amounts of memory. In order
1.417 + * to save memory, any code that calls PreserveIconData should also
1.418 + * explicitly call DestroyIconData when the icon data is no longer
1.419 + * required.
1.420 + *
1.421 + * @since 2.8
1.422 + * @param aBitmap bitmap or mask of the icon.
1.423 + */
1.424 + IMPORT_C static void PreserveIconData( CFbsBitmap* aBitmap );
1.425 +
1.426 + /**
1.427 + * Destroys the icon data related to the given icon,
1.428 + * if it was preserved in memory. Note that this does not affect
1.429 + * the rendered frame buffers (CFbsBitmap objects).
1.430 + *
1.431 + * @since 2.8
1.432 + * @param aBitmap bitmap or mask of the icon.
1.433 + */
1.434 + IMPORT_C static void DestroyIconData( CFbsBitmap* aBitmap );
1.435 +
1.436 + /**
1.437 + * Initializes the icon to the given size, if the parameter aBitmap is
1.438 + * an instance of CAknBitmap, i.e. created with AknIconUtils methods.
1.439 + * If it is not CAknBitmap, this method does nothing. Note that this call
1.440 + * sets the sizes of both bitmap and mask (if it exists), regardless of
1.441 + * which is given as the parameter.
1.442 + *
1.443 + * @since 2.8
1.444 + * @param aBitmap bitmap or mask of the icon
1.445 + * @param aSize icon size
1.446 + * @param aMode scale mode
1.447 + * @return Standard Symbian OS error code. In error cases, it is guaranteed
1.448 + * that the returned bitmap is a valid CFbsBitmap, but there is no guarantee
1.449 + * of its size, except that it is non-negative.
1.450 + */
1.451 + IMPORT_C static TInt SetSize(
1.452 + CFbsBitmap* aBitmap,
1.453 + const TSize& aSize,
1.454 + TScaleMode aMode = EAspectRatioPreserved );
1.455 +
1.456 + /**
1.457 + * Initializes the icon to the given size, if the parameter aBitmap is
1.458 + * an instance of CAknBitmap, i.e. created with AknIconUtils methods.
1.459 + * If it is not CAknBitmap, this method does nothing. Note that this call
1.460 + * sets the sizes of both bitmap and mask (if it exists), regardless of
1.461 + * which is given as the parameter. Additionally, this method rotates
1.462 + * the icon according to the given angle.
1.463 + *
1.464 + * @since 2.8
1.465 + * @param aBitmap bitmap or mask of the icon
1.466 + * @param aSize icon size
1.467 + * @param aAngle Rotation angle in degrees.
1.468 + * @return Standard Symbian OS error code. In error cases, it is guaranteed
1.469 + * that the returned bitmap is a valid CFbsBitmap, but there is no guarantee
1.470 + * of its size, except that it is non-negative.
1.471 + */
1.472 + IMPORT_C static TInt SetSizeAndRotation(
1.473 + CFbsBitmap* aBitmap,
1.474 + const TSize& aSize,
1.475 + TScaleMode aMode,
1.476 + TInt aAngle );
1.477 +
1.478 + /**
1.479 + * Sets observer for change notification.
1.480 + *
1.481 + * The method BitmapChanged() will be called when the contents of the CFbsBitmap
1.482 + * are changed. Controls can use this to redraw themselves when icon
1.483 + * animation progresses.
1.484 + *
1.485 + * @since 2.8
1.486 + * @param aBitmap bitmap
1.487 + * @param aObserver observer
1.488 + */
1.489 + IMPORT_C static void SetObserver( CFbsBitmap* aBitmap, MAknIconObserver* aObserver );
1.490 +
1.491 + /**
1.492 + * Returns the file name of Avkon's icon file, containing full path.
1.493 + *
1.494 + * @since 2.8
1.495 + * @ret Avkon's icon file name, containing full path.
1.496 + */
1.497 + IMPORT_C static const TDesC& AvkonIconFileName();
1.498 +
1.499 + /**
1.500 + * Validates logical app icon ID so that it can be used as a parameter to
1.501 + * CreateIconL or CreateIconLC. If the given icon file name is .MBM file,
1.502 + * this method does nothing. If it is .MIF file, a predefined offset is
1.503 + * added to the given IDs.
1.504 + *
1.505 + * This method is only intended to be used when loading icons from the
1.506 + * icon file retrieved from AppArc.
1.507 + *
1.508 + * @param aIconFileName Icon file name retrieved from AppArc.
1.509 + * @param aId Logical bitmap ID used in the app icon file, usually 0.
1.510 + * @param aId Logical mask ID used in the app icon file, usually 1.
1.511 + */
1.512 + IMPORT_C static void ValidateLogicalAppIconId(
1.513 + const TDesC& aIconFileName,
1.514 + TInt& aBitmapId,
1.515 + TInt& aMaskId );
1.516 +
1.517 + /**
1.518 + * Tells whether the given file name is recognized as a MIF file or not.
1.519 + * Only the file name extension is examined, not the contents of the file.
1.520 + *
1.521 + * @since 2.8
1.522 + * @param aFileName file name
1.523 + *
1.524 + * @return ETrue if MIF file, EFalse otherwise.
1.525 + */
1.526 + IMPORT_C static TBool IsMifFile( const TDesC& aFileName );
1.527 +
1.528 + /**
1.529 + * Tells whether the given bitmap is a part of a MIF icon or not.
1.530 + * Accepts any pointer (also NULL) as a parameter.
1.531 + *
1.532 + * @since 2.8
1.533 + * @param aBitmap bitmap
1.534 + *
1.535 + * @return ETrue if the given bitmap is part of a MIF icon,
1.536 + * EFalse otherwise.
1.537 + */
1.538 + IMPORT_C static TBool IsMifIcon( const CFbsBitmap* aBitmap );
1.539 +
1.540 + /**
1.541 + * Returns the content dimensions of the given icon.
1.542 + * In case of MBM icons, this is the original size of the bitmap.
1.543 + * In case of SVG icons, this is defined in the icon data.
1.544 + *
1.545 + * If SetSize or SetSizeAndRotation is going to be called on the same
1.546 + * icon after this call, the performance can be improved by calling
1.547 + * PreserveIconData before calling this method.
1.548 + *
1.549 + * @deprecated
1.550 + * @since 2.8
1.551 + * @param aBitmap bitmap
1.552 + * @param aContentDimensions The content dimensions are returned here.
1.553 + *
1.554 + * @ret Standard Symbian OS error code.
1.555 + */
1.556 + IMPORT_C static TInt GetContentDimensions(
1.557 + CFbsBitmap* aBitmap,
1.558 + TSize& aContentDimensions );
1.559 +
1.560 + /**
1.561 + * Returns the content dimensions of the given icon.
1.562 + * In case of MBM icons, this is the original size of the bitmap.
1.563 + * In case of SVG icons, this is defined in the icon data.
1.564 + *
1.565 + * If SetSize or SetSizeAndRotation is going to be called on the same
1.566 + * icon after this call, the performance can be improved by calling
1.567 + * PreserveIconData before calling this method.
1.568 + *
1.569 + * @since 3.0
1.570 + * @param aBitmap bitmap
1.571 + * @param aContentDimensions The content dimensions are returned here.
1.572 + *
1.573 + * @ret Standard Symbian OS error code.
1.574 + */
1.575 + IMPORT_C static TInt GetContentDimensions(
1.576 + CFbsBitmap* aBitmap,
1.577 + TAknContentDimensions& aContentDimensions );
1.578 +
1.579 +
1.580 + /**
1.581 + * Creates bitmap and mask for an icon.
1.582 + * Allocates bitmap and mask objects and sets aResultIcon to point at them.
1.583 + *
1.584 + * When this method returns, the resulting bitmaps are
1.585 + * duplicates of the source bitmaps.
1.586 + * Also the source bitmap instances are preserved in memory.
1.587 + *
1.588 + * Ownership of aSourceIcon is transferred from caller.
1.589 + * This method takes the responsibility of deleting the object
1.590 + * even if the method leaves.
1.591 + *
1.592 + * The returned icon bitmaps are instances of CAknBitmap,
1.593 + * so AknIconUtils::SetSize is functional for them.
1.594 + *
1.595 + * AknIconUtils::SetSize first creates duplicates of the source bitmaps
1.596 + * and after that, if required, creates new bitmaps and performs scaling.
1.597 + *
1.598 + * Note that due to the additional memory consumption caused by the source bitmaps,
1.599 + * this method should only be used if it is not possible to use the variant of
1.600 + * CreateIconL that takes icon file name and IDs as parameters.
1.601 + *
1.602 + * @since 2.8
1.603 + *
1.604 + * @param aSourceIcon Contains source bitmap and mask.
1.605 + * Ownership of aSourceIcon is transferred from caller.
1.606 + * This method takes the responsibility of deleting the object
1.607 + * even if the method leaves.
1.608 + *
1.609 + * @ret Resulting icon. Ownership transferred to the caller.
1.610 + */
1.611 + IMPORT_C static CAknIcon* CreateIconL( CAknIcon* aSourceIcon );
1.612 +
1.613 + /**
1.614 + * Non-masked variant of CreateIconL.
1.615 + *
1.616 + * Ownership of aSourceBitmap is transferred from caller.
1.617 + * This method takes the responsibility of deleting the object
1.618 + * even if the method leaves.
1.619 + *
1.620 + * @since 2.8
1.621 + * @param aSourceBitmap Source bitmap.
1.622 + * Ownership is transferred from caller.
1.623 + * This method takes the responsibility of deleting the object
1.624 + * even if the method leaves.
1.625 + *
1.626 + * @ret Resulting icon bitmap. Ownership transferred to the caller.
1.627 + */
1.628 + IMPORT_C static CFbsBitmap* CreateIconL( CFbsBitmap* aSourceBitmap );
1.629 +
1.630 + /**
1.631 + * Determines the icon color. Only effective if the given bitmap is
1.632 + * an instance of CAknBitmap. This method only needs to be called either
1.633 + * for the bitmap or the mask of an icon, but to be effective, it needs
1.634 + * to be called before calling SetSize or SetSizeAndRotation.
1.635 + *
1.636 + * @since 2.8
1.637 + * @param aBitmap bitmap
1.638 + * @param aColor icon color
1.639 + */
1.640 + IMPORT_C static void SetIconColor( CFbsBitmap* aBitmap, const TRgb aColor );
1.641 +
1.642 +
1.643 + /**
1.644 + * Excludes the icon form the icon cache.
1.645 + * Only effective if the given bitmap is an instance of CAknBitmap. This call
1.646 + * sets the sizes of both bitmap and mask (if it exists), regardless of
1.647 + * which is given as the parameter.
1.648 + * This method should be called after calling CreateIconL or CreateIconLC
1.649 + * and before calling AknIconUtils::SetSize.
1.650 + *
1.651 + * By default icons are being put to icon cache after they are no longer used.
1.652 + * This makes it possible to retrieve recently used icons fast without the need to
1.653 + * render them again.
1.654 + * The icon cache has a limited size and when the cache is full to cache new icons
1.655 + * the oldest icons from the cache will be removed.
1.656 + * In certain situations it might be feasible to exclude some icons from the
1.657 + * icon cache (e.g. in case of infrequently used large icons) to prevent some more
1.658 + * frequently used icon being kicked out from the cache. Excluding infrequently used
1.659 + * icons from icon cache could improve performance and memory usage of the system.
1.660 + *
1.661 + *
1.662 + * @since 3.1
1.663 + * @param aBitmap bitmap
1.664 + */
1.665 + IMPORT_C static void ExcludeFromCache( CFbsBitmap* aBitmap );
1.666 +
1.667 + /**
1.668 + * Disables bitmap compression for the icon.
1.669 + * Only effective if the given bitmap is an instance of CAknBitmap. This call
1.670 + * prevents AknIcon framework from compressing the CFbsBitmap objects
1.671 + * (bitmap, mask) of the icon.
1.672 + * This method should be called after calling CreateIconL or CreateIconLC
1.673 + * and before calling AknIconUtils::SetSize.
1.674 + *
1.675 + * @since 3.1
1.676 + * @param aBitmap bitmap
1.677 + */
1.678 + IMPORT_C static void DisableCompression( CFbsBitmap* aBitmap );
1.679 +
1.680 +
1.681 + /**
1.682 + * Performs bitmap scaling.
1.683 + * Draws a source bitmap to fit a given rectangle within a target bitmap.
1.684 + * This is ~15x faster than scaling with Symbian's DrawBitmap. Following
1.685 + * bitmap modes are supported: EGray256, EColor4K, EColor64K, EColor256,
1.686 + * EColor16MU. For all other bitmap modes, Symbian's DrawBitmap API will
1.687 + * be used. Bitmap modes of the source and target bitmap should be the
1.688 + * same.
1.689 + * @ since 3.2
1.690 + * @ param aTrgRect target rect inside the target bitmap
1.691 + * @ param aTrgBitmap the target bitmap
1.692 + * @ param aSrcBitmap the source bitmap
1.693 + * @leave KErrArgument
1.694 + * If source bitmap mode is not the same as target bitmap mode.
1.695 + * @leave Any other Symbian OS specific error codes.
1.696 + */
1.697 + IMPORT_C static void ScaleBitmapL(
1.698 + const TRect& aTrgRect,
1.699 + CFbsBitmap* aTrgBitmap,
1.700 + CFbsBitmap* aSrcBitmap );
1.701 +
1.702 + /**
1.703 + * Bitmap rotation and scaling. Might be exported later. Scales and
1.704 + * rotates the given bitmap according to the parameters. Supported
1.705 + * bitmap modes are EGray2, EGray256, EColor256, EColor4K, EColor64K and
1.706 + * EColor16MU. All other bitmap depts will cause a leave with
1.707 + * KErrNotSupported. The only supported scalemode is
1.708 + * EAspectRatioPreserved. The unused area in the target bitmap is
1.709 + * filled with black color unless the bitmap depth is EGray8 when the
1.710 + * area is filled with white. Areas that do not fit to the target area
1.711 + * after rotation are clipped out
1.712 + *
1.713 + * If the bitmap depth is EGray2, the routine will perform noticeably worse.
1.714 + *
1.715 + * @param aTrgRect target rect inside the target bitmap
1.716 + * @param aTrgBitmap the target bitmap
1.717 + * @param aSrcBitmap the source bitmap
1.718 + * @param aAngle the rotation angle in degrees
1.719 + */
1.720 + static void RotateAndScaleBitmapL(
1.721 + const TRect& aTrgRect,
1.722 + CFbsBitmap* aTrgBitmap,
1.723 + CFbsBitmap* aSrcBitmap,
1.724 + TInt aAngle );
1.725 +
1.726 + /**
1.727 + * @internal
1.728 + */
1.729 + static TBool DoesScaleBitmapUseFallBack(
1.730 + CFbsBitmap* aSrcBitmap );
1.731 +
1.732 + /**
1.733 + * @internal
1.734 + */
1.735 + static void ScaleBitmapExtL(
1.736 + const TRect& aTrgRect,
1.737 + CFbsBitmap* aTrgBitmap,
1.738 + CFbsBitmap* aSrcBitmap,
1.739 + TBool aForceFallBack );
1.740 +
1.741 + private:
1.742 +
1.743 + /**
1.744 + * Utility for down-cast of CFbsBitmap objects. It informs whether
1.745 + * the given CFbsBitmap is CAknBitmap or not. A list of CAknBitmap
1.746 + * pointers is managed in TLS for this.
1.747 + *
1.748 + * @param aBitmap bitmap
1.749 + * @ret ETrue iff the given CFbsBitmap is an CAknBitmap instance.
1.750 + */
1.751 + static TBool IsAknBitmap( const CFbsBitmap* aBitmap );
1.752 +
1.753 + /**
1.754 + * Internal utility.
1.755 + */
1.756 + static void CreateIconLC(
1.757 + CFbsBitmap*& aBitmap,
1.758 + CFbsBitmap*& aMask,
1.759 + const TDesC& aFileName,
1.760 + TInt aBitmapId,
1.761 + TInt aMaskId,
1.762 + MAknIconFileProvider* aFileProvider );
1.763 +
1.764 + /**
1.765 + * Internal utility.
1.766 + * @deprecated
1.767 + */
1.768 + static void CreateIconLC(
1.769 + CFbsBitmap*& aBitmap,
1.770 + CFbsBitmap*& aMask,
1.771 + const TDesC& aFileName,
1.772 + TInt aBitmapId,
1.773 + TInt aMaskId,
1.774 + RFile& aFile );
1.775 +
1.776 + private:
1.777 +
1.778 + AknIconUtils();
1.779 + };
1.780 +
1.781 +#include "AknIconUtils.inl"
1.782 +#endif // AKN_ICON_UTILS_H
1.783 +
1.784 +// End of File