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