1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/mw/AknsUtils.h Wed Mar 31 12:33:34 2010 +0100
1.3 @@ -0,0 +1,1036 @@
1.4 +/*
1.5 +* Copyright (c) 2002-2004 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: Defines a public static utility class AknsUtils.
1.18 +*
1.19 +*/
1.20 +
1.21 +
1.22 +#ifndef AKNSUTILS_H
1.23 +#define AKNSUTILS_H
1.24 +
1.25 +// INCLUDES
1.26 +#include <AknsSkinInstance.h>
1.27 +#include <apgicnfl.h>
1.28 +#include <AknIconUtils.h>
1.29 +
1.30 +// FORWARD DECLARATIONS
1.31 +class CFbsBitmap;
1.32 +class CAknsItemDef;
1.33 +class CCoeControl;
1.34 +class CGulIcon;
1.35 +
1.36 +// TYPE DEFINITIONS
1.37 +
1.38 +/**
1.39 +* Type of the application icon.
1.40 +*
1.41 +* @since 2.8
1.42 +*/
1.43 +enum TAknsAppIconType
1.44 + {
1.45 + EAknsAppIconTypeList = 0,
1.46 + EAknsAppIconTypeContext = 1,
1.47 + EAknsAppIconType3D = 2
1.48 + };
1.49 +
1.50 +// CLASS DECLARATION
1.51 +
1.52 +/**
1.53 +* Static utility class to support AVKON SKINS common operations.
1.54 +* AknsUtils provides utility method to initialize application skin support,
1.55 +* retrieve current skin instance or data context, retrieve skin data
1.56 +* items and to perform other skin-related tasks.
1.57 +*
1.58 +* This is a public static class with exported functions.
1.59 +* The class is not intended for derivation outside the library.
1.60 +*
1.61 +* @lib AknSkins.lib
1.62 +*
1.63 +* @since 2.0
1.64 +*/
1.65 +class AknsUtils
1.66 + {
1.67 +
1.68 + public: // New functions - Creators
1.69 +
1.70 + /**
1.71 + * Initializes application skin support.
1.72 + * Creates application skin instance. Method should be called once
1.73 + * in the construction phase of application, before any other
1.74 + * skin-related operations take place.
1.75 + *
1.76 + * @since 2.0
1.77 + *
1.78 + * @par Notes:
1.79 + * The framework calls this method automatically for each
1.80 + * application. Thus, a normal application does not need to
1.81 + * call this method explicitly.
1.82 + *
1.83 + * @par Exceptions:
1.84 + * - If allocation fails, function leaves with an error code.
1.85 + */
1.86 + IMPORT_C static void InitSkinSupportL();
1.87 +
1.88 + /**
1.89 + * Creates data context suitable for a container.
1.90 + * Constructs a new data context suitable for a container. Container
1.91 + * should store the pointer and perform proper destruction when
1.92 + * the lifetime of the container itself ends.
1.93 + *
1.94 + * @since 2.0
1.95 + *
1.96 + * @return Newly created data context. Ownership of the context object
1.97 + * is transferred to the caller.
1.98 + */
1.99 + IMPORT_C static MAknsDataContext* CreateDataContextForContainerL();
1.100 +
1.101 + /**
1.102 + * Constructs a new bitmap item definition object.
1.103 + *
1.104 + * @since 2.0
1.105 + *
1.106 + * @param aID Item ID of the item definition object to be created:
1.107 + *
1.108 + * @param aFile Filename of the MBM file.
1.109 + *
1.110 + * @param aIndex Index of the bitmap in the file.
1.111 + *
1.112 + * @return Newly constructed item definition object.
1.113 + *
1.114 + * @par Exceptions:
1.115 + * If construction fails, the method leaves with an error code.
1.116 + */
1.117 + IMPORT_C static CAknsItemDef* CreateBitmapItemDefL(
1.118 + const TAknsItemID& aID, const TDesC& aFilename,
1.119 + const TInt aIndex );
1.120 +
1.121 + /**
1.122 + * Constructs a new masked bitmap item definition object.
1.123 + *
1.124 + * @since 2.0
1.125 + *
1.126 + * @param aID Item ID of the item definition object to be created:
1.127 + *
1.128 + * @param aFile Filename of the MBM file.
1.129 + *
1.130 + * @param aIndex Index of the bitmap in the file.
1.131 + *
1.132 + * @param aIndex Index of the bitmap mask in the file.
1.133 + *
1.134 + * @return Newly constructed item definition object. Ownership of the
1.135 + * object is transferred to the caller.
1.136 + *
1.137 + * @par Exceptions:
1.138 + * If construction fails, the method leaves with an error code.
1.139 + */
1.140 + IMPORT_C static CAknsItemDef* CreateMaskedBitmapItemDefL(
1.141 + const TAknsItemID& aID, const TDesC& aFilename,
1.142 + const TInt aIndex, const TInt aMaskIndex );
1.143 +
1.144 + public: // New functions - Skin access
1.145 +
1.146 + /**
1.147 + * Returns pointer to current skin instance.
1.148 + * Retrieves pointer to the current application skin instance singleton.
1.149 + * If there is none, @c NULL value is returned.
1.150 + *
1.151 + * @since 2.0
1.152 + *
1.153 + * @return Pointer to current skin instance, or @c NULL if no skin
1.154 + * support is available.
1.155 + */
1.156 + IMPORT_C static MAknsSkinInstance* SkinInstance();
1.157 +
1.158 + /**
1.159 + * Returns pointer to current data context.
1.160 + * If aMop parameter is specified, retrieves the nearest data context
1.161 + * in control hierarchy. If none is found (or @c NULL parameter was
1.162 + * given) returns root data context from skin instance. If there is
1.163 + * no skin instance, @c NULL value is returned.
1.164 + *
1.165 + * @since 2.0
1.166 + *
1.167 + * @param aMop Object provider to be used to find the nearest data
1.168 + * context. In most cases this should be a pointer to the calling
1.169 + * @c CCoeControl. @c NULL value is also valid.
1.170 + *
1.171 + * @return Pointer to the nearest data context, or @c NULL if no
1.172 + * skin support is available.
1.173 + */
1.174 + IMPORT_C static MAknsDataContext* DataContext( MObjectProvider* aMop );
1.175 +
1.176 + public: // New functions - Item access w/ fallback support
1.177 +
1.178 + /**
1.179 + * Constructs an independent masked bitmap with fallback support.
1.180 + * Creates an independent (in terms of instance ownership) copy of a
1.181 + * masked bitmap by the given item ID.
1.182 + *
1.183 + * If no matching item is found in the currently activate skin,
1.184 + * attempts to construct the item using the given file.
1.185 + *
1.186 + * @since 2.6
1.187 + *
1.188 + * @lib AknSkins.lib
1.189 + *
1.190 + * @param aInstance Pointer to the current skin instance.
1.191 + * Usually retrieved using @c AknsUtils::SkinInstance.
1.192 + *
1.193 + * @param aID Item ID of the masked bitmap to be created.
1.194 + *
1.195 + * @param aBitmap If method succeeds, set to point to the
1.196 + * newly constructed bitmap. Ownership of the bitmap is transferred
1.197 + * to the caller.
1.198 + *
1.199 + * @param aMask If method succeeds, set to point to the newly
1.200 + * constructed mask bitmap. Ownership of the bitmap is transferred
1.201 + * to the caller.
1.202 + *
1.203 + * @param aFilename Filename to be used to construct the item,
1.204 + * if no matching item was found in the currently active skin.
1.205 + *
1.206 + * @param aFileBitmapId ID of the bitmap in the file.
1.207 + * Used only if no matching item was found in the currently
1.208 + * active skin.
1.209 + *
1.210 + * @param aFileMaskId ID of the mask in the file.
1.211 + * Used only if no matching item was found in the currently
1.212 + * active skin.
1.213 + *
1.214 + * @par Exceptions:
1.215 + * If data construction fails or bitmap is not found, the function
1.216 + * leaves with an error code.
1.217 + */
1.218 + IMPORT_C static void CreateIconL(
1.219 + MAknsSkinInstance* aInstance, const TAknsItemID& aID,
1.220 + CFbsBitmap*& aBitmap, CFbsBitmap*& aMask,
1.221 + const TDesC& aFilename,
1.222 + const TInt aFileBitmapId, const TInt aFileMaskId );
1.223 +
1.224 + /**
1.225 + * Otherwise identical to CreateIconL, but leaves both the bitmaps
1.226 + * in the cleanup stack.
1.227 + * The order in which they are pushed into the stack and types of
1.228 + * the items in the stack are both undefined.
1.229 + *
1.230 + * @copydoc AknsUtils::CreateIconL(MAknsSkinInstance*,TAknsItemID&,CFbsBitmap*&,CFbsBitmap*&,const TDesC&,const TInt,const TInt)
1.231 + *
1.232 + * @par Note:
1.233 + * Since both the bitmaps are left in the cleanup stack,
1.234 + * call to this method can not be enclosed in an immediate TRAP.
1.235 + */
1.236 + IMPORT_C static void CreateIconLC(
1.237 + MAknsSkinInstance* aInstance, const TAknsItemID& aID,
1.238 + CFbsBitmap*& aBitmap, CFbsBitmap*& aMask,
1.239 + const TDesC& aFilename,
1.240 + const TInt aFileBitmapId, const TInt aFileMaskId );
1.241 +
1.242 + /**
1.243 + * Constructs an independent non-masked bitmap with fallback support.
1.244 + * Creates an independent (in terms of instance ownership) copy of a
1.245 + * non-masked bitmap by the given item ID.
1.246 + *
1.247 + * If no matching item is found in the currently activate skin,
1.248 + * attempts to construct the item using the given file.
1.249 + *
1.250 + * @since 2.6
1.251 + *
1.252 + * @lib AknSkins.lib
1.253 + *
1.254 + * @param aInstance Pointer to the current skin instance.
1.255 + * Usually retrieved using @c AknsUtils::SkinInstance.
1.256 + *
1.257 + * @param aID Item ID of the non-masked bitmap to be created.
1.258 + *
1.259 + * @param aBitmap If method succeeds, set to point to the
1.260 + * newly constructed bitmap. Ownership of the bitmap is transferred
1.261 + * to the caller.
1.262 + *
1.263 + * @param aFilename Filename to be used to construct the item,
1.264 + * if no matching item was found in the currently active skin.
1.265 + *
1.266 + * @param aFileBitmapId ID of the bitmap in the file.
1.267 + * Used only if no matching item was found in the currently
1.268 + * active skin.
1.269 + *
1.270 + * @par Exceptions:
1.271 + * If data construction fails or bitmap is not found, the function
1.272 + * leaves with an error code.
1.273 + */
1.274 + IMPORT_C static void CreateIconL(
1.275 + MAknsSkinInstance* aInstance, const TAknsItemID& aID,
1.276 + CFbsBitmap*& aBitmap,
1.277 + const TDesC& aFilename,
1.278 + const TInt aFileBitmapId );
1.279 +
1.280 + /**
1.281 + * Otherwise identical to CreateIconL, but leaves the bitmap
1.282 + * in the cleanup stack.
1.283 + * The type of the item pushed into the stack is undefined.
1.284 + *
1.285 + * @copydoc AknsUtils::CreateIconL(MAknsSkinInstance*,TAknsItemID&,CFbsBitmap*&,const TDesC&,const TInt)
1.286 + *
1.287 + * @par Note:
1.288 + * Since the bitmap is left in the cleanup stack,
1.289 + * call to this method can not be enclosed in an immediate TRAP.
1.290 + */
1.291 + IMPORT_C static void CreateIconLC(
1.292 + MAknsSkinInstance* aInstance, const TAknsItemID& aID,
1.293 + CFbsBitmap*& aBitmap,
1.294 + const TDesC& aFilename,
1.295 + const TInt aFileBitmapId );
1.296 +
1.297 + /**
1.298 + * Constructs an independent masked bitmap with fallback support.
1.299 + * Creates an independent (in terms of instance ownership) copy of a
1.300 + * masked bitmap by the given item ID.
1.301 + *
1.302 + * If no matching item is found in the currently activate skin,
1.303 + * attempts to construct the item using the given file.
1.304 + *
1.305 + * @since 2.6
1.306 + *
1.307 + * @lib AknSkins.lib
1.308 + *
1.309 + * @param aInstance Pointer to the current skin instance.
1.310 + *
1.311 + * @param aID Item ID of the masked bitmap to be created.
1.312 + *
1.313 + * @param aFilename Filename to be used to construct the item,
1.314 + * if no matching item was found in the currently active skin.
1.315 + *
1.316 + * @param aFileIndex Index (for bitmap) in the file.
1.317 + * Used only if no matching item was found in the currently
1.318 + * active skin.
1.319 + *
1.320 + * @param aFileMaskIndex Index (for mask) in the file.
1.321 + * Used only if no matching item was found in the currently
1.322 + * active skin.
1.323 + *
1.324 + * @return Pointer to the newly created CApaMaskedBitmap object.
1.325 + * Ownership of the object is transferred to the caller.
1.326 + *
1.327 + * @par Exceptions:
1.328 + * If data construction fails or bitmap is not found, the function
1.329 + * leaves with an error code.
1.330 + *
1.331 + * @par Note:
1.332 + * Since @c CApaMaskedBitmap can not be used to store scalable
1.333 + * graphics, consider using @c CreateIconLC instead.
1.334 + */
1.335 + IMPORT_C static CApaMaskedBitmap* CreateMaskedBitmapL(
1.336 + MAknsSkinInstance* aInstance, const TAknsItemID& aID,
1.337 + const TDesC& aFilename,
1.338 + const TInt aFileIndex, const TInt aFileMaskIndex );
1.339 +
1.340 + /**
1.341 + * Constructs an independent CGulIcon object with fallback support.
1.342 + * Creates an independent (in terms of instance ownership) copy of a
1.343 + * masked bitmap by the given item ID, and returns it as a
1.344 + * newly constructed CGulIcon object.
1.345 + *
1.346 + * If no matching item is found in the currently active skin,
1.347 + * attempts to construct the item using the given file.
1.348 + *
1.349 + * @since 2.6
1.350 + *
1.351 + * @lib AknSkins.lib
1.352 + *
1.353 + * @param aInstance Pointer to the current skin instance.
1.354 + *
1.355 + * @param aID Item ID of the masked bitmap to be created.
1.356 + *
1.357 + * @param aFilename Filename to be used to construct the item,
1.358 + * if no matching item was found in the currently active skin.
1.359 + *
1.360 + * @param aFileIndex Index (for bitmap) in the file.
1.361 + * Used only if no matching item was found in the currently
1.362 + * active skin.
1.363 + *
1.364 + * @param aFileMaskIndex Index (for mask) in the file.
1.365 + * Used only if no matching item was found in the currently
1.366 + * active skin.
1.367 + *
1.368 + * @return Pointer to the newly created CGulIcon object.
1.369 + * Ownership of the object is transferred to the caller.
1.370 + *
1.371 + * @par Exceptions:
1.372 + * If data construction fails or bitmap is not found, the function
1.373 + * leaves with an error code.
1.374 + */
1.375 + IMPORT_C static CGulIcon* CreateGulIconL(
1.376 + MAknsSkinInstance* aInstance, const TAknsItemID& aID,
1.377 + const TDesC& aFilename,
1.378 + const TInt aFileIndex, const TInt aFileMaskIndex );
1.379 +
1.380 + /**
1.381 + * Constructs an application icon supporting scalable graphics.
1.382 + *
1.383 + * This method is fallback-enabled. If no icon is found in the
1.384 + * currently active skin, the application icon is retrieved using
1.385 + * application resource file or AIF.
1.386 + *
1.387 + * After successful completion, the method leaves both the bitmaps
1.388 + * in the cleanup stack.
1.389 + * The order in which they are pushed into the stack and types of
1.390 + * the items in the stack are both undefined.
1.391 + *
1.392 + * The caller must set the size of the returned bitmaps.
1.393 + * See @c AknIconUtils for details.
1.394 + *
1.395 + * @par Note:
1.396 + * Since both the bitmaps are left in the cleanup stack,
1.397 + * call to this method can not be enclosed in an immediate TRAP.
1.398 + *
1.399 + * @since 2.8
1.400 + *
1.401 + * @lib AknSkins.lib
1.402 + *
1.403 + * @param aInstance Pointer to current skin instance.
1.404 + *
1.405 + * @param aAppUid Application UID. Icon is searched with major IID
1.406 + * ::EAknsIIDMajorAppIcon and minor IID aAppUid.
1.407 + *
1.408 + * @param aType Type of the application icon (list or context).
1.409 + * This parameter is tentative. If no icon of the given type
1.410 + * is found, the other icon is returned. Only the following values
1.411 + * are allowed: EAknsAppIconTypeList and EAknsAppIconTypeContext.
1.412 + *
1.413 + * @param aBitmap If method succeeds, set to point to the
1.414 + * newly constructed bitmap. Ownership of the bitmap is transferred
1.415 + * to the caller.
1.416 + *
1.417 + * @param aMask If method succeeds, set to point to the newly
1.418 + * constructed mask bitmap. Ownership of the bitmap is transferred
1.419 + * to the caller.
1.420 + *
1.421 + * @par Exceptions:
1.422 + * If the method fails, it leaves with a standard error code.
1.423 + */
1.424 + IMPORT_C static void CreateAppIconLC(
1.425 + MAknsSkinInstance* aInstance, TUid aAppUid,
1.426 + TAknsAppIconType aType,
1.427 + CFbsBitmap*& aBitmap, CFbsBitmap*& aMask );
1.428 +
1.429 + /**
1.430 + * Opens the file containing application icon data.
1.431 + *
1.432 + * This method first checks whether there is a data file of the given
1.433 + * type associated with the application icon of the given UID. If no
1.434 + * file is found, an error code is returned and the caller should use
1.435 + * @c CreateAppIconLC to construct the icon. Otherwise, one of the
1.436 + * associated files is opened using the given @c RFile object.
1.437 + *
1.438 + * @since 3.0
1.439 + *
1.440 + * @lib AknSkins.lib
1.441 + *
1.442 + * @param aInstance Pointer to current skin instance.
1.443 + *
1.444 + * @param aAppUid Application UID. Icon is searched with major IID
1.445 + * ::EAknsIIDMajorAppIcon and minor IID aAppUid.
1.446 + *
1.447 + * @param aType Only EAknsAppIconType3D is allowed.
1.448 + *
1.449 + * @param aFile Reference to a @c RFile. If @c KErrNone is returned,
1.450 + * this handle refers to an open file containing the data.
1.451 + * If an error code is returned, the file is not opened.
1.452 + *
1.453 + * @return @c KErrNone if a file was opened, an error code otherwise.
1.454 + */
1.455 + IMPORT_C TInt OpenAppIconFile(
1.456 + MAknsSkinInstance* aInstance, TUid aAppUid,
1.457 + TAknsAppIconType aType, RFile& aFile );
1.458 +
1.459 + /**
1.460 + * Constructs an independent masked color-customized icon with
1.461 + * fallback support without setting its size.
1.462 + *
1.463 + * Creates an independent (in terms of instance ownership) copy of a
1.464 + * masked bitmap by the given item ID and applies color-based
1.465 + * skinning to it.
1.466 + *
1.467 + * This method:
1.468 + * - Creates a masked bitmap item from skin, or from the given
1.469 + * MBM or MIF file if no matching item is found in the active skin.
1.470 + * - If the icon can be color-skinned, applies the color retrieved
1.471 + * from the given color table and index. If no color information
1.472 + * is found in the active skin, uses the given fallback color value.
1.473 + * - Returns the resulting bitmaps. If no color skinning was applied,
1.474 + * returns the original bitmaps.
1.475 + *
1.476 + * The method fails only, if the masked bitmap can not be constructed
1.477 + * at all. If the icon can not be color-skinned, it is returned as-is.
1.478 + *
1.479 + * @since 2.6
1.480 + *
1.481 + * @lib AknSkins.lib
1.482 + *
1.483 + * @param aInstance Pointer to the current skin instance.
1.484 + * Usually retrieved using @c AknsUtils::SkinInstance.
1.485 + *
1.486 + * @param aID Item ID of the masked bitmap to be created.
1.487 + *
1.488 + * @param aColorID Item ID of the color table.
1.489 + *
1.490 + * @param aColorIndex Index in the color table.
1.491 + *
1.492 + * @param aBitmap If method succeeds, set to point to the
1.493 + * newly constructed bitmap. Ownership of the bitmap is transferred
1.494 + * to the caller.
1.495 + *
1.496 + * @param aMask If method succeeds, set to point to the newly
1.497 + * constructed mask bitmap. Ownership of the bitmap is transferred
1.498 + * to the caller.
1.499 + *
1.500 + * @param aFilename Filename to be used to construct the item,
1.501 + * if no matching item was found in the currently active skin.
1.502 + *
1.503 + * @param aFileBitmapId ID of the bitmap in the file.
1.504 + * Used only if no matching item was found in the currently
1.505 + * active skin.
1.506 + *
1.507 + * @param aFileMaskId ID of the mask in the file.
1.508 + * Used only if no matching item was found in the currently
1.509 + * active skin.
1.510 + *
1.511 + * @param aDefaultColor Color RGB value to be used, if no color
1.512 + * is found in the currently active skin.
1.513 + *
1.514 + * @par Exceptions:
1.515 + * If data construction fails or bitmap is not found, the function
1.516 + * leaves with an error code.
1.517 + */
1.518 + IMPORT_C static void CreateColorIconL(
1.519 + MAknsSkinInstance* aInstance, const TAknsItemID& aID,
1.520 + const TAknsItemID& aColorID, const TInt aColorIndex,
1.521 + CFbsBitmap*& aBitmap, CFbsBitmap*& aMask,
1.522 + const TDesC& aFilename,
1.523 + const TInt aFileBitmapId, const TInt aFileMaskId,
1.524 + const TRgb aDefaultColor );
1.525 +
1.526 + /**
1.527 + * Otherwise identical to @c CreateColorIconL, but leaves both the
1.528 + * bitmap and the mask in the cleanup stack.
1.529 + * The order in which they are pushed into the stack and types of
1.530 + * the items in the stack are both undefined.
1.531 + *
1.532 + * @since 2.6
1.533 + *
1.534 + * @lib AknSkins.lib
1.535 + *
1.536 + * @par Note:
1.537 + * Since two bitmaps are left in the cleanup stack,
1.538 + * call to this method can not be enclosed in an immediate TRAP.
1.539 + */
1.540 + IMPORT_C static void CreateColorIconLC(
1.541 + MAknsSkinInstance* aInstance, const TAknsItemID& aID,
1.542 + const TAknsItemID& aColorID, const TInt aColorIndex,
1.543 + CFbsBitmap*& aBitmap, CFbsBitmap*& aMask,
1.544 + const TDesC& aFilename,
1.545 + const TInt aFileBitmapId, const TInt aFileMaskId,
1.546 + const TRgb aDefaultColor );
1.547 +
1.548 + /**
1.549 + * Otherwise identical to @c CreateColorIconL without size parameters,
1.550 + * but calls @c SetSize to set the size of the resulting icon.
1.551 + *
1.552 + * @since 2.8
1.553 + *
1.554 + * @lib AknSkins.lib
1.555 + */
1.556 + IMPORT_C static void CreateColorIconL(
1.557 + MAknsSkinInstance* aInstance, const TAknsItemID& aID,
1.558 + const TAknsItemID& aColorID, const TInt aColorIndex,
1.559 + CFbsBitmap*& aBitmap, CFbsBitmap*& aMask,
1.560 + const TDesC& aFilename,
1.561 + const TInt aFileBitmapId, const TInt aFileMaskId,
1.562 + const TRgb aDefaultColor,
1.563 + const TSize& aSize, const TScaleMode aScaleMode );
1.564 +
1.565 + /**
1.566 + * Otherwise identical to @c CreateColorIconL, but leaves both the
1.567 + * bitmap and the mask in the cleanup stack.
1.568 + * The order in which they are pushed into the stack and types of
1.569 + * the items in the stack are both undefined.
1.570 + *
1.571 + * @since 2.8
1.572 + *
1.573 + * @lib AknSkins.lib
1.574 + *
1.575 + * @par Note:
1.576 + * Since two bitmaps are left in the cleanup stack,
1.577 + * call to this method can not be enclosed in an immediate TRAP.
1.578 + */
1.579 + IMPORT_C static void CreateColorIconLC(
1.580 + MAknsSkinInstance* aInstance, const TAknsItemID& aID,
1.581 + const TAknsItemID& aColorID, const TInt aColorIndex,
1.582 + CFbsBitmap*& aBitmap, CFbsBitmap*& aMask,
1.583 + const TDesC& aFilename,
1.584 + const TInt aFileBitmapId, const TInt aFileMaskId,
1.585 + const TRgb aDefaultColor,
1.586 + const TSize& aSize, const TScaleMode aScaleMode );
1.587 +
1.588 + public: // New functions - Item access w/o support for scalable graphics
1.589 +
1.590 + /**
1.591 + * Constructs an application icon. Icon bitmaps are duplicated to the
1.592 + * given CApaMaskedBitmap object.
1.593 + *
1.594 + * Since Series 60 Release 2.6, this method is fallback-enabled.
1.595 + * If no icon is found in the currently active skin, it uses
1.596 + * AppArch to construct the icon.
1.597 + *
1.598 + * @since 2.0
1.599 + *
1.600 + * @param aInstance Pointer to current skin instance.
1.601 + *
1.602 + * @param aAppUid Application UID. Icon is searched with major IID
1.603 + * ::EAknsIIDMajorAppIcon and minor IID aAppUid. AppArch search
1.604 + * is always performed with UID only.
1.605 + *
1.606 + * @param aSize Maximum size of the icon.
1.607 + *
1.608 + * @param aAppBitmap On return contains the icon.
1.609 + *
1.610 + * @return KErrNone if succeeded, KErrNotFound if no icon was found
1.611 + * or size requirements were not met, other error code if
1.612 + * another error occured.
1.613 + *
1.614 + * @par Note:
1.615 + * This method does not support scalable graphics.
1.616 + * Consider using @c CreateAppIconLC instead.
1.617 + */
1.618 + IMPORT_C static TInt GetAppIcon(
1.619 + MAknsSkinInstance* aInstance, TUid aAppUid, TSize aSize,
1.620 + CApaMaskedBitmap& aAppBitmap );
1.621 +
1.622 + public: // New functions - Item access w/ ownership
1.623 +
1.624 + /**
1.625 + * Constructs an independent bitmap.
1.626 + * Creates an independent copy of bitmap (in terms of instance ownership)
1.627 + * by given item ID.
1.628 + *
1.629 + * @since 2.0
1.630 + *
1.631 + * @param aInstance Pointer to current skin instance.
1.632 + *
1.633 + * @param aID Item ID of the bitmap to be created.
1.634 + *
1.635 + * @return Pointer to the newly created bitmap. Ownership of the object
1.636 + * is transferred to the caller.
1.637 + *
1.638 + * @par Exceptions:
1.639 + * - If data construction fails or bitmap is not found, function
1.640 + * leaves with an error code.
1.641 + */
1.642 + IMPORT_C static CFbsBitmap* CreateBitmapL(
1.643 + MAknsSkinInstance* aInstance, const TAknsItemID& aID );
1.644 +
1.645 + /**
1.646 + * Constructs an independent masked bitmap.
1.647 + * Creates an independent (in terms of instance ownership) copy of a
1.648 + * masked bitmap by the given item ID.
1.649 + *
1.650 + * Alternatively, masked bitmaps can be retrieved by using
1.651 + * @c MAknsSkinInstance::GetCachedItemData(TAknsItemID,TAknsItemType)
1.652 + * or
1.653 + * @c MAknsSkinInstance::CreateUncachedItemDataL(TAknsItemID,TAknsItemType)
1.654 + * methods. For these, @c ::EAknsITMaskedBitmap should be given as the
1.655 + * second parameter. Returned @c CAknsItemData pointer can be casted
1.656 + * to a @c CAknsMaskedBitmapItemData pointer in order to get access
1.657 + * to the bitmap objects themselves.
1.658 + *
1.659 + * @par Note:
1.660 + * This method does not have fallback support (to load the bitmap from
1.661 + * the specified file in case it is not available in the current
1.662 + * skin). Consider using one of the fallback-enabled overloads
1.663 + * instead.
1.664 + *
1.665 + * @since 2.0
1.666 + *
1.667 + * @param aInstance Pointer to the current skin instance.
1.668 + *
1.669 + * @param aID Item ID of the masked bitmap to be created.
1.670 + *
1.671 + * @return Pointer to the newly created CApaMaskedBitmap object.
1.672 + * Ownership of the object is transferred to the caller.
1.673 + *
1.674 + * @par Exceptions:
1.675 + * If data construction fails or bitmap is not found, the function
1.676 + * leaves with an error code.
1.677 + *
1.678 + * @par Note:
1.679 + * Since @c CApaMaskedBitmap can not be used to store scalable
1.680 + * graphics, consider using @c CreateIconLC instead.
1.681 + */
1.682 + IMPORT_C static CApaMaskedBitmap* CreateMaskedBitmapL(
1.683 + MAknsSkinInstance* aInstance, const TAknsItemID& aID );
1.684 +
1.685 + /**
1.686 + * Constructs an independent CGulIcon object.
1.687 + * Creates an independent (in terms of instance ownership) copy of a
1.688 + * bitmap or a masked bitmap by the given item ID, and returns it as a
1.689 + * newly constructed CGulIcon object.
1.690 + *
1.691 + * @par Note:
1.692 + * This method does not have fallback support (to load the bitmap from
1.693 + * the specified file in case it is not available in the current
1.694 + * skin). Consider using one of the fallback-enabled overloads
1.695 + * instead.
1.696 + *
1.697 + * @since 2.1
1.698 + *
1.699 + * @lib AknSkins.lib
1.700 + *
1.701 + * @param aInstance Pointer to the current skin instance.
1.702 + *
1.703 + * @param aID Item ID of the bitmap or masked bitmap to be created.
1.704 + *
1.705 + * @param aRequireMask ETrue if masked bitmap is explicitly required.
1.706 + * EFalse if mask is optional.
1.707 + *
1.708 + * @return Pointer to the newly created CGulIcon object.
1.709 + * Ownership of the object is transferred to the caller.
1.710 + *
1.711 + * @par Exceptions:
1.712 + * If data construction fails or bitmap is not found, the function
1.713 + * leaves with an error code.
1.714 + */
1.715 + IMPORT_C static CGulIcon* CreateGulIconL(
1.716 + MAknsSkinInstance* aInstance, const TAknsItemID& aID,
1.717 + const TBool aRequireMask );
1.718 +
1.719 + public: // New functions - Item access w/o ownership
1.720 +
1.721 + /**
1.722 + * Returns pointer to a cached bitmap.
1.723 + * Retrieves (and constructs if necessary) a bitmap in skin instance
1.724 + * cache. Caller can use the bitmap temporarily (e.g. in drawing code),
1.725 + * but should not store pointer to it, since its lifetime is determined
1.726 + * by cache.
1.727 + *
1.728 + * @since 2.0
1.729 + *
1.730 + * @param aInstance Pointer to current skin instance. If @c NULL value
1.731 + * is specified, method immediately returns with @c NULL return value.
1.732 + *
1.733 + * @param aID Item ID of the bitmap to be retrieved.
1.734 + *
1.735 + * @return Pointer to the bitmap, or @c NULL if no bitmap with given ID
1.736 + * was found or an error occured.
1.737 + *
1.738 + * @par Exceptions:
1.739 + * - Because the method can not leave, error handling procedure
1.740 + * described in
1.741 + * MAknsSkinInstance::GetCachedItemData(const TAknsItemID& aID) is
1.742 + * used if data construction fails.
1.743 + */
1.744 + IMPORT_C static CFbsBitmap* GetCachedBitmap(
1.745 + MAknsSkinInstance* aInstance, const TAknsItemID& aID );
1.746 +
1.747 + /**
1.748 + * Retrieves temporary pointers to a cached bitmap and its mask.
1.749 + * Retrieves (and constructs, if necessary) a masked bitmap in the skin
1.750 + * instance cache. Pointers to the bitmap (and its mask) are stored
1.751 + * to the pointers given as parameters. Caller can use the bitmaps
1.752 + * temporarily (e.g. in drawing code), but should not store them, since
1.753 + * their lifetimes are determined by the cache.
1.754 + *
1.755 + * @since 2.1
1.756 + *
1.757 + * @param aInstance Pointer to the current skin instance. If @c NULL
1.758 + * value is specified, the method assigns @c NULL to both the given
1.759 + * pointers and then returns.
1.760 + *
1.761 + * @param aID Item ID of the bitmap (or masked bitmap) to be retrieved.
1.762 + *
1.763 + * @param aBitmap Reference to the pointer that will receive the bitmap.
1.764 + * @c NULL value is assigned if no bitmap with the given ID was found
1.765 + * or an error occured.
1.766 + *
1.767 + * @param aMask Reference to the pointer that will receive the mask.
1.768 + * @c NULL value is assigned if no bitmap with the given ID was found,
1.769 + * or the bitmap did not have a mask, or an error occured.
1.770 + *
1.771 + * @par Exceptions:
1.772 + * - Because the method can not leave, error handling procedure
1.773 + * described in
1.774 + * MAknsSkinInstance::GetCachedItemData(const TAknsItemID& aID) is
1.775 + * used if data construction fails.
1.776 + */
1.777 + IMPORT_C static void GetCachedMaskedBitmap(
1.778 + MAknsSkinInstance* aInstance, const TAknsItemID& aID,
1.779 + CFbsBitmap*& aBitmap, CFbsBitmap*& aMask );
1.780 +
1.781 + /**
1.782 + * Returns a color value from a cached color table.
1.783 + * Retrieves (and constructs if necessary) a color table in
1.784 + * skin instance cache and returns a color value from it.
1.785 + *
1.786 + * Since release 2.8, this method also handles any backward
1.787 + * compatibility operations possibly required.
1.788 + *
1.789 + * @since 2.0
1.790 + *
1.791 + * @param aInstance Pointer to current skin instance. If @c NULL value
1.792 + * is specified, returns KErrNotSupported.
1.793 + *
1.794 + * @param aRgb Reference to a TRgb that will receive the color.
1.795 + *
1.796 + * @param aID Item ID of the color table.
1.797 + *
1.798 + * @param aIndex Index of the color in the color table.
1.799 + *
1.800 + * @return KErrNone if successful, otherwise an error code is returned.
1.801 + */
1.802 + IMPORT_C static TInt GetCachedColor(
1.803 + MAknsSkinInstance* aInstance, TRgb& aRgb, const TAknsItemID& aID,
1.804 + const TInt aIndex );
1.805 +
1.806 + /**
1.807 + * Retrieves the value of the given boolean property skin item.
1.808 + *
1.809 + * @since 2.8
1.810 + *
1.811 + * @param aInstance Pointer to current skin instance. If @c NULL value
1.812 + * is specified, the method leaves.
1.813 + *
1.814 + * @param aID Item ID of the boolean property.
1.815 + *
1.816 + * @return Value of the boolean property as @c TBool.
1.817 + *
1.818 + * @par Exceptions:
1.819 + * - If the item is not found, leaves with @c KErrNotFound.
1.820 + * - If the item is not a boolean property or another error occures,
1.821 + * leaves with a system-wide error code.
1.822 + */
1.823 + IMPORT_C static TBool BooleanPropertyL( MAknsSkinInstance* aInstance,
1.824 + const TAknsItemID& aID );
1.825 +
1.826 + /**
1.827 + * Test whether the given type is derived from the given base type.
1.828 + *
1.829 + * @since 2.0
1.830 + *
1.831 + * @param aBaseType Base type.
1.832 + *
1.833 + * @param aDerivedType Derived type.
1.834 + *
1.835 + * @return ETrue if the type is derived from the base type, EFalse
1.836 + * otherwise.
1.837 + *
1.838 + * @internal
1.839 + */
1.840 + static TBool IsDerivedType( const TAknsItemType aBaseType,
1.841 + const TAknsItemType aDerivedType );
1.842 +
1.843 + public: // New functions - Avkon parameters
1.844 +
1.845 + /**
1.846 + * Sets the flag indicating whether default skin parameters should
1.847 + * be used for newly created Avkon controls in the scope of the
1.848 + * current AppUi.
1.849 + *
1.850 + * @since 2.0
1.851 + *
1.852 + * @param Value of the flag as TBool.
1.853 + *
1.854 + * @par Exceptions:
1.855 + * If construction of the storage object for the flag fails,
1.856 + * leaves with an error code.
1.857 + */
1.858 + IMPORT_C static void SetAvkonSkinEnabledL( const TBool aEnabled );
1.859 +
1.860 + /**
1.861 + * Queries whether default skin parameters should be used for newly
1.862 + * created Avkon controls. Components supporting
1.863 + * <code>SetSkinEnabledL</code> method should also check for this
1.864 + * value upon construction and set their internal state accordingly.
1.865 + *
1.866 + * Note that this flag is intended to be used to determine whether or
1.867 + * not controls should create skin backgrounds for main pane
1.868 + * layouts. Skins are always enabled for e.g. all the popup windows,
1.869 + * even through the flag may be @c EFalse, and therefore the flag
1.870 + * must not be used as a generic "are skins enabled" switch.
1.871 + *
1.872 + * Most controls do not (and should not) query the flag value. If
1.873 + * control just fetches the skin control context with
1.874 + * @c AknsDrawUtils::ControlContext, it will get the proper @c NULL
1.875 + * value if no background has been defined.
1.876 + *
1.877 + * @since 2.0
1.878 + *
1.879 + * @return ETrue if default skin parameters should be used,
1.880 + * EFalse otherwise. The default value is EFalse.
1.881 + */
1.882 + IMPORT_C static TBool AvkonSkinEnabled();
1.883 +
1.884 + /**
1.885 + * Sets the flag indicating whether highlight animations should be used
1.886 + * for Avkon list controls in the scope of the current AppUi.
1.887 + *
1.888 + * @since 3.0
1.889 + *
1.890 + * @param Value of the flag as TBool.
1.891 + *
1.892 + * @par Exceptions:
1.893 + * If construction of the storage object for the flag fails,
1.894 + * leaves with an error code.
1.895 + */
1.896 + IMPORT_C static void SetAvkonHighlightAnimationEnabledL( const TBool aEnabled );
1.897 +
1.898 + /**
1.899 + * Queries whether highlight animation should be used for newly created
1.900 + * Avkon list controls.
1.901 + *
1.902 + * @since 3.0
1.903 + *
1.904 + * @return ETrue if list highlight animation should be used, EFalse
1.905 + * otherwise. The default value is ETrue.
1.906 + */
1.907 + IMPORT_C static TBool AvkonHighlightAnimationEnabled();
1.908 +
1.909 + public: // New functions - Control position list
1.910 +
1.911 + /**
1.912 + * Registers the position of the given control.
1.913 + * The position is stored in the thread-local control position list.
1.914 + * If the control has already been registered, its position is updated.
1.915 + *
1.916 + * Registering the position of the control enables background drawing
1.917 + * methods in AknsDrawUtils to calculate positions in
1.918 + * parent-absolute layouts without causing window server flushes.
1.919 + *
1.920 + * When a registered control goes out of scope, it must call
1.921 + * AknsUtils::DeregisterControlPosition to ensure that it is properly
1.922 + * removed from the list.
1.923 + *
1.924 + * @since 2.0
1.925 + *
1.926 + * @param aControl Pointer to the control that needs its position
1.927 + * to be updated in the control position list.
1.928 + */
1.929 + IMPORT_C static void RegisterControlPosition(
1.930 + const CCoeControl* aControl );
1.931 +
1.932 + /**
1.933 + * Registers the position of the given control with given position.
1.934 + * The position is stored in the thread-local control position list.
1.935 + * If the control has already been registered, its position is updated.
1.936 + *
1.937 + * Registering the position of the control enables background drawing
1.938 + * methods in AknsDrawUtils to calculate positions in
1.939 + * parent-absolute layouts without causing window server flushes.
1.940 + *
1.941 + * When a registered control goes out of scope, it must call
1.942 + * AknsUtils::DeregisterControlPosition to ensure that it is properly
1.943 + * removed from the list.
1.944 + *
1.945 + * @since 2.0
1.946 + *
1.947 + * @param aControl Pointer to the control that needs its position
1.948 + * to be updated in the control position list.
1.949 + *
1.950 + * @param aPoint The new position to be registered with the given
1.951 + * control (in screen coordinates).
1.952 + */
1.953 + IMPORT_C static void RegisterControlPosition(
1.954 + const CCoeControl* aControl, const TPoint& aPoint );
1.955 +
1.956 + /**
1.957 + * Removes the position of the given control from the list.
1.958 + * The position of the given control is removed from the thread-local
1.959 + * control position list. If the control has not been registered,
1.960 + * this method does nothing.
1.961 + *
1.962 + * @since 2.0
1.963 + *
1.964 + * @param aControl Pointer to the control that needs to be removed
1.965 + * from the control position list.
1.966 + */
1.967 + IMPORT_C static void DeregisterControlPosition(
1.968 + const CCoeControl* aControl );
1.969 +
1.970 + /**
1.971 + * Gets the position of the control registered in the control position
1.972 + * list.
1.973 + *
1.974 + * @param aControl Pointer to the control whose position is to be
1.975 + * queried.
1.976 + *
1.977 + * @param aScreenPos Reference to the TPoint that will receive the
1.978 + * position.
1.979 + *
1.980 + * @return KErrNone if successful, KErrNotFound if the control has
1.981 + * not been registered.
1.982 + */
1.983 + IMPORT_C static TInt GetControlPosition( const CCoeControl* aControl,
1.984 + TPoint& aScreenPos );
1.985 +
1.986 + private: // Internal methods
1.987 +
1.988 + /**
1.989 + * Gets an application icon from skin.
1.990 + *
1.991 + * @since 2.8
1.992 + *
1.993 + * @internal
1.994 + */
1.995 + static TInt GetAppIconFromSkin(
1.996 + MAknsSkinInstance* aInstance, TUid aAppUid, TSize aSize,
1.997 + CFbsBitmap*& aBitmap, CFbsBitmap*& aMask );
1.998 +
1.999 + /**
1.1000 + * Returns the best application icon bitmap IID among the listed icons.
1.1001 + *
1.1002 + * @since 2.1
1.1003 + *
1.1004 + * @param aSize Maximum size.
1.1005 + *
1.1006 + * @param aSkin Skin instance.
1.1007 + *
1.1008 + * @param aAppIconIID Item ID of the application icon.
1.1009 + *
1.1010 + * @return Icon bitmap IID.
1.1011 + *
1.1012 + * @internal
1.1013 + */
1.1014 + static TAknsItemID SelectBestAppIconBitmapL(
1.1015 + const TSize& aSize, MAknsSkinInstance* aSkin,
1.1016 + const TAknsItemID& aAppIconIID );
1.1017 +
1.1018 + private: // Reserved exports
1.1019 +
1.1020 + /**
1.1021 + * Reserved for future use.
1.1022 + *
1.1023 + * @since 2.0
1.1024 + *
1.1025 + * @return Always returns zero.
1.1026 + */
1.1027 + IMPORT_C static TInt Reserved();
1.1028 +
1.1029 + private: // Prohibited constructors and destructor
1.1030 +
1.1031 + // Construction prohibited (static class)
1.1032 + AknsUtils();
1.1033 + // Destruction prohibited (static class)
1.1034 + ~AknsUtils();
1.1035 + };
1.1036 +
1.1037 +#endif // AKNSUTILS_H
1.1038 +
1.1039 +// End of File