diff -r 514d98f21c43 -r 4ea6f81c838a mmuifw_plat/alf_widgetfactory_api/inc/alf/ialfwidgetfactory.h --- a/mmuifw_plat/alf_widgetfactory_api/inc/alf/ialfwidgetfactory.h Mon Jun 21 16:15:51 2010 +0300 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,567 +0,0 @@ -/* -* 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