diff -r 4ea6f81c838a -r 0e9bb658ef58 inc/alf/alfelement.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/inc/alf/alfelement.h Wed Sep 01 12:23:18 2010 +0100 @@ -0,0 +1,423 @@ +/* +* 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 +#include +#include +#include + +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 + 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 mData; + }; + +#include "alf/alfelement.inl" + + } // namespace Alf +#endif // ALFELEMENT_H