/*

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

#define ALFWIDGET_H

#include <osn/osndefines.h>

#include <alf/ialfwidget.h>

#include <memory>

#include <osn/ustring.h>

#include "alf/ialfcontainerwidget.h"

#include <alf/alfwidgetcontrol.h>

#include <vector>

class CAlfEnv;

class CAlfDisplay;

namespace osncore

    {

template <class T> class AlfPtrVector;

    }

using namespace std;

using namespace osncore;

namespace Alf

    {

//class CAlfWidgetControl;

class IAlfModel;

class IAlfWidgetFactory;

class AlfWidgetImpl;

/**

 * @class AlfWidget alfwidget.h "alf/alfwidget.h"

 * The base class for widgets.

 * @see IAlfWidget IAlfContainerWidget IAlfHostApi

 *

 * @lib alfwidgetmodel.lib

 * @since S60 ?S60_version

 * @status Draft

 * @interfaces IAlfWidget,IAlfAttributeOwner,IAlfContainerWidget,IAlfWidgetControl,IAlfHostAPI,

 *             All interfaces returned by the elements associated with the widget's control,

 *             All interfaces returned by the layout manager associated widget control ,  

 *             All interfaces returned by the model assoiated with the widget.

 */ 

class AlfWidget : public IAlfContainerWidget

    {

public:

    /**

     * Constructor.

     *

     * This will create a default control to the widget to enable the widget

     * containment hierarchy from the beginning. User can replace the default

     * control with custom control by calling the setControl() - method.

     * @exception std::bad_alloc

     *

     * @see setControl()

     *

     * @param aWidgetName The name of the widget.

     * @param aContainer  Container widget that will contain this widget.

     * @param aEnv        Toolkit environment object that will be used to create the

     *                    default control.

     */

    OSN_IMPORT AlfWidget(const char* aWidgetName, IAlfContainerWidget& aContainer, CAlfEnv& aEnv);

    /**

     * Constructor to be used only by view widget.

     * All the other widgets should use the other public constructor to ensure

     * widget hierarchy consistency from start.

     * @exception std::bad_alloc

     *

     * @see AlfWidget(const char*, IAlfContainerWidget&, CAlfEnv&)

     *

     * @param aWidgetName The name of the widget.

     */

    OSN_IMPORT AlfWidget(const char* aWidgetName);

    /**

     * Destructor.

     *

     * It also takes care that all the child widgets contained by this widget

     * are destroyed correctly, provided that they have been instantiated correctly

     * (e.g. through widget factory) and thus added to the ALF environment (CAlfEnv).

     *

     * In other words, client code does not need to take care of destroying the child

     * widgets contained by a container widget.

     */

    OSN_IMPORT virtual ~AlfWidget();

    /**

     * Constructor. The new widget is left on the cleanup stack.

     *

     * @since S60 ?S60_version

     * @param aWidgetName The name of the widget.

     * @return New object. The widgets are owned by Alfred.

     */

    OSN_IMPORT CAlfWidgetControl* control() const;

    /**

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

     *

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

     */

    OSN_IMPORT IAlfContainerWidget* parent() const;

    /**

     * Sets new widget control to this widget.

     * @exception osncore::AlfException Thrown with error code osncore::EInvalidArgument if aControl is  

     *                                  alreasy associated with another widget.      

     * @see IAlfWidget::setControl()

     *

     * @since S60 ?S60_version

     * @param aControl Control to be set to the widget.

     * @param aDeletePreviousControl If true, the previous widget control is destroyed. 

     */

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

    /**

     * Constructor. The new widget is left on the cleanup stack.

     *

     * @since S60 ?S60_version

     * @param aWidgetName The name of the widget.

     * @return New object. The widgets are owned by Alfred.

     */

    OSN_IMPORT IAlfModel* model();

    /**

     * Sets the model for the Widget.

     *

     * @since S60 ?S60_version

     * @param aModel Model to be set to this widget.

     * @param aTakeOwnership Whether takes ownership or not.

     */

    OSN_IMPORT void setModel( IAlfModel* aModel,bool aTakeOwnerShip=true );

    /**

     * Constructor. The new widget is left on the cleanup stack.

     *

     * @since S60 ?S60_version

     * @param aWidgetName The name of the widget.

     * @return New object. The widgets are owned by Alfred.

     */

    OSN_IMPORT const char* widgetName() const;

    //From IAlfInterfaceBase

    /**

     * Getter for interfaces provided by the widget, the control,

     * or the model.

     *

     * @since S60 ?S60_version

     * @param aWidget   The widget to get the interface for.

     * @param aType     The type id of the queried interface.

     * @return The queried interface, or NULL if the interface is not

     *         supported or available.

     */

    OSN_IMPORT static IAlfInterfaceBase* makeInterface( AlfWidget* aWidget, const IfId& aType );

    /**

     * Template getter for interfaces provided by the widget, the control,

     * or the model. The type of the queried interface is specified by the

     * template parameter.

     *

     * @since S60 ?S60_version

     * @param aWidget The widget to get the interface for.

     * @return The queried interface, or NULL if the interface is not

     *         supported or available.

     */

    template <class T>

    static T* makeInterface( AlfWidget* aWidget );

    // from base class IAlfInterfaceBase

    /**

     * From IAlfInterfaceBase.

     * Getter for interfaces provided by the widget classes.

     * Derived classes should always call the base class method

     * from the overridden MakeInterface.

     *

     * @since S60 ?S60_version

     * @param aType A descriptor to identify the type of the queried interface.

     * @return The queried interface, or NULL if the interface is not

     *         supported or available.

     */

    OSN_IMPORT virtual IAlfInterfaceBase* makeInterface( const IfId& aType );

    // from base class IAlfContainerWidget

    /**

     * Returns total number of widgets contained by this container.

     *

     * @return int Total number of widgets.

     */

    OSN_IMPORT int widgetCount() const;

    /**

     * Adds a child widget to the container.

     *

     * @param  aWidget Child widget to be added to container.

     * return void

     */

    OSN_IMPORT void addWidget(IAlfWidget& aWidget);

    /**

     * Returns child widget at given index.If index is not found return null.

     *

     * @param  aIndex Index of widget to be returned.

     * @return Widget at given index

     */

    OSN_IMPORT IAlfWidget* getWidget(int aIndex) const;

    /**

     * Returns the child index, when given the child widget.

     *

     * @param  aWidget child widget, which index is returned 

     * @return the index of the child widget, or -1, if widget is not child of this container.

     */

    OSN_IMPORT int getWidgetIndex(IAlfWidget& aWidget) const;

    /**

     * Removes the child widget from given index.

     *

     * @param aIndex Index from which widget has to be removed.

     * return void

     */

    void removeWidget(int aIndex);

    /**

     * Sets the base layout of container widget.

     *

     * @param aLayout New base layout of container widget.

     * return void

     */

    OSN_IMPORT void applyLayout(IAlfLayoutManager& aLayout);

    //from IAlfWidget

    /**

     * 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

     */

    OSN_IMPORT void setChildFocus(bool aFocus);

    /**

     * Removes the given widget from this widget's child widget

     * array. Does not modify control connections or control

     * group containment.

     *

     * Does nothing if the given widget is not found from

     * widget array.

     *

     * @param aWidget Reference to a widget that is searched

     *                from the widget array of this widget and removed

     *                of found.

     */    

    OSN_IMPORT void removeWidget(IAlfWidget& aWidget);

    /** 

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

     */

    OSN_IMPORT void setPresentation(const char* aFilePath);

protected:

    /**

     * The protected constructor.

     *

     * @since S60 ?S60_version

     */

    OSN_IMPORT AlfWidget();

private:

    /**

     * Adds the Common Properties for the widget

     *

     * @since S60 ?S60_version

     */

    void addCommonWidgetProperties();

    /**

     * Removes reference from this widget's control to this

     * widget.

     */

    void removeReferenceFromControl();

private: // data

    auto_ptr<AlfWidgetImpl> mImpl;

    };

using namespace osncore;

#include "alf/alfwidget.inl"

    } // namespace Alf

#endif // ALFWIDGET_H

// End of File