/*

* 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:  The base class for all widgets.

*

*/

#ifndef I_ALFWIDGET_H

#define I_ALFWIDGET_H

#include <alf/ialfinterfacebase.h>

#include <alf/alftypes.h>

#include <alf/alfvarianttype.h>

namespace duiuimodel

    {

class DuiNode;

    }

using namespace duiuimodel;

class CAlfEnv;

namespace Alf

    {

class CAlfWidgetControl;

class IAlfModel;

class IAlfWidgetFactory;

class IAlfContainerWidget;

class AlfCustomInitDataBase;  

namespace alfwidget

    {

static const IfId ident=

    {

    0,"alfwidget"

    };

    }

/**

 *  An interface for all widgets.

 *  Widgets consist of a model and a control.

 *  The model is owned by the widget, but all

 *  controls are owned by Alfred environment.

 *  The widget can be queried for interfaces provided

 *  by derived widget classes, the control or the model.

 *  Widgets can be constructed using the widget factory.

 *  Widgets are owned and accessed using the Alfred

 *  environment.

 *

 *  @lib alfwidgetmodel.lib

 *  @since S60 ?S60_version

 *  @status Draft

 */

class IAlfWidget : public IAlfInterfaceBase

    {

public:

    static inline const IfId& type()

        {

        return alfwidget::ident;

        }

    /** Virtual destructor. */

    virtual ~IAlfWidget() {}

    /**

     * Getter for the control. The ownership is not passed.

     *

     * @since S60 ?S60_version

     * @return The control of this widget, or NULL if the control is not specified.

     */

    virtual CAlfWidgetControl* control() const = 0;

    /**

     * Getter for the parent container. The ownership is not passed.

     *

     * @return the parent container or 0 if the widget is the root-widget.

     */

    virtual IAlfContainerWidget* parent() const = 0;

    /**

     * Sets a new widget control. After this call has been succesfully executed, the control is 

     * owned by this widget. When a new widget control is set to a widget the previously set widget

     * control is removed.

     *

     * Through the aDeletePreviousControl - parameter user can specify whether the previously set 

     * control is destroyed when new control is set. Otherwise the previous control is left on the

     * ownership of the caller. The caller has to manually delete the control or reset it to another

     * widget or control group.

     *

     * If the control passed through this method exists in a control group it is appended to the

     * control group of the view where this widget is contained in and removed from its previous

     * control group.

     *

     * Widget should always have a valid control. An osncore::AlfException is thrown with error code

     * osncore::EInvalidArgument if a control that is already used in another widget is attempted to

     * be used with this widget. You have to replace the control in the source widget first

     * before you can reuse that control in the target widget. See two code snippets below for details:

     *

     * @code

     * // This will throw an osncore::AlfException with error code osncore::EInvalidArgument.

     * targetWidget.setControl(sourceWidget.control());

     * @endcode

     *

     * @code

     * CAlfWidgetControl* control = sourceWidget.control();

     * sourceWidget.setControl(newControl, false);

     * // This is ok, since control is not set in sourceWidget anymore.

     * targetWidget.setControl(control);

     * @endcode

     *

     * @see IAlfViewWidget

     *

     * @param aControl                The new widget control to be used with this widget.

     * @param aDeletePreviousControl  If set to true will destroy the previously set control from UI Accelerator Toolkit Environment.

     *

     * @exception osncore::AlfException If the given control is already set to another widget an osncore::AlfException

     *                                  is thrown with error code osncore::EInvalidArgument.

     */

    virtual void setControl( CAlfWidgetControl* aControl, bool aDeletePreviousControl = true ) = 0;

    /**

     * Getter for the model. The ownership is not passed.

     *

     * @since S60 ?S60_version

     * @return The model of this widget, or NULL if the model is not specified.

     */

    virtual IAlfModel* model() = 0;

    /**

     * Setter for the model. Ownership is passed and the old model is released.

     *

     * @since S60 ?S60_version

     * @param aModel The model for this widget.

     * @param aTakeOwnership Whether takes ownership of model or not

     * return void

     */

    virtual void setModel( IAlfModel* aModel,bool aTakeOwnership = true) = 0;

    /**

     * Get the name of the widget instance.

     *

     * @since S60 ?S60_version

     * @return Widget name

     */

    virtual const char* widgetName() const = 0;

    /**

     * Sets/Releases the Focus from child widget of container.

     * Does not set the actual focused status in roster.

     *

     * @since S60 ?S60_version

     * @param aFocus boolean value for focused status

     * return void

     */

    virtual void setChildFocus(bool aFocus) = 0;

    /** 

     * Sets the presentation for the widget using presentation XML file.

     * Destroys any existing presentation.

     * @param aFilePath Path to XML file describing the presentation 

     *                  of the widget. Not Owned.

     * @exception AlfWidgetException if no visualization node available 

     *                               in Presentation XML or if no control

     *                               is associated with the widget.

     * @exception bad_alloc 

     * @since S60 ?S60_version

     * @return void.

     */

    virtual void setPresentation(const char* aFilePath) = 0;    

    };

/**

 * Placeholder for information required to instantiate a widget

 *  via the widget factory mechanism.

 *  A pointer to this structure is casted to a void pointer and sent to the

 *  factory plugin.

 *  @lib alfwidgetmodel.lib

 *  @since S60 ?S60_version

 */

struct AlfWidgetInitData

    {

    /**

     * Owner environment for the widget

     */

    CAlfEnv* mEnv;

    /**

     * Container widget pointer that is going to contain the created widget.

     */

    IAlfContainerWidget* mContainerWidget;

    /**

     * Widget instance ID.This uniquely identifies every widget instance

     * and is its name. Also see AlfWidget::Widgetname().

     */

    char*     mWidgetId;

    /**

     * Pointer to node in declaration containing information for the widget.

     */

    DuiNode* mNode;

    /**

     * XML file name containing the declaration for the presention of the widget. 

     */

    const char* mFilePath;

    /**

     * Pointer to custom data passed via factory mechanism

     * Not Owned.

     */

    AlfCustomInitDataBase* mCustomData;  

    };

    } // namespace Alf

#endif // I_ALFWIDGET_H

// End of File