/*

 * 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 <e32std.h>

 #include <AknsDataContext.h>

 #include <AknsItemData.h>

 // 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