|
1 // Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
2 // All rights reserved. |
|
3 // This component and the accompanying materials are made available |
|
4 // under the terms of "Eclipse Public License v1.0" |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // |
|
15 |
|
16 #ifndef __COEMOP_H__ |
|
17 #define __COEMOP_H__ |
|
18 |
|
19 #include <e32std.h> |
|
20 |
|
21 /** Declares an object type, ETypeId, for a class, in order to allow the object |
|
22 provider mechanism to locate and provide objects from the class. |
|
23 |
|
24 @publishedAll |
|
25 @released |
|
26 @see MObjectProvider */ |
|
27 #define DECLARE_TYPE_ID(id) enum { ETypeId = id }; |
|
28 |
|
29 // |
|
30 // Used to wrap object type IDs in a standardised manner. Object type IDs must be asserted |
|
31 // in an ETypeId member data property by any types of object which |
|
32 // are capable of being retrieved by the MObjectProvider interface |
|
33 // |
|
34 class TTypeUid : public TUid |
|
35 /** Part of the object provider mechanism, this class encapsulates the Uid that |
|
36 identifies the type of object that an object provider is to get. |
|
37 |
|
38 The class is also used to encapsulate a pointer to the object that the object |
|
39 provider has found. |
|
40 |
|
41 An object that is intended to be capable of being retrieved by the object |
|
42 provider mechanism must include enum {ETypeId = 0xabcdefgh}; in its class |
|
43 definition, where 0xabcdefgh is the Uid value. The macro DECLARE_TYPE_ID can |
|
44 be used to do this. |
|
45 |
|
46 An instance of this class is passed to the MObjectProvider::MopSupplyObject() |
|
47 function implemented by an object provider. A TTypeUid::Ptr is also returned |
|
48 by this function. |
|
49 |
|
50 @publishedAll |
|
51 @released |
|
52 @see MObjectProvider */ |
|
53 { |
|
54 public: |
|
55 class Ptr |
|
56 /** Encapsulates a pointer to an object fetched by an object provider. |
|
57 |
|
58 The class has no public constructor. TTypeUid::MakePtr() or TTypeUid::Null() |
|
59 must be used to construct instances of this class. */ |
|
60 { |
|
61 friend class TTypeUid; |
|
62 private: |
|
63 explicit inline Ptr(TAny* aPtr) |
|
64 : iPtr(aPtr) |
|
65 {} |
|
66 public: |
|
67 inline TAny* Pointer() const |
|
68 /** Retrieves the pointer to an object which is encapsulated by the Ptr. |
|
69 |
|
70 @return A pointer to an object. */ |
|
71 {return iPtr;} |
|
72 private: |
|
73 TAny* iPtr; |
|
74 }; |
|
75 public: |
|
76 inline TTypeUid(TInt aUid) |
|
77 /** Constructor that takes a Uid value. |
|
78 |
|
79 @param aUid The Uid value that defines the type of object that an object provider |
|
80 is to get. */ |
|
81 { iUid = aUid; } |
|
82 inline static Ptr Null() |
|
83 /** Constructs a Ptr which encapsulates a NULL pointer. |
|
84 |
|
85 @return The constructed Ptr object */ |
|
86 { return Ptr(NULL); } |
|
87 template <class T> inline Ptr MakePtr(T* aT) const |
|
88 /** Constructs a Ptr which encapsulates the specified object pointer. |
|
89 |
|
90 @param aT A pointer to the object which is to be encapsulated. |
|
91 @return The constructed Ptr object */ |
|
92 { __ASSERT_DEBUG(iUid == T::ETypeId,User::Invariant()); return Ptr(aT); } |
|
93 }; |
|
94 |
|
95 |
|
96 class MObjectProvider |
|
97 /** An interface that allows an object to be part of a network of object providers. |
|
98 |
|
99 The object provider mechanism can be used to find and access objects of a |
|
100 given type, where the type is defined by a TTypeUid object. Object providers |
|
101 may be arranged in a hierarchy, i.e. an object provider may have a parent-child |
|
102 relationship with another object provider. |
|
103 |
|
104 An object provider must provide an implementation for the MopSupplyObject() |
|
105 function and can choose to provide an implementation for the MopNext() function. |
|
106 Typically, it will also have functionality to define who its parent is. |
|
107 |
|
108 CCoeControl is an example of a class that implements this interface. Top level |
|
109 controls must have the view or app UI set as their object provider. This is |
|
110 done by calling CCoeControl::SetMopParent() on the view or the app UI. The |
|
111 view or app UI does this by calling the top level control's CCoeControl::SetMopParent() |
|
112 function. |
|
113 |
|
114 @publishedAll |
|
115 @released */ |
|
116 { |
|
117 public: |
|
118 template<class T> |
|
119 T* MopGetObject(T*& aPtr) |
|
120 /** Gets an object of the type defined by the template parameter. |
|
121 |
|
122 The object may be supplied directly by this object provider, or by other object |
|
123 providers higher up the hierarchy. |
|
124 |
|
125 @param aPtr A reference to a pointer to an object of a type that is to be |
|
126 retrieved. |
|
127 @return A pointer to an object of the type required, or NULL if none can be |
|
128 found. */ |
|
129 { return (aPtr=(T*)MopGetById(T::ETypeId)); } |
|
130 |
|
131 |
|
132 template<class T> |
|
133 T* MopGetObjectNoChaining(T*& aPtr) |
|
134 /** Gets an object of the type defined by the template parameter. |
|
135 |
|
136 The object will be supplied directly by this object provider, or NULL |
|
137 will be returned, this function does not recurse through the object chain. |
|
138 |
|
139 @param aPtr A reference to a pointer to an object of a type that is to be |
|
140 retrieved. |
|
141 @return A pointer to an object of the type required, or NULL if none can be |
|
142 found. */ |
|
143 { return (aPtr=(T*)MopGetByIdNoChaining(T::ETypeId)); } |
|
144 |
|
145 /** |
|
146 @publishedAll |
|
147 @released */ |
|
148 MObjectProvider* FindParent(MObjectProvider* aMopToFind); |
|
149 |
|
150 private: // must be overridden |
|
151 /** Gets an object whose type is encapsulated by the specified TTypeUid object. |
|
152 |
|
153 @param aId Encapsulates the Uid that identifies the type of object required. |
|
154 @return Encapsulates the pointer to the object provided. |
|
155 Note that the encapsulated pointer may be NULL. |
|
156 |
|
157 @publishedAll |
|
158 @released */ |
|
159 virtual TTypeUid::Ptr MopSupplyObject(TTypeUid aId) = 0; |
|
160 |
|
161 protected: |
|
162 IMPORT_C MObjectProvider(); |
|
163 |
|
164 private: // may be overridden to continue chain of responsibility |
|
165 /** |
|
166 @publishedAll |
|
167 @released */ |
|
168 IMPORT_C virtual MObjectProvider* MopNext(); |
|
169 IMPORT_C virtual void MObjectProvider_Reserved1(); |
|
170 IMPORT_C virtual void MObjectProvider_Reserved2(); |
|
171 |
|
172 private: |
|
173 IMPORT_C TAny* MopGetById(TTypeUid aId); |
|
174 IMPORT_C TAny* MopGetByIdNoChaining(TTypeUid aId); |
|
175 |
|
176 private: |
|
177 TInt iMObjectProvider_Reserved1; |
|
178 }; |
|
179 |
|
180 #endif // __COEMOP_H__ |