|
1 /* |
|
2 * Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
3 * All rights reserved. |
|
4 * This component and the accompanying materials are made available |
|
5 * under the terms of "Eclipse Public License v1.0" |
|
6 * which accompanies this distribution, and is available |
|
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
8 * |
|
9 * Initial Contributors: |
|
10 * Nokia Corporation - initial contribution. |
|
11 * |
|
12 * Contributors: |
|
13 * |
|
14 * Description: Defines an ECOM interface for third parties to customize |
|
15 * contact related icons in certain platform applications. |
|
16 */ |
|
17 |
|
18 #ifndef CCONTACTICONCUSTOMPLUGINBASE_H |
|
19 #define CCONTACTICONCUSTOMPLUGINBASE_H |
|
20 |
|
21 // INCLUDES |
|
22 #include <e32base.h> |
|
23 #include <ecom/ecom.h> |
|
24 #include <ContactCustomIconPluginDefs.h> |
|
25 |
|
26 // FORWARD DECLARATIONS |
|
27 class CGulIcon; |
|
28 class CCustomIconIdMap; |
|
29 class CCustomIconDecisionData; |
|
30 class MCustomIconChangeObserver; |
|
31 |
|
32 // CONSTANTS |
|
33 |
|
34 /** |
|
35 * Interface UID for ECOM plug-ins, which inherit from this interface. |
|
36 * This is used in plug-in registration resource file (interface_uid). Example: |
|
37 * |
|
38 * RESOURCE REGISTRY_INFO cs_ecom_reg_info |
|
39 * { |
|
40 * dll_uid = <UID_OF_ECOM_DLL>; |
|
41 * interfaces = |
|
42 * { |
|
43 * INTERFACE_INFO |
|
44 * { |
|
45 * // Make sure to use KContactIconCustomizationInterfaceUidValue |
|
46 * interface_uid = 0x2001E2DA; |
|
47 * |
|
48 * implementations = |
|
49 * { |
|
50 * IMPLEMENTATION_INFO |
|
51 * { |
|
52 * implementation_uid = <...>; // maps to IMPLEMENTATION_PROXY_ENTRY in CPP exporting plugin factory functions |
|
53 * version_no = 1; |
|
54 * display_name = "CMyContactIconCustomizationPlugin"; |
|
55 * default_data = ""; |
|
56 * opaque_data = ""; |
|
57 * } |
|
58 * }; |
|
59 * } |
|
60 * }; |
|
61 * } |
|
62 */ |
|
63 const TInt KContactIconCustomizationInterfaceUidValue = 0x2001E2DA; |
|
64 const TUid KContactIconCustomizationInterfaceUid = |
|
65 { KContactIconCustomizationInterfaceUidValue }; |
|
66 |
|
67 |
|
68 // CLASS DECLARATION |
|
69 |
|
70 /** |
|
71 * Base class for contact related icon customization ECOM plugins. |
|
72 * |
|
73 * This API allows customizing contact related icons of certain |
|
74 * applications at runtime. |
|
75 * |
|
76 * The API defines two roles: |
|
77 * - Customizable entity is typically an application supporting icon |
|
78 * customization. It is a caller of this API. |
|
79 * - Customizer is an entity implementing ecom plug-in, a callee. |
|
80 * |
|
81 * As a concrete example, Logs application has 'Dialled calls' view |
|
82 * where it by default shows in each listbox row a call specific icon. |
|
83 * Plugin can change each of the icons by implementing this API. |
|
84 * |
|
85 * The customizer needs only one plug-in implementation, which affects |
|
86 * multiple applications at a same time. This means the API cannot define |
|
87 * application specific info. |
|
88 * |
|
89 * Note that customizable entity - typically an application - has to provide |
|
90 * a connection to Font and Bitmap server. The plug-in may fail to provide |
|
91 * the icon (KErrCouldNotConnect), if the connection does not exist. |
|
92 */ |
|
93 class CContactCustomIconPluginBase : public CBase |
|
94 { |
|
95 public: // API to be implemented by ECOM plug-in |
|
96 |
|
97 /** |
|
98 * An icon size hint from application to plug-in. Plug-in |
|
99 * may use this to load icons of appropriate size. |
|
100 * @see IconsL |
|
101 */ |
|
102 enum TIconSizeHint |
|
103 { |
|
104 EReallySmall, |
|
105 ESmall, |
|
106 EMedium, |
|
107 EMediumLarge, |
|
108 ELarge |
|
109 }; |
|
110 |
|
111 /** |
|
112 * Calling application uses this method to register itself as an observer |
|
113 * for the plug-in state change notifications. |
|
114 * |
|
115 * Plug-in uses observer interface for notifying calling application |
|
116 * about icon related changes. |
|
117 * |
|
118 * @param aObserver Observer interface, implemented by calling client |
|
119 * code. Ownership of the object is not transferred. |
|
120 */ |
|
121 virtual void AddObserverL( |
|
122 MCustomIconChangeObserver* aObserver ) = 0; |
|
123 |
|
124 /** |
|
125 * Calling application uses this method to deregister itself as an observer |
|
126 * from the plug-in state change notifications. |
|
127 * |
|
128 * @param aObserver Observer interface, implemented by calling client |
|
129 * code. Ownership of the object is not transferred. |
|
130 */ |
|
131 virtual void RemoveObserver( |
|
132 MCustomIconChangeObserver* aObserver ) = 0; |
|
133 |
|
134 /** |
|
135 * Gets an array of custom icons from the plug-in. |
|
136 * |
|
137 * Application calls this method typically in its initialization phase |
|
138 * to prepare for replacing its default icons. When it is time to show |
|
139 * the icons, calling application may call IconChoiceL. |
|
140 * |
|
141 * ECOM plug-in implementation should fill in the potential icons |
|
142 * and give each icon an identifier, which it can use later to refer |
|
143 * to a certain icon it wants to use as replacement for application's |
|
144 * default icon. |
|
145 * |
|
146 * @see CCustomIconIdMap.h |
|
147 * @param aContext Context of the function call. For more information |
|
148 * about context semantics see CCustomIconDecisionData |
|
149 * documentation. |
|
150 * @param aSizeHint Hint for plug-in to load icons of appropriate size. |
|
151 * @return Icon-to-id map. |
|
152 * @leave On typical leave level problems. Application should handle |
|
153 * this by ignoring ECOM plug-in functionality and continue |
|
154 * using its default icons. |
|
155 */ |
|
156 virtual CCustomIconIdMap* IconsL( |
|
157 TUid aContext, |
|
158 TIconSizeHint aSizeHint ) = 0; |
|
159 |
|
160 /** |
|
161 * Application uses this method to make a choice of the icon to be |
|
162 * displayed in certain UI condition. |
|
163 * |
|
164 * Note that application should have always had called the IconsL |
|
165 * function before this gets called. |
|
166 * |
|
167 * ECOM plug-in implementation should use aHint parameter to make a decision |
|
168 * which icon it wants to use. |
|
169 * |
|
170 * @param aHint Hint from the application to the plug-in, which tells |
|
171 * what kind of icon is being replaced. For example, the |
|
172 * plug-in may want to choose the icon based on the |
|
173 * phonenumber. For more details see |
|
174 * CCustomIconDecisionData.h. |
|
175 * Plug-in must not take ownership of the object's |
|
176 * members. The instance and its members are guaranteed to |
|
177 * be valid only during the method call. |
|
178 * |
|
179 * Caller must fill at least one of the members, otherwise |
|
180 * plug-in can and should leave with KErrArgument. |
|
181 * |
|
182 * @param aIdResult Icon reference value filled by the ECOM plug-in. The id |
|
183 * should be one of the ids, which were used to build the |
|
184 * CCustomIconIdMap object in IconsL function. If the |
|
185 * calling application cannot find an icon by aIdResult |
|
186 * from the map, it should use application's default icon. |
|
187 * |
|
188 * @return Return value indicating if the decision could be made. |
|
189 * ETrue, if the icon choice decision could be made. |
|
190 * EFalse, if the icon choice could not be made. |
|
191 * This is an indication from plug-in to application that |
|
192 * application should use its default icon. |
|
193 * |
|
194 * @leave On typical leave level problems like database access failure |
|
195 * or condition where application may not be able to provide the |
|
196 * requested functionality. It is up to application how it |
|
197 * handles leave from the plug-in. Recommendation is that it |
|
198 * ignores plug-in's functionality and uses default icons. |
|
199 */ |
|
200 virtual TBool IconChoiceL( |
|
201 const CCustomIconDecisionData& aHint, |
|
202 TCustomIconId& aIdResult ) = 0; |
|
203 |
|
204 /** |
|
205 * Application uses this method when it dynamically needs to replace |
|
206 * its default icon. This can typically happen at any time of the |
|
207 * application runtime. |
|
208 * |
|
209 * Application should favor using the IconsL/IconChoiceL pair, if it |
|
210 * is likely to use multiple icons and several times. This function is |
|
211 * useful if the application needs only couple of icons only couple |
|
212 * of times. This is discouraged for use in frequent draw requests. |
|
213 * |
|
214 * The plug-in implementation should use the aHint to make a decision |
|
215 * which icon it wants to use. |
|
216 * |
|
217 * @param aHint Hint from application to plug-in, which tells what |
|
218 * kind of icon is being replaced. For example, the |
|
219 * plug-in may want to choose the icon based on the |
|
220 * phonenumber. For more details see |
|
221 * CCustomIconDecisionData.h |
|
222 * Plug-in must not take ownership of the object or its |
|
223 * members. The instance and its members are guaranteed to |
|
224 * be valid only during the method call. |
|
225 * Caller must fill at least one of the members, otherwise |
|
226 * plug-in can and should leave with KErrArgument. |
|
227 * |
|
228 * @param aSizeHint Hint for plug-in to load icon of appropriate size. |
|
229 * |
|
230 * @return Icon instance. NULL, if plug-in wants to indicate it is |
|
231 * not willing to replace caller's default icon. |
|
232 */ |
|
233 virtual CGulIcon* IconL( |
|
234 const CCustomIconDecisionData& aHint, |
|
235 TIconSizeHint aSizeHint ) = 0; |
|
236 |
|
237 /** |
|
238 * Application uses this method when it dynamically needs to update |
|
239 * previously loaded custom icon. Typically this happens after |
|
240 * application has received update notification from plug-in. |
|
241 * |
|
242 * @param aContext Context of the function call. While this override |
|
243 * provides known icon id rather than |
|
244 * CCustomIconDecisionData, the context is given here |
|
245 * separately. For more information about context |
|
246 * semantics see CCustomIconDecisionData |
|
247 * documentation. |
|
248 * |
|
249 * @param aIconId Specifies the icon for the client to provide. This is |
|
250 * valid when a known custom icon has changed and is |
|
251 * being replaced. |
|
252 * |
|
253 * @param aSizeHint Hint for plug-in to load icon of appropriate size. |
|
254 * |
|
255 * @return Icon instance. NULL, if plug-in wants to indicate it is |
|
256 * not willing to replace application's default icon. |
|
257 */ |
|
258 virtual CGulIcon* IconL( |
|
259 TUid aContext, |
|
260 TCustomIconId aIconId, |
|
261 TIconSizeHint aSizeHint ) = 0; |
|
262 |
|
263 /** |
|
264 * Factory function for getting access to extended API functionality. |
|
265 * Uid defines the extension interface being used. |
|
266 * |
|
267 * @param aExtensionUid Identifier for extension API class. |
|
268 * @return Extension API class, casted to one of M-interfaces defined |
|
269 * by this API (later). Ownership of the object is not transferred. |
|
270 */ |
|
271 virtual TAny* ContactCustomIconExtension( TUid /*aExtensionUid*/ ) |
|
272 { |
|
273 return NULL; |
|
274 } |
|
275 |
|
276 public: |
|
277 |
|
278 /** |
|
279 * ~CContactIconCustomPluginBase |
|
280 * |
|
281 * Cleans up resources, specifically notify ECOM server that this |
|
282 * instance is being deleted. |
|
283 */ |
|
284 inline virtual ~CContactCustomIconPluginBase() |
|
285 { |
|
286 REComSession::DestroyedImplementation( iDtorKey ); |
|
287 } |
|
288 |
|
289 public: |
|
290 /// Own: Key UID |
|
291 TUid iDtorKey; |
|
292 }; |
|
293 |
|
294 #endif // CCONTACTICONCUSTOMPLUGINBASE_H |
|
295 |
|
296 // End of File |