diff -r 000000000000 -r 05e9090e2422 uiresources_pub/skins_api/inc/AknsSkinInstance.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/uiresources_pub/skins_api/inc/AknsSkinInstance.h Thu Dec 17 09:14:12 2009 +0200 @@ -0,0 +1,294 @@ +/* +* Copyright (c) 2002 Nokia Corporation and/or its subsidiary(-ies). +* All rights reserved. +* This component and the accompanying materials are made available +* under the terms of "Eclipse Public License v1.0" +* which accompanies this distribution, and is available +* at the URL "http://www.eclipse.org/legal/epl-v10.html". +* +* Initial Contributors: +* Nokia Corporation - initial contribution. +* +* Contributors: +* +* Description: Defines a public interface class MAknsSkinInstance and related +* enumerations. +* +*/ + + +#ifndef AKNSSKININSTANCE_H +#define AKNSSKININSTANCE_H + +// INCLUDES +#include + +#include +#include + +// FORWARD DECLARATIONS +class CFbsBitGc; +class CAknsItemDef; + +// DATA TYPES + +/** +* Type enumeration for skin client errors. +* +* @since 2.0 +*/ +enum TAknsClientError + { + /** + * Unspecified error. + */ + EAknsClientErrorUnspecified = 0, + + /** + * Out of memory. + * + * @since 2.5 + */ + EAknsClientErrorOOM = -4 + }; + +/** +* Type enumeration for the last skin change reason. +* +* @since 3.1 +* +*/ +enum TAknsSkinChangeReason + { + // For normal skin change events, ie. all item change + ENormalSkinChange = 0, + // When a morphing state is changed, ie. only backgrounds change + EMorphingStateChange = 1, + // When the wallpaper is changed, ie. only the wallpaper change + EWallpaperChange = 2 + }; + + +// CLASS DECLARATION + +/** +* Interface to skin instance. +* Skin instance is a singleton object that can be retrieved using +* AknsUtils::SkinInstance(). It maintains item cache, but also +* local item definition list and root data context. While skin instance +* can be used directly by client code, it is often easier to use utility +* methods provided in AknsUtils and AknsDrawUtils. +* +* This is a public interface class that contains no exported functions. +* The class is not intended for derivation outside the library. +* +* @since 2.0 +*/ +class MAknsSkinInstance + { + public: // Constructors and destructor + + /** + * Destructor for internal use. + * Destructor is reserved for internal use and should be never + * called by client code on singleton instance. + * + * @internal + */ + inline virtual ~MAknsSkinInstance() {} + + public: // New functions - Item data + + /** + * Returns root data context. + * Root data context is used by other data context instances to + * indicate data reservations and releases. It may also be used + * directly by application code, if no other context is available. + * Nearest data context can be retrieved using + * AknsUtils::DataContext(MObjectProvider* aMop) utility method. + * + * @since 2.0 + * + * @return Pointer to root data context. Skin instance still owns the + * data context and its lifetime is that of skin instance itself. + */ + virtual MAknsDataContext* RootDataContext() =0; + + /** + * Returns (and constructs if necessary) cached item data object. + * The method first searches the cache for the specified item. + * If none is found, it creates and caches a new instance of the + * item data. + * + * @since 2.0 + * + * @param aID Item ID of the item to be retrieved. + * + * @param aType Type of the item. + * + * @return Item data for the specified item, or @c NULL value if + * none was found or an error occured. The caller can assume that a + * non-NULL value is a pointer that can be casted to the subclass + * corresponding to aType. + * + * @par Exceptions: + * Since this is a non-leaving method, the skin instance may perform + * error handling, e.g., by instructing the system to switch to the + * default skin. + */ + virtual CAknsItemData* GetCachedItemData( const TAknsItemID& aID, + const TAknsItemType aType ) =0; + + /** + * Returns (and constructs if necessary) cached item data object. + * The method first searches the cache for the specified item. + * If none is found, it creates and caches a new instance of the + * item data. + * + * This overload can be used to retrieve items if the type of the + * item is not known beforehand. In other cases, the first overload + * shold be preferred, since it may be considerably faster. + * + * @since 2.0 + * + * @param aID Item ID of the item to be retrieved. + * + * @return Item data for the specified item, or @c NULL value if + * none was found or an error occured. + * + * @par Exceptions: + * Since this is a non-leaving method, the skin instance may perform + * error handling, e.g., by instructing the system to switch to the + * default skin. + */ + virtual CAknsItemData* GetCachedItemData( const TAknsItemID& aID ) =0; + + /** + * Creates a new non-cached item data object. + * The method constructs a new instance of item data of the specified + * skin item and returns it. + * + * @since 2.0 + * + * @param aID Item ID of the item to be created. + * + * @param aType Type of the item. + * + * @return Newly created item data object. Ownership of the object is + * transferred to the caller. If no item definition for the specified + * ID was found, @c NULL value is returned. The caller can assume that + * a non-NULL value is a pointer that can be casted to the subclass + * corresponding to aType. + * + * @par Exceptions: + * If item data construction fails, function leaves with an error code. + */ + virtual CAknsItemData* CreateUncachedItemDataL( const TAknsItemID& aID, + const TAknsItemType aType ) =0; + + /** + * Creates a new non-cached item data object. + * The method constructs a new instance of item data of the specified + * skin item and returns it. + * + * This overload can be used to create items if the type of the + * item is not known beforehand. In other cases, the first overload + * shold be preferred, since it may be considerably faster. + * + * @since 2.0 + * + * @param aID Item ID of the item to be created. + * + * @return Newly created item data object. Ownership of the object is + * transferred to the caller. If no item definition for the specified + * ID was found, @c NULL value is returned. + * + * @par Exceptions: + * If item data construction fails, function leaves with an error code. + */ + virtual CAknsItemData* CreateUncachedItemDataL( const TAknsItemID& aID ) =0; + + public: // New functions - Item definitions + + /** + * Sets local item definition. + * Adds (or replaces if one already exists) a local item definition. + * + * @since 2.0 + * + * @param aDef New local item definition. Ownership of definition object + * is transferred to skin instance and caller should make no access + * to it after this call. + * + * @par Exceptions: + * If an error occurs, function leaves with an error code. Item + * definition object is either added into local definition list or + * destroyed depending on when the error occured. + * + * @par Note: + * Since the method always assumes ownership of @c aDef, it must + * not be pushed into the cleanup stack. + */ + virtual void SetLocalItemDefL( CAknsItemDef* aDef ) =0; + + /** + * Enables or disables change notifications. + * When enabled, resource change events are sent to the application when + * item definitions change. If a change occurs when events are disabled, + * it will be sent (collated, only one event) when events are re-enabled. + * + * @since 2.0 + * + * @param aEnabled ETrue to enable events, EFalse to disable them. + */ + virtual void SetChangeEventsEnabled( TBool aEnabled ) =0; + + public: // New functions - Error handling + + /** + * Notifies the skin instance about an error condition. + * Errors that can be reported to the skin instance include incorrect + * skin content (e.g., a bitmap that can not be constructed) or + * out of memory situations. The error condition is usually handled by + * switching to the default system skin. Error notifications will be + * ignored when there is no reasonable recovery operation available. + * + * @since 2.0 + * + * @param aError Error type. Currently only EAknsClientErrorUnspecified + * is supported. + */ + virtual void NotifyClientError( const TAknsClientError aError ) =0; + + public: // New functions - querying the skin change reason. + /** + * Queries the last skin change reason. This function can be used + * to query the last reason why skin change occurred. Usually client + * would use this inside the HandleResourceChange call. If no skin + * change events have been reported for the application, the function + * returns ENormalSkinChange. + * + * @since 3.1 + * + * @return the last skin change reason. + */ + virtual TAknsSkinChangeReason SkinChangeReason() = 0; + + public: + /** + * Removes all local item defs from this instance set by + * SetLocalItemDefL + */ + virtual void RemoveLocalItemDefs() = 0; + + /** + * Checks whether a skin update is currently being done. + * + * @since 5.0 + */ + virtual TBool IsUpdateInProgress() = 0; + }; + +#endif // AKNSSKININSTANCE_H + +// End of File