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