1 /*

     2 * Copyright (c) 2007 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Visual template class for alfred widget model.

    15 *      This class creates and updates visual tree.

    16 *

    17 */

    18 

    19 

    20 #ifndef I_ALFVISUALTEMPLATE_H

    21 #define I_ALFVISUALTEMPLATE_H

    22 

    23 #include <alf/ialfinterfacebase.h>

    24 #include <alf/alftypes.h>

    25 #include <osn/ustring.h>

    26 #include <alf/alflayout.h>

    27 

    28 class CAlfVisual;

    29 class CAlfControl;

    30 class CAlfBrush;

    31 class CAlfLayout;

    32 

    33 namespace duiuimodel

    34     {

    35     //FORWARD DECLARATIONS

    36     class DuiNode;	

    37     }	

    38 using namespace duiuimodel;

    39 using namespace osncore;

    40     

    41 namespace Alf

    42     {

    43 // FORWARD DECLARATIONS

    44 class IAlfMap;

    45 class IAlfAttributeSetter;

    46 class IAlfElement;

    47 class AlfAttributeContainer;

    48 class AlfCustomInitDataBase;  

    49 

    50 namespace alfvisualtemplate

    51     {

    52 static const IfId ident =

    53     {

    54     0, "alfvisualtemplate"

    55     };

    56     }

    57     

    58 //INTERFACE DECLARATIONS

    59 

    60 /**

    61  * An interface for visual templates.

    62  *

    63  * A visual template hierarchy can be formed using visual template objects. From a visual template

    64  * hierarchy a concrete visual tree can be constructed that composes of toolkit visuals.

    65  * Produced concrete visual tree will match the visual template hierarchy constructed by

    66  * adding visual templates as children of each other. User can create any number of identical 

    67  * visual trees from one visual template hierarchy. Each visual template object creates 

    68  * one visual in the produced concrete visual tree.

    69  *

    70  * A visual template can be owned by a widget element (Alf::IAlfElement).

    71  * Only root visual templates of a visual template hierarchy can be owned by an element.

    72  * As a consequence of this an owner element of a visual template and a parent visual template

    73  * are mutually exclusive properties. That is, if a visual template is a child of

    74  * another visual template it cannot be owned by an element. Also if an element

    75  * owns a visual template it cannot be a child of another visual template.

    76  *

    77  * If a child visual template is set to an element the connection between child visual template

    78  * and its parent is removed thus making the visual template a root of the visual template hierarchy

    79  * below it. Similarly if a visual template owned by an element is set as a child to a visual template

    80  * the ownership of that visual template by its element is removed leaving the element with no visual

    81  * template. 

    82  *

    83  * Concrete visual trees can be produced using createVisualTree() method. Existing concrete visual

    84  * trees can be updated using the updateVisualTree() method. Attributes of the produced concrete 

    85  * visuals can be manipulated through attribute setters and containers assigned to visual template

    86  * using method addAttributeSetter(). Data that is passed to the createVisualTree() and updateVisualTree()

    87  * methods contain the attribute values that are set to the concrete visuals giving users a 

    88  * possibility to customize the produced concrete visual trees.

    89  *

    90  * @see Alf::IAlfElement

    91  *

    92  * @lib alfwidgetmodel.lib

    93  * @since S60 ?S60_version

    94  * @status Draft

    95  */

    96 class IAlfVisualTemplate : public IAlfInterfaceBase

    97     {

    98 public:

    99     /**

   100      * Getter for the type identifier of this interface.

   101      *

   102      * @since S60 ?S60_version

   103      * @return Identifier of this interface.

   104      */

   105     static inline const IfId& type()

   106         {

   107         return alfvisualtemplate::ident;

   108         }

   109 

   110     /** Virtual destructor. */

   111     virtual ~IAlfVisualTemplate() {}

   112     

   113     /**

   114      * Sets the owner element. User should not call this method directly. It will

   115      * be called implicitly by Alf::IAlfElement::setVisualTemplate() method.

   116      * Call to this method cannot throw an exception.

   117      *

   118      * @see Alf::IAlfElement::setVisualTemplate()

   119      *

   120      * @since S60 ?S60_version

   121      *

   122      * @param aOwner Element that owns this root visual template.

   123      */

   124     virtual void setOwner(IAlfElement* aElement) throw() = 0;

   125     

   126     /**

   127      * Returns the owner element. Call to this method cannot

   128      * throw an exception.

   129      *

   130      * @see Alf::IAlfElement::setVisualTemplate()

   131      *

   132      * @since S60 ?S60_version

   133      *

   134      * @return The owner element of a visual template, if this visual template is owned

   135      *         by an element. NULL if visual template is not owned by an element.

   136      */

   137     virtual IAlfElement* owner() const throw() = 0;

   138     

   139     /**

   140      * Set name of the visual. This name is used when creating

   141      * concrete visual trees. Name is assigned to each of the produced concrete

   142      * visuals as a tag. Note thus that all concrete visual

   143      * trees produced from this visual template share the same tag.

   144      *

   145      * @see name()

   146      *

   147      * @exception std::bad_alloc thrown if heap memory allocation fails.

   148      *

   149      * @since S60 ?S60_version

   150      *

   151      * @param aName The name of the visual.

   152      */

   153     virtual void setName(const char* aName) = 0;

   154     

   155     /**

   156      * Returns the name of the visual. Call to this method

   157      * cannot throw an exception.

   158      *

   159      * @see setName()

   160      *

   161      * @since S60 ?S60_version

   162      *

   163      * @return aName The name of the visual.

   164      */

   165     virtual const char* name() const throw() = 0;

   166 

   167     /**

   168      * Get the number of child visual templates.

   169      * This returns the number of child visual templates directly

   170      * under this visual template in the visual template

   171      * hierarchy. Call to this method cannot throw an exception.

   172      *

   173      * @since S60 ?S60_version

   174      *

   175      * @return The number of direct child visual templates

   176      *         under this visual template in the visual template hierarchy.

   177      */

   178     virtual int numChildTemplates() const throw() = 0;

   179 

   180     /**

   181      * Returns a child visual template at a given index.

   182      *

   183      * @exception osncore::AlfException thrown with error code osncore::EInvalidArrayIndex if

   184      *            the index is out of bounds.

   185      *

   186      * @since S60 ?S60_version

   187      *

   188      * @param aIndex The index of the child visual template.

   189      *

   190      * @return Reference to the child visual template object.

   191      */

   192     virtual IAlfVisualTemplate& childTemplate(int aIndex) const = 0;

   193     

   194     /**

   195      * Set the visual type. Every visual template maps to

   196      * one concrete visual or layout type. Each visual template

   197      * node in the visual template hierarchy can produce

   198      * only visuals that match its type. Container nodes

   199      * in the visual template hierarchy map to layouts

   200      * and leaf visual template nodes map to visuals.

   201      *

   202      * Call to this method will make this visual template 

   203      * a visual type. The type can thus change from layout

   204      * type to a visual type.

   205      *

   206      * @see setLayoutType()

   207      * @see visualType()

   208      * @see layoutType()

   209      *

   210      * @since S60 ?S60_version

   211      *

   212      * @param aType Type of visual

   213      */

   214     virtual void setVisualType(TAlfVisualType aType) = 0;

   215 

   216     /**

   217      * Get the visual type or a negative integer

   218      * if this visual template is of layout type.

   219      * Call to this method cannot throw an exception.

   220      *

   221      * @see setVisualType()

   222      *

   223      * @since S60 ?S60_version

   224      *

   225      * @return Type of visual that this visual template produces

   226      *         or a negative integer if this visual template

   227      *         produces layouts.

   228      */

   229     virtual int visualType() const throw() = 0;

   230 

   231     /**

   232      * Set the layout type. Every visual template maps to

   233      * one concrete visual or layout type. Each visual template

   234      * node in the visual template hierarchy can produce

   235      * only visuals that match its type. Container nodes

   236      * in the visual template hierarchy map to layouts

   237      * and leaf visual template nodes map to visuals.

   238      *

   239      * Call to this method will make this visual template 

   240      * a layout type. The type can thus change from visual

   241      * producer to a layout producer.

   242      *

   243      * @see setVisualType()

   244      * @see visualType()

   245      * @see layoutType()

   246      *

   247      * @since S60 ?S60_version

   248      *

   249      * @param aType Type of layout

   250      */

   251     virtual void setLayoutType(TAlfLayoutType aType) = 0;

   252 

   253     /**

   254      * Get the layout type or a negative integer

   255      * if this visual template is of visual type.

   256      * Call to this method cannot throw an exception.

   257      *

   258      * @since S60 ?S60_version

   259      *

   260      * @return Type of layout that this visual template produces

   261      *         or a negative integer if this visual template

   262      *         produces visuals.

   263      */

   264     virtual int layoutType() const throw() = 0;

   265 

   266     /**

   267      * Adds brush to the brush array.

   268      *

   269      * All brushes added to a visual template will be applied to

   270      * the produced concrete visual when one is produced. The same

   271      * brush array is shared across all concrete visual instancies

   272      * created from same visual template.

   273      * 

   274      * @see brush()

   275      * @see numBrushes()

   276      *

   277      * @exception std::bad_alloc thrown if a heap memory allocation fails.

   278      *

   279      * @since S60 ?S60_version

   280      *

   281      * @param aBrush Brush to be added

   282      */

   283     virtual void addBrush(CAlfBrush& aBrush) = 0;

   284 

   285     /**

   286      * Returns the number of brushes in the brush array.

   287      *

   288      * @since S60 ?S60_version

   289      *

   290      * @return The number of brushes

   291      */

   292     virtual int numBrushes() const = 0;

   293 

   294     /**

   295      * Returns a brush instance from the array of brushes.

   296      *

   297      * @see addBrush()

   298      * @see numBrushes()

   299      *

   300      * @exception osncore::AlfException thrown with error code osncore::EInvalidArrayIndex if

   301      *            the given index is out of bounds.

   302      *     

   303      * @since S60 ?S60_version

   304      *

   305      * @param aIndex The index into the array of brushes.

   306      *

   307      * @return Reference to the brush object instance at the given array index.

   308      */

   309     virtual CAlfBrush& brush(int aIndex) const = 0;

   310 

   311     /**

   312      * Enables or disables selected child mode. By default

   313      * this is disabled and thus visual template creates or updates

   314      * all its children when createVisualTree() or updateVisualTree()

   315      * is called. If selected child mode is enabled the visual template 

   316      * will create or update only the selected child. The child which 

   317      * is affected in selected child mode is determined in the data passed

   318      * in the createVisualTree() or updateVisualTree() method. In the 

   319      * passed data map a search is done to match the child index 

   320      * field name with the keys in the map. If an entry is found its value

   321      * is used as an index to determine the child branch that is to be 

   322      * created or updated.

   323      *

   324      * @see createVisualTree()

   325      * @see updateVisualTree()

   326      *

   327      * @since S60 ?S60_version

   328      *

   329      * @param aSelectChild Set to true to enable the child mode or false to disable the child mode.

   330      * @param aChildIndFieldName Key in data map, from which entry the index of

   331      *                           the selected child is fetched.

   332      */

   333     virtual void setSelectChildMode(bool aSelectChild, const UString& aChildIndFieldName) = 0;

   334 

   335     /**

   336      * Add a child visual template. The visual templates may form

   337      * a tree structure to create and update a visual tree. The visuals

   338      * created by children are added to the layout created by this

   339      * visual template. This visual template acquires the ownership for the

   340      * child visual template passed as an argument.

   341      *

   342      * If a visual template added as a child to this visual template is owned

   343      * by an Alf::IAlfElement the connection between the child visual template

   344      * and its owner element is implicitly removed in this call when a 

   345      * parent-child connection is created. Effectively having a parent visual

   346      * template or being owned by an element are mutually exclusive properties

   347      * for a visual template. Elements can own only root visual templates and

   348      * if an owned root visual template becomes a child of another visual 

   349      * template the visual template will be removed from the associated owner

   350      * element.

   351      *

   352      * @see insertChildTemplate()

   353      *

   354      * @exception std::bad_alloc Thrown if memory allocation fails in appending the child

   355      *            visual template to child array of this visual template.

   356      * @exception osncore::AlfException thrown with error code osncore::EInvalidHierarchy if

   357      *            the call to this method would result in an invalid visual template hierarchy.

   358      *            This can occur if a child is added to a non-layout visual template or if a

   359      *            call would result in a parent becoming a descendant of it's child (a recursive

   360      *            tree).

   361      *

   362      * @since S60 ?S60_version

   363      *

   364      * @param aChild Child visual template to be appended to the children of this visual template.

   365      */

   366     virtual void addChildTemplate(IAlfVisualTemplate& aChild) = 0;

   367 

   368     /**

   369      * Inserts a child visual template at given index. The visual templates may form

   370      * a tree structure to create and update a concrete visual tree. The concrete visuals

   371      * created by children are added to the layout created by this

   372      * visual template. This visual template acquires the ownership of the inserted

   373      * child visual template.

   374      *

   375      * @see addChildTemplate()

   376      *     

   377      * @exception std::bad_alloc thrown if memory allocation fails in inserting the child visual

   378      *            template to the child list of this visual template.

   379      * @exception osncore::AlfException thrown with error code osncore::EInvalidArrayIndex when

   380      *            index supplied is out of range for array of visual templates.

   381      * @exception osncore::AlfException thrown with error code osncore::EInvalidHierarchy if

   382      *            the call to this method would result in an invalid visual template hierarchy.

   383      *            This can occur if a child is added to a non-layout visual template or if a

   384      *            call would result in a parent becoming a descendant of it's child (a recursive

   385      *            tree) or if the same child visual template is added to the hierarchy twice.

   386      *

   387      * @since S60 ?S60_version

   388      *

   389      * @param aChild  The child visual template.

   390      * @param aIndex  Position at which child template is to be added.

   391      */

   392     virtual void insertChildTemplate(IAlfVisualTemplate& aChild, int aIndex) = 0;

   393 

   394     /**

   395      * Removes and destroyes a child visual template from an index in the child list

   396      * of this visual template. This will recursively also destroy all child visual templates

   397      * in the hierarchy below the destroyed child visual template. This call is silently

   398      * ignored if the index is out of bounds. Call to this method cannot throw an

   399      * exception.

   400      *

   401      * @since S60 ?S60_version

   402      *

   403      * @param aIndex Position from which child visual template is to be removed.

   404      */

   405     virtual void destroyChildTemplate(int aIndex) throw() = 0;

   406 

   407     /**

   408      * Destroyes a child visual template with the given name and removes it from the children

   409      * of this visual template. This will recursively also destroy all child visual templates

   410      * in the hierarchy below the destroyed child visual template. This call is silently

   411      * ignored if a child visual template with the given name is not found. Call

   412      * to this method cannot throw an exception.

   413      *

   414      * @since S60 ?S60_version

   415      *

   416      * @param aName Name of child visual template to be destroyed.

   417      */

   418     virtual void destroyChildTemplate(const char* aName) throw() = 0;

   419 

   420     /**

   421      * Update an existing concrete visual tree with new values. The existing visual tree

   422      * should be produced from this visual template hierarchy using the createVisualTree() -

   423      * method.

   424      * 

   425      * @see createVisualTree()

   426      * @see setSelectChildMode()

   427      * @see addAttributeSetter()

   428      *

   429      * @since S60 ?S60_version

   430      *

   431      * @param aData A map containing new data for the visuals.

   432      * @param aOldData Old data, that will be replaced. This is used to for instance tear down

   433      *                 the old selected child branch before creating a new branch in the selected

   434      *                 child mode.

   435      * @param aVisual The root of the concrete visual tree that will be updated. This root visual

   436      *                needs to match this visual template and should have been created using this

   437      *                visual template.

   438      * @return Root visual of the updated concrete visual tree.

   439      */

   440     virtual CAlfVisual* updateVisualTree(IAlfMap* aData, IAlfMap* aOldData, CAlfVisual& aVisual) = 0;

   441 

   442     /**

   443      * Creates a new concrete visual tree from this visual template hierarchy and initializes the visuals.

   444      * Created visual tree matches the visual template hierarchy under this visual template.

   445      *

   446      * @see updateVisualTree()

   447      * @see setSelectChildMode()

   448      * @see addAttributeSetter()

   449      *

   450      * @since S60 ?S60_version

   451      *

   452      * @param aControl The owner control of the new concrete visual hierarchy.

   453      * @param aData A map containing data for the visuals. This is used to set the attributes of the

   454      *              produced concrete visuals using the attribute containers and attribute setters

   455      *              added through the addAttributeSetter() - method.

   456      * @param aParentLayout Concrete layout visual to insert the created concrete visual tree into.

   457      *                      Parent layout for a created visual.

   458      * @param aLayoutIndex Ordinal index, into where the created visual should be placed in the parent layout.

   459      *

   460      * @return Pointer to the root visual object of the concrete visual hierarchy that was constructed.

   461      */

   462     virtual CAlfVisual* createVisualTree(CAlfControl& aControl,

   463                                          IAlfMap* aData, CAlfLayout* aParentLayout, int aLayoutIndex) = 0;

   464 

   465     /**

   466      * Add a new attribute setter and associated attribute container to set visual attributes

   467      * of the concrete visual hierarchies created or updated with this visual template hierarchy.

   468      * This visual template object acquires ownership of both the passed attribute setter as well

   469      * as the attribute container. Attribute containers in a visual template are iterated through

   470      * whenever concrete visual trees are created or updated. Concrete visual tree attributes

   471      * are set from the data passed in through the createVisualTree() and updateVisualTree() methods

   472      * using the attribute setters and containers added into the visual template using this method.

   473      *

   474      * @see createVisualTree()

   475      * @see updateVisualTree()

   476      *

   477      * @exception std::bad_alloc thrown if heap memory allocation fails.

   478      *

   479      * @since S60 ?S60_version

   480      *

   481      * @param aSetter Attribute setter that will be used to set the attributes in the passed in

   482      *                container to concrete visuals.

   483      * @param aContainer Container holding the attribute value used by the attribute setter.

   484      */

   485     virtual void addAttributeSetter(IAlfAttributeSetter* aSetter, AlfAttributeContainer* aContainer) = 0;

   486 

   487     /**

   488      * Get the number of the attribute setters and the corresponding attribute containers.

   489      * Call to this method cannot throw an exception.

   490      *

   491      * @since S60 ?S60_version

   492      *

   493      * @return The number of the attribute setters and containers.

   494      */

   495     virtual int numAttributeSetters() const throw() = 0;

   496 

   497     /**

   498      * Returns an attribute setter maintained in this visual template from the given index.

   499      *

   500      * @exception osncore::AlfException thrown with error code osncore::EInvalidArrayIndex if

   501      *            the given index is out of bounds.

   502      *

   503      * @since S60 ?S60_version

   504      *

   505      * @param aIndex The index of the visual attribute setter.

   506      * @return Reference to the attribute setter object.

   507      */

   508     virtual IAlfAttributeSetter& attributeSetter(int aIndex) const = 0;

   509 

   510     /**

   511      * Returns an attribute container maintained in this visual template from the given index.

   512      *

   513      * @exception osncore::AlfException thrown with error code osncore::EInvalidArrayIndex if

   514      *            the given index is out of bounds.

   515      *

   516      * @since S60 ?S60_version

   517      *

   518      * @param aIndex The index of the visual attribute container.

   519      * @return Reference to the attribute container object.

   520      */

   521     virtual AlfAttributeContainer& attributeContainer(int aIndex) const = 0;

   522          

   523     /**

   524      * Retrieves pointer to the parent visual template.

   525      * Returns NULL if this is a root visual template of a visual template

   526      * hierarchy. Call to this method cannot throw an exception.

   527      *

   528      * @see addChildTemplate()

   529      * @see insertChildTemplate()

   530      * @see Alf::IAlfElement::setVisualTemplate()

   531      *

   532      * @return Pointer to a Alf::IAlfVisualTemplate object that this visual template

   533      *         is a child of.

   534      */

   535     virtual IAlfVisualTemplate* parent() const throw() = 0;

   536     

   537     /**

   538      * Removes the given child visual template from this visual template.

   539      * Call to this method is silently ignored if the given visual template

   540      * is not found from children. The parent template of the removed child

   541      * is set to null. Ownership of the removed child visual template is

   542      * transferred to the caller of this method. Call to this method cannot

   543      * throw an exception.

   544      *

   545      * @see setParent()

   546      * @see parent()

   547      *

   548      * @param aChild Reference to the child visual template that is located

   549      *               and removed from this visual template.

   550      */

   551     virtual void removeChildTemplate(IAlfVisualTemplate& aChild) throw() = 0;    

   552 

   553     /**

   554      * Sets the parent visual template.

   555      *

   556      * User should not call this method directly. It will be called implicitly

   557      * by addChildTemplate() or insertChildTemplate() methods of

   558      * the parent visual template into which this visual template is

   559      * added to.

   560      *

   561      * Parent visual template and owner element are mutually exclusive.

   562      * If a visual template is added under another visual template

   563      * in a visual template hierarchy the connection to owner element

   564      * is implicitly removed. Alf::IAlfElement objects can thus own only

   565      * roots of visual template hierarchies.

   566      *

   567      * Call to this method cannot throw an exception.

   568      * 

   569      * @see addChildTemplate()

   570      * @see insertChildTemplate()

   571      * @see parent()

   572      * @see Alf::IAlfElement::setVisualTemplate()

   573      *

   574      * @param aParent Pointer to a parent visual template under which this

   575      *                visual template is located in in the visual template

   576      *                hierarchy or null, if the visual template is removed from

   577      *                a visual template hierarchy.

   578      */

   579     virtual void setParent(IAlfVisualTemplate* aParent) throw() = 0;

   580     

   581     };

   582     

   583 /**

   584  * Placeholder for information required to instantiate a visual template

   585  * via the widget factory mechanism.

   586  * A pointer to this structure is casted to a void pointer and sent to the

   587  * factory plugin.

   588  * @lib alfwidgetmodel.lib

   589  * @since S60 ?S60_version

   590  */

   591 struct AlfVisualTemplateInitData

   592     {

   593     /**

   594      * Visual template instance ID.This uniquely identifies every visual template instance

   595      */

   596     char* mVisualTemplateId;

   597 

   598     /**

   599      * Pointer to node in declaration containing information for the widget.

   600      */

   601     DuiNode* mNode;

   602 

   603     /**

   604      * Pointer to custom data passed via factory mechanism

   605      * Not Owned.

   606      */

   607     AlfCustomInitDataBase* mCustomData;  

   608     };

   609 

   610     } // namespace Alf

   611 

   612 #endif // I_ALFVISUALTEMPLATE_H

   613 

   614 // End of File