diff -r 4ea6f81c838a -r 0e9bb658ef58 inc/alf/ialfvisualtemplate.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/inc/alf/ialfvisualtemplate.h Wed Sep 01 12:23:18 2010 +0100 @@ -0,0 +1,614 @@ +/* +* 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 I_ALFVISUALTEMPLATE_H +#define I_ALFVISUALTEMPLATE_H + +#include +#include +#include +#include + +class CAlfVisual; +class CAlfControl; +class CAlfBrush; +class CAlfLayout; + +namespace duiuimodel + { + //FORWARD DECLARATIONS + class DuiNode; + } +using namespace duiuimodel; +using namespace osncore; + +namespace Alf + { +// FORWARD DECLARATIONS +class IAlfMap; +class IAlfAttributeSetter; +class IAlfElement; +class AlfAttributeContainer; +class AlfCustomInitDataBase; + +namespace alfvisualtemplate + { +static const IfId ident = + { + 0, "alfvisualtemplate" + }; + } + +//INTERFACE DECLARATIONS + +/** + * An interface for visual templates. + * + * A visual template hierarchy can be formed using visual template objects. From a visual template + * hierarchy a concrete visual tree can be constructed that composes of toolkit visuals. + * Produced concrete visual tree will match the visual template hierarchy constructed by + * adding visual templates as children of each other. User can create any number of identical + * visual trees from one visual template hierarchy. Each visual template object creates + * one visual in the produced concrete visual tree. + * + * A visual template can be owned by a widget element (Alf::IAlfElement). + * Only root visual templates of a visual template hierarchy can be owned by an element. + * As a consequence of this an owner element of a visual template and a parent visual template + * are mutually exclusive properties. That is, if a visual template is a child of + * another visual template it cannot be owned by an element. Also if an element + * owns a visual template it cannot be a child of another visual template. + * + * If a child visual template is set to an element the connection between child visual template + * and its parent is removed thus making the visual template a root of the visual template hierarchy + * below it. Similarly if a visual template owned by an element is set as a child to a visual template + * the ownership of that visual template by its element is removed leaving the element with no visual + * template. + * + * Concrete visual trees can be produced using createVisualTree() method. Existing concrete visual + * trees can be updated using the updateVisualTree() method. Attributes of the produced concrete + * visuals can be manipulated through attribute setters and containers assigned to visual template + * using method addAttributeSetter(). Data that is passed to the createVisualTree() and updateVisualTree() + * methods contain the attribute values that are set to the concrete visuals giving users a + * possibility to customize the produced concrete visual trees. + * + * @see Alf::IAlfElement + * + * @lib alfwidgetmodel.lib + * @since S60 ?S60_version + * @status Draft + */ +class IAlfVisualTemplate : public IAlfInterfaceBase + { +public: + /** + * Getter for the type identifier of this interface. + * + * @since S60 ?S60_version + * @return Identifier of this interface. + */ + static inline const IfId& type() + { + return alfvisualtemplate::ident; + } + + /** Virtual destructor. */ + virtual ~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. + */ + virtual void setOwner(IAlfElement* aElement) throw() = 0; + + /** + * 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. + */ + virtual IAlfElement* owner() const throw() = 0; + + /** + * 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. + */ + virtual void setName(const char* aName) = 0; + + /** + * 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. + */ + virtual const char* name() const throw() = 0; + + /** + * 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. + */ + virtual int numChildTemplates() const throw() = 0; + + /** + * 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. + */ + virtual IAlfVisualTemplate& childTemplate(int aIndex) const = 0; + + /** + * 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 + */ + virtual void setVisualType(TAlfVisualType aType) = 0; + + /** + * Get the visual type or a negative integer + * if this visual template is of layout type. + * Call to this method cannot throw an exception. + * + * @see setVisualType() + * + * @since S60 ?S60_version + * + * @return Type of visual that this visual template produces + * or a negative integer if this visual template + * produces layouts. + */ + virtual int visualType() const throw() = 0; + + /** + * 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 + */ + virtual void setLayoutType(TAlfLayoutType aType) = 0; + + /** + * 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. + */ + virtual int layoutType() const throw() = 0; + + /** + * 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 + */ + virtual void addBrush(CAlfBrush& aBrush) = 0; + + /** + * Returns the number of brushes in the brush array. + * + * @since S60 ?S60_version + * + * @return The number of brushes + */ + virtual int numBrushes() const = 0; + + /** + * 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. + */ + virtual CAlfBrush& brush(int aIndex) const = 0; + + /** + * 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. + */ + virtual void setSelectChildMode(bool aSelectChild, const UString& aChildIndFieldName) = 0; + + /** + * 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. + */ + virtual void addChildTemplate(IAlfVisualTemplate& aChild) = 0; + + /** + * 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. + */ + virtual void insertChildTemplate(IAlfVisualTemplate& aChild, int aIndex) = 0; + + /** + * 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. + */ + virtual void destroyChildTemplate(int aIndex) throw() = 0; + + /** + * 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. + */ + virtual void destroyChildTemplate(const char* aName) throw() = 0; + + /** + * 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. + */ + virtual CAlfVisual* updateVisualTree(IAlfMap* aData, IAlfMap* aOldData, CAlfVisual& aVisual) = 0; + + /** + * 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. + */ + virtual CAlfVisual* createVisualTree(CAlfControl& aControl, + IAlfMap* aData, CAlfLayout* aParentLayout, int aLayoutIndex) = 0; + + /** + * 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. + */ + virtual void addAttributeSetter(IAlfAttributeSetter* aSetter, AlfAttributeContainer* aContainer) = 0; + + /** + * 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. + */ + virtual int numAttributeSetters() const throw() = 0; + + /** + * 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. + */ + virtual IAlfAttributeSetter& attributeSetter(int aIndex) const = 0; + + /** + * 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. + */ + virtual AlfAttributeContainer& attributeContainer(int aIndex) const = 0; + + /** + * 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. + */ + virtual IAlfVisualTemplate* parent() const throw() = 0; + + /** + * 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. + */ + virtual void removeChildTemplate(IAlfVisualTemplate& aChild) throw() = 0; + + /** + * 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. + */ + virtual void setParent(IAlfVisualTemplate* aParent) throw() = 0; + + }; + +/** + * Placeholder for information required to instantiate a visual template + * via the widget factory mechanism. + * A pointer to this structure is casted to a void pointer and sent to the + * factory plugin. + * @lib alfwidgetmodel.lib + * @since S60 ?S60_version + */ +struct AlfVisualTemplateInitData + { + /** + * Visual template instance ID.This uniquely identifies every visual template instance + */ + char* mVisualTemplateId; + + /** + * Pointer to node in declaration containing information for the widget. + */ + DuiNode* mNode; + + /** + * Pointer to custom data passed via factory mechanism + * Not Owned. + */ + AlfCustomInitDataBase* mCustomData; + }; + + } // namespace Alf + +#endif // I_ALFVISUALTEMPLATE_H + +// End of File