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 MAknsDataContext.

    15 *

    16 */

    17 

    18 

    19 #ifndef AKNSDATACONTEXT_H

    20 #define AKNSDATACONTEXT_H

    21 

    22 //  INCLUDES

    23 #include <AknsConstants.h>

    24 #include <AknsItemID.h>

    25 #include <coemop.h>

    26 

    27 // CLASS DECLARATION

    28 

    29 /**

    30 * Interface that provides context sensitive control over data allocation.

    31 * MAknsDataContext can be used to indicate need for specific skin items

    32 * and thus to ensure that they are allocated before first use.

    33 *

    34 * This is a public class with exported functions.

    35 * The class is not usually intended for user derivation - concrete classes

    36 * implementing the interface are provided by the library.

    37 * See @c AknsUtils::CreateDataContextForContainerL() for further 

    38 * details.

    39 *

    40 * @lib AknSkins.lib

    41 *

    42 * @since 2.0

    43 */

    44 class MAknsDataContext 

    45     {

    46     public: // Type UID

    47         /**         

    48         * Type ID declaration.

    49         * Type ID is used to make it possible to retrieve data context

    50         * through @c MObjectProvider::MopSupplyObject interface.

    51         */

    52         DECLARE_TYPE_ID(0x10005a28)

    53 

    54     public:  // Constructors and destructor    

    55 

    56         /**

    57         * Destructor.

    58         * Destructor is only provided to enable deletion using base class

    59         * pointer. Caller should never delete context retrieved using

    60         * @c MObjectProvider interface.

    61         */

    62         inline virtual ~MAknsDataContext() {}

    63         

    64     public: // New functions

    65 

    66         /**

    67         * Reserves and allocates specified item.

    68         * Instructs the data context that the specified item will be used

    69         * by caller and should be allocated and cached by skin instance.

    70         * Any control using cached skin items should reserve them, preferably

    71         * in @c ConstructL(), by calling this method.

    72         * Note that reservation does not guarantee that the item will be

    73         * available in cache - it's only a tentative request for allocation.

    74         *

    75         * @since 2.0

    76         *

    77         * @param aID Item ID of the item to be reserved.

    78         *

    79         * @par Exceptions:

    80         *   If item data allocation fails, function leaves with error code.

    81         */

    82         virtual void ReserveItemL( const TAknsItemID& aID ) =0;

    83 

    84 		/**

    85         * Indicates that specified item will no longer be used.

    86         * Instructs the data context that the specified item will not

    87         * be used by caller anymore. Exact behavior (e.g. whether cached

    88         * instance is deallocated) depends on the cache policy of data

    89         * context and skin instance. Controls should not usually call this

    90         * method, but instead allow data context (in most cases implemented

    91         * by a container) go out of scope. 

    92         *

    93         * @since 2.0

    94         * 

    95         * @param aID Item ID of the item to be released.

    96         */

    97         virtual void ReleaseItem( const TAknsItemID& aID ) =0;

    98 

    99     protected: // Reserved virtual functions

   100 

   101         /**

   102         * Reserved for future use.

   103         *

   104         * @since 2.0

   105         */

   106         virtual TInt Reserved1();

   107 

   108         /**

   109         * Reserved for future use.

   110         *

   111         * @since 2.0

   112         */

   113         virtual TInt Reserved2();

   114 

   115     public: // New functions

   116 

   117         /**

   118         * Returns type UID pointer that can be used in MopSupplyObject.

   119         *

   120         * @since 2.0

   121         *

   122         * @param aId Type UID, should be the same that was given as aId

   123         *   parameter of MopSupplyObject.

   124         *

   125         * @param aContext Pointer to an MAknsDataContext instance.

   126         *

   127         * @return Type UID pointer containing aContext, or @c NULL type UID

   128         *   pointer if given type UID does not match MAknsDataContext or

   129         *   aContext is @c NULL.

   130         */

   131         IMPORT_C static TTypeUid::Ptr SupplyMopObject( TTypeUid aId, 

   132             MAknsDataContext* aContext );

   133 

   134     };

   135 

   136 #endif // AKNSDATACONTEXT_H

   137             

   138 // End of File