1.1 --- a/epoc32/include/coemop.h Tue Mar 16 16:12:26 2010 +0000
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,180 +0,0 @@
1.4 -// Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 -// All rights reserved.
1.6 -// This component and the accompanying materials are made available
1.7 -// 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
1.8 -// which accompanies this distribution, and is available
1.9 -// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.10 -//
1.11 -// Initial Contributors:
1.12 -// Nokia Corporation - initial contribution.
1.13 -//
1.14 -// Contributors:
1.15 -//
1.16 -// Description:
1.17 -//
1.18 -
1.19 -#ifndef __COEMOP_H__
1.20 -#define __COEMOP_H__
1.21 -
1.22 -#include <e32std.h>
1.23 -
1.24 -/** Declares an object type, ETypeId, for a class, in order to allow the object
1.25 -provider mechanism to locate and provide objects from the class.
1.26 -
1.27 -@publishedAll
1.28 -@released
1.29 -@see MObjectProvider */
1.30 -#define DECLARE_TYPE_ID(id) enum { ETypeId = id };
1.31 -
1.32 -//
1.33 -// Used to wrap object type IDs in a standardised manner. Object type IDs must be asserted
1.34 -// in an ETypeId member data property by any types of object which
1.35 -// are capable of being retrieved by the MObjectProvider interface
1.36 -//
1.37 -class TTypeUid : public TUid
1.38 -/** Part of the object provider mechanism, this class encapsulates the Uid that
1.39 -identifies the type of object that an object provider is to get.
1.40 -
1.41 -The class is also used to encapsulate a pointer to the object that the object
1.42 -provider has found.
1.43 -
1.44 -An object that is intended to be capable of being retrieved by the object
1.45 -provider mechanism must include enum {ETypeId = 0xabcdefgh}; in its class
1.46 -definition, where 0xabcdefgh is the Uid value. The macro DECLARE_TYPE_ID can
1.47 -be used to do this.
1.48 -
1.49 -An instance of this class is passed to the MObjectProvider::MopSupplyObject()
1.50 -function implemented by an object provider. A TTypeUid::Ptr is also returned
1.51 -by this function.
1.52 -
1.53 -@publishedAll
1.54 -@released
1.55 -@see MObjectProvider */
1.56 - {
1.57 -public:
1.58 - class Ptr
1.59 - /** Encapsulates a pointer to an object fetched by an object provider.
1.60 -
1.61 - The class has no public constructor. TTypeUid::MakePtr() or TTypeUid::Null()
1.62 - must be used to construct instances of this class. */
1.63 - {
1.64 - friend class TTypeUid;
1.65 - private:
1.66 - explicit inline Ptr(TAny* aPtr)
1.67 - : iPtr(aPtr)
1.68 - {}
1.69 - public:
1.70 - inline TAny* Pointer() const
1.71 - /** Retrieves the pointer to an object which is encapsulated by the Ptr.
1.72 -
1.73 - @return A pointer to an object. */
1.74 - {return iPtr;}
1.75 - private:
1.76 - TAny* iPtr;
1.77 - };
1.78 -public:
1.79 - inline TTypeUid(TInt aUid)
1.80 - /** Constructor that takes a Uid value.
1.81 -
1.82 - @param aUid The Uid value that defines the type of object that an object provider
1.83 - is to get. */
1.84 - { iUid = aUid; }
1.85 - inline static Ptr Null()
1.86 - /** Constructs a Ptr which encapsulates a NULL pointer.
1.87 -
1.88 - @return The constructed Ptr object */
1.89 - { return Ptr(NULL); }
1.90 - template <class T> inline Ptr MakePtr(T* aT) const
1.91 - /** Constructs a Ptr which encapsulates the specified object pointer.
1.92 -
1.93 - @param aT A pointer to the object which is to be encapsulated.
1.94 - @return The constructed Ptr object */
1.95 - { __ASSERT_DEBUG(iUid == T::ETypeId,User::Invariant()); return Ptr(aT); }
1.96 - };
1.97 -
1.98 -
1.99 -class MObjectProvider
1.100 -/** An interface that allows an object to be part of a network of object providers.
1.101 -
1.102 -The object provider mechanism can be used to find and access objects of a
1.103 -given type, where the type is defined by a TTypeUid object. Object providers
1.104 -may be arranged in a hierarchy, i.e. an object provider may have a parent-child
1.105 -relationship with another object provider.
1.106 -
1.107 -An object provider must provide an implementation for the MopSupplyObject()
1.108 -function and can choose to provide an implementation for the MopNext() function.
1.109 -Typically, it will also have functionality to define who its parent is.
1.110 -
1.111 -CCoeControl is an example of a class that implements this interface. Top level
1.112 -controls must have the view or app UI set as their object provider. This is
1.113 -done by calling CCoeControl::SetMopParent() on the view or the app UI. The
1.114 -view or app UI does this by calling the top level control's CCoeControl::SetMopParent()
1.115 -function.
1.116 -
1.117 -@publishedAll
1.118 -@released */
1.119 - {
1.120 -public:
1.121 - template<class T>
1.122 - T* MopGetObject(T*& aPtr)
1.123 - /** Gets an object of the type defined by the template parameter.
1.124 -
1.125 - The object may be supplied directly by this object provider, or by other object
1.126 - providers higher up the hierarchy.
1.127 -
1.128 - @param aPtr A reference to a pointer to an object of a type that is to be
1.129 - retrieved.
1.130 - @return A pointer to an object of the type required, or NULL if none can be
1.131 - found. */
1.132 - { return (aPtr=(T*)MopGetById(T::ETypeId)); }
1.133 -
1.134 -
1.135 - template<class T>
1.136 - T* MopGetObjectNoChaining(T*& aPtr)
1.137 - /** Gets an object of the type defined by the template parameter.
1.138 -
1.139 - The object will be supplied directly by this object provider, or NULL
1.140 - will be returned, this function does not recurse through the object chain.
1.141 -
1.142 - @param aPtr A reference to a pointer to an object of a type that is to be
1.143 - retrieved.
1.144 - @return A pointer to an object of the type required, or NULL if none can be
1.145 - found. */
1.146 - { return (aPtr=(T*)MopGetByIdNoChaining(T::ETypeId)); }
1.147 -
1.148 - /**
1.149 - @publishedAll
1.150 - @released */
1.151 - MObjectProvider* FindParent(MObjectProvider* aMopToFind);
1.152 -
1.153 -private: // must be overridden
1.154 - /** Gets an object whose type is encapsulated by the specified TTypeUid object.
1.155 -
1.156 - @param aId Encapsulates the Uid that identifies the type of object required.
1.157 - @return Encapsulates the pointer to the object provided.
1.158 - Note that the encapsulated pointer may be NULL.
1.159 -
1.160 - @publishedAll
1.161 - @released */
1.162 - virtual TTypeUid::Ptr MopSupplyObject(TTypeUid aId) = 0;
1.163 -
1.164 -protected:
1.165 - IMPORT_C MObjectProvider();
1.166 -
1.167 -private: // may be overridden to continue chain of responsibility
1.168 - /**
1.169 - @publishedAll
1.170 - @released */
1.171 - IMPORT_C virtual MObjectProvider* MopNext();
1.172 - IMPORT_C virtual void MObjectProvider_Reserved1();
1.173 - IMPORT_C virtual void MObjectProvider_Reserved2();
1.174 -
1.175 -private:
1.176 - IMPORT_C TAny* MopGetById(TTypeUid aId);
1.177 - IMPORT_C TAny* MopGetByIdNoChaining(TTypeUid aId);
1.178 -
1.179 -private:
1.180 - TInt iMObjectProvider_Reserved1;
1.181 - };
1.182 -
1.183 -#endif // __COEMOP_H__