|
1 /* |
|
2 * Copyright (c) 2005-2008 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: Header file for CGSPluginInterface class. |
|
15 * |
|
16 */ |
|
17 |
|
18 |
|
19 #ifndef GSPLUGININTERFACE_H |
|
20 #define GSPLUGININTERFACE_H |
|
21 |
|
22 // System includes |
|
23 #include <gsframeworkrsc.rsg> // For default icons |
|
24 #include <gsfwicon.mbg> |
|
25 |
|
26 #include <aknview.h> |
|
27 #include <aknViewAppUi.h> |
|
28 #include <gulicon.h> |
|
29 #include <AknsUtils.h> |
|
30 #include <aknViewAppUi.h> |
|
31 #include <data_caging_path_literals.hrh> |
|
32 |
|
33 // Constant for plugin interface: |
|
34 const TUid KGSPluginInterfaceUid = { 0x10207236 }; |
|
35 |
|
36 // Constant for listbox icon type: |
|
37 const TUid KGSIconTypeLbxItem = { 0x10207357 }; |
|
38 // Constant for listbox settings item icon type: |
|
39 const TUid KGSIconTypeLbxSettingsItem = { 0x102750C5 }; |
|
40 // Constant for tab icon type: |
|
41 const TUid KGSIconTypeTab = { 0x10207358 }; |
|
42 // Constant for icon in D-Column: |
|
43 const TUid KGSIconTypeDColumn = { 0x10207359 }; |
|
44 |
|
45 |
|
46 // Constant for indexing (iOrder): |
|
47 const TInt KGSPluginNotIndexed = -1; |
|
48 |
|
49 _LIT( KGSDefaultIconFileName, "Z:Gsfwicon.mbm" ); |
|
50 |
|
51 /** |
|
52 * This enum is used for defining custom operations types. |
|
53 */ |
|
54 enum TGSCustomOperationType |
|
55 { |
|
56 // This operation type returns current status of the plugin's view. |
|
57 // If the plugin's view is active, ETrue will be returned, otherwise |
|
58 // EFalse. Currently supported by GSStandbyPlugin. |
|
59 EGSCustomOperationViewActive = 1 |
|
60 }; |
|
61 |
|
62 /** |
|
63 * Used by GetValue(). These are the keys for retrieving a specific |
|
64 * value. This enum can be extended to provide other values as well as |
|
65 * long as the original keys are not changed. |
|
66 */ |
|
67 enum TGSPluginValueKeys |
|
68 { |
|
69 // Value for this key is the localized string to be shown in the second row |
|
70 // of a listbox item. Plugins providing second row of text should provide |
|
71 // value for this key. Second row of list item text is used for following |
|
72 // listbox types: |
|
73 // - EGSListBoxTypeSingleLarge |
|
74 // - EGSListBoxTypeDouble2Large. |
|
75 // For plugins listed in these listbox types, second row value can either |
|
76 // be defined or left empty. |
|
77 EGSPluginKeySettingsItemValueString = 1, |
|
78 // Localized string to be used in case of custom MSK and menu activation |
|
79 // item. See TGSMenuActivationItems. |
|
80 EGSCustomMenuActivationText |
|
81 }; |
|
82 |
|
83 /** |
|
84 * Used by PluginItemType(). These enumerations define the desired appearance |
|
85 * of the plugin in a parent plugin's listbox. Please notice that the parent |
|
86 * listbox type cannot be altered by a child plugin so plugins using these must |
|
87 * be aware of the parent plugin listbox type. Safest alternative is to leave |
|
88 * default implementation for ItemType() in which case EGSItemTypeSingleLarge is |
|
89 * used. This should fit most of the listbox types. Additionall types can be |
|
90 * implemented and defined as long as the old enumerations will not be changed. |
|
91 * |
|
92 * Different type of items are handled differently: |
|
93 * - In case of CAknView type items, such as EGSItemTypeSingleLarge and |
|
94 * EGSItemTypeSetting, the plugin's DoActivate() is called when user selects |
|
95 * the item. |
|
96 * - In case of items supporting dialogs, such as EGSItemTypeSettingDialog and |
|
97 * EGSItemTypeSettingIconDialog, HandleSelection() is called instead of |
|
98 * DoActivate(). |
|
99 * |
|
100 * Item types can be described in a matrix: |
|
101 * X: Normal list tems with large icon, |
|
102 * settings items, |
|
103 * settings items with icon |
|
104 * Y: Items providing CAknView - activated by DoActivate(), |
|
105 * items providing dialog - activated by HandleSelection() |
|
106 * |
|
107 * All combinations of these are not allowed/supported. |
|
108 */ |
|
109 enum TGSListboxItemTypes |
|
110 { |
|
111 // CAknSingleLargeStyleListBox item: |
|
112 // Caption of the item is a descriptor from GetCaptionL(). |
|
113 // Icon is from CreateIconL( KGSIconTypeLbxItem ). |
|
114 EGSItemTypeSingleLarge = 1, // Default |
|
115 // CAknSettingStyleListBox item providing a CAknView: |
|
116 // 1st row content is a descriptor from GetCaptionL() |
|
117 // 2nd row content is a descriptor (can be empty string id needed) from |
|
118 // GetValue( ..., EGSPluginKeySettingsItemValueString ). |
|
119 EGSItemTypeSetting, |
|
120 // CAknSettingStyleListBox item providing a CAknView: |
|
121 // 1st row content is a descriptor from GetCaptionL() |
|
122 // 2nd row content is a icon from CreateIconL( KGSIconTypeLbxSettingsItem ) |
|
123 // GetValue(, EGSPluginKeySettingsItemValueString ). |
|
124 EGSItemTypeSettingIcon, |
|
125 // CAknSettingStyleListBox item launching a dialog: |
|
126 // 1st row content is a descriptor from GetCaptionL() |
|
127 // 2nd row content is a descriptor (can be empty string id needed) from |
|
128 // GetValue( ..., EGSPluginKeySettingsItemValueString ). |
|
129 EGSItemTypeSettingDialog, |
|
130 // CAknSingleLargeStyleListBox item launching a dialog: |
|
131 // Caption of the item is a descriptor from GetCaptionL(). |
|
132 // Icon is from CreateIconL( KGSIconTypeLbxItem ). |
|
133 EGSItemTypeSingleLargeDialog |
|
134 }; |
|
135 |
|
136 /** |
|
137 * These are used to define the type of the menu item which opens the selected |
|
138 * plugin. By default, parent plugin's menu has 'Open' item for child plugins. |
|
139 * If parent plugin's menu must have 'Change' instead of 'Open' for activating |
|
140 * the plugin, use EGSMenuActivationItemChange. This functionality is just for |
|
141 * the visual aspects for views in GS - requested by UI design. Plugins are |
|
142 * handled logically similarly regardless this value. |
|
143 */ |
|
144 enum TGSMenuActivationItems |
|
145 { |
|
146 // Default - will use the item defined in menu resource. |
|
147 EGSMenuActivationItemDefault = 0, |
|
148 // Menu should contain 'Open' Item. |
|
149 EGSMenuActivationItemOpen = 1, |
|
150 // Menu should contain 'Change' item. |
|
151 EGSMenuActivationItemChange, |
|
152 // Menu should contain custom text which is defined by GetValue() function: |
|
153 // GetValue( EGSCustomMenuActivationText, ... ); |
|
154 // NOTE: When this custom menu item is selected, used menu command ID is |
|
155 // EGSCmdAppChange. This might be checked in for example plugin's |
|
156 // HandleCommand(). If text is empy, MSK is empty and there's no |
|
157 // corresponding item in options menu. |
|
158 EGSMenuActivationItemCustom |
|
159 }; |
|
160 |
|
161 /** |
|
162 * Selection types. Used in HandleSelection(). |
|
163 */ |
|
164 enum TGSSelectionTypes |
|
165 { |
|
166 // User selected the item by pressing selection key. |
|
167 EGSSelectionBySelectionKey = 1, |
|
168 // User selected the item by selecting a command from the menu. |
|
169 EGSSelectionByMenu |
|
170 }; |
|
171 |
|
172 /** |
|
173 * Interface class for GS plugin. All GS plugins will implement this class. |
|
174 * |
|
175 * The main functionality GS framework will use from CAknView is: |
|
176 * -DoActivate() |
|
177 * -DoDeactivate() |
|
178 * -Id() |
|
179 * functions. |
|
180 * |
|
181 * Id() function must return the value of the plugin implementation UID. This |
|
182 * means that the main view of the plugin will have the same UID as the plugin |
|
183 * implementation. This will prevent multiple plugins from having same view |
|
184 * UIDs as their main view. If plugin has more views, it is plugin's |
|
185 * responsibility to ensure that the UIDs of the other views are unique. This |
|
186 * can be done for example reserving a unique UID from Symbian. |
|
187 * |
|
188 * Most of the functions have implementation using default values. Override |
|
189 * functions if different values or implementations are desired. |
|
190 * |
|
191 * CGSPluginInterface UID = 0x10207236 |
|
192 * |
|
193 * See GSFWViewUIDs.h for plugin UIDs. |
|
194 * |
|
195 * Plugin implementation UID will be used when defining the parent view of a |
|
196 * plugin. If plugin belongs to application settings view, set the |
|
197 * ApplicationSettingsView plugin implementation Uid as a value in the plugin's |
|
198 * default_data field in plugin's implementation info resource file. |
|
199 * |
|
200 * Needed libraries (at least): |
|
201 * GSEcomPlugin.lib |
|
202 * GSFramework.lib |
|
203 * egul.lib |
|
204 * aknskins.lib |
|
205 * efsrv.lib |
|
206 * |
|
207 * @lib GSFramework.lib |
|
208 * @since Series60_3.1 |
|
209 */ |
|
210 class CGSPluginInterface: public CAknView |
|
211 { |
|
212 |
|
213 // CGSPluginLoader accesses iOrder which should not be accessed outside. |
|
214 friend class CGSPluginLoader; |
|
215 |
|
216 public: // Constructors & destructors |
|
217 |
|
218 /** |
|
219 * Creates new GS plugin having the given UID. |
|
220 * Uses Leave code KErrNotFound if implementation is not found. |
|
221 * |
|
222 * @param aImplementationUid Implementation UID of the plugin to be |
|
223 * created. |
|
224 * @param aInitParams Plugin's initialization parameters. Make sure you know |
|
225 * what the plugin expects as initialization parameters. This |
|
226 * should be an agreement between the plugin client and the |
|
227 * plugin. Parameter can be used for example as sharing a common |
|
228 * data model between multiple plugins. |
|
229 */ |
|
230 IMPORT_C static CGSPluginInterface* NewL( |
|
231 const TUid aImplementationUid, |
|
232 TAny* aInitParams ); |
|
233 |
|
234 /** |
|
235 * Destructor |
|
236 */ |
|
237 IMPORT_C ~CGSPluginInterface(); |
|
238 |
|
239 public: // New |
|
240 |
|
241 /** |
|
242 * Method for getting caption of this plugin. This should be the |
|
243 * localized name of the settings view to be shown in parent view. |
|
244 * |
|
245 * @param aCaption pointer to Caption variable |
|
246 */ |
|
247 virtual void GetCaptionL( TDes& aCaption ) const = 0; |
|
248 |
|
249 /** |
|
250 * Function for getting plugin's value for a certain key. |
|
251 * Override to provide own functionality. |
|
252 * |
|
253 * @param aKey Key for the value to be retrieved. |
|
254 * @parem aValue Value for the given gey in TDes format. |
|
255 */ |
|
256 IMPORT_C virtual void GetValue( const TGSPluginValueKeys aKey, |
|
257 TDes& aValue ); |
|
258 |
|
259 /** |
|
260 * This function is called in case plugin is an item in a settings |
|
261 * listbox and user selects the item. Override this if plugin needs to |
|
262 * provide functionality for item selection. |
|
263 * |
|
264 * Default implementation activates the plugin. |
|
265 * @param aSelectionType Defines how user selected the plugin. See |
|
266 * TGSSelectionTypes. |
|
267 */ |
|
268 IMPORT_C virtual void HandleSelection( |
|
269 const TGSSelectionTypes aSelectionType ); |
|
270 |
|
271 /** |
|
272 * This defines the appearance of the plugin in a parent plugin listbox. |
|
273 * Default value is EGSItemTypeSingleLarge. Please notice that the |
|
274 * parent listbox type cannot be defined by a child plugin so plugins |
|
275 * using these must be aware of the parent plugin listbox type. |
|
276 * |
|
277 * @return Desired listbox presentation and functional type for the |
|
278 * plugin. |
|
279 */ |
|
280 IMPORT_C virtual TGSListboxItemTypes ItemType(); |
|
281 |
|
282 /** |
|
283 * This function is only used for child plugins. Defines the dynamic |
|
284 * menu item that activates this plugin from parent plugin. This menu |
|
285 * item will override the item defined in resource file. Normally |
|
286 * 'Open' is used to open the child plugin. Override this to change the |
|
287 * activation to for example 'Change'. TGSMenuActivationItems defines the |
|
288 * different possible menu items that can be used to open this plugin. |
|
289 * |
|
290 * Note: This also defines MSK. Menu activation item and MSK have |
|
291 * identical label and behaviour. An exception to this is |
|
292 * when custom text is empty: in this case MSK is empty but there |
|
293 * is no item in options menu (no empty item in menu). |
|
294 * |
|
295 * @ return Type of the menu item and MSK that should activate this |
|
296 * child plugin from parent plugin. |
|
297 */ |
|
298 IMPORT_C virtual TGSMenuActivationItems MenuActivationItem(); |
|
299 |
|
300 /** |
|
301 * Creates a new icon of desired type. Override this to provide custom |
|
302 * icons. Othervise default icon is used for KGSIconTypeLbxItem. Other |
|
303 * icons are empty. Ownership of the created icon is transferred to the |
|
304 * caller. |
|
305 * NOTE: Return NULL if icon is not to be displayed. |
|
306 * |
|
307 * Icon type UIDs (use these defined constants): |
|
308 * KGSIconTypeLbxItem - ListBox item icon. |
|
309 * KGSIconTypeLbxSettingsItem - Settings item icon. |
|
310 * KGSIconTypeTab - Tab icon. |
|
311 * KGSIconTypeDColumn - Small icon in D-column. |
|
312 * |
|
313 * @param aIconType UID Icon type UID of the icon to be created. |
|
314 * @return Pointer of the icon or NULL. |
|
315 */ |
|
316 IMPORT_C virtual CGulIcon* CreateIconL( const TUid aIconType ); |
|
317 |
|
318 /** |
|
319 * Method for reading the ID of the plugin provider category. See |
|
320 * TGSPluginProviderCategory. PluginProviderCategory can be used for |
|
321 * sorting plugins. |
|
322 * |
|
323 * Default value is EGSPluginProvider3rdParty. Override this function |
|
324 * to change the category. |
|
325 * |
|
326 * @return Plugin provider category ID defined by |
|
327 * TGSPluginProviderCategory |
|
328 */ |
|
329 IMPORT_C virtual TInt PluginProviderCategory() const; |
|
330 |
|
331 /** |
|
332 * Reserved for future use/plugin's custom functionality. This can be |
|
333 * overwritten if plugin needs to have custom functionality which cannot |
|
334 * be fulfilled otherwise. |
|
335 * |
|
336 * Use TGSCustomOperationType enumeration as aParam1 to |
|
337 * define operation type. |
|
338 */ |
|
339 IMPORT_C virtual TAny* CustomOperationL( TAny* aParam1, TAny* aParam2 ); |
|
340 |
|
341 /** |
|
342 * Method for checking, if plugin should be visible and used in GS FW. |
|
343 * (for example shown in listbox of the parent view). |
|
344 * |
|
345 * On default plugin is visible. Overwrite this function to enable or |
|
346 * disable your plugin dynamically. |
|
347 * |
|
348 * @return ETrue if plugin should be visible in GS. |
|
349 * @return EFalse if plugin should not be visible in GS. |
|
350 */ |
|
351 IMPORT_C virtual TBool Visible() const; |
|
352 |
|
353 /** |
|
354 * Resets plugin's selected item index if this is supported. Default |
|
355 * implementation does nothing. This is needed when navigating from |
|
356 * child plugin back to parent plugin. In this case child plugin should |
|
357 * reset selected index in its listbox. |
|
358 */ |
|
359 IMPORT_C virtual void ResetSelectedItemIndex(); |
|
360 |
|
361 /** |
|
362 * Sets the Index of the plugin in listbox. Used for CGSPluginLoader. Default |
|
363 * value is KGSPluginNotIndexed which means not ordered. This value is |
|
364 * read, if defined, from the opaque_data field of the plugin's resource |
|
365 * definition. Index starts from 0. |
|
366 */ |
|
367 IMPORT_C void SetOrder( TInt aOrder ); |
|
368 |
|
369 /** |
|
370 * In case plug-in is loaded outside GS application and CGSPluginLoader, |
|
371 * cleaning up plug-in's ECOM resources must be done manually. |
|
372 * |
|
373 * Example: |
|
374 * CGSPluginInterface* myPlugin = CGSPluginInterface::NewL(...); |
|
375 * REComSession::DestroyedImplementation( myPlugin->GetEcomDestructorKey() ); |
|
376 * delete myPlugin; |
|
377 * |
|
378 * @return UID of the plug-in instance which can be used to free dependent ECOM resources. |
|
379 */ |
|
380 IMPORT_C TUid GetEcomDestructorKey(); |
|
381 |
|
382 protected: // New |
|
383 |
|
384 /** |
|
385 * C++ constructor. |
|
386 */ |
|
387 IMPORT_C CGSPluginInterface(); |
|
388 |
|
389 public: // Enumerations |
|
390 |
|
391 /** |
|
392 * Category of the plugin provider. Provider's type affects the sorting |
|
393 * of the plugins. Type EGSPluginProvider3rdParty plugins are allowed |
|
394 * to be loaded only by Applications-plugin. Other categories may exist |
|
395 * but they should be used only internally. |
|
396 **/ |
|
397 enum TGSPluginProviderCategory |
|
398 { |
|
399 EGSPluginProviderOEM = 1, |
|
400 EGSPluginProviderOperator = 2, |
|
401 EGSPluginProvider3rdParty = 3 |
|
402 }; |
|
403 |
|
404 private: // Data |
|
405 |
|
406 // ECOM plugin instance UID. |
|
407 TUid iDtor_ID_Key; |
|
408 |
|
409 /** |
|
410 * Index of the plugin in listbox. Used for CGSPluginLoader. Default |
|
411 * value is KGSPluginNotIndexed which means not ordered. This value is |
|
412 * read, if defined, from the opaque_data field of the plugin's resource |
|
413 * definition. Index starts from 0. |
|
414 */ |
|
415 TInt iOrder; |
|
416 |
|
417 }; |
|
418 |
|
419 #endif // GSPLUGININTERFACE_H |
|
420 //End of file |