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 ALF_VISUALTEMPLATE_H

    21 #define ALF_VISUALTEMPLATE_H

    22 

    23 #include <osn/osndefines.h>

    24 #include <alf/alflayout.h>

    25 #include "alf/ialfvisualtemplate.h"

    26 #include <osn/ustring.h>

    27 #include <osn/alfptrvector.h>

    28 #include <alf/ialfinterfacebase.h>

    29 #include <vector>

    30 

    31 class CAlfControl;

    32 class CAlfBrush;

    33 class CAlfVisual;

    34 

    35 using namespace osncore;

    36 

    37 namespace Alf

    38     {

    39 // FORWARD DECLARATIONS

    40 class IAlfMap;

    41 class IAlfAttributeSetter;

    42 class AlfAttributeContainer;

    43 

    44 /**

    45  * @class AlfVisualTemplate alfvisualtemplate.h "alf/alfvisualtemplate.h"

    46  * A generic visual template for creating or updating a visual tree.

    47  * The visual templates may form a tree structure that matches

    48  * the visual tree to be created or updated. Each template is

    49  * responsible for creating and initializing a single visual.

    50  * Visual templates contain a number of attribute setters

    51  * to initialize or update the visuals. Attribute setters use values

    52  * from the corresponding attribute containers.

    53  *

    54  * @lib alfwidgetmodel.lib

    55  * @since S60 ?S60_version

    56  * @status Draft

    57  * @interfaces IAlfVisualTemplate

    58  */

    59 class AlfVisualTemplate : public IAlfVisualTemplate

    60     {

    61 public:

    62 

    63     /**

    64      * Constructor for a template for creating a visual.

    65      * @exception std::bad_alloc

    66      *            

    67      * @since S60 ?S60_version

    68      *

    69      * @param aType  The type of the visual to create.

    70      */

    71     OSN_IMPORT static AlfVisualTemplate* create(TAlfVisualType aType);

    72 

    73     /**

    74      * Constructor for a template for creating a layout.

    75      * @exception std::bad_alloc

    76      *

    77      * @since S60 ?S60_version

    78      *

    79      * @param aType  The type of the layout to create.

    80      */

    81     OSN_IMPORT static AlfVisualTemplate* create(TAlfLayoutType aType);

    82 

    83     /**

    84      * Constructor for an empty template.

    85      * @exception std::bad_alloc

    86      *

    87      * @since S60 ?S60_version

    88      *

    89      */

    90     OSN_IMPORT static AlfVisualTemplate* create();

    91 

    92     // Destructor.

    93     OSN_IMPORT virtual ~AlfVisualTemplate();

    94 

    95 	//From IAlfVisualTemplate

    96          

    97     /**

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

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

   100      * Call to this method cannot throw an exception.

   101      *

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

   103      *

   104      * @since S60 ?S60_version

   105      *

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

   107      */

   108     OSN_IMPORT void setOwner(IAlfElement* aElement) throw();

   109     

   110     /**

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

   112      * throw an exception.

   113      *

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

   115      *

   116      * @since S60 ?S60_version

   117      *

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

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

   120      */

   121     OSN_IMPORT IAlfElement* owner() const throw();

   122 

   123     /**

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

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

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

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

   128      *

   129      * @see name()

   130      *

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

   132      *

   133      * @since S60 ?S60_version

   134      *

   135      * @param aName The name of the visual.

   136      */

   137     OSN_IMPORT void setName(const char* aName);

   138     

   139     /**

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

   141      * cannot throw an exception.

   142      *

   143      * @see setName()

   144      *

   145      * @since S60 ?S60_version

   146      *

   147      * @return aName The name of the visual.

   148      */

   149     OSN_IMPORT const char* name() const throw();

   150 

   151     /**

   152      * Get the number of child visual templates.

   153      * This returns the number of child visual templates directly

   154      * under this visual template in the visual template

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

   156      *

   157      * @since S60 ?S60_version

   158      *

   159      * @return The number of direct child visual templates

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

   161      */

   162     OSN_IMPORT int numChildTemplates() const throw();

   163 

   164     /**

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

   166      *

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

   168      *            the index is out of bounds.

   169      *

   170      * @since S60 ?S60_version

   171      *

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

   173      *

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

   175      */

   176     OSN_IMPORT IAlfVisualTemplate& childTemplate(int aIndex) const;

   177 

   178     /**

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

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

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

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

   183      * child visual template passed as an argument.

   184      *

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

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

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

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

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

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

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

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

   193      * element.

   194      *

   195      * @see insertChildTemplate()

   196      *

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

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

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

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

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

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

   203      *            tree).

   204      *

   205      * @since S60 ?S60_version

   206      *

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

   208      */

   209     OSN_IMPORT void addChildTemplate(IAlfVisualTemplate& aChild);

   210     

   211     /**

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

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

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

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

   216      * child visual template.

   217      *

   218      * @see addChildTemplate()

   219      *     

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

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

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

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

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

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

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

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

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

   229      *

   230      * @since S60 ?S60_version

   231      *

   232      * @param aChild  The child visual template.

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

   234      */

   235     OSN_IMPORT void insertChildTemplate(IAlfVisualTemplate& aChild, int aIndex);

   236 

   237     /**

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

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

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

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

   242      * exception.

   243      *

   244      * @since S60 ?S60_version

   245      *

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

   247      */

   248     OSN_IMPORT void destroyChildTemplate(int aIndex) throw();

   249 

   250     /**

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

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

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

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

   255      * to this method cannot throw an exception.

   256      *

   257      * @since S60 ?S60_version

   258      *

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

   260      */

   261     OSN_IMPORT void destroyChildTemplate(const char* aName) throw();

   262 

   263     /**

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

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

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

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

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

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

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

   271      *

   272      * @see createVisualTree()

   273      * @see updateVisualTree()

   274      *

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

   276      *

   277      * @since S60 ?S60_version

   278      *

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

   280      *                container to concrete visuals.

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

   282      */

   283     OSN_IMPORT void addAttributeSetter(IAlfAttributeSetter* aSetter,

   284                                        AlfAttributeContainer* aContainer);

   285 

   286     /**

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

   288      * Call to this method cannot throw an exception.

   289      *

   290      * @since S60 ?S60_version

   291      *

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

   293      */

   294     OSN_IMPORT int numAttributeSetters() const throw();

   295 

   296     /**

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

   298      *

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

   300      *            the given index is out of bounds.

   301      *

   302      * @since S60 ?S60_version

   303      *

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

   305      * @return Reference to the attribute setter object.

   306      */

   307     OSN_IMPORT IAlfAttributeSetter& attributeSetter( int aIndex ) const;

   308 

   309     /**

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

   311      *

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

   313      *            the given index is out of bounds.

   314      *

   315      * @since S60 ?S60_version

   316      *

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

   318      * @return Reference to the attribute container object.

   319      */

   320     OSN_IMPORT AlfAttributeContainer& attributeContainer( int aIndex ) const;

   321 

   322     /**

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

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

   325      * method.

   326      * 

   327      * @see createVisualTree()

   328      * @see setSelectChildMode()

   329      * @see addAttributeSetter()

   330      *

   331      * @since S60 ?S60_version

   332      *

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

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

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

   336      *                 child mode.

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

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

   339      *                visual template.

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

   341      */

   342     OSN_IMPORT CAlfVisual* updateVisualTree(IAlfMap* aData,

   343                                             IAlfMap* aOldData, CAlfVisual& aVisual);

   344 

   345     /**

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

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

   348      *

   349      * @see updateVisualTree()

   350      * @see setSelectChildMode()

   351      * @see addAttributeSetter()

   352      *

   353      * @since S60 ?S60_version

   354      *

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

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

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

   358      *              added through the addAttributeSetter() - method.

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

   360      *                      Parent layout for a created visual.

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

   362      *

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

   364      */

   365     OSN_IMPORT CAlfVisual* createVisualTree(CAlfControl& aControl,

   366                                             IAlfMap* aData, CAlfLayout* aParentLayout, int aLayoutIndex);

   367 

   368     /**

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

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

   371      * node in the visual template hierarchy can produce

   372      * only visuals that match its type. Container nodes

   373      * in the visual template hierarchy map to layouts

   374      * and leaf visual template nodes map to visuals.

   375      *

   376      * Call to this method will make this visual template 

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

   378      * type to a visual type.

   379      *

   380      * @see setLayoutType()

   381      * @see visualType()

   382      * @see layoutType()

   383      *

   384      * @since S60 ?S60_version

   385      *

   386      * @param aType Type of visual

   387      */

   388     OSN_IMPORT void setVisualType(TAlfVisualType aType);

   389 

   390     /**

   391      * Get the visual type

   392      *

   393      * @since S60 ?S60_version

   394      *

   395      * @return aType Type of visual

   396      */

   397     OSN_IMPORT int visualType() const throw();

   398 

   399     /**

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

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

   402      * node in the visual template hierarchy can produce

   403      * only visuals that match its type. Container nodes

   404      * in the visual template hierarchy map to layouts

   405      * and leaf visual template nodes map to visuals.

   406      *

   407      * Call to this method will make this visual template 

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

   409      * producer to a layout producer.

   410      *

   411      * @see setVisualType()

   412      * @see visualType()

   413      * @see layoutType()

   414      *

   415      * @since S60 ?S60_version

   416      *

   417      * @param aType Type of layout

   418      */

   419     OSN_IMPORT void setLayoutType(TAlfLayoutType aType);

   420 

   421     /**

   422      * Get the layout type or a negative integer

   423      * if this visual template is of visual type.

   424      * Call to this method cannot throw an exception.

   425      *

   426      * @since S60 ?S60_version

   427      *

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

   429      *         or a negative integer if this visual template

   430      *         produces visuals.

   431      */

   432     OSN_IMPORT int layoutType() const throw();

   433 

   434     /**

   435      * Adds brush to the brush array.

   436      *

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

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

   439      * brush array is shared across all concrete visual instancies

   440      * created from same visual template.

   441      * 

   442      * @see brush()

   443      * @see numBrushes()

   444      *

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

   446      *

   447      * @since S60 ?S60_version

   448      *

   449      * @param aBrush Brush to be added

   450      */

   451     OSN_IMPORT void addBrush(CAlfBrush& aBrush);

   452 

   453     /**

   454      * Get the munber of brushes

   455      *

   456      * @since S60 ?S60_version

   457      *

   458      * @return The number of brushes

   459      */

   460     OSN_IMPORT int numBrushes() const;

   461 

   462     /**

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

   464      *

   465      * @see addBrush()

   466      * @see numBrushes()

   467      *

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

   469      *            the given index is out of bounds.

   470      *     

   471      * @since S60 ?S60_version

   472      *

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

   474      *

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

   476      */

   477     OSN_IMPORT CAlfBrush& brush(int aIndex) const;

   478 

   479     /**

   480      * Enables or disables selected child mode. By default

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

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

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

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

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

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

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

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

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

   490      * created or updated.

   491      *

   492      * @see createVisualTree()

   493      * @see updateVisualTree()

   494      *

   495      * @since S60 ?S60_version

   496      *

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

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

   499      *                           the selected child is fetched.

   500      */

   501     OSN_IMPORT void setSelectChildMode(bool aSelectChild,

   502                                        const UString& aChildIndFieldName );

   503 

   504     //From IAlfInterfaceBase

   505     /**

   506      * From IAlfInterfaceBase.

   507      * Getter for interfaces provided by the visual template.

   508      * Derived classes should always call the base class method

   509      * from the overridden makeInterface.

   510      *

   511      * @since S60 ?S60_version

   512      * @param aType A descriptor to identify the type of the queried interface.

   513      * @return The queried interface, or NULL if the interface is not

   514      *         supported or available.

   515      */

   516     OSN_IMPORT virtual IAlfInterfaceBase* makeInterface( const IfId& aType );

   517 

   518     /**

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

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

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

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

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

   524      * throw an exception.

   525      *

   526      * @see setParent()

   527      * @see parent()

   528      *

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

   530      *               and removed from this visual template.

   531      */

   532     void removeChildTemplate(IAlfVisualTemplate& aChild) throw();

   533     

   534     /**

   535      * Retrieves pointer to the parent visual template.

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

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

   538      *

   539      * @see addChildTemplate()

   540      * @see insertChildTemplate()

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

   542      *

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

   544      *         is a child of.

   545      */

   546     OSN_IMPORT IAlfVisualTemplate* parent() const throw();

   547         

   548     /**

   549      * Sets the parent visual template.

   550      *

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

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

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

   554      * added to.

   555      *

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

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

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

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

   560      * roots of visual template hierarchies.

   561      *

   562      * Call to this method cannot throw an exception.

   563      * 

   564      * @see addChildTemplate()

   565      * @see insertChildTemplate()

   566      * @see parent()

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

   568      *

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

   570      *                visual template is located in in the visual template

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

   572      *                a visual template hierarchy.

   573      */

   574     OSN_IMPORT void setParent(IAlfVisualTemplate* aParent) throw();

   575 

   576 protected:

   577     /**

   578      * c++-constructor for a template for creating a visual.

   579      *

   580      * @since S60 ?S60_version

   581      *

   582      * @param aType  The type of the visual to create.

   583      */

   584     OSN_IMPORT AlfVisualTemplate(TAlfVisualType aType);

   585 

   586     /**

   587      * c++-constructor for a template for creating a layout.

   588      *

   589      * @since S60 ?S60_version

   590      *

   591      * @param aType  The type of the layout to create.

   592      */

   593     OSN_IMPORT AlfVisualTemplate(TAlfLayoutType aType);

   594 

   595     /**

   596      * c++-constructor for an empty template.

   597      *

   598      * @since S60 ?S60_version

   599      */

   600     OSN_IMPORT AlfVisualTemplate();

   601 

   602 private:

   603     /**

   604      * returns the index to child, that should be created. The index is

   605      * fetched from the data.

   606      *

   607      * @since S60 ?S60_version

   608      *

   609      * @param aData data-map, where the index is fetched.

   610      * @return  index to child, that should be created.

   611      */

   612     int selectedChildInd(IAlfMap* aData);

   613     

   614 private:

   615 

   616     // Type of the visual to create.

   617     // Negative values are layout types, positive values visual types.

   618     int mVisualType;

   619 

   620     // The array containing child visual templates. Owned.

   621     std::vector<IAlfVisualTemplate*> mChildren;

   622 

   623     // The tag of the visual to create.

   624     UString mVisualName;

   625 

   626     // The array containing visual attribute setters. Owned.

   627     AlfPtrVector<IAlfAttributeSetter> mAttributeArray;

   628 

   629     // The array containing attribute containers.

   630     AlfPtrVector<AlfAttributeContainer> mContainerArray;

   631 

   632     //The array containing brushes. Owned.

   633     AlfPtrVector<CAlfBrush> mBrushArray;

   634 

   635     //if true, creates only one child visual tree.

   636     bool mSelectOneChild;

   637 

   638     //field name in data where child index is read.

   639     //if iSelectOneChild is true, index points to child in childarray, to create.

   640     UString mChildIndFieldName;

   641     

   642     // Owner element of this visual template. Not owned.

   643 	IAlfElement* mOwner;

   644 	

   645 	// Pointer to the parent visual template.

   646 	IAlfVisualTemplate* mParent;

   647     };

   648 

   649     } // namespace Alf

   650 

   651 #endif //ALF_VISUALTEMPLATE_H