1 /*

     2 * Copyright (c) 2002 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Defines a public interface class MAknsSkinInstance and related

    15 *                enumerations.

    16 *

    17 */

    18 

    19 

    20 #ifndef AKNSSKININSTANCE_H

    21 #define AKNSSKININSTANCE_H

    22 

    23 //  INCLUDES

    24 #include <e32std.h>

    25 

    26 #include <AknsDataContext.h>

    27 #include <AknsItemData.h>

    28 

    29 // FORWARD DECLARATIONS

    30 class CFbsBitGc;

    31 class CAknsItemDef;

    32 

    33 // DATA TYPES

    34 

    35 /**

    36 * Type enumeration for skin client errors.

    37 *

    38 * @since 2.0

    39 */

    40 enum TAknsClientError

    41     {

    42     /**

    43     * Unspecified error.

    44     */

    45     EAknsClientErrorUnspecified     = 0,

    46 

    47     /**

    48     * Out of memory.

    49     *

    50     * @since 2.5

    51     */

    52     EAknsClientErrorOOM             = -4

    53     };

    54 

    55 /**

    56 * Type enumeration for the last skin change reason.

    57 *

    58 * @since 3.1

    59 *

    60 */

    61 enum TAknsSkinChangeReason

    62     {

    63     // For normal skin change events, ie. all item change

    64     ENormalSkinChange       = 0,

    65     // When a morphing state is changed, ie. only backgrounds change

    66     EMorphingStateChange    = 1,

    67     // When the wallpaper is changed, ie. only the wallpaper change

    68     EWallpaperChange        = 2

    69     };

    70 

    71 

    72 // CLASS DECLARATION

    73 

    74 /**

    75 * Interface to skin instance.

    76 * Skin instance is a singleton object that can be retrieved using

    77 * AknsUtils::SkinInstance(). It maintains item cache, but also

    78 * local item definition list and root data context. While skin instance

    79 * can be used directly by client code, it is often easier to use utility

    80 * methods provided in AknsUtils and AknsDrawUtils.

    81 *

    82 * This is a public interface class that contains no exported functions.

    83 * The class is not intended for derivation outside the library.

    84 *

    85 * @since 2.0

    86 */

    87 class MAknsSkinInstance

    88     {

    89     public:  // Constructors and destructor

    90         

    91         /**

    92         * Destructor for internal use.

    93         * Destructor is reserved for internal use and should be never

    94         * called by client code on singleton instance.

    95         *

    96         * @internal

    97         */

    98         inline virtual ~MAknsSkinInstance() {}

    99 

   100     public: // New functions - Item data

   101 

   102         /**

   103         * Returns root data context.

   104         * Root data context is used by other data context instances to

   105         * indicate data reservations and releases. It may also be used

   106         * directly by application code, if no other context is available.

   107         * Nearest data context can be retrieved using 

   108         * AknsUtils::DataContext(MObjectProvider* aMop) utility method.

   109         *

   110         * @since 2.0

   111         *

   112         * @return Pointer to root data context. Skin instance still owns the

   113         *   data context and its lifetime is that of skin instance itself.

   114         */

   115         virtual MAknsDataContext* RootDataContext() =0;

   116 

   117         /**

   118         * Returns (and constructs if necessary) cached item data object.

   119         * The method first searches the cache for the specified item. 

   120         * If none is found, it creates and caches a new instance of the 

   121         * item data.

   122         *

   123         * @since 2.0

   124         *

   125         * @param aID Item ID of the item to be retrieved.

   126         *

   127         * @param aType Type of the item.

   128         *

   129         * @return Item data for the specified item, or @c NULL value if

   130         *   none was found or an error occured. The caller can assume that a

   131         *   non-NULL value is a pointer that can be casted to the subclass

   132         *   corresponding to aType.

   133         *

   134         * @par Exceptions:

   135         *   Since this is a non-leaving method, the skin instance may perform

   136         *   error handling, e.g., by instructing the system to switch to the

   137         *   default skin.

   138         */

   139         virtual CAknsItemData* GetCachedItemData( const TAknsItemID& aID,

   140             const TAknsItemType aType ) =0;

   141 

   142         /**

   143         * Returns (and constructs if necessary) cached item data object.

   144         * The method first searches the cache for the specified item. 

   145         * If none is found, it creates and caches a new instance of the 

   146         * item data. 

   147         *

   148         * This overload can be used to retrieve items if the type of the

   149         * item is not known beforehand. In other cases, the first overload

   150         * shold be preferred, since it may be considerably faster.

   151         *

   152         * @since 2.0

   153         *

   154         * @param aID Item ID of the item to be retrieved.

   155         *

   156         * @return Item data for the specified item, or @c NULL value if

   157         *   none was found or an error occured.

   158         *

   159         * @par Exceptions:

   160         *   Since this is a non-leaving method, the skin instance may perform

   161         *   error handling, e.g., by instructing the system to switch to the

   162         *   default skin.

   163         */

   164         virtual CAknsItemData* GetCachedItemData( const TAknsItemID& aID ) =0;

   165 

   166         /**

   167         * Creates a new non-cached item data object.

   168         * The method constructs a new instance of item data of the specified 

   169         * skin item and returns it.

   170         *

   171         * @since 2.0

   172         *

   173         * @param aID Item ID of the item to be created.

   174         *

   175         * @param aType Type of the item.

   176         *

   177         * @return Newly created item data object. Ownership of the object is

   178         *   transferred to the caller. If no item definition for the specified

   179         *   ID was found, @c NULL value is returned. The caller can assume that

   180         *   a non-NULL value is a pointer that can be casted to the subclass

   181         *   corresponding to aType.

   182         *

   183         * @par Exceptions:

   184         *   If item data construction fails, function leaves with an error code.

   185         */

   186         virtual CAknsItemData* CreateUncachedItemDataL( const TAknsItemID& aID,

   187             const TAknsItemType aType ) =0;

   188 

   189         /**

   190         * Creates a new non-cached item data object.

   191         * The method constructs a new instance of item data of the specified 

   192         * skin item and returns it.

   193         *

   194         * This overload can be used to create items if the type of the

   195         * item is not known beforehand. In other cases, the first overload

   196         * shold be preferred, since it may be considerably faster.

   197         *

   198         * @since 2.0

   199         *

   200         * @param aID Item ID of the item to be created.

   201         *

   202         * @return Newly created item data object. Ownership of the object is

   203         *   transferred to the caller. If no item definition for the specified

   204         *   ID was found, @c NULL value is returned.

   205         *

   206         * @par Exceptions:

   207         *   If item data construction fails, function leaves with an error code.

   208         */

   209         virtual CAknsItemData* CreateUncachedItemDataL( const TAknsItemID& aID ) =0;

   210  

   211     public: // New functions - Item definitions

   212 

   213         /**

   214         * Sets local item definition.

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

   216         *

   217         * @since 2.0

   218         *

   219         * @param aDef New local item definition. Ownership of definition object

   220         *   is transferred to skin instance and caller should make no access

   221         *   to it after this call.

   222         *

   223         * @par Exceptions:

   224         *   If an error occurs, function leaves with an error code. Item 

   225         *   definition object is either added into local definition list or

   226         *   destroyed depending on when the error occured.

   227         *

   228         * @par Note:

   229         *   Since the method always assumes ownership of @c aDef, it must

   230         *   not be pushed into the cleanup stack.

   231         */

   232         virtual void SetLocalItemDefL( CAknsItemDef* aDef ) =0;   

   233         

   234         /**

   235         * Enables or disables change notifications.

   236         * When enabled, resource change events are sent to the application when

   237         * item definitions change. If a change occurs when events are disabled,

   238         * it will be sent (collated, only one event) when events are re-enabled.

   239         *

   240         * @since 2.0

   241         *

   242         * @param aEnabled ETrue to enable events, EFalse to disable them.

   243         */

   244         virtual void SetChangeEventsEnabled( TBool aEnabled ) =0;

   245 

   246     public: // New functions - Error handling

   247 

   248         /**

   249         * Notifies the skin instance about an error condition.

   250         * Errors that can be reported to the skin instance include incorrect

   251         * skin content (e.g., a bitmap that can not be constructed) or

   252         * out of memory situations. The error condition is usually handled by

   253         * switching to the default system skin. Error notifications will be

   254         * ignored when there is no reasonable recovery operation available.

   255         *

   256         * @since 2.0

   257         *

   258         * @param aError Error type. Currently only EAknsClientErrorUnspecified

   259         *   is supported.

   260         */

   261         virtual void NotifyClientError( const TAknsClientError aError ) =0;

   262     

   263     public: // New functions - querying the skin change reason.

   264         /**

   265         * Queries the last skin change reason. This function can be used

   266         * to query the last reason why skin change occurred. Usually client

   267         * would use this inside the HandleResourceChange call. If no skin

   268         * change events have been reported for the application, the function

   269         * returns ENormalSkinChange.

   270         *

   271         * @since 3.1

   272         *

   273         * @return the last skin change reason.

   274         */

   275         virtual TAknsSkinChangeReason SkinChangeReason() = 0;

   276         

   277     public:

   278         /**

   279         * Removes all local item defs from this instance set by

   280         * SetLocalItemDefL

   281         */

   282         virtual void RemoveLocalItemDefs() = 0;

   283         

   284         /**

   285         * Checks whether a skin update is currently being done.

   286         *

   287         * @since 5.0

   288         */

   289         virtual TBool IsUpdateInProgress() = 0;       

   290     };

   291 

   292 #endif      // AKNSSKININSTANCE_H   

   293             

   294 // End of File