/*

* 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