mulwidgets/alfviewwidget/inc/alfviewwidget.h
author Simon Howkins <simonh@symbian.org>
Tue, 16 Nov 2010 11:09:56 +0000
branchRCL_3
changeset 33 2d34f54f7334
parent 0 e83bab7cf002
permissions -rw-r--r--
Fixed path to IBY files to be exported

/*
* 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.
     * This is used to restore focus to the correct child when the view
     * is shown and to remember the focused child when the view  is hidden.
     */
    std::string mFocusedChildWidgetID;
    
    TRect mDisplayRect;
    
    /**
     * Stores the naame of all the children widgets
     */
    AlfPtrVector<UString> mChildWidgetName;
    
    /**
     * Flag to indicate whether AcquireFocus() has been called on one
     * of the controls.
     */
    TBool mHasFocus;
    };

    }

#endif /*ALFVIEWWIDGET_H*/