/*

* 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(