/*

* 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:  Widget interface with utilities for container widget.

*

*/

#ifndef ALFCONTAINERWIDGET_H

#define ALFCONTAINERWIDGET_H

#include "alf/ialfcontainerwidget.h"

#include <alf/alflayout.h>

// Forward declarations

class CAlfEnv;

namespace Alf

{

// Forward declarations

class AlfWidget;

/**

 * Container widget implementation.

 * 

 * Container widget can be used to contain other widgets in an arbitrary layout.

 * To create a container widget see CAlfContainerWidgetFactoryPlugin class.

 * 

 * Container widget creates a control group with ID 0 and stores it's control

 * in it. It will also append all added widget controls into the same control group

 * unless the added widget control is added to its own control group.

 */

class AlfContainerWidget : public IAlfContainerWidget

{

public:

    /**

     * Default constructor.

     * 

     * Use CAlfContainerWidgetFactoryPlugin::CreateProduct() to instantiate a container

     * widget.

     * 

     * @param aWidgetName The widget name or ID to be assigned to this widget.

     * @param aContainer Container widget in which this container is contained. 

     * @param aEnv UI Accelerator Environment instance to which the widget is created. 

     * @param aNode Runtime declaration of the widget 

     * @param aFilePath Path to XML file describing the presentation of the widget 

     */

	AlfContainerWidget(	const char* aWidgetName, 

						IAlfContainerWidget& aContainer, 

						CAlfEnv& aEnv,

						DuiNode* aNode,

						const char* aFilePath);

    /**

     * Default destructor.

     */

	virtual ~AlfContainerWidget();

    // From Alf::IAlfWidget base class

    /**

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

     *

     * @since S60 5.0

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

     */

    virtual CAlfWidgetControl* control() const;

    /**

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

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

     */

    virtual IAlfContainerWidget* parent() const;

    /**

     * Setter for the control. The control is owned by the Alfred environment.

     * The previously set control can be destroyed when new control is set.

     * 

     * The set control is added to the control group of this container widget.

     * The set control is removed from it's previous control group.

     *

     * @since S60 5.0

     * @param aControl The control for this widget.

     * @param aDeletePreviousControl A boolean to indicate whether the previously set control

     * 								 is to be destroyed when this method is called.

     */

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

    /**

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

     *

     * @since S60 5.0

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

     */

    virtual IAlfModel* model();

    /**

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

     *

     * @since S60 5.0

     * @param aModel The model for this widget.

     * @param aTakeOwnership Whether takes ownership of model or not

     */

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

    /**

     * Get the name of the widget instance.

     *

     * @since S60 5.0

     * @return Widget name

     */

    virtual const char* widgetName() const;   

    /**

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

     * Does not set the actual focused status in roster.

     *

     * @since S60 5.0

     * @param aFocus boolean value for focused status

     */

    virtual void setChildFocus(bool aFocus);    

    /** 

     * 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);      

    // From Alf::IAlfContainerWidget base class

    /**

     * Returns total number of widgets contained by this container.

     *

     * @return int Total number of widgets.

     */

    virtual int widgetCount() const;

    /**

     * Adds a child widget to the container.

     * 

     * Ownership of the widget is transferred to this container

     * object.

     * 

     * The control of the added widget is appended to the control group of

     * this container widget unless the control already is appended to

     * another control group.

     *

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

     */

    virtual void addWidget(IAlfWidget& aWidget);

    /**

     * Returns child widget at given index.

     * 

     * If index is not found returns null.

     *

     * @param  aIndex Index of widget to be returned.

     * @return Widget at given index or null if not found.

     */

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

     */

    virtual int getWidgetIndex(IAlfWidget& aWidget) const;

    /**

     * Removes the child widget from given index.

     * 

     * This will destroy the widget object at the given index.

     *

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

     */

    virtual void removeWidget(int aIndex);

    /**

     * Sets the base layout of container widget.

     *

     * @param aLayout New base layout of container widegt.

     */

    virtual void applyLayout(IAlfLayoutManager& aLayout);

    // From Alf::IAlfInterfaceBase base class

    /**

     * Interface getter.

     * Derived classes should always call the base class method

     * from the overridden MakeInterface.

     *

     * @since S60 5.0

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

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

     *         supported or available.

     */

    virtual IAlfInterfaceBase* makeInterface(const IfId& aType);

private:

	/**

	 * Constructs widget from declaration.

	 *

	 * @param aNode declaration node.

	 */

	void constructComponentsFromNode();

	/**

	 * Constructs widget from declaration.

	 *

	 * @param aNode declaration node.

	 */

	void processTreeRecursively();

	/**

	 * Constructs widget using the presentation XML.

	 *

	 * @param aFilePath Path to XML file describing the presentation of the widget.

	 */

	void constructFromPresentationXML(const char *aFilePath);

	/**

	 * Constructs control for widget

	 *

	 */

	void constructDefault();

	/**

     * Sets default layout mgr.

     */

    void setDefaultLayoutManager();

private:

	/** Pointer to the adaptee AlfWidget - object. */

	auto_ptr<AlfWidget> mWidget;

	/**

	 * UI Accelerator Environment where this widget is used.

	 * Not owned.

	 */

	CAlfEnv& mEnv;

};

}

#endif /*ALFCONTAINERWIDGET_H*/