inc/alf/ialfvisualtemplate.h
branchRCL_3
changeset 25 4ea6f81c838a
parent 23 514d98f21c43
child 26 0e9bb658ef58
--- a/inc/alf/ialfvisualtemplate.h	Mon Jun 21 16:15:51 2010 +0300
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,614 +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 I_ALFVISUALTEMPLATE_H
-#define I_ALFVISUALTEMPLATE_H
-
-#include <alf/ialfinterfacebase.h>
-#include <alf/alftypes.h>
-#include <osn/ustring.h>
-#include <alf/alflayout.h>
-
-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