/*

* 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 interface and the basic implementation for presentation elements.

*

*/

#ifndef ALFELEMENT_H

#define ALFELEMENT_H

#include <osn/osndefines.h>

#include <memory>

#include <alf/ialfelement.h>

#include <osn/alfptrvector.h>

using osncore::AlfPtrVector;

using std::auto_ptr;

class CAlfVisual;

class CAlfLayout;

namespace Alf

    {

class CAlfWidgetControl;

class IAlfVariantType;

class AlfReferenceToVisual;

class IAlfVisualTemplate;

class AlfElementImpl;

class IfId;

/** @class AlfElement alfelement.h "alf/alfelement.h"

 *  The implementation of a generic element. Elements can be used,

 *  e.g., from declaration, to describe a specific part of

 *  the presentation of a component. The presentation may

 *  be predefined, or it may depend on the component data.

 *

 *  @lib alfwidgetmodel.lib

 *  @since S60 ?S60_version

 *  @status Draft

 *  @interfaces IAlfAttributeOwner, IAlfElement

 *	@attributes duiuimodel::tactileattributes::KEventInput\n

 *				duiuimodel::tactileattributes::KFeedbackType\n

 *				duiuimodel::commonvisualattributes::KOpacity\n

 *				duiuimodel::layoutattributes::KPositionX\n

 *				duiuimodel::layoutattributes::KPositionY\n

 *				duiuimodel::layoutattributes::KWidth\n

 *				duiuimodel::layoutattributes::KHeight\n

 *				duiuimodel::layoutattributes::KMaxWidth\n

 *				duiuimodel::layoutattributes::KMaxHeight\n

 *				duiuimodel::layoutattributes::KMinWidth\n

 *				duiuimodel::layoutattributes::KMinHeight

 */

class AlfElement : public IAlfElement

    {

public:

    /**

     * Static cnstructor. The new element is left on the cleanup stack.

     *

     * @since S60 ?S60_version

     * @param aControl  The owner control.

     * @param aName     The name of the element.

     * @return New object. Should be added to the control.

     */

    OSN_IMPORT AlfElement(CAlfWidgetControl& aControl, const char* aName);

    /**

     * Destructor.

     */

    OSN_IMPORT virtual ~AlfElement();

    /**

     * Returns name of element set via Constructor.

     *

     * @since S60 ?S60_version

     * @return name of element.

     */

    OSN_IMPORT const char* name() const;

    /**

     * Creates a visual tree in given element.

     *

     * @since S60 ?S60_version

     * @param aElement Element for which visual tree will be created

     * @param aChildData Data for visual tree to be created

     * @param aData Data for parent visual tree

     * @param aIndex Position in parent layout at which new visual tree will be added

     * @param aDataID Parent visual tree's data id

     */

    OSN_IMPORT virtual void createChildVisualTree( IAlfElement* aElement,

                                                  IAlfVariantType& aChildData,

                                                  IAlfBranch& aData,

                                                  int aIndex, uint aDataID );

    /**

     * Creates a visual tree with the data given for visuals.

     *

     * @exception osncore::AlfElementException Thrown with the error code osncore::EInvalidElement\n 

     *										  when creation of visual tree fails.

     * @since S60 ?S60_version

     * @param aChildData Data for visual tree to be created

     * @param aParentData Data for parent visual tree

     * @param aIndex Position in parent layout at which new visual tree will be added

     * @param aParentDataID Parent visual tree's data id

     * @param aParentLayout Parent layout to which newly created visual tree will be added

     * @param aLayoutIndex Position in parent layout at which new visual tree will be added

     */

    OSN_IMPORT virtual CAlfVisual* createVisualTree(

        IAlfVariantType& aChildData, IAlfBranch& aParentData, int aIndex,

        uint aParentDataID, CAlfLayout* aParentLayout, int aLayoutIndex );

    /**

     * Creates a visual tree with the data given for visuals.

     *

     * @exception std::bad_alloc 

     * @exception osncore::AlfVisualException Thrown with the error code osncore::ECanNotCreateVisual\n 

     *										  when creation of visual fails.

     * @exception osncore::AlfVisualException Thrown with the error code osncore::EInvalidElement\n 

     *										  when wrond data id is supplied.

	 * @exception std::bad_alloc     

     * @since S60 ?S60_version

     * @param aData Data for visual tree to be created

     * @param aDataID Parent visual tree's data id

     * @param aParentLayout Parent layout to which newly created visual tree will be added

     * @param aLayoutIndex Position in parent layout at which new visual tree will be added

     */

    OSN_IMPORT virtual CAlfVisual* createVisualTree(

        IAlfVariantType& aData, uint aDataID,

        CAlfLayout* aParentLayout, int aLayoutIndex );

    /**

     * Removes visual tree from given element.

     *

     * @since S60 ?S60_version

     * @param aElement Element from which visual tree is to be removed

     * @param aData

     * @param aIndex 

     * @param aDataID 

     */

    OSN_IMPORT virtual void removeChildVisualTree( IAlfElement* aElement,

                                                  IAlfBranch& aData,

                                                  int aIndex, uint aDataID );

    /**

     * Removes visual tree.

     *

     * @exception osncore::AlfVisualException Thrown with the error code osncore::EInvalidElement\n 

     *										  when removal of visual tree fails.

     * @since S60 ?S60_version

     * @param aParentData

     * @param aIndex 

     * @param aParentDataID 

     */

    OSN_IMPORT virtual void removeVisualTree( IAlfBranch& aParentData,

                                             int aIndex, uint aParentDataID );

    /**

     * Removes visual tree.

     *

     * @exception osncore::AlfVisualException Thrown with the error code osncore::EInvalidElement\n 

     *										  when removal of visual tree fails.

     * @since S60 ?S60_version

     * @param aData

     * @param aDataID 

     */

    OSN_IMPORT virtual void removeVisualTree( IAlfVariantType& aData,

                                             uint aDataID );

    /**

     * Updates the visual tree.

     *

     * @exception osncore::AlfVisualException Thrown with the error code osncore::EInvalidElement\n 

     *										  when a visual can not be created.

     * @since S60 ?S60_version

     * @param aNewData

     * @param aOldData 

     * @param aDataID 

     */

    OSN_IMPORT virtual void updateVisualTree( IAlfVariantType& aNewData,

                                                  IAlfVariantType& aOldData,

                                             uint aDataID );

    /**

     * Replaces the visual tree.

     *

     * @exception osncore::AlfVisualException Thrown with the error code osncore::EInvalidElement\n 

     *										  when old data id is wrong.

     * @since S60 ?S60_version

     * @param aData

     * @param aDataID 

     * @param aOldDataID 

     */

    OSN_IMPORT void replaceVisualTree( IAlfVariantType& aData, 

                                       uint aDataID, uint aOldDataID );

    /**

     * Add a new visual tree to the element.

     * Used by derived classes.

     *

     * @exception osncore::AlfVisualException Thrown with the error code osncore::EInvalidElement\n 

     *										  when either the visual is NULL or data id is wrong.

     * @exception std::bad_alloc 

     * @since S60 ?S60_version

     * @param aVisualTree visual to be appended.

     * @param aDataID   data id of the visual.

     */

    OSN_IMPORT void addVisualTree(CAlfVisual* aVisualTree, uint aDataID);

    /**

     * Updates the Data ids in an the element.

     *

     * @since S60 ?S60_version

     * @param aParentBranch Data in which IDs to be updated

     * @param aStartIndex Index from which IDs to be updated

     * @param aOffset Amount by which IDs are increased/decreased

     * @param aOldParentDataId Not used.

     * @param aParentDataID Parent data id of the element

     */

    OSN_IMPORT void updateDataIDs( IAlfBranch& aParentBranch, int aStartIndex,

                                 int aOffset, uint aOldParentDataId, uint aParentDataID );

    /**

     * Returns the default parent layout of visual tree in an element.

     *

     * @exception osncore::AlfVisualException Thrown with the error code osncore::EInvalidVisual\n 

     *										  when wrong data id is supplied.

     * @since S60 ?S60_version

     * @param aParentDataIS

     * @return Parent layout

     */

    OSN_IMPORT CAlfLayout* defaultParentLayout(uint aParentDataID);

    /**

     * Set reference to the default parent layout.

     *

     * @since S60 ?S60_version

     * @param aReference The reference to the default parent layout.

     */

    OSN_IMPORT void setDefaultParentLayout(AlfReferenceToVisual* aReference);

    /**

     * Finds visual with the given name and id in visual tree of element.

     *

     * @since S60 ?S60_version

     * @param aName Name of the visual

     * @param aDataID Data id of the visual

     * @return Visual.Returns NULL if no matching visual is found.

     */

    OSN_IMPORT CAlfVisual* findVisual(const char* aName, uint aDataID);

    /**

     * Get visual from the data id.

     *

     * @since S60 ?S60_version

     * @param aDataID data id of the visual.

     */

    OSN_IMPORT CAlfVisual* findVisual(uint aDataID);

    /**

     * Returns the data id of given visual.

     *

     * @since S60 ?S60_version

     * @param aVisual Reference to visual whose data id is needed.

     * @return Data id of the visual

     */

    OSN_IMPORT uint dataID(const CAlfVisual& aVisual) const;

    /**

     * Returns parent element of the element.

     *

     * @since S60 ?S60_version

     * @return Parent element. NULL, if there is no parent element.

     */

    OSN_IMPORT const IAlfElement* parentElement() const;

    /**

     * Makes the element child of given element.

     *

     * @since S60 ?S60_version

     * @param aParent Parent element.

     */

    OSN_IMPORT void setParentElement(IAlfElement& aParent);

    /**

     * Sets the visual template for the element. This element

     * will acquire ownership of the visual template hierarchy

     * under the given visual template.

     * Call to this method cannot throw an exception.

     *

     * @since S60 ?S60_version

     * @param aTemplate Root of the visual template hierarchy to be set

     *                  into the widget element.

     */

    OSN_IMPORT void setVisualTemplate(IAlfVisualTemplate& aTemplate) throw();

    /**

     * Returns the root visual template of the visual template hierarchy

     * owned by this element. Call to this method cannot throw an exception.

     *

     * @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 IAlfVisualTemplate* getVisualTemplate() const throw();

    /**

     * Destroyes the visual template object assigned to this element and the whole

     * visual template hierarchy under it.

     *

     * @since S60 ?S60_version

     */

    OSN_IMPORT void destroyVisualTemplate() throw();

     /**

     * Removes the visual template from this element. Returns pointer to the removed visual

     * template object. The ownership of the visual template object is transferred to the

     * caller. Call to this method cannot throw an exception.

     *

     * @since S60 ?S60_version

     */

    OSN_IMPORT IAlfVisualTemplate* removeVisualTemplate() throw();

    /**

     * Getter for the type identifier of this class.

     *

     * @since S60 ?S60_version

     * @return A descriptor to identify the type of this class.

     */

    /**

     * Template getter for interfaces provided by the element classes.

     * The type of the queried interface is specified by the

     * template parameter.

     *

     * @since S60 ?S60_version

     * @param aElement The element 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( AlfElement* aElement );

// from base class IAlfInterfaceBase

    /**

     * From IAlfInterfaceBase.

     * Getter for interfaces provided by the element 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 );

    /**

     * removes and destroys all the visuals in the element.

     *

     * @since S60 ?S60_version

     * @param aTimeMilliseconds the animation time for remove.

     */    

    OSN_IMPORT void removeAndDestroyVisuals( int aTimeMilliseconds );

    /**

     * from IAlfElement

     */

    OSN_IMPORT bool contains(CAlfVisual& aVisual) const;

protected:

    /**

     * The protected constructor.

     *

     * @since S60 ?S60_version

     */

    OSN_IMPORT AlfElement();

    /**

     * The second phase constructor.

     * The element is added to the control.

     *

	 * @exception std::bad_alloc     

     * @since S60 ?S60_version

     * @param aControl  The owner control.

     * @param aName     The name of the element.

     */

    OSN_IMPORT void construct( CAlfWidgetControl& aControl, const char* aName );

    /**

     * APi to get the control containing the element.

     *

     * @since S60 ?S60_version

     */

    OSN_IMPORT CAlfWidgetControl& control();

private:

    int findFromArray( uint aDataID ) const;

private: // data

    auto_ptr<AlfElementImpl> mData;

    };

#include "alf/alfelement.inl"

    } // namespace Alf

#endif // ALFELEMENT_H