1 /* |
|
2 * Copyright (c) 2007 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: Custom widget factories are registered into factory chain |
|
15 * |
|
16 */ |
|
17 |
|
18 |
|
19 #ifndef I_ALFWIDGETFACTORY_H |
|
20 #define I_ALFWIDGETFACTORY_H |
|
21 |
|
22 //Widget Utils includes |
|
23 #include <alf/alftypes.h> |
|
24 |
|
25 //Widget Model Includes |
|
26 #include <alf/ialfinterfacebase.h> |
|
27 |
|
28 //Forward declaration |
|
29 class CAlfDisplay; |
|
30 |
|
31 //Namespaces |
|
32 namespace duiuimodel |
|
33 { |
|
34 class DuiNode; |
|
35 } |
|
36 |
|
37 using namespace duiuimodel; |
|
38 |
|
39 namespace Alf |
|
40 { |
|
41 |
|
42 //Forward declarations |
|
43 class IAlfWidget; |
|
44 class IAlfModel; |
|
45 class IAlfWidgetControl; |
|
46 class IAlfElement; |
|
47 class IAlfVisualTemplate; |
|
48 class IAlfWidgetEventHandler; |
|
49 class IAlfFactoryPlugin; |
|
50 class IAlfViewWidget; |
|
51 class IAlfContainerWidget; |
|
52 class IAlfLayoutManager; |
|
53 |
|
54 //Namespace |
|
55 namespace category |
|
56 { |
|
57 static const char* const KWidget = "widget"; |
|
58 static const char* const KModel = "model"; |
|
59 static const char* const KControl ="control"; |
|
60 static const char* const KElement ="element"; |
|
61 static const char* const KVisualTemplate ="visualtemplate"; |
|
62 static const char* const KEventHandler = "eventhandler"; |
|
63 } |
|
64 |
|
65 namespace alfwidgetfactory |
|
66 { |
|
67 static const IfId ident= |
|
68 { |
|
69 0,"alfwidgetfactory" |
|
70 }; |
|
71 |
|
72 } |
|
73 |
|
74 /** |
|
75 * @class AlfCustomInitDataBase ialfwidgetfactory.h "alf/ialfwidgetfactory.h" |
|
76 * |
|
77 * Empty placeholder for custom data to be plumbed through the factory while |
|
78 * creating widgets or widget parts. |
|
79 * Derive from this class to pass custom data via the factory. |
|
80 * |
|
81 * @lib alfwidgetfactory.lib |
|
82 * @since S60 ?S60_version |
|
83 * @status Draft |
|
84 */ |
|
85 class AlfCustomInitDataBase |
|
86 { |
|
87 public: |
|
88 |
|
89 /** |
|
90 * Virtual destructor. |
|
91 */ |
|
92 virtual ~AlfCustomInitDataBase() {} |
|
93 }; |
|
94 |
|
95 |
|
96 /** |
|
97 * @class IAlfWidgetFactory ialfwidgetfactory.h "alf/ialfwidgetfactory.h" |
|
98 * |
|
99 * Interface to create widgets, register custom widget factories and query |
|
100 * factory products. |
|
101 * |
|
102 * Widget factory provides methods to create widgets, event handlers, |
|
103 * controls, visual templates and elements through a factory chain. |
|
104 * @code |
|
105 * MAlfListWidget* list = widgetFactory.CreateWidget<MAlfListWidget>( |
|
106 * "alflistwidget"); |
|
107 * if( list ) |
|
108 * { |
|
109 * // do operations with widget |
|
110 * } |
|
111 * @endcode |
|
112 * |
|
113 * @lib alfwidgetfactory.lib |
|
114 * @since S60 ?S60_version |
|
115 * @status Draft |
|
116 */ |
|
117 class IAlfWidgetFactory: public IAlfInterfaceBase |
|
118 { |
|
119 public: |
|
120 static inline const IfId& type() |
|
121 { |
|
122 return alfwidgetfactory::ident; |
|
123 } |
|
124 |
|
125 /** |
|
126 * Destructor |
|
127 */ |
|
128 virtual ~IAlfWidgetFactory() {} |
|
129 |
|
130 // Templates |
|
131 |
|
132 /** |
|
133 * Constructs a new widget. |
|
134 * |
|
135 * Each widget will have to be added into a container widget. The root |
|
136 * container widget of an application user interface view can be created |
|
137 * with the createViewWidget() method. The widget hierarchy can be |
|
138 * constructed from the root container widget by using container and leaf |
|
139 * widgets. When a new widget is created a container has to be specified |
|
140 * that is going to contain the created widget. The container can be a |
|
141 * root container widget or some of the inner container widgets in the |
|
142 * widget containment hierarchy. |
|
143 * |
|
144 * Widget's control is bound to a display object when this widget is first |
|
145 * shown. The widget is bound to the same display that was given in the |
|
146 * constructor of its containing view. |
|
147 * |
|
148 * @see createViewWidget() |
|
149 * @see Alf::IAlfContainerWidget |
|
150 * |
|
151 * @exception osncore::AlfWidgetException Thrown with error code |
|
152 * osncore::EInvalidArgument if both node and declaration file |
|
153 * path have non-null value at the same time. |
|
154 * @exception osncore::AlfWidgetException Thrown with error code |
|
155 * osncore::EInvalidWidgetInstanceId if an attempt is made to |
|
156 * create a widget with the Instance ID of an existing widget. |
|
157 * |
|
158 * @param aLoadId Widget type identifier. |
|
159 * @param aInstanceId Id or name of the widget to be created. |
|
160 * @param aContainerWidget Reference to a container widget that will |
|
161 * contain the created widget. |
|
162 * @param aNode Declarative UI node which is used to construct |
|
163 * and configure this widget from a declaration. |
|
164 * Default implementation if aNode is NULL. |
|
165 * @param aFilePath File handle to an XML file describing the |
|
166 * presentation of the widget. Both aNode and |
|
167 * aFilePath cannot be non-null values at the |
|
168 * same time. |
|
169 * @param aCustomData Custom data to be passed to the widget during |
|
170 * construction. |
|
171 * |
|
172 * @return Pointer to the created widget or 0. The created widget is |
|
173 * maintained in the UI Accelerator Toolkit environment. |
|
174 */ |
|
175 template<class T> |
|
176 T* createWidget( |
|
177 const char* aLoadId, const char* aInstanceId, |
|
178 IAlfContainerWidget& aContainerWidget, |
|
179 DuiNode* aNode=0, const char* aFilePath=0, |
|
180 AlfCustomInitDataBase* aCustomData=0) |
|
181 { |
|
182 return static_cast<T*>( |
|
183 createWidget(aLoadId,aInstanceId,aContainerWidget, |
|
184 aNode,aFilePath,aCustomData)); |
|
185 } |
|
186 |
|
187 /** |
|
188 * Destroy widget |
|
189 * |
|
190 * @param aWidget A widget to be destroyed. |
|
191 * @return Error code, if widget was not found, 0 otherwise. |
|
192 */ |
|
193 template<class T> |
|
194 int destroyWidget(T* aWidget) |
|
195 { |
|
196 return destroyWidget(static_cast<IAlfWidget*>(aWidget)); |
|
197 } |
|
198 |
|
199 /** |
|
200 * Create a widget model |
|
201 * |
|
202 * @param aLoadId Implementation to load |
|
203 * @param aCustomData Custom data to be passed to the model during |
|
204 * construction. |
|
205 * @return Pointer to model or 0. |
|
206 */ |
|
207 template<class T> |
|
208 T* createModel(const char* aLoadId, AlfCustomInitDataBase* aCustomData=0) |
|
209 { |
|
210 return static_cast<T*>(createModel(aLoadId,aCustomData)); |
|
211 } |
|
212 |
|
213 /** |
|
214 * Create a control |
|
215 * |
|
216 * @param aLoadId Load identifier |
|
217 * @param aInstanceId Instance identifier |
|
218 * @param aDisplay Display where control is bound |
|
219 * @param aCustomData Custom data to be passed to the control during |
|
220 * construction. |
|
221 * @return Pointer to control or 0. |
|
222 */ |
|
223 template<class T> T* createControl( |
|
224 const char* aLoadId, const char* aInstanceId, |
|
225 CAlfDisplay* aDisplay=0, AlfCustomInitDataBase* aCustomData=0) |
|
226 { |
|
227 return static_cast<T*>( |
|
228 createControl(aLoadId,aInstanceId,aDisplay,aCustomData)); |
|
229 } |
|
230 |
|
231 /** |
|
232 * Create an element |
|
233 * |
|
234 * @param aLoadId Load identifier |
|
235 * @param aInstanceId Instance identifier |
|
236 * @param aControl Control Use by element contructor |
|
237 * @param aCustomData Custom data to be passed to the element during |
|
238 * construction. |
|
239 * @return Pointer to element or 0. |
|
240 */ |
|
241 template<class T> T* createElement( |
|
242 const char* aLoadId, const char* aInstanceId, |
|
243 IAlfWidgetControl& aControl, DuiNode* aNode=0, |
|
244 AlfCustomInitDataBase* aCustomData=0) |
|
245 { |
|
246 return static_cast<T*>( |
|
247 createElement(aLoadId,aInstanceId,aControl,aNode,aCustomData)); |
|
248 } |
|
249 |
|
250 /** |
|
251 * Create a visual template |
|
252 * |
|
253 * @param aLoadId Load identifier |
|
254 * @param aInstanceId Instance identifier |
|
255 * @param aCustomData Custom data to be passed to the visual template |
|
256 * during construction. |
|
257 * @return Pointer to visual template or 0. |
|
258 */ |
|
259 template<class T> T* createVisualTemplate( |
|
260 const char* aLoadId, const char* aInstanceId, |
|
261 DuiNode* aNode=0, AlfCustomInitDataBase* aCustomData=0) |
|
262 { |
|
263 return static_cast<T*>( |
|
264 createVisualTemplate(aLoadId,aInstanceId,aNode,aCustomData)); |
|
265 } |
|
266 |
|
267 /** |
|
268 * Create an event handler |
|
269 * |
|
270 * @param aLoadId Load identifier |
|
271 * @param aInstanceId Instance identifier |
|
272 * @param aCustomData Custom data to be passed to the event handler |
|
273 * during construction. |
|
274 * @return Pointer to event handler or 0. |
|
275 */ |
|
276 template<class T> T* createEventHandler( |
|
277 const char* aLoadId, |
|
278 const char* aInstanceId, |
|
279 DuiNode* aNode=0, |
|
280 AlfCustomInitDataBase* aCustomData=0) |
|
281 { |
|
282 return static_cast<T*>( |
|
283 createEventHandler(aLoadId,aInstanceId,aNode,aCustomData)); |
|
284 } |
|
285 |
|
286 /** |
|
287 * Create an layoutmanager. |
|
288 * |
|
289 * @param aLoadId Load identifier |
|
290 * @param aInstanceId Instance identifier |
|
291 * @param aNode declaration node. |
|
292 * @param aCustomData Custom data to be passed to the layout manager |
|
293 * during construction. |
|
294 * @return Pointer to instance or NULL |
|
295 */ |
|
296 template<class T> T* createLayoutManager( |
|
297 const char* aLoadId, |
|
298 const char* aInstanceId, |
|
299 DuiNode* aNode=0, |
|
300 AlfCustomInitDataBase* aCustomData=0) |
|
301 { |
|
302 return static_cast<T*>( |
|
303 createLayoutManager(aLoadId,aInstanceId,aNode,aCustomData)); |
|
304 } |
|
305 |
|
306 public: |
|
307 |
|
308 /** |
|
309 * Constructs a new view widget. |
|
310 * |
|
311 * Application user interface contains always at least one view widget. |
|
312 * |
|
313 * View widget is a container widget that can be used to contain other |
|
314 * container or leaf widgets. View widget is the root of the application |
|
315 * user interface view into which the widget hierarchy can be built. |
|
316 * |
|
317 * View widget control is appended in a control group. Each view will be |
|
318 * associated with a unique control group. A unique, unreserved control |
|
319 * group ID should be passed through this construction method. |
|
320 * Construction method will then create a new control group for the given |
|
321 * ID and append the view widget's control into the control group. When |
|
322 * the view widget is destroyed also its control group is destroyed and |
|
323 * the control group ID is free to be used again. If an already reserved |
|
324 * control group ID is passed an osncore::AlfException is thrown with |
|
325 * error code osncore::EInvalidArgument. |
|
326 * |
|
327 * If the application contains multiple views it is possible to apply |
|
328 * transitions from a view widget to another by manipulating the |
|
329 * associated control groups. |
|
330 * |
|
331 * View widget is bound to a single display. If no display is given as a |
|
332 * construction parameter then primary display of the UI Accelerator |
|
333 * Toolkit environment is used. If no display is given and there is no |
|
334 * primary display in the environment an osncore::AlfException is thrown |
|
335 * with error code osncore::EDisplayNotFound. |
|
336 * |
|
337 * @see Alf::IAlfViewWidget |
|
338 * @see Alf::IAlfContainerWidget |
|
339 * @see CAlfControlGroup |
|
340 * |
|
341 * @exception osncore::AlfException Thrown with error code |
|
342 * osncore::EInvalidArgument if a control group with the |
|
343 * provided id already exists and with error code |
|
344 * osncore::EDisplayNotFound if no display object is provided |
|
345 * and there is no primary display. |
|
346 * |
|
347 * @exception osncore::AlfWidgetException Thrown with error code |
|
348 * osncore::EInvalidArgument if both node and declaration |
|
349 * file path have non-null value at the same time. |
|
350 * @exception osncore::AlfWidgetException Thrown with error code |
|
351 * osncore::EInvalidWidgetInstanceId if an attempt is made to |
|
352 * create a view widget with the Instance ID of an existing widget. |
|
353 * |
|
354 * @param aInstanceId Id or name of the view widget to be created. |
|
355 * @param aControlGroupId Id of the control group to be created. This has |
|
356 * to be unique and unreserved control group id. |
|
357 * @param aNode Declarative UI node which is used to construct |
|
358 * and configure this widget from a declaration. |
|
359 * Default implementation if aNode is NULL. |
|
360 * @param aDisplay Display in which the view widget is maintained. |
|
361 * Primary display is used if no display is |
|
362 * provided. |
|
363 * @param aFilePath File handle to an XML file describing the |
|
364 * presentation of the view widget. Both aNode and |
|
365 * aFilePath cannot be non-null values at the same |
|
366 * time. |
|
367 * @param aCustomData Custom data to be passed to the widget during |
|
368 * construction. |
|
369 * |
|
370 * @return Pointer to a new view widget or 0. The created widget is |
|
371 * maintained in the UI Accelerator Toolkit environment. |
|
372 */ |
|
373 virtual IAlfViewWidget* createViewWidget( |
|
374 const char* aInstanceId, |
|
375 int aControlGroupId, |
|
376 DuiNode* aNode=0, |
|
377 CAlfDisplay* aDisplay=0, |
|
378 const char* aFilePath=0, |
|
379 AlfCustomInitDataBase* aCustomData=0) = 0; |
|
380 |
|
381 /** |
|
382 * Constructs a new widget. |
|
383 * |
|
384 * Each widget will have to be added into a container widget. The root |
|
385 * container widget of an application user interface view can be created |
|
386 * with the createViewWidget() method. The widget hierarchy can be |
|
387 * constructed from the root container widget by using container and leaf |
|
388 * widgets. When a new widget is created a container has to be specified |
|
389 * that is going to contain the created widget. The container can be a |
|
390 * root container widget or some of the inner container widgets in the |
|
391 * widget containment hierarchy. |
|
392 * |
|
393 * Widget's control is bound to a display object when this widget is first |
|
394 * shown. The widget is bound to the same display that was given in the |
|
395 * constructor of its containing view. |
|
396 * |
|
397 * @see createViewWidget() |
|
398 * @see Alf::IAlfContainerWidget |
|
399 * |
|
400 * @exception osncore::AlfWidgetException Thrown with error code |
|
401 * osncore::EInvalidArgument if both node and declaration file |
|
402 * path have non-null value at the same time. |
|
403 * @exception osncore::AlfWidgetException Thrown with error code |
|
404 * osncore::EInvalidWidgetInstanceId if an attempt is made to |
|
405 * create a widget with the Instance ID of an existing widget. |
|
406 * |
|
407 * @param aLoadId Widget type identifier. |
|
408 * @param aInstanceId Id or name of the widget to be created. |
|
409 * @param aContainerWidget Reference to a container widget that will |
|
410 * contain the created widget. |
|
411 * @param aNode Declarative UI node which is used to construct |
|
412 * and configure this widget from a declaration. |
|
413 * Default implementation if aNode is NULL. |
|
414 * @param aFilePath File handle to an XML file describing the |
|
415 * presentation of the widget. Both aNode and |
|
416 * aFilePath cannot be non-null |
|
417 * values at the same time. |
|
418 * @param aCustomData Custom data to be passed to the widget during |
|
419 * construction. |
|
420 * |
|
421 * @return Pointer to the created widget or 0. The created widget is |
|
422 * maintained in the UI Accelerator Toolkit environment. |
|
423 */ |
|
424 virtual IAlfWidget* createWidget( |
|
425 const char* aLoadId, |
|
426 const char* aInstanceId, |
|
427 IAlfContainerWidget& aContainerWidget, |
|
428 DuiNode* aNode=0, |
|
429 const char* aFilePath=0, |
|
430 AlfCustomInitDataBase* aCustomData=0) = 0; |
|
431 |
|
432 /** |
|
433 * Destroy widget |
|
434 * |
|
435 * @param aWidget A widget to be destroyed. |
|
436 * @return -1, if widget was not found, 0 otherwise. |
|
437 */ |
|
438 virtual int destroyWidget(IAlfWidget* aWidget) = 0; |
|
439 |
|
440 /** |
|
441 * Find named widgets owned by the factory |
|
442 * |
|
443 * @param aWidgetName A widget name to be found. |
|
444 * |
|
445 * @return The widget pointer if it is found, 0 otherwise. |
|
446 */ |
|
447 virtual IAlfWidget* findWidget(const char* aWidgetName)const = 0; |
|
448 |
|
449 |
|
450 /** |
|
451 * Append widgets into the widget factory |
|
452 * |
|
453 * @param aWidget A widget to be added |
|
454 * |
|
455 * @return -1, if widget was already added to the factory, 0 otherwise. |
|
456 */ |
|
457 virtual int appendWidget(IAlfWidget* aWidget) = 0; |
|
458 |
|
459 /** |
|
460 * Create a widget model |
|
461 * |
|
462 * @param aLoadId Implementation to load |
|
463 * @param aCustomData Custom data to be passed to the model during |
|
464 * construction. |
|
465 * @return Pointer to widget or 0. Ownership is transferred to caller. |
|
466 */ |
|
467 virtual IAlfModel* createModel( |
|
468 const char* aLoadId, |
|
469 AlfCustomInitDataBase* aCustomData=0) = 0; |
|
470 |
|
471 /** |
|
472 * Create a control |
|
473 * |
|
474 * @param aLoadId Load identifier |
|
475 * @param aInstanceId Instance identifier |
|
476 * @param aDisplay Display where control is bound |
|
477 * @param aCustomData Custom data to be passed to the control during |
|
478 * construction. |
|
479 * @return Pointer to created control or 0. |
|
480 */ |
|
481 virtual IAlfWidgetControl* createControl( |
|
482 const char* aLoadId, |
|
483 const char* aInstanceId, |
|
484 CAlfDisplay* aDisplay=0, |
|
485 AlfCustomInitDataBase* aCustomData=0) = 0; |
|
486 |
|
487 /** |
|
488 * Create an element |
|
489 * |
|
490 * @param aLoadId Load identifier |
|
491 * @param aInstanceId Instance identifier |
|
492 * @param aControl Control Use by element contructor |
|
493 * @param aCustomData Custom data to be passed to the element during |
|
494 * construction. |
|
495 * @return Pointer to created element or 0. |
|
496 */ |
|
497 virtual IAlfElement* createElement( |
|
498 const char* aLoadId, |
|
499 const char* aInstanceId, |
|
500 IAlfWidgetControl& aControl, |
|
501 DuiNode* aNode=0, |
|
502 AlfCustomInitDataBase* aCustomData=0) = 0; |
|
503 |
|
504 /** |
|
505 * Create a visual template |
|
506 * |
|
507 * @param aLoadId Load identifier |
|
508 * @param aInstanceId Instance identifier |
|
509 * @param aCustomData Custom data to be passed to the visual template |
|
510 * during construction. |
|
511 * @return Pointer to created visual template or 0. |
|
512 */ |
|
513 virtual IAlfVisualTemplate* createVisualTemplate( |
|
514 const char* aLoadId, |
|
515 const char* aInstanceId, |
|
516 DuiNode* aNode=0, |
|
517 AlfCustomInitDataBase* aCustomData=0) = 0; |
|
518 |
|
519 /** |
|
520 * Create an event handler |
|
521 * |
|
522 * @param aLoadId Load identifier |
|
523 * @param aInstanceId Instance identifier |
|
524 * @param aCustomData Custom data to be passed to the event handler |
|
525 * during construction. |
|
526 * @return Pointer to created event handler or 0. |
|
527 */ |
|
528 virtual IAlfWidgetEventHandler* createEventHandler( |
|
529 const char* aLoadId, |
|
530 const char* aInstanceId, |
|
531 DuiNode* aNode=0, |
|
532 AlfCustomInitDataBase* aCustomData=0) = 0; |
|
533 |
|
534 /** |
|
535 * Create an layoutmanager. |
|
536 * |
|
537 * @param aLoadId Load identifier |
|
538 * @param aInstanceId Instance identifier |
|
539 * @param aNode declaration node. |
|
540 * @param aCustomData Possible custom initialization data for the |
|
541 * layoutmanager. |
|
542 * @return Pointer to created layout manager or 0. |
|
543 */ |
|
544 virtual IAlfLayoutManager* createLayoutManager( |
|
545 const char* aLoadId, |
|
546 const char* aInstanceId, |
|
547 DuiNode* aNode=0, |
|
548 AlfCustomInitDataBase* aCustomData=0) = 0; |
|
549 |
|
550 /** |
|
551 * Application can register a custom factory to create custom factory |
|
552 * products. |
|
553 * Ownership is transferred to a widget factory chain, |
|
554 * if call is successfull. |
|
555 * |
|
556 * @exception std::bad_alloc |
|
557 * @param aFactory Custom factory |
|
558 * @return void |
|
559 */ |
|
560 virtual void registerCustomWidgetFactory(IAlfFactoryPlugin* aFactory) = 0; |
|
561 }; |
|
562 |
|
563 } // namespace Alf |
|
564 |
|
565 #endif |
|
566 |
|
567 // End of File |
|