inc/alf/alfelement.h
branchRCL_3
changeset 25 4ea6f81c838a
parent 23 514d98f21c43
child 26 0e9bb658ef58
equal deleted inserted replaced
23:514d98f21c43 25:4ea6f81c838a
     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:  The interface and the basic implementation for presentation elements.
       
    15 *
       
    16 */
       
    17 
       
    18 
       
    19 #ifndef ALFELEMENT_H
       
    20 #define ALFELEMENT_H
       
    21 
       
    22 #include <osn/osndefines.h>
       
    23 #include <memory>
       
    24 #include <alf/ialfelement.h>
       
    25 #include <osn/alfptrvector.h>
       
    26 
       
    27 using osncore::AlfPtrVector;
       
    28 using std::auto_ptr;
       
    29 
       
    30 class CAlfVisual;
       
    31 class CAlfLayout;
       
    32 
       
    33 namespace Alf
       
    34     {
       
    35 class CAlfWidgetControl;
       
    36 class IAlfVariantType;
       
    37 class AlfReferenceToVisual;
       
    38 class IAlfVisualTemplate;
       
    39 class AlfElementImpl;
       
    40 class IfId;
       
    41 
       
    42 /** @class AlfElement alfelement.h "alf/alfelement.h"
       
    43  *  The implementation of a generic element. Elements can be used,
       
    44  *  e.g., from declaration, to describe a specific part of
       
    45  *  the presentation of a component. The presentation may
       
    46  *  be predefined, or it may depend on the component data.
       
    47  *
       
    48  *  @lib alfwidgetmodel.lib
       
    49  *  @since S60 ?S60_version
       
    50  *  @status Draft
       
    51  *  @interfaces IAlfAttributeOwner, IAlfElement
       
    52  *	@attributes duiuimodel::tactileattributes::KEventInput\n
       
    53  *				duiuimodel::tactileattributes::KFeedbackType\n
       
    54  *				duiuimodel::commonvisualattributes::KOpacity\n
       
    55  *				duiuimodel::layoutattributes::KPositionX\n
       
    56  *				duiuimodel::layoutattributes::KPositionY\n
       
    57  *				duiuimodel::layoutattributes::KWidth\n
       
    58  *				duiuimodel::layoutattributes::KHeight\n
       
    59  *				duiuimodel::layoutattributes::KMaxWidth\n
       
    60  *				duiuimodel::layoutattributes::KMaxHeight\n
       
    61  *				duiuimodel::layoutattributes::KMinWidth\n
       
    62  *				duiuimodel::layoutattributes::KMinHeight
       
    63  */
       
    64 class AlfElement : public IAlfElement
       
    65     {
       
    66 public:
       
    67 
       
    68 
       
    69     /**
       
    70      * Static cnstructor. The new element is left on the cleanup stack.
       
    71      *
       
    72      * @since S60 ?S60_version
       
    73      * @param aControl  The owner control.
       
    74      * @param aName     The name of the element.
       
    75      * @return New object. Should be added to the control.
       
    76      */
       
    77     OSN_IMPORT AlfElement(CAlfWidgetControl& aControl, const char* aName);
       
    78 
       
    79     /**
       
    80      * Destructor.
       
    81      */
       
    82     OSN_IMPORT virtual ~AlfElement();
       
    83 
       
    84     /**
       
    85      * Returns name of element set via Constructor.
       
    86      *
       
    87      * @since S60 ?S60_version
       
    88      * @return name of element.
       
    89      */
       
    90     OSN_IMPORT const char* name() const;
       
    91 
       
    92     /**
       
    93      * Creates a visual tree in given element.
       
    94      *
       
    95      * @since S60 ?S60_version
       
    96      * @param aElement Element for which visual tree will be created
       
    97      * @param aChildData Data for visual tree to be created
       
    98      * @param aData Data for parent visual tree
       
    99      * @param aIndex Position in parent layout at which new visual tree will be added
       
   100      * @param aDataID Parent visual tree's data id
       
   101      */
       
   102     OSN_IMPORT virtual void createChildVisualTree( IAlfElement* aElement,
       
   103                                                   IAlfVariantType& aChildData,
       
   104                                                   IAlfBranch& aData,
       
   105                                                   int aIndex, uint aDataID );
       
   106 
       
   107     /**
       
   108      * Creates a visual tree with the data given for visuals.
       
   109      *
       
   110      * @exception osncore::AlfElementException Thrown with the error code osncore::EInvalidElement\n 
       
   111      *										  when creation of visual tree fails.
       
   112      * @since S60 ?S60_version
       
   113      * @param aChildData Data for visual tree to be created
       
   114      * @param aParentData Data for parent visual tree
       
   115      * @param aIndex Position in parent layout at which new visual tree will be added
       
   116      * @param aParentDataID Parent visual tree's data id
       
   117      * @param aParentLayout Parent layout to which newly created visual tree will be added
       
   118      * @param aLayoutIndex Position in parent layout at which new visual tree will be added
       
   119      */
       
   120     OSN_IMPORT virtual CAlfVisual* createVisualTree(
       
   121         IAlfVariantType& aChildData, IAlfBranch& aParentData, int aIndex,
       
   122         uint aParentDataID, CAlfLayout* aParentLayout, int aLayoutIndex );
       
   123 
       
   124     /**
       
   125      * Creates a visual tree with the data given for visuals.
       
   126      *
       
   127      * @exception std::bad_alloc 
       
   128      * @exception osncore::AlfVisualException Thrown with the error code osncore::ECanNotCreateVisual\n 
       
   129      *										  when creation of visual fails.
       
   130      * @exception osncore::AlfVisualException Thrown with the error code osncore::EInvalidElement\n 
       
   131      *										  when wrond data id is supplied.
       
   132 	 * @exception std::bad_alloc     
       
   133      * @since S60 ?S60_version
       
   134      * @param aData Data for visual tree to be created
       
   135      * @param aDataID Parent visual tree's data id
       
   136      * @param aParentLayout Parent layout to which newly created visual tree will be added
       
   137      * @param aLayoutIndex Position in parent layout at which new visual tree will be added
       
   138      */
       
   139     OSN_IMPORT virtual CAlfVisual* createVisualTree(
       
   140         IAlfVariantType& aData, uint aDataID,
       
   141         CAlfLayout* aParentLayout, int aLayoutIndex );
       
   142 
       
   143     /**
       
   144      * Removes visual tree from given element.
       
   145      *
       
   146      * @since S60 ?S60_version
       
   147      * @param aElement Element from which visual tree is to be removed
       
   148      * @param aData
       
   149      * @param aIndex 
       
   150      * @param aDataID 
       
   151      */
       
   152     OSN_IMPORT virtual void removeChildVisualTree( IAlfElement* aElement,
       
   153                                                   IAlfBranch& aData,
       
   154                                                   int aIndex, uint aDataID );
       
   155 
       
   156     /**
       
   157      * Removes visual tree.
       
   158      *
       
   159      * @exception osncore::AlfVisualException Thrown with the error code osncore::EInvalidElement\n 
       
   160      *										  when removal of visual tree fails.
       
   161      * @since S60 ?S60_version
       
   162      * @param aParentData
       
   163      * @param aIndex 
       
   164      * @param aParentDataID 
       
   165      */
       
   166     OSN_IMPORT virtual void removeVisualTree( IAlfBranch& aParentData,
       
   167                                              int aIndex, uint aParentDataID );
       
   168 
       
   169     /**
       
   170      * Removes visual tree.
       
   171      *
       
   172      * @exception osncore::AlfVisualException Thrown with the error code osncore::EInvalidElement\n 
       
   173      *										  when removal of visual tree fails.
       
   174      * @since S60 ?S60_version
       
   175      * @param aData
       
   176      * @param aDataID 
       
   177      */
       
   178     OSN_IMPORT virtual void removeVisualTree( IAlfVariantType& aData,
       
   179                                              uint aDataID );
       
   180 
       
   181     /**
       
   182      * Updates the visual tree.
       
   183      *
       
   184      * @exception osncore::AlfVisualException Thrown with the error code osncore::EInvalidElement\n 
       
   185      *										  when a visual can not be created.
       
   186      * @since S60 ?S60_version
       
   187      * @param aNewData
       
   188      * @param aOldData 
       
   189      * @param aDataID 
       
   190      */
       
   191     OSN_IMPORT virtual void updateVisualTree( IAlfVariantType& aNewData,
       
   192                                                   IAlfVariantType& aOldData,
       
   193                                              uint aDataID );
       
   194 
       
   195     /**
       
   196      * Replaces the visual tree.
       
   197      *
       
   198      * @exception osncore::AlfVisualException Thrown with the error code osncore::EInvalidElement\n 
       
   199      *										  when old data id is wrong.
       
   200      * @since S60 ?S60_version
       
   201      * @param aData
       
   202      * @param aDataID 
       
   203      * @param aOldDataID 
       
   204      */
       
   205     OSN_IMPORT void replaceVisualTree( IAlfVariantType& aData, 
       
   206                                        uint aDataID, uint aOldDataID );
       
   207 
       
   208     /**
       
   209      * Add a new visual tree to the element.
       
   210      * Used by derived classes.
       
   211      *
       
   212      * @exception osncore::AlfVisualException Thrown with the error code osncore::EInvalidElement\n 
       
   213      *										  when either the visual is NULL or data id is wrong.
       
   214      * @exception std::bad_alloc 
       
   215      * @since S60 ?S60_version
       
   216      * @param aVisualTree visual to be appended.
       
   217      * @param aDataID   data id of the visual.
       
   218      */
       
   219     OSN_IMPORT void addVisualTree(CAlfVisual* aVisualTree, uint aDataID);
       
   220 
       
   221     /**
       
   222      * Updates the Data ids in an the element.
       
   223      *
       
   224      * @since S60 ?S60_version
       
   225      * @param aParentBranch Data in which IDs to be updated
       
   226      * @param aStartIndex Index from which IDs to be updated
       
   227      * @param aOffset Amount by which IDs are increased/decreased
       
   228      * @param aOldParentDataId Not used.
       
   229      * @param aParentDataID Parent data id of the element
       
   230      */
       
   231     OSN_IMPORT void updateDataIDs( IAlfBranch& aParentBranch, int aStartIndex,
       
   232                                  int aOffset, uint aOldParentDataId, uint aParentDataID );
       
   233 
       
   234     /**
       
   235      * Returns the default parent layout of visual tree in an element.
       
   236      *
       
   237      * @exception osncore::AlfVisualException Thrown with the error code osncore::EInvalidVisual\n 
       
   238      *										  when wrong data id is supplied.
       
   239      * @since S60 ?S60_version
       
   240      * @param aParentDataIS
       
   241      * @return Parent layout
       
   242      */
       
   243     OSN_IMPORT CAlfLayout* defaultParentLayout(uint aParentDataID);
       
   244 
       
   245     /**
       
   246      * Set reference to the default parent layout.
       
   247      *
       
   248      * @since S60 ?S60_version
       
   249      * @param aReference The reference to the default parent layout.
       
   250      */
       
   251     OSN_IMPORT void setDefaultParentLayout(AlfReferenceToVisual* aReference);
       
   252 
       
   253     /**
       
   254      * Finds visual with the given name and id in visual tree of element.
       
   255      *
       
   256      * @since S60 ?S60_version
       
   257      * @param aName Name of the visual
       
   258      * @param aDataID Data id of the visual
       
   259      * @return Visual.Returns NULL if no matching visual is found.
       
   260      */
       
   261     OSN_IMPORT CAlfVisual* findVisual(const char* aName, uint aDataID);
       
   262 
       
   263     /**
       
   264      * Get visual from the data id.
       
   265      *
       
   266      * @since S60 ?S60_version
       
   267      * @param aDataID data id of the visual.
       
   268      */
       
   269     OSN_IMPORT CAlfVisual* findVisual(uint aDataID);
       
   270     
       
   271     /**
       
   272      * Returns the data id of given visual.
       
   273      *
       
   274      * @since S60 ?S60_version
       
   275      * @param aVisual Reference to visual whose data id is needed.
       
   276      * @return Data id of the visual
       
   277      */
       
   278     OSN_IMPORT uint dataID(const CAlfVisual& aVisual) const;
       
   279 
       
   280     /**
       
   281      * Returns parent element of the element.
       
   282      *
       
   283      * @since S60 ?S60_version
       
   284      * @return Parent element. NULL, if there is no parent element.
       
   285      */
       
   286     OSN_IMPORT const IAlfElement* parentElement() const;
       
   287 
       
   288     /**
       
   289      * Makes the element child of given element.
       
   290      *
       
   291      * @since S60 ?S60_version
       
   292      * @param aParent Parent element.
       
   293      */
       
   294     OSN_IMPORT void setParentElement(IAlfElement& aParent);
       
   295     
       
   296     /**
       
   297      * Sets the visual template for the element. This element
       
   298      * will acquire ownership of the visual template hierarchy
       
   299      * under the given visual template.
       
   300      * Call to this method cannot throw an exception.
       
   301      *
       
   302      * @since S60 ?S60_version
       
   303      * @param aTemplate Root of the visual template hierarchy to be set
       
   304      *                  into the widget element.
       
   305      */
       
   306     OSN_IMPORT void setVisualTemplate(IAlfVisualTemplate& aTemplate) throw();
       
   307     
       
   308     /**
       
   309      * Returns the root visual template of the visual template hierarchy
       
   310      * owned by this element. Call to this method cannot throw an exception.
       
   311      *
       
   312      * @since S60 ?S60_version
       
   313      * @param aType A descriptor to identify the type of the queried interface.
       
   314      * @return The queried interface, or NULL if the interface is not
       
   315      *         supported or available.
       
   316      */
       
   317     OSN_IMPORT IAlfVisualTemplate* getVisualTemplate() const throw();
       
   318         
       
   319     /**
       
   320      * Destroyes the visual template object assigned to this element and the whole
       
   321      * visual template hierarchy under it.
       
   322      *
       
   323      * @since S60 ?S60_version
       
   324      */
       
   325     OSN_IMPORT void destroyVisualTemplate() throw();
       
   326 
       
   327      /**
       
   328      * Removes the visual template from this element. Returns pointer to the removed visual
       
   329      * template object. The ownership of the visual template object is transferred to the
       
   330      * caller. Call to this method cannot throw an exception.
       
   331      *
       
   332      * @since S60 ?S60_version
       
   333      */
       
   334     OSN_IMPORT IAlfVisualTemplate* removeVisualTemplate() throw();
       
   335     
       
   336     /**
       
   337      * Getter for the type identifier of this class.
       
   338      *
       
   339      * @since S60 ?S60_version
       
   340      * @return A descriptor to identify the type of this class.
       
   341      */
       
   342 
       
   343     /**
       
   344      * Template getter for interfaces provided by the element classes.
       
   345      * The type of the queried interface is specified by the
       
   346      * template parameter.
       
   347      *
       
   348      * @since S60 ?S60_version
       
   349      * @param aElement The element to get the interface for.
       
   350      * @return The queried interface, or NULL if the interface is not
       
   351      *         supported or available.
       
   352      */
       
   353     template <class T>
       
   354     static T* makeInterface( AlfElement* aElement );
       
   355 
       
   356 // from base class IAlfInterfaceBase
       
   357 
       
   358     /**
       
   359      * From IAlfInterfaceBase.
       
   360      * Getter for interfaces provided by the element classes.
       
   361      * Derived classes should always call the base class method
       
   362      * from the overridden MakeInterface.
       
   363      *
       
   364      * @since S60 ?S60_version
       
   365      * @param aType A descriptor to identify the type of the queried interface.
       
   366      * @return The queried interface, or NULL if the interface is not
       
   367      *         supported or available.
       
   368      */
       
   369     OSN_IMPORT virtual IAlfInterfaceBase* makeInterface( const IfId& aType );
       
   370     
       
   371     /**
       
   372      * removes and destroys all the visuals in the element.
       
   373      *
       
   374      * @since S60 ?S60_version
       
   375      * @param aTimeMilliseconds the animation time for remove.
       
   376      */    
       
   377     OSN_IMPORT void removeAndDestroyVisuals( int aTimeMilliseconds );
       
   378 
       
   379     /**
       
   380      * from IAlfElement
       
   381      */
       
   382     OSN_IMPORT bool contains(CAlfVisual& aVisual) const;
       
   383     
       
   384 protected:
       
   385 
       
   386     /**
       
   387      * The protected constructor.
       
   388      *
       
   389      * @since S60 ?S60_version
       
   390      */
       
   391     OSN_IMPORT AlfElement();
       
   392 
       
   393     /**
       
   394      * The second phase constructor.
       
   395      * The element is added to the control.
       
   396      *
       
   397 	 * @exception std::bad_alloc     
       
   398      * @since S60 ?S60_version
       
   399      * @param aControl  The owner control.
       
   400      * @param aName     The name of the element.
       
   401      */
       
   402     OSN_IMPORT void construct( CAlfWidgetControl& aControl, const char* aName );
       
   403 
       
   404     /**
       
   405      * APi to get the control containing the element.
       
   406      *
       
   407      * @since S60 ?S60_version
       
   408      */
       
   409     OSN_IMPORT CAlfWidgetControl& control();
       
   410 
       
   411 private:
       
   412 
       
   413     int findFromArray( uint aDataID ) const;
       
   414     
       
   415 private: // data
       
   416 
       
   417     auto_ptr<AlfElementImpl> mData;
       
   418     };
       
   419 
       
   420 #include "alf/alfelement.inl"
       
   421 
       
   422     } // namespace Alf
       
   423 #endif // ALFELEMENT_H