/*

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

*

*/

#ifndef ALFVIEWWIDGET_H

#define ALFVIEWWIDGET_H

#include "alf/alfwidget.h"

#include <alf/ialfviewwidget.h>

#include <AknsItemID.h>

#include <alf/alfeventhandler.h>

#include <alf/alfenv.h>

#include <osn/ustring.h>

#include <osn/alfptrvector.h>

// Forward declarations

class CAlfControlGroup;

namespace dui

    {

    class DuiNode;

    }

namespace Alf

{

class AlfWidget;

class AlfViewWidgetZOrderChangedObserver;

/**

 * View widget implementation.

 *

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

 *

 * View widget creates a control group with ID passed in its constructor and

 * stores it's control in it.

 */

class AlfViewWidget : public IAlfViewWidget, public MAlfActionObserver,MAlfEventHandler

{

public:

    /**

     * Default constructor.

     * 

     * Use AlfViewWidgetFactoryPlugin::CreateProduct() to instantiate a view

     * widget. View widget will create a new control group from the ID passed to this

     * constructor and append the view control into the control group.

     *

     * @exception AlfException Error code EInvalidArgument is thrown if a control group already

     *            exists with the given ID.

     * @exception AlfViewWidgetException with Symbian Error code if the view 

     *            is unable to register itself as an action observer in the 

     *            Alfred Environment.

     * 

     * @param aWidgetName Name of the constructed view widget.

     * @param aControlGroupId ID of the control group to append the view widget control into.     

     * @param aEnv UI Accelerator Toolkit environment in which this widget is defined.

     * @param aDisplay Display in which this widget is defined.

     */

	AlfViewWidget(const char* aWidgetName, int aControlGroupId, CAlfEnv& aEnv, 

            CAlfDisplay& aDisplay, DuiNode* aNode=NULL, const char *aFilePath=NULL);

    /**

     * Default destructor.

     */

    virtual ~AlfViewWidget();

    // 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 view 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 view.

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

    // From Alf::IAlfContainerWidget base class

    /**

     * Returns total number of widgets contained by this view.

     *

     * @return int Total number of widgets.

     */

    virtual int widgetCount() const;

    /**

     * Adds a child widget to the view.

     *

     * Ownership of the widget is transferred to this view

     * object.

     *

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

     */

    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 view widget.

     *

     * @param aLayout New base layout of view widegt.

     */

    virtual void applyLayout(IAlfLayoutManager& aLayout);

    /** 

     * 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 IAlfViewWidget*/

    //--------------------------------------------------------------------------------------//

	/**

	 * API to show the view widget.

	 * @param aShow	true if the view is to be shown, else false

	 *				The view is not shown, till this api is called 

	 *              with true parameter.    

	 * @since S60 ?S60_version

	 */

	virtual void show(bool aShow = true);

    /**

     * API to make the view widget accept events.

     *

     * @param aAccept true if the view is to accept inputs, else false

     *     default value is true

     * @since S60 ?S60_version

     */

    virtual void acceptEvents(bool aAccept = true);

    /**

     * API to hide/show Avkon status pane.

     * If the AlfDisplay bound to the view widget does not occupy the 

     * entire client rectangle, this API has no effect. 

     *

     * @param aEnable true to enable the status pane, else false

     *        the default value is true.

     * @since S60 ?S60_version

     */

    virtual void enableStatusPane(bool aEnable = true);

    /**

     * API to hide/show Avkon control pane

     * If the AlfDisplay bound to the view widget does not occupy the 

     * entire client rectangle, this API has no effect.

     *

     * @param aEnable true to enable the control pane, else false

     *     the default value is true.

     * @since S60 ?S60_version

     */

    virtual void enableControlPane(bool aEnable = true);

    /**

     * API to enable/disable Avkon Skin to be used as view widget's background.

     *

     * @param aSkinBackground true if the view has to use Avkon Skin as background.

     *                        false otherwise.

     * @since S60 ?S60_version

     */

    virtual void useSkinBackground(bool aSkinBackground = true);

    /**

     * API to use Skin with the given ID to be used as view widget's background.

     * Also enables skin background. See IAlfViewWidget::useSkinBackground()

     *

     * @param aID Skin id of the graphics to be used in the texture.

     *

     * @since S60 ?S60_version

     */

    virtual void setSkinBackground(TAknsItemID aSkinID);

    /**

     * API to check whether the view is shown

     *

     * @return true if the view is shown, else false

     *

     * @since S60 ?S60_version

     */

    virtual bool shown();

    /**

     * Returns the position of the view on the view stack.

     * This tells the view Z-coordinate position relative to other views.

     * Top-most view returns zero. Views under that have a growing

     * number of position. If the view is hidden -1 is returned.

     * Only view widgets are taken into consideration in the position calculation.

     * Other control groups in the display roster are ignored. For example,

     * position zero doesn't mean that the control group of this view would be

     * top-most.

     *

     * Only top-most view is activate while all other views are being deactivate.

     * 

     * @return Position of the view, -1 if view is hidden.

     */

    virtual int getViewStackPosition() const;

    /**

     * API to check whether the view accepts events

     *

     * @return true if the view accepts events, else false

     *

     * @since S60 ?S60_version

     */

    virtual bool eventsAccepted();

    /**

     * API to check whether the status pane is enabled

     *

     * @return true if the status pane is enabled, else false

     *

     * @since S60 ?S60_version

     */

    virtual bool statusPaneEnabled();

    /**

     * API to check whether the control pane is enabled

     *

     * @return true if the control pane is enabled, else false

     *

     * @since S60 ?S60_version

     */

    virtual bool controlPaneEnabled();

	/**

	 * API to check whether skin info is being used for background

	 * or not

	 *

	 * @return true if the skin info is being used, else false 

	 *

	 * @since S60 ?S60_version

	 */

	virtual bool usingSkinBackground();

	/**

     * API to get the Avkon Skin ID being used as view widget's background.

     * Use IAlfViewWidget::usingSkinBackground() to check if this is 

     * being used.       

     * 

     * @return Avkon Skin ID being used for view's background.

     *         Returns an ID with major and minor fields=-1 if 

     *         this info was never set. 

     *         See IAlfViewWidget::setSkinBackground()

     *

     * @since S60 ?S60_version

	 */

	virtual TAknsItemID skinBackground();

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

    // New methods

    /**

     * Called to notify the view of view activation (view becoming top most in

     * z-order) or deactivation. The view can be deactivated multiple times

     * in a row without being reactivated.

     *

     * This method is called internally by the view widget itself.

     * 

     * @see getViewStackPosition()

     * 

     * @param aIsActivated Indicates whether view widget is activated or not

     */

    void notifyViewActivated(bool aIsActivated);

    //From MAlfActionObserver

    /**

     * @see MAlfActionObserver

     */ 

    void HandleActionL(const TAlfActionCommand& aActionCommand);

    /**

     * API to Set the display area of the view widget.

     * This will set the alfdisplay area with param passed

     * Client need to call this api with screen/apprect to make 

     * view full screen or application rect

     *

     * @param aDisplayRect: the area in which view widget should be

     *                      displayed

     *

     * @since S60 ?S60_version

     */

    void setRect(const TRect& aDisplayRect);

   /**

    * Updates the array which contains the name of all the children widgets

    * 

    * @param aChildName the name of a child widget

    */ 

    void setChildNameToDelete( UString aChildName );

private:

    /**

     * Constructs widget from declaration.

     *

     * @param aEnv The environment for the widget.

     * @param aNode declaration node.

     */

    void constructComponentsFromNode(CAlfEnv& aEnv);

    /**

     * Constructs widget using the presentation XML.

     *

     * @param aEnv The environment for the widget.

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

     */

    void constructFromPresentationXML(CAlfEnv& aEnv, const char *aFilePath);

    /**

     * Constructs default widget

     *

     * @param aEnv The environment for the widget.

     */

    void constructDefault(CAlfEnv& aEnv, bool aCreateLM = true);

    /**

     * Sets default layout mgr.

     */

    void setDefaultLayoutManager();

    /**

     * Utility function

     */

    void updateBackGroundImage();

    /**

     * Updates the status pane according to the view settings.

     */

    void updateStatusPane();

    /**

     * Updates the control pane according to the view settings.

     */

    void updateControlPane();

    /**

     * Finds the focused control of this view.

     */

    CAlfControl* focusedControl();

    /**

     * from MAlfEventHandler

     */

    TBool OfferEventL(const TAlfEvent& aEvent);

private:

    /**

     * AlfWidget instance, owned.

     */

    auto_ptr<AlfWidget> mWidget;

    /**

     * UI Accelerator Environment where this widget is used.

     * Not owned.

     */

    CAlfEnv* mEnv;

    /**

     * Display to be associated with the view.

     * Not owned.

     */

    CAlfDisplay* mDisplay;

    /**

	 * Control group to contain the view widget control in.

	 * Not owned.

	 */

	CAlfControlGroup* mControlGroup;

	/**

	 * Control group order changed observer object used to activate

	 * this view when necessary.

	 * Owned.

	 */

	auto_ptr<AlfViewWidgetZOrderChangedObserver> mZOrderChangedObserver;

    /**

	 * Control group resource ID.

	 */

	TInt mControlGroupResourceId;

    /**

     * Flag to indicate if the view is being shown or not.

     */

    bool mShown;

    /**

     * Flag to indicate if the Avkon Control Pane is shown or not.

     */

    bool mControlPaneEnabled;

    /**

     * Flag to indicate if the Avkon Status Pane is shown or not.

     */

    bool mStatusPaneEnabled;

    /**

     * Flag to indicate if the view uses skin background or not.

     */

    bool mSkinEnabled;

    /**

     * ID for skin related information to be used for background.

     */

    TAknsItemID mSkinId;   

    /**

     * Cache for ID of the child widget that is currently focused.