diff -r 4ea6f81c838a -r 0e9bb658ef58 mmuifw_plat/alf_widgetfactory_api/inc/alf/ialfwidgetfactory.h --- /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 + +//Widget Model Includes +#include + +//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( + * "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 + T* createWidget( + const char* aLoadId, const char* aInstanceId, + IAlfContainerWidget& aContainerWidget, + DuiNode* aNode=0, const char* aFilePath=0, + AlfCustomInitDataBase* aCustomData=0) + { + return static_cast( + 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 + int destroyWidget(T* aWidget) + { + return destroyWidget(static_cast(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 + T* createModel(const char* aLoadId, AlfCustomInitDataBase* aCustomData=0) + { + return static_cast(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 T* createControl( + const char* aLoadId, const char* aInstanceId, + CAlfDisplay* aDisplay=0, AlfCustomInitDataBase* aCustomData=0) + { + return static_cast( + 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 T* createElement( + const char* aLoadId, const char* aInstanceId, + IAlfWidgetControl& aControl, DuiNode* aNode=0, + AlfCustomInitDataBase* aCustomData=0) + { + return static_cast( + 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 T* createVisualTemplate( + const char* aLoadId, const char* aInstanceId, + DuiNode* aNode=0, AlfCustomInitDataBase* aCustomData=0) + { + return static_cast( + 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 T* createEventHandler( + const char* aLoadId, + const char* aInstanceId, + DuiNode* aNode=0, + AlfCustomInitDataBase* aCustomData=0) + { + return static_cast( + 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 T* createLayoutManager( + const char* aLoadId, + const char* aInstanceId, + DuiNode* aNode=0, + AlfCustomInitDataBase* aCustomData=0) + { + return static_cast( + 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