diff -r 000000000000 -r e83bab7cf002 inc/alf/alfvisualtemplate.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/inc/alf/alfvisualtemplate.h Thu Dec 17 08:56:02 2009 +0200 @@ -0,0 +1,651 @@ +/* +* 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: Visual template class for alfred widget model. +* This class creates and updates visual tree. +* +*/ + + +#ifndef ALF_VISUALTEMPLATE_H +#define ALF_VISUALTEMPLATE_H + +#include +#include +#include "alf/ialfvisualtemplate.h" +#include +#include +#include +#include + +class CAlfControl; +class CAlfBrush; +class CAlfVisual; + +using namespace osncore; + +namespace Alf + { +// FORWARD DECLARATIONS +class IAlfMap; +class IAlfAttributeSetter; +class AlfAttributeContainer; + +/** + * @class AlfVisualTemplate alfvisualtemplate.h "alf/alfvisualtemplate.h" + * A generic visual template for creating or updating a visual tree. + * The visual templates may form a tree structure that matches + * the visual tree to be created or updated. Each template is + * responsible for creating and initializing a single visual. + * Visual templates contain a number of attribute setters + * to initialize or update the visuals. Attribute setters use values + * from the corresponding attribute containers. + * + * @lib alfwidgetmodel.lib + * @since S60 ?S60_version + * @status Draft + * @interfaces IAlfVisualTemplate + */ +class AlfVisualTemplate : public IAlfVisualTemplate + { +public: + + /** + * Constructor for a template for creating a visual. + * @exception std::bad_alloc + * + * @since S60 ?S60_version + * + * @param aType The type of the visual to create. + */ + OSN_IMPORT static AlfVisualTemplate* create(TAlfVisualType aType); + + /** + * Constructor for a template for creating a layout. + * @exception std::bad_alloc + * + * @since S60 ?S60_version + * + * @param aType The type of the layout to create. + */ + OSN_IMPORT static AlfVisualTemplate* create(TAlfLayoutType aType); + + /** + * Constructor for an empty template. + * @exception std::bad_alloc + * + * @since S60 ?S60_version + * + */ + OSN_IMPORT static AlfVisualTemplate* create(); + + // Destructor. + OSN_IMPORT virtual ~AlfVisualTemplate(); + + //From IAlfVisualTemplate + + /** + * Sets the owner element. User should not call this method directly. It will + * be called implicitly by Alf::IAlfElement::setVisualTemplate() method. + * Call to this method cannot throw an exception. + * + * @see Alf::IAlfElement::setVisualTemplate() + * + * @since S60 ?S60_version + * + * @param aOwner Element that owns this root visual template. + */ + OSN_IMPORT void setOwner(IAlfElement* aElement) throw(); + + /** + * Returns the owner element. Call to this method cannot + * throw an exception. + * + * @see Alf::IAlfElement::setVisualTemplate() + * + * @since S60 ?S60_version + * + * @return The owner element of a visual template, if this visual template is owned + * by an element. NULL if visual template is not owned by an element. + */ + OSN_IMPORT IAlfElement* owner() const throw(); + + /** + * Set name of the visual. This name is used when creating + * concrete visual trees. Name is assigned to each of the produced concrete + * visuals as a tag. Note thus that all concrete visual + * trees produced from this visual template share the same tag. + * + * @see name() + * + * @exception std::bad_alloc thrown if heap memory allocation fails. + * + * @since S60 ?S60_version + * + * @param aName The name of the visual. + */ + OSN_IMPORT void setName(const char* aName); + + /** + * Returns the name of the visual. Call to this method + * cannot throw an exception. + * + * @see setName() + * + * @since S60 ?S60_version + * + * @return aName The name of the visual. + */ + OSN_IMPORT const char* name() const throw(); + + /** + * Get the number of child visual templates. + * This returns the number of child visual templates directly + * under this visual template in the visual template + * hierarchy. Call to this method cannot throw an exception. + * + * @since S60 ?S60_version + * + * @return The number of direct child visual templates + * under this visual template in the visual template hierarchy. + */ + OSN_IMPORT int numChildTemplates() const throw(); + + /** + * Returns a child visual template at a given index. + * + * @exception osncore::AlfException thrown with error code osncore::EInvalidArrayIndex if + * the index is out of bounds. + * + * @since S60 ?S60_version + * + * @param aIndex The index of the child visual template. + * + * @return Reference to the child visual template object. + */ + OSN_IMPORT IAlfVisualTemplate& childTemplate(int aIndex) const; + + /** + * Add a child visual template. The visual templates may form + * a tree structure to create and update a visual tree. The visuals + * created by children are added to the layout created by this + * visual template. This visual template acquires the ownership for the + * child visual template passed as an argument. + * + * If a visual template added as a child to this visual template is owned + * by an Alf::IAlfElement the connection between the child visual template + * and its owner element is implicitly removed in this call when a + * parent-child connection is created. Effectively having a parent visual + * template or being owned by an element are mutually exclusive properties + * for a visual template. Elements can own only root visual templates and + * if an owned root visual template becomes a child of another visual + * template the visual template will be removed from the associated owner + * element. + * + * @see insertChildTemplate() + * + * @exception std::bad_alloc Thrown if memory allocation fails in appending the child + * visual template to child array of this visual template. + * @exception osncore::AlfException thrown with error code osncore::EInvalidHierarchy if + * the call to this method would result in an invalid visual template hierarchy. + * This can occur if a child is added to a non-layout visual template or if a + * call would result in a parent becoming a descendant of it's child (a recursive + * tree). + * + * @since S60 ?S60_version + * + * @param aChild Child visual template to be appended to the children of this visual template. + */ + OSN_IMPORT void addChildTemplate(IAlfVisualTemplate& aChild); + + /** + * Inserts a child visual template at given index. The visual templates may form + * a tree structure to create and update a concrete visual tree. The concrete visuals + * created by children are added to the layout created by this + * visual template. This visual template acquires the ownership of the inserted + * child visual template. + * + * @see addChildTemplate() + * + * @exception std::bad_alloc thrown if memory allocation fails in inserting the child visual + * template to the child list of this visual template. + * @exception osncore::AlfException thrown with error code osncore::EInvalidArrayIndex when + * index supplied is out of range for array of visual templates. + * @exception osncore::AlfException thrown with error code osncore::EInvalidHierarchy if + * the call to this method would result in an invalid visual template hierarchy. + * This can occur if a child is added to a non-layout visual template or if a + * call would result in a parent becoming a descendant of it's child (a recursive + * tree) or if the same child visual template is added to the hierarchy twice. + * + * @since S60 ?S60_version + * + * @param aChild The child visual template. + * @param aIndex Position at which child template is to be added. + */ + OSN_IMPORT void insertChildTemplate(IAlfVisualTemplate& aChild, int aIndex); + + /** + * Removes and destroyes a child visual template from an index in the child list + * of this visual template. This will recursively also destroy all child visual templates + * in the hierarchy below the destroyed child visual template. This call is silently + * ignored if the index is out of bounds. Call to this method cannot throw an + * exception. + * + * @since S60 ?S60_version + * + * @param aIndex Position from which child visual template is to be removed. + */ + OSN_IMPORT void destroyChildTemplate(int aIndex) throw(); + + /** + * Destroyes a child visual template with the given name and removes it from the children + * of this visual template. This will recursively also destroy all child visual templates + * in the hierarchy below the destroyed child visual template. This call is silently + * ignored if a child visual template with the given name is not found. Call + * to this method cannot throw an exception. + * + * @since S60 ?S60_version + * + * @param aName Name of child visual template to be destroyed. + */ + OSN_IMPORT void destroyChildTemplate(const char* aName) throw(); + + /** + * Add a new attribute setter and associated attribute container to set visual attributes + * of the concrete visual hierarchies created or updated with this visual template hierarchy. + * This visual template object acquires ownership of both the passed attribute setter as well + * as the attribute container. Attribute containers in a visual template are iterated through + * whenever concrete visual trees are created or updated. Concrete visual tree attributes + * are set from the data passed in through the createVisualTree() and updateVisualTree() methods + * using the attribute setters and containers added into the visual template using this method. + * + * @see createVisualTree() + * @see updateVisualTree() + * + * @exception std::bad_alloc thrown if heap memory allocation fails. + * + * @since S60 ?S60_version + * + * @param aSetter Attribute setter that will be used to set the attributes in the passed in + * container to concrete visuals. + * @param aContainer Container holding the attribute value used by the attribute setter. + */ + OSN_IMPORT void addAttributeSetter(IAlfAttributeSetter* aSetter, + AlfAttributeContainer* aContainer); + + /** + * Get the number of the attribute setters and the corresponding attribute containers. + * Call to this method cannot throw an exception. + * + * @since S60 ?S60_version + * + * @return The number of the attribute setters and containers. + */ + OSN_IMPORT int numAttributeSetters() const throw(); + + /** + * Returns an attribute setter maintained in this visual template from the given index. + * + * @exception osncore::AlfException thrown with error code osncore::EInvalidArrayIndex if + * the given index is out of bounds. + * + * @since S60 ?S60_version + * + * @param aIndex The index of the visual attribute setter. + * @return Reference to the attribute setter object. + */ + OSN_IMPORT IAlfAttributeSetter& attributeSetter( int aIndex ) const; + + /** + * Returns an attribute container maintained in this visual template from the given index. + * + * @exception osncore::AlfException thrown with error code osncore::EInvalidArrayIndex if + * the given index is out of bounds. + * + * @since S60 ?S60_version + * + * @param aIndex The index of the visual attribute container. + * @return Reference to the attribute container object. + */ + OSN_IMPORT AlfAttributeContainer& attributeContainer( int aIndex ) const; + + /** + * Update an existing concrete visual tree with new values. The existing visual tree + * should be produced from this visual template hierarchy using the createVisualTree() - + * method. + * + * @see createVisualTree() + * @see setSelectChildMode() + * @see addAttributeSetter() + * + * @since S60 ?S60_version + * + * @param aData A map containing new data for the visuals. + * @param aOldData Old data, that will be replaced. This is used to for instance tear down + * the old selected child branch before creating a new branch in the selected + * child mode. + * @param aVisual The root of the concrete visual tree that will be updated. This root visual + * needs to match this visual template and should have been created using this + * visual template. + * @return Root visual of the updated concrete visual tree. + */ + OSN_IMPORT CAlfVisual* updateVisualTree(IAlfMap* aData, + IAlfMap* aOldData, CAlfVisual& aVisual); + + /** + * Creates a new concrete visual tree from this visual template hierarchy and initializes the visuals. + * Created visual tree matches the visual template hierarchy under this visual template. + * + * @see updateVisualTree() + * @see setSelectChildMode() + * @see addAttributeSetter() + * + * @since S60 ?S60_version + * + * @param aControl The owner control of the new concrete visual hierarchy. + * @param aData A map containing data for the visuals. This is used to set the attributes of the + * produced concrete visuals using the attribute containers and attribute setters + * added through the addAttributeSetter() - method. + * @param aParentLayout Concrete layout visual to insert the created concrete visual tree into. + * Parent layout for a created visual. + * @param aLayoutIndex Ordinal index, into where the created visual should be placed in the parent layout. + * + * @return Pointer to the root visual object of the concrete visual hierarchy that was constructed. + */ + OSN_IMPORT CAlfVisual* createVisualTree(CAlfControl& aControl, + IAlfMap* aData, CAlfLayout* aParentLayout, int aLayoutIndex); + + /** + * Set the visual type. Every visual template maps to + * one concrete visual or layout type. Each visual template + * node in the visual template hierarchy can produce + * only visuals that match its type. Container nodes + * in the visual template hierarchy map to layouts + * and leaf visual template nodes map to visuals. + * + * Call to this method will make this visual template + * a visual type. The type can thus change from layout + * type to a visual type. + * + * @see setLayoutType() + * @see visualType() + * @see layoutType() + * + * @since S60 ?S60_version + * + * @param aType Type of visual + */ + OSN_IMPORT void setVisualType(TAlfVisualType aType); + + /** + * Get the visual type + * + * @since S60 ?S60_version + * + * @return aType Type of visual + */ + OSN_IMPORT int visualType() const throw(); + + /** + * Set the layout type. Every visual template maps to + * one concrete visual or layout type. Each visual template + * node in the visual template hierarchy can produce + * only visuals that match its type. Container nodes + * in the visual template hierarchy map to layouts + * and leaf visual template nodes map to visuals. + * + * Call to this method will make this visual template + * a layout type. The type can thus change from visual + * producer to a layout producer. + * + * @see setVisualType() + * @see visualType() + * @see layoutType() + * + * @since S60 ?S60_version + * + * @param aType Type of layout + */ + OSN_IMPORT void setLayoutType(TAlfLayoutType aType); + + /** + * Get the layout type or a negative integer + * if this visual template is of visual type. + * Call to this method cannot throw an exception. + * + * @since S60 ?S60_version + * + * @return Type of layout that this visual template produces + * or a negative integer if this visual template + * produces visuals. + */ + OSN_IMPORT int layoutType() const throw(); + + /** + * Adds brush to the brush array. + * + * All brushes added to a visual template will be applied to + * the produced concrete visual when one is produced. The same + * brush array is shared across all concrete visual instancies + * created from same visual template. + * + * @see brush() + * @see numBrushes() + * + * @exception std::bad_alloc thrown if a heap memory allocation fails. + * + * @since S60 ?S60_version + * + * @param aBrush Brush to be added + */ + OSN_IMPORT void addBrush(CAlfBrush& aBrush); + + /** + * Get the munber of brushes + * + * @since S60 ?S60_version + * + * @return The number of brushes + */ + OSN_IMPORT int numBrushes() const; + + /** + * Returns a brush instance from the array of brushes. + * + * @see addBrush() + * @see numBrushes() + * + * @exception osncore::AlfException thrown with error code osncore::EInvalidArrayIndex if + * the given index is out of bounds. + * + * @since S60 ?S60_version + * + * @param aIndex The index into the array of brushes. + * + * @return Reference to the brush object instance at the given array index. + */ + OSN_IMPORT CAlfBrush& brush(int aIndex) const; + + /** + * Enables or disables selected child mode. By default + * this is disabled and thus visual template creates or updates + * all its children when createVisualTree() or updateVisualTree() + * is called. If selected child mode is enabled the visual template + * will create or update only the selected child. The child which + * is affected in selected child mode is determined in the data passed + * in the createVisualTree() or updateVisualTree() method. In the + * passed data map a search is done to match the child index + * field name with the keys in the map. If an entry is found its value + * is used as an index to determine the child branch that is to be + * created or updated. + * + * @see createVisualTree() + * @see updateVisualTree() + * + * @since S60 ?S60_version + * + * @param aSelectChild Set to true to enable the child mode or false to disable the child mode. + * @param aChildIndFieldName Key in data map, from which entry the index of + * the selected child is fetched. + */ + OSN_IMPORT void setSelectChildMode(bool aSelectChild, + const UString& aChildIndFieldName ); + + //From IAlfInterfaceBase + /** + * From IAlfInterfaceBase. + * Getter for interfaces provided by the visual template. + * 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 the given child visual template from this visual template. + * Call to this method is silently ignored if the given visual template + * is not found from children. The parent template of the removed child + * is set to null. Ownership of the removed child visual template is + * transferred to the caller of this method. Call to this method cannot + * throw an exception. + * + * @see setParent() + * @see parent() + * + * @param aChild Reference to the child visual template that is located + * and removed from this visual template. + */ + void removeChildTemplate(IAlfVisualTemplate& aChild) throw(); + + /** + * Retrieves pointer to the parent visual template. + * Returns NULL if this is a root visual template of a visual template + * hierarchy. Call to this method cannot throw an exception. + * + * @see addChildTemplate() + * @see insertChildTemplate() + * @see Alf::IAlfElement::setVisualTemplate() + * + * @return Pointer to a Alf::IAlfVisualTemplate object that this visual template + * is a child of. + */ + OSN_IMPORT IAlfVisualTemplate* parent() const throw(); + + /** + * Sets the parent visual template. + * + * User should not call this method directly. It will be called implicitly + * by addChildTemplate() or insertChildTemplate() methods of + * the parent visual template into which this visual template is + * added to. + * + * Parent visual template and owner element are mutually exclusive. + * If a visual template is added under another visual template + * in a visual template hierarchy the connection to owner element + * is implicitly removed. Alf::IAlfElement objects can thus own only + * roots of visual template hierarchies. + * + * Call to this method cannot throw an exception. + * + * @see addChildTemplate() + * @see insertChildTemplate() + * @see parent() + * @see Alf::IAlfElement::setVisualTemplate() + * + * @param aParent Pointer to a parent visual template under which this + * visual template is located in in the visual template + * hierarchy or null, if the visual template is removed from + * a visual template hierarchy. + */ + OSN_IMPORT void setParent(IAlfVisualTemplate* aParent) throw(); + +protected: + /** + * c++-constructor for a template for creating a visual. + * + * @since S60 ?S60_version + * + * @param aType The type of the visual to create. + */ + OSN_IMPORT AlfVisualTemplate(TAlfVisualType aType); + + /** + * c++-constructor for a template for creating a layout. + * + * @since S60 ?S60_version + * + * @param aType The type of the layout to create. + */ + OSN_IMPORT AlfVisualTemplate(TAlfLayoutType aType); + + /** + * c++-constructor for an empty template. + * + * @since S60 ?S60_version + */ + OSN_IMPORT AlfVisualTemplate(); + +private: + /** + * returns the index to child, that should be created. The index is + * fetched from the data. + * + * @since S60 ?S60_version + * + * @param aData data-map, where the index is fetched. + * @return index to child, that should be created. + */ + int selectedChildInd(IAlfMap* aData); + +private: + + // Type of the visual to create. + // Negative values are layout types, positive values visual types. + int mVisualType; + + // The array containing child visual templates. Owned. + std::vector mChildren; + + // The tag of the visual to create. + UString mVisualName; + + // The array containing visual attribute setters. Owned. + AlfPtrVector mAttributeArray; + + // The array containing attribute containers. + AlfPtrVector mContainerArray; + + //The array containing brushes. Owned. + AlfPtrVector mBrushArray; + + //if true, creates only one child visual tree. + bool mSelectOneChild; + + //field name in data where child index is read. + //if iSelectOneChild is true, index points to child in childarray, to create. + UString mChildIndFieldName; + + // Owner element of this visual template. Not owned. + IAlfElement* mOwner; + + // Pointer to the parent visual template. + IAlfVisualTemplate* mParent; + }; + + } // namespace Alf + +#endif //ALF_VISUALTEMPLATE_H