--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/mmuifw_plat/alf_widgetfactory_api/inc/alf/ialfwidgetfactory.h Wed Sep 01 12:23:18 2010 +0100
@@ -0,0 +1,567 @@
+/*
+* Copyright (c) 2007 Nokia Corporation and/or its subsidiary(-ies).
+* All rights reserved.
+* This component and the accompanying materials are made available
+* under the terms of "Eclipse Public License v1.0"
+* which accompanies this distribution, and is available
+* at the URL "http://www.eclipse.org/legal/epl-v10.html".
+*
+* Initial Contributors:
+* Nokia Corporation - initial contribution.
+*
+* Contributors:
+*
+* Description: Custom widget factories are registered into factory chain
+*
+*/
+
+
+#ifndef I_ALFWIDGETFACTORY_H
+#define I_ALFWIDGETFACTORY_H
+
+//Widget Utils includes
+#include <alf/alftypes.h>
+
+//Widget Model Includes
+#include <alf/ialfinterfacebase.h>
+
+//Forward declaration
+class CAlfDisplay;
+
+//Namespaces
+namespace duiuimodel
+ {
+ class DuiNode;
+ }
+
+using namespace duiuimodel;
+
+namespace Alf
+ {
+
+//Forward declarations
+class IAlfWidget;
+class IAlfModel;
+class IAlfWidgetControl;
+class IAlfElement;
+class IAlfVisualTemplate;
+class IAlfWidgetEventHandler;
+class IAlfFactoryPlugin;
+class IAlfViewWidget;
+class IAlfContainerWidget;
+class IAlfLayoutManager;
+
+//Namespace
+namespace category
+ {
+ static const char* const KWidget = "widget";
+ static const char* const KModel = "model";
+ static const char* const KControl ="control";
+ static const char* const KElement ="element";
+ static const char* const KVisualTemplate ="visualtemplate";
+ static const char* const KEventHandler = "eventhandler";
+ }
+
+namespace alfwidgetfactory
+ {
+ static const IfId ident=
+ {
+ 0,"alfwidgetfactory"
+ };
+
+ }
+
+/**
+ * @class AlfCustomInitDataBase ialfwidgetfactory.h "alf/ialfwidgetfactory.h"
+ *
+ * Empty placeholder for custom data to be plumbed through the factory while
+ * creating widgets or widget parts.
+ * Derive from this class to pass custom data via the factory.
+ *
+ * @lib alfwidgetfactory.lib
+ * @since S60 ?S60_version
+ * @status Draft
+ */
+class AlfCustomInitDataBase
+ {
+public:
+
+ /**
+ * Virtual destructor.
+ */
+ virtual ~AlfCustomInitDataBase() {}
+ };
+
+
+/**
+ * @class IAlfWidgetFactory ialfwidgetfactory.h "alf/ialfwidgetfactory.h"
+ *
+ * Interface to create widgets, register custom widget factories and query
+ * factory products.
+ *
+ * Widget factory provides methods to create widgets, event handlers,
+ * controls, visual templates and elements through a factory chain.
+ * @code
+ * MAlfListWidget* list = widgetFactory.CreateWidget<MAlfListWidget>(
+ * "alflistwidget");
+ * if( list )
+ * {
+ * // do operations with widget
+ * }
+ * @endcode
+ *
+ * @lib alfwidgetfactory.lib
+ * @since S60 ?S60_version
+ * @status Draft
+ */
+class IAlfWidgetFactory: public IAlfInterfaceBase
+ {
+public:
+ static inline const IfId& type()
+ {
+ return alfwidgetfactory::ident;
+ }
+
+ /**
+ * Destructor
+ */
+ virtual ~IAlfWidgetFactory() {}
+
+ // Templates
+
+ /**
+ * Constructs a new widget.
+ *
+ * Each widget will have to be added into a container widget. The root
+ * container widget of an application user interface view can be created
+ * with the createViewWidget() method. The widget hierarchy can be
+ * constructed from the root container widget by using container and leaf
+ * widgets. When a new widget is created a container has to be specified
+ * that is going to contain the created widget. The container can be a
+ * root container widget or some of the inner container widgets in the
+ * widget containment hierarchy.
+ *
+ * Widget's control is bound to a display object when this widget is first
+ * shown. The widget is bound to the same display that was given in the
+ * constructor of its containing view.
+ *
+ * @see createViewWidget()
+ * @see Alf::IAlfContainerWidget
+ *
+ * @exception osncore::AlfWidgetException Thrown with error code
+ * osncore::EInvalidArgument if both node and declaration file
+ * path have non-null value at the same time.
+ * @exception osncore::AlfWidgetException Thrown with error code
+ * osncore::EInvalidWidgetInstanceId if an attempt is made to
+ * create a widget with the Instance ID of an existing widget.
+ *
+ * @param aLoadId Widget type identifier.
+ * @param aInstanceId Id or name of the widget to be created.
+ * @param aContainerWidget Reference to a container widget that will
+ * contain the created widget.
+ * @param aNode Declarative UI node which is used to construct
+ * and configure this widget from a declaration.
+ * Default implementation if aNode is NULL.
+ * @param aFilePath File handle to an XML file describing the
+ * presentation of the widget. Both aNode and
+ * aFilePath cannot be non-null values at the
+ * same time.
+ * @param aCustomData Custom data to be passed to the widget during
+ * construction.
+ *
+ * @return Pointer to the created widget or 0. The created widget is
+ * maintained in the UI Accelerator Toolkit environment.
+ */
+ template<class T>
+ T* createWidget(
+ const char* aLoadId, const char* aInstanceId,
+ IAlfContainerWidget& aContainerWidget,
+ DuiNode* aNode=0, const char* aFilePath=0,
+ AlfCustomInitDataBase* aCustomData=0)
+ {
+ return static_cast<T*>(
+ createWidget(aLoadId,aInstanceId,aContainerWidget,
+ aNode,aFilePath,aCustomData));
+ }
+
+ /**
+ * Destroy widget
+ *
+ * @param aWidget A widget to be destroyed.
+ * @return Error code, if widget was not found, 0 otherwise.
+ */
+ template<class T>
+ int destroyWidget(T* aWidget)
+ {
+ return destroyWidget(static_cast<IAlfWidget*>(aWidget));
+ }
+
+ /**
+ * Create a widget model
+ *
+ * @param aLoadId Implementation to load
+ * @param aCustomData Custom data to be passed to the model during
+ * construction.
+ * @return Pointer to model or 0.
+ */
+ template<class T>
+ T* createModel(const char* aLoadId, AlfCustomInitDataBase* aCustomData=0)
+ {
+ return static_cast<T*>(createModel(aLoadId,aCustomData));
+ }
+
+ /**
+ * Create a control
+ *
+ * @param aLoadId Load identifier
+ * @param aInstanceId Instance identifier
+ * @param aDisplay Display where control is bound
+ * @param aCustomData Custom data to be passed to the control during
+ * construction.
+ * @return Pointer to control or 0.
+ */
+ template<class T> T* createControl(
+ const char* aLoadId, const char* aInstanceId,
+ CAlfDisplay* aDisplay=0, AlfCustomInitDataBase* aCustomData=0)
+ {
+ return static_cast<T*>(
+ createControl(aLoadId,aInstanceId,aDisplay,aCustomData));
+ }
+
+ /**
+ * Create an element
+ *
+ * @param aLoadId Load identifier
+ * @param aInstanceId Instance identifier
+ * @param aControl Control Use by element contructor
+ * @param aCustomData Custom data to be passed to the element during
+ * construction.
+ * @return Pointer to element or 0.
+ */
+ template<class T> T* createElement(
+ const char* aLoadId, const char* aInstanceId,
+ IAlfWidgetControl& aControl, DuiNode* aNode=0,
+ AlfCustomInitDataBase* aCustomData=0)
+ {
+ return static_cast<T*>(
+ createElement(aLoadId,aInstanceId,aControl,aNode,aCustomData));
+ }
+
+ /**
+ * Create a visual template
+ *
+ * @param aLoadId Load identifier
+ * @param aInstanceId Instance identifier
+ * @param aCustomData Custom data to be passed to the visual template
+ * during construction.
+ * @return Pointer to visual template or 0.
+ */
+ template<class T> T* createVisualTemplate(
+ const char* aLoadId, const char* aInstanceId,
+ DuiNode* aNode=0, AlfCustomInitDataBase* aCustomData=0)
+ {
+ return static_cast<T*>(
+ createVisualTemplate(aLoadId,aInstanceId,aNode,aCustomData));
+ }
+
+ /**
+ * Create an event handler
+ *
+ * @param aLoadId Load identifier
+ * @param aInstanceId Instance identifier
+ * @param aCustomData Custom data to be passed to the event handler
+ * during construction.
+ * @return Pointer to event handler or 0.
+ */
+ template<class T> T* createEventHandler(
+ const char* aLoadId,
+ const char* aInstanceId,
+ DuiNode* aNode=0,
+ AlfCustomInitDataBase* aCustomData=0)
+ {
+ return static_cast<T*>(
+ createEventHandler(aLoadId,aInstanceId,aNode,aCustomData));
+ }
+
+ /**
+ * Create an layoutmanager.
+ *
+ * @param aLoadId Load identifier
+ * @param aInstanceId Instance identifier
+ * @param aNode declaration node.
+ * @param aCustomData Custom data to be passed to the layout manager
+ * during construction.
+ * @return Pointer to instance or NULL
+ */
+ template<class T> T* createLayoutManager(
+ const char* aLoadId,
+ const char* aInstanceId,
+ DuiNode* aNode=0,
+ AlfCustomInitDataBase* aCustomData=0)
+ {
+ return static_cast<T*>(
+ createLayoutManager(aLoadId,aInstanceId,aNode,aCustomData));
+ }
+
+public:
+
+ /**
+ * Constructs a new view widget.
+ *
+ * Application user interface contains always at least one view widget.
+ *
+ * View widget is a container widget that can be used to contain other
+ * container or leaf widgets. View widget is the root of the application
+ * user interface view into which the widget hierarchy can be built.
+ *
+ * View widget control is appended in a control group. Each view will be
+ * associated with a unique control group. A unique, unreserved control
+ * group ID should be passed through this construction method.
+ * Construction method will then create a new control group for the given
+ * ID and append the view widget's control into the control group. When
+ * the view widget is destroyed also its control group is destroyed and
+ * the control group ID is free to be used again. If an already reserved
+ * control group ID is passed an osncore::AlfException is thrown with
+ * error code osncore::EInvalidArgument.
+ *
+ * If the application contains multiple views it is possible to apply
+ * transitions from a view widget to another by manipulating the
+ * associated control groups.
+ *
+ * View widget is bound to a single display. If no display is given as a
+ * construction parameter then primary display of the UI Accelerator
+ * Toolkit environment is used. If no display is given and there is no
+ * primary display in the environment an osncore::AlfException is thrown
+ * with error code osncore::EDisplayNotFound.
+ *
+ * @see Alf::IAlfViewWidget
+ * @see Alf::IAlfContainerWidget
+ * @see CAlfControlGroup
+ *
+ * @exception osncore::AlfException Thrown with error code
+ * osncore::EInvalidArgument if a control group with the
+ * provided id already exists and with error code
+ * osncore::EDisplayNotFound if no display object is provided
+ * and there is no primary display.
+ *
+ * @exception osncore::AlfWidgetException Thrown with error code
+ * osncore::EInvalidArgument if both node and declaration
+ * file path have non-null value at the same time.
+ * @exception osncore::AlfWidgetException Thrown with error code
+ * osncore::EInvalidWidgetInstanceId if an attempt is made to
+ * create a view widget with the Instance ID of an existing widget.
+ *
+ * @param aInstanceId Id or name of the view widget to be created.
+ * @param aControlGroupId Id of the control group to be created. This has
+ * to be unique and unreserved control group id.
+ * @param aNode Declarative UI node which is used to construct
+ * and configure this widget from a declaration.
+ * Default implementation if aNode is NULL.
+ * @param aDisplay Display in which the view widget is maintained.
+ * Primary display is used if no display is
+ * provided.
+ * @param aFilePath File handle to an XML file describing the
+ * presentation of the view widget. Both aNode and
+ * aFilePath cannot be non-null values at the same
+ * time.
+ * @param aCustomData Custom data to be passed to the widget during
+ * construction.
+ *
+ * @return Pointer to a new view widget or 0. The created widget is
+ * maintained in the UI Accelerator Toolkit environment.
+ */
+ virtual IAlfViewWidget* createViewWidget(
+ const char* aInstanceId,
+ int aControlGroupId,
+ DuiNode* aNode=0,
+ CAlfDisplay* aDisplay=0,
+ const char* aFilePath=0,
+ AlfCustomInitDataBase* aCustomData=0) = 0;
+
+ /**
+ * Constructs a new widget.
+ *
+ * Each widget will have to be added into a container widget. The root
+ * container widget of an application user interface view can be created
+ * with the createViewWidget() method. The widget hierarchy can be
+ * constructed from the root container widget by using container and leaf
+ * widgets. When a new widget is created a container has to be specified
+ * that is going to contain the created widget. The container can be a
+ * root container widget or some of the inner container widgets in the
+ * widget containment hierarchy.
+ *
+ * Widget's control is bound to a display object when this widget is first
+ * shown. The widget is bound to the same display that was given in the
+ * constructor of its containing view.
+ *
+ * @see createViewWidget()
+ * @see Alf::IAlfContainerWidget
+ *
+ * @exception osncore::AlfWidgetException Thrown with error code
+ * osncore::EInvalidArgument if both node and declaration file
+ * path have non-null value at the same time.
+ * @exception osncore::AlfWidgetException Thrown with error code
+ * osncore::EInvalidWidgetInstanceId if an attempt is made to
+ * create a widget with the Instance ID of an existing widget.
+ *
+ * @param aLoadId Widget type identifier.
+ * @param aInstanceId Id or name of the widget to be created.
+ * @param aContainerWidget Reference to a container widget that will
+ * contain the created widget.
+ * @param aNode Declarative UI node which is used to construct
+ * and configure this widget from a declaration.
+ * Default implementation if aNode is NULL.
+ * @param aFilePath File handle to an XML file describing the
+ * presentation of the widget. Both aNode and
+ * aFilePath cannot be non-null
+ * values at the same time.
+ * @param aCustomData Custom data to be passed to the widget during
+ * construction.
+ *
+ * @return Pointer to the created widget or 0. The created widget is
+ * maintained in the UI Accelerator Toolkit environment.
+ */
+ virtual IAlfWidget* createWidget(
+ const char* aLoadId,
+ const char* aInstanceId,
+ IAlfContainerWidget& aContainerWidget,
+ DuiNode* aNode=0,
+ const char* aFilePath=0,
+ AlfCustomInitDataBase* aCustomData=0) = 0;
+
+ /**
+ * Destroy widget
+ *
+ * @param aWidget A widget to be destroyed.
+ * @return -1, if widget was not found, 0 otherwise.
+ */
+ virtual int destroyWidget(IAlfWidget* aWidget) = 0;
+
+ /**
+ * Find named widgets owned by the factory
+ *
+ * @param aWidgetName A widget name to be found.
+ *
+ * @return The widget pointer if it is found, 0 otherwise.
+ */
+ virtual IAlfWidget* findWidget(const char* aWidgetName)const = 0;
+
+
+ /**
+ * Append widgets into the widget factory
+ *
+ * @param aWidget A widget to be added
+ *
+ * @return -1, if widget was already added to the factory, 0 otherwise.
+ */
+ virtual int appendWidget(IAlfWidget* aWidget) = 0;
+
+ /**
+ * Create a widget model
+ *
+ * @param aLoadId Implementation to load
+ * @param aCustomData Custom data to be passed to the model during
+ * construction.
+ * @return Pointer to widget or 0. Ownership is transferred to caller.
+ */
+ virtual IAlfModel* createModel(
+ const char* aLoadId,
+ AlfCustomInitDataBase* aCustomData=0) = 0;
+
+ /**
+ * Create a control
+ *
+ * @param aLoadId Load identifier
+ * @param aInstanceId Instance identifier
+ * @param aDisplay Display where control is bound
+ * @param aCustomData Custom data to be passed to the control during
+ * construction.
+ * @return Pointer to created control or 0.
+ */
+ virtual IAlfWidgetControl* createControl(
+ const char* aLoadId,
+ const char* aInstanceId,
+ CAlfDisplay* aDisplay=0,
+ AlfCustomInitDataBase* aCustomData=0) = 0;
+
+ /**
+ * Create an element
+ *
+ * @param aLoadId Load identifier
+ * @param aInstanceId Instance identifier
+ * @param aControl Control Use by element contructor
+ * @param aCustomData Custom data to be passed to the element during
+ * construction.
+ * @return Pointer to created element or 0.
+ */
+ virtual IAlfElement* createElement(
+ const char* aLoadId,
+ const char* aInstanceId,
+ IAlfWidgetControl& aControl,
+ DuiNode* aNode=0,
+ AlfCustomInitDataBase* aCustomData=0) = 0;
+
+ /**
+ * Create a visual template
+ *
+ * @param aLoadId Load identifier
+ * @param aInstanceId Instance identifier
+ * @param aCustomData Custom data to be passed to the visual template
+ * during construction.
+ * @return Pointer to created visual template or 0.
+ */
+ virtual IAlfVisualTemplate* createVisualTemplate(
+ const char* aLoadId,
+ const char* aInstanceId,
+ DuiNode* aNode=0,
+ AlfCustomInitDataBase* aCustomData=0) = 0;
+
+ /**
+ * Create an event handler
+ *
+ * @param aLoadId Load identifier
+ * @param aInstanceId Instance identifier
+ * @param aCustomData Custom data to be passed to the event handler
+ * during construction.
+ * @return Pointer to created event handler or 0.
+ */
+ virtual IAlfWidgetEventHandler* createEventHandler(
+ const char* aLoadId,
+ const char* aInstanceId,
+ DuiNode* aNode=0,
+ AlfCustomInitDataBase* aCustomData=0) = 0;
+
+ /**
+ * Create an layoutmanager.
+ *
+ * @param aLoadId Load identifier
+ * @param aInstanceId Instance identifier
+ * @param aNode declaration node.
+ * @param aCustomData Possible custom initialization data for the
+ * layoutmanager.
+ * @return Pointer to created layout manager or 0.
+ */
+ virtual IAlfLayoutManager* createLayoutManager(
+ const char* aLoadId,
+ const char* aInstanceId,
+ DuiNode* aNode=0,
+ AlfCustomInitDataBase* aCustomData=0) = 0;
+
+ /**
+ * Application can register a custom factory to create custom factory
+ * products.
+ * Ownership is transferred to a widget factory chain,
+ * if call is successfull.
+ *
+ * @exception std::bad_alloc
+ * @param aFactory Custom factory
+ * @return void
+ */
+ virtual void registerCustomWidgetFactory(IAlfFactoryPlugin* aFactory) = 0;
+ };
+
+ } // namespace Alf
+
+#endif
+
+// End of File