/*

 * Copyright (c) 2002-2007 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 MAknsControlContext and 

 *                related enumerations.

 *

 */

 #ifndef AKNSCONTROLCONTEXT_H

 #define AKNSCONTROLCONTEXT_H

 //  INCLUDES

 #include <AknsConstants.h>

 #include <AknsItemID.h>

 #include <coemop.h>

 // DATA TYPES

 /** 

 * Skin parameter types for MAknsControlContext::SupplySkinParameter.

 *

 * @since 2.0

 */

 enum TAknsCCParameter

     {

     // This enumeration is intentionally empty.

     };

 /** 

 * Values for skin object types (given as aObject parameter for 

 * MAknsControlContext::SupplySkinObject).

 *

 * @since 2.0

 */

 enum TAknsCCObject

     {

     /**

     * Item ID for layout background.

     *

     * MAknsControlContext::SupplySkinObject

     * should return a pointer to TAknsBackground or @c NULL (default used).

     *

     * @since 2.0

     */

     EAknsCCOBackground              = 0,

     /**

     * Pointer to parent context.

     *

     * MAknsControlContext::SupplySkinObject

     * should return a pointer to the parent context (of type 

     * @c MAknsControlContext) or @c NULL (no parent context).

     *

     * @since 2.6

     */

     EAknsCCOParentContext           = 1

     };

 /**

 * Control context type enumeration.

 *

 * @since 2.0

 */

 enum TAknsControlContextType

     {

     /**

     * Unknown type. The control context can only be assumed to be compatible

     * with MAknsControlContext.

     *

     * @since 2.0

     */

     EAknsControlContextTypeUnknown  = 0,

     /**

     * The control context type for CAknsBasicBackgroundControlContext

     * (and derived types).

     *

     * @since 2.0

     */

     EAknsControlContextTypeBasic    = 1,

     /**

     * The control context type for CAknsLayeredBackgroundControlContext

     * (and derived types).

     *

     * @since 2.0

     */

     EAknsControlContextTypeLayered  = 2,

     /**

     * The control context type for CAknsListBoxBackgroundControlContext

     * (and derived types).

     *

     * @since 2.0

     */

     EAknsControlContextTypeListBox  = 3,

     /**

     * The control context type for CAknsFrameBackgroundControlContext

     * (and derived types).

     *

     * @since 2.0

     */

     EAknsControlContextTypeFrame    = 4,

     /**

     * The control context type for CAknsCombinedBackgroundControlContext

     * (and derived types).

     *

     * @since 3.2

     */

     EAknsControlContextTypeCombined = 5,

     /**

     * The control context type for CAknsMaskedFrameBackgroundControlContext

     * (and derived types).

     *

     * @since 3.2

     */

     EAknsControlContextTypeMasked = 6

     };

 // CLASS DECLARATIONS

 /**

 * Interface that provides context specific skin parameters.

 * This interface is used by AknsDrawUtils to query context specific parameters,

 * such as background override. Application should instantiate a class that 

 * implements this interface and provide pointer to it using 

 * @c MObjectProvider::MopSupplyObject in the appropriate control. 

 *

 * This is a public class with exported functions.

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

 * the interface are provided by the library. See 

 * @c CAknsBasicBackgroundControlContext and 

 * @c CAknsListBoxBackgroundControlContext for further details.

 *

 * @lib AknSkins.lib

 *

 * @since 2.0

 */

 class MAknsControlContext

     {

     public: // Type UID

         /**         

         * Type ID declaration.

         * Type ID is used to make it possible to retrieve control context

         * through @c MObjectProvider::MopSupplyObject interface.        

         */

         DECLARE_TYPE_ID(0x10005a29)

     public: // Destructor

         /**

         * Destructor.

         * Destructor is provided only to enable deletion using base class

         * pointer. Caller should never delete control context retrieved through

         * @c MObjectProvider interface.

         */

         inline virtual ~MAknsControlContext() {}

     public: // New functions

         /**

         * Provides context specific integer parameter.

         *

         * @since 2.0

         *

         * @param aParam Type of the parameter to be retrieved. Possible values

         *   are defined in ::TAknsCCParameter enumeration.

         *

         * @return Integer value as defined in ::TAknsCCParameter for the 

         *   particular parameter. For unknown or unhandled values zero must be

         *   returned.        

         */

         virtual TInt SupplySkinParameter( TAknsCCParameter aParam ) =0;

         /**

         * Provides context specific object.

         *

         * @since 2.0

         *

         * @param aObject Type of the object to be retrieved. Possible values 

         *   are defined in ::TAknsCCObject enumeration.

         *

         * @return Pointer to object as defined in ::TAknsCCObject for that 

         *   specific aObject parameter value. For unknown or unhandled values

         *   @c NULL must be returned.        

         */

         virtual TAny* SupplySkinObject( TAknsCCObject aObject ) =0;

         /**

         * Determines whether this control context is compatible with the

         * given derived type.

         *

         * @since 2.0

         *

         * @param aType Type of the derived control context class (one of

         *   the values in TAknsControlContextType).

         *

         * @return ETrue if this control context instance is compatible with

         *   the given type (i.e. can be casted to the corresponding concrete

         *   class). EFalse otherwise.

         */

         virtual TBool IsCompatibleWithType( 

             const TAknsControlContextType aType ) const =0;

         /**

         * Updates the control context, if necessary.

         * This method is called by the framework before drawing with the 

         * context.

         *

         * Base class implementation returns 0.

         *

         * @since 2.6

         *

         * @return Return value reserved for future use. Currently returns 0.

         */

         virtual TInt UpdateContext();

     protected: // Reserved virtual functions

         /**

         * Reserved for future use.

         *

         * @since 2.0

         */

         virtual TInt Reserved2();

     public: // New functions

         /**

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

         *

         * @since 2.0

         *

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

         *   parameter of MopSupplyObject.

         *

         * @param aContext Pointer to an MAknsControlContext instance.

         *

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

         *   pointer if given type UID does not match MAknsControlContext or

         *   aContext is @c NULL.

         */

         IMPORT_C static TTypeUid::Ptr SupplyMopObject( TTypeUid aId, 

             MAknsControlContext* aContext );

     };

 #endif      // AKNSCONTROLCONTEXT_H   

 // End of File