diff -r 4526337fb576 -r 3eca7e70b1b8 inc/alf/alfelement.h --- a/inc/alf/alfelement.h Tue Feb 02 00:28:09 2010 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,423 +0,0 @@ -/* -* 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