--- a/mmuifw_plat/alf_widgetfactory_api/inc/alf/ialfwidgetfactory.h Tue Feb 02 00:28:09 2010 +0200
+++ /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 <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