williamr@2: // Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies). williamr@2: // All rights reserved. williamr@2: // This component and the accompanying materials are made available williamr@2: // under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members williamr@2: // which accompanies this distribution, and is available williamr@2: // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". williamr@2: // williamr@2: // Initial Contributors: williamr@2: // Nokia Corporation - initial contribution. williamr@2: // williamr@2: // Contributors: williamr@2: // williamr@2: // Description: williamr@2: // williamr@2: williamr@2: #ifndef __COEMOP_H__ williamr@2: #define __COEMOP_H__ williamr@2: williamr@2: #include williamr@2: williamr@2: /** Declares an object type, ETypeId, for a class, in order to allow the object williamr@2: provider mechanism to locate and provide objects from the class. williamr@2: williamr@2: @publishedAll williamr@2: @released williamr@2: @see MObjectProvider */ williamr@2: #define DECLARE_TYPE_ID(id) enum { ETypeId = id }; williamr@2: williamr@2: // williamr@2: // Used to wrap object type IDs in a standardised manner. Object type IDs must be asserted williamr@2: // in an ETypeId member data property by any types of object which williamr@2: // are capable of being retrieved by the MObjectProvider interface williamr@2: // williamr@2: class TTypeUid : public TUid williamr@2: /** Part of the object provider mechanism, this class encapsulates the Uid that williamr@2: identifies the type of object that an object provider is to get. williamr@2: williamr@2: The class is also used to encapsulate a pointer to the object that the object williamr@2: provider has found. williamr@2: williamr@2: An object that is intended to be capable of being retrieved by the object williamr@2: provider mechanism must include enum {ETypeId = 0xabcdefgh}; in its class williamr@2: definition, where 0xabcdefgh is the Uid value. The macro DECLARE_TYPE_ID can williamr@2: be used to do this. williamr@2: williamr@2: An instance of this class is passed to the MObjectProvider::MopSupplyObject() williamr@2: function implemented by an object provider. A TTypeUid::Ptr is also returned williamr@2: by this function. williamr@2: williamr@2: @publishedAll williamr@2: @released williamr@2: @see MObjectProvider */ williamr@2: { williamr@2: public: williamr@2: class Ptr williamr@2: /** Encapsulates a pointer to an object fetched by an object provider. williamr@2: williamr@2: The class has no public constructor. TTypeUid::MakePtr() or TTypeUid::Null() williamr@2: must be used to construct instances of this class. */ williamr@2: { williamr@2: friend class TTypeUid; williamr@2: private: williamr@2: explicit inline Ptr(TAny* aPtr) williamr@2: : iPtr(aPtr) williamr@2: {} williamr@2: public: williamr@2: inline TAny* Pointer() const williamr@2: /** Retrieves the pointer to an object which is encapsulated by the Ptr. williamr@2: williamr@2: @return A pointer to an object. */ williamr@2: {return iPtr;} williamr@2: private: williamr@2: TAny* iPtr; williamr@2: }; williamr@2: public: williamr@2: inline TTypeUid(TInt aUid) williamr@2: /** Constructor that takes a Uid value. williamr@2: williamr@2: @param aUid The Uid value that defines the type of object that an object provider williamr@2: is to get. */ williamr@2: { iUid = aUid; } williamr@2: inline static Ptr Null() williamr@2: /** Constructs a Ptr which encapsulates a NULL pointer. williamr@2: williamr@2: @return The constructed Ptr object */ williamr@2: { return Ptr(NULL); } williamr@2: template inline Ptr MakePtr(T* aT) const williamr@2: /** Constructs a Ptr which encapsulates the specified object pointer. williamr@2: williamr@2: @param aT A pointer to the object which is to be encapsulated. williamr@2: @return The constructed Ptr object */ williamr@2: { __ASSERT_DEBUG(iUid == T::ETypeId,User::Invariant()); return Ptr(aT); } williamr@2: }; williamr@2: williamr@2: williamr@2: class MObjectProvider williamr@2: /** An interface that allows an object to be part of a network of object providers. williamr@2: williamr@2: The object provider mechanism can be used to find and access objects of a williamr@2: given type, where the type is defined by a TTypeUid object. Object providers williamr@2: may be arranged in a hierarchy, i.e. an object provider may have a parent-child williamr@2: relationship with another object provider. williamr@2: williamr@2: An object provider must provide an implementation for the MopSupplyObject() williamr@2: function and can choose to provide an implementation for the MopNext() function. williamr@2: Typically, it will also have functionality to define who its parent is. williamr@2: williamr@2: CCoeControl is an example of a class that implements this interface. Top level williamr@2: controls must have the view or app UI set as their object provider. This is williamr@2: done by calling CCoeControl::SetMopParent() on the view or the app UI. The williamr@2: view or app UI does this by calling the top level control's CCoeControl::SetMopParent() williamr@2: function. williamr@2: williamr@2: @publishedAll williamr@2: @released */ williamr@2: { williamr@2: public: williamr@2: template williamr@2: T* MopGetObject(T*& aPtr) williamr@2: /** Gets an object of the type defined by the template parameter. williamr@2: williamr@2: The object may be supplied directly by this object provider, or by other object williamr@2: providers higher up the hierarchy. williamr@2: williamr@2: @param aPtr A reference to a pointer to an object of a type that is to be williamr@2: retrieved. williamr@2: @return A pointer to an object of the type required, or NULL if none can be williamr@2: found. */ williamr@2: { return (aPtr=(T*)MopGetById(T::ETypeId)); } williamr@2: williamr@2: williamr@2: template williamr@2: T* MopGetObjectNoChaining(T*& aPtr) williamr@2: /** Gets an object of the type defined by the template parameter. williamr@2: williamr@2: The object will be supplied directly by this object provider, or NULL williamr@2: will be returned, this function does not recurse through the object chain. williamr@2: williamr@2: @param aPtr A reference to a pointer to an object of a type that is to be williamr@2: retrieved. williamr@2: @return A pointer to an object of the type required, or NULL if none can be williamr@2: found. */ williamr@2: { return (aPtr=(T*)MopGetByIdNoChaining(T::ETypeId)); } williamr@2: williamr@2: /** williamr@2: @publishedAll williamr@2: @released */ williamr@2: MObjectProvider* FindParent(MObjectProvider* aMopToFind); williamr@2: williamr@2: private: // must be overridden williamr@2: /** Gets an object whose type is encapsulated by the specified TTypeUid object. williamr@2: williamr@2: @param aId Encapsulates the Uid that identifies the type of object required. williamr@2: @return Encapsulates the pointer to the object provided. williamr@2: Note that the encapsulated pointer may be NULL. williamr@2: williamr@2: @publishedAll williamr@2: @released */ williamr@2: virtual TTypeUid::Ptr MopSupplyObject(TTypeUid aId) = 0; williamr@2: williamr@2: protected: williamr@2: IMPORT_C MObjectProvider(); williamr@2: williamr@2: private: // may be overridden to continue chain of responsibility williamr@2: /** williamr@2: @publishedAll williamr@2: @released */ williamr@2: IMPORT_C virtual MObjectProvider* MopNext(); williamr@2: IMPORT_C virtual void MObjectProvider_Reserved1(); williamr@2: IMPORT_C virtual void MObjectProvider_Reserved2(); williamr@2: williamr@2: private: williamr@2: IMPORT_C TAny* MopGetById(TTypeUid aId); williamr@2: IMPORT_C TAny* MopGetByIdNoChaining(TTypeUid aId); williamr@2: williamr@2: private: williamr@2: TInt iMObjectProvider_Reserved1; williamr@2: }; williamr@2: williamr@2: #endif // __COEMOP_H__