MAknsSkinInstance Class Reference

API published in: S60 2nd Ed

Link against: aknskins.lib aknskinsrv.lib aknswallpaperutils.lib

Capability Information

Required Capabilities

None

#include <aknsskininstance.h>

Detailed Description

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.


Public Member Functions
virtual  ~MAknsSkinInstance ()
  Destructor for internal use.
virtual MAknsDataContext *  RootDataContext ()=0
  Returns root data context.
virtual CAknsItemData *  GetCachedItemData (const TAknsItemID &aID, const TAknsItemType aType)=0
  Returns (and constructs if necessary) cached item data object.
virtual CAknsItemData *  GetCachedItemData (const TAknsItemID &aID)=0
  Returns (and constructs if necessary) cached item data object.
virtual CAknsItemData *  CreateUncachedItemDataL (const TAknsItemID &aID, const TAknsItemType aType)=0
  Creates a new non-cached item data object.
virtual CAknsItemData *  CreateUncachedItemDataL (const TAknsItemID &aID)=0
  Creates a new non-cached item data object.
virtual void  SetLocalItemDefL (CAknsItemDef *aDef)=0
  Sets local item definition.
virtual void  SetChangeEventsEnabled (TBool aEnabled)=0
  Enables or disables change notifications.
virtual void  NotifyClientError (const TAknsClientError aError)=0
  Notifies the skin instance about an error condition.
virtual TAknsSkinChangeReason  SkinChangeReason ()=0
  Queries the last skin change reason.
virtual void  RemoveLocalItemDefs ()=0
  Removes all local item defs from this instance set by SetLocalItemDefL.

Constructor & Destructor Documentation

virtual MAknsSkinInstance::~MAknsSkinInstance (   )  [inline, virtual]
 

Destructor for internal use.

Destructor is reserved for internal use and should be never called by client code on singleton instance.

Member Function Documentation

virtual CAknsItemData* MAknsSkinInstance::CreateUncachedItemDataL (  const TAknsItemID &  aID  )  [pure virtual]
 

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.

Parameters:
aID  Item ID of the item to be created.
Returns:
Newly created item data object. Ownership of the object is transferred to the caller. If no item definition for the specified ID was found, NULL value is returned.
Exceptions:
If item data construction fails, function leaves with an error code.
virtual CAknsItemData* MAknsSkinInstance::CreateUncachedItemDataL (  const TAknsItemID &  aID,
const TAknsItemType  aType
)  [pure virtual]
 

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.

Parameters:
aID  Item ID of the item to be created.
aType  Type of the item.
Returns:
Newly created item data object. Ownership of the object is transferred to the caller. If no item definition for the specified ID was found, 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.
Exceptions:
If item data construction fails, function leaves with an error code.
virtual CAknsItemData* MAknsSkinInstance::GetCachedItemData (  const TAknsItemID &  aID  )  [pure virtual]
 

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.

Parameters:
aID  Item ID of the item to be retrieved.
Returns:
Item data for the specified item, or NULL value if none was found or an error occured.
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* MAknsSkinInstance::GetCachedItemData (  const TAknsItemID &  aID,
const TAknsItemType  aType
)  [pure virtual]
 

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.

Parameters:
aID  Item ID of the item to be retrieved.
aType  Type of the item.
Returns:
Item data for the specified item, or 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.
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 void MAknsSkinInstance::NotifyClientError (  const TAknsClientError  aError  )  [pure virtual]
 

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.

Parameters:
aError  Error type. Currently only EAknsClientErrorUnspecified is supported.
virtual void MAknsSkinInstance::RemoveLocalItemDefs (   )  [pure virtual]
 

Removes all local item defs from this instance set by SetLocalItemDefL.

virtual MAknsDataContext* MAknsSkinInstance::RootDataContext (   )  [pure virtual]
 

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.

Returns:
Pointer to root data context. Skin instance still owns the data context and its lifetime is that of skin instance itself.
virtual void MAknsSkinInstance::SetChangeEventsEnabled (  TBool  aEnabled  )  [pure virtual]
 

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.

Parameters:
aEnabled  ETrue to enable events, EFalse to disable them.
virtual void MAknsSkinInstance::SetLocalItemDefL (  CAknsItemDef *  aDef  )  [pure virtual]
 

Sets local item definition.

Adds (or replaces if one already exists) a local item definition.

Parameters:
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.
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.
Note:
Since the method always assumes ownership of aDef, it must not be pushed into the cleanup stack.
virtual TAknsSkinChangeReason MAknsSkinInstance::SkinChangeReason (   )  [pure virtual]
 

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.

Returns:
the last skin change reason.
The documentation for this class was generated from the following file:
Copyright © Nokia Corporation 2001-2008
Back to top