--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/mmuifw_plat/alf_widgetmodel_api/inc/alf/ialfelement.h Wed Sep 01 12:23:18 2010 +0100
@@ -0,0 +1,373 @@
+/*
+* 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: The interface and the basic implementation for presentation elements.
+*
+*/
+
+
+#ifndef I_ALFELEMENT_H
+#define I_ALFELEMENT_H
+
+#include <alf/ialfinterfacebase.h>
+#include <alf/alftypes.h>
+#include <osn/osntypes.h>
+
+class CAlfVisual;
+class CAlfLayout;
+
+using namespace osncore;
+
+namespace duiuimodel
+ {
+class DuiNode;
+ }
+using namespace duiuimodel;
+
+namespace Alf
+ {
+//FORWARD DECLARATION
+class IAlfVariantType;
+class IAlfBranch;
+class IAlfWidgetControl;
+class AlfCustomInitDataBase;
+class IAlfVisualTemplate;
+
+namespace alfelement
+ {
+static const IfId ident=
+ {
+ 0,"alfelement"
+ };
+ }
+
+/**
+ * The interface for presentation elements.
+ * The presentation of a widget can be divided into parts by using
+ * elements. Each element is responsible for populating and maintaining
+ * a specific part of the presentation. The element creates and updates
+ * visual trees according to the data provided by the control. Elements
+ * may also implement presentation logic, such as visual lifetime and
+ * resource management, scrolling, and animations.
+ *
+ * @lib alfwidgetmodel.lib
+ * @since S60 ?S60_version
+ * @status Draft
+ */
+class IAlfElement : public IAlfInterfaceBase
+ {
+public:
+ static inline const IfId& type()
+ {
+ return alfelement::ident;
+ }
+ /**
+ * Get the name of the element.
+ *
+ * @since S60 ?S60_version
+ * @return The name of the element.
+ */
+ virtual const char* name() const = 0;
+
+ /**
+ * Create a new visual tree to the child element of this element.
+ * Some elements, e.g., CAlfRecyclingGridElement and CAlfRecyclingCurvePathElement
+ * implement visual lifetime management to control the creation of the
+ * visual trees in the child elements. This method can be implemented to
+ * control, if the visual tree should be created or not.
+ *
+ * @since S60 ?S60_version
+ * @param aElement The child element.
+ * @param aChildData The data for the new visual tree.
+ * @param aData The parent branch of the added data. Used to determine the
+ * visual trees that have outdated data IDs.
+ *
+ * @param aIndex The index of the new data .
+ */
+ virtual void createChildVisualTree( IAlfElement* aElement,
+ IAlfVariantType& aChildData,
+ IAlfBranch& aData,
+ int aIndex, uint aDataID ) = 0;
+
+ /**
+ *
+ *
+ * @since S60 ?S60_version
+ * @param aData
+ * @param aParentData
+ * @param aIndex
+ * @param aParentDataID
+ * @param aParentLayout
+ * @param aLayoutIndex
+ * @return
+ */
+ virtual CAlfVisual* createVisualTree( IAlfVariantType& aData,
+ IAlfBranch& aParentData,
+ int aIndex, uint aParentDataID,
+ CAlfLayout* aParentLayout,
+ int aLayoutIndex ) = 0;
+
+ /**
+ *
+ *
+ * @since S60 ?S60_version
+ * @param aData
+ * @param aDataID
+ * @param aParentLayout
+ * @param aLayoutIndex
+ * @return
+ */
+ virtual CAlfVisual* createVisualTree( IAlfVariantType& aData,
+ uint aDataID,
+ CAlfLayout* aParentLayout,
+ int aLayoutIndex ) = 0;
+
+ /**
+ *
+ *
+ * @since S60 ?S60_version
+ * @param aElement
+ * @param aData
+ * @param aIndex
+ * @param aDataID
+ * @return void
+ */
+ virtual void removeChildVisualTree( IAlfElement* aElement,
+ IAlfBranch& aData,
+ int aIndex, uint aDataID ) = 0;
+
+ /**
+ *
+ *
+ * @since S60 ?S60_version
+ * @param aParentData
+ * @param aIndex
+ * @param aParentDataID
+ * @return void
+ */
+ virtual void removeVisualTree( IAlfBranch& aParentData, int aIndex,
+ uint aParentDataID ) = 0;
+
+ /**
+ *
+ *
+ * @since S60 ?S60_version
+ * @param aData
+ * @param aDataID
+ * @return void
+ */
+ virtual void removeVisualTree( IAlfVariantType& aData, uint aDataID ) = 0;
+
+ /**
+ * Create or update a visual tree according to the given data. A data id is assigned
+ * to the created visual tree. If a visual tree with the given data id already
+ * exists, the visuals are just updated. The caller is responsible for providing
+ * the parent layout for the visual tree. The default parent layout may or may not
+ * be used.
+ *
+ * @since S60 ?S60_version
+ * @param aData The data for the visuals.
+ * @param aOldData the old data for the visuals. The data, that is replaced.
+ * @param aDataID The data id for the visual tree.
+ * @return The created or updated visual tree.
+ */
+ virtual void updateVisualTree( IAlfVariantType& aNewData,
+ IAlfVariantType& aOldData,
+ uint aDataID ) = 0;
+
+ /**
+ * Replace an existing visual tree with a new one. A data id is used
+ * to find the visual tree to be replaced. A new data id is assigned
+ * to the visual tree, and the visuals are updated according to the
+ * given data. The method is used for recycling visual trees for
+ * a large number of presentation instances (@see CAlfRecyclingGridElement).
+ * The structure of the new visual tree should match the structure
+ * of the replaced visual tree. Otherwise, the visuals structure
+ * needs to be modified by creating and destroying visuals. The visual
+ * tree remains in the same layout as it was before.
+ *
+ * @since S60 ?S60_version
+ * @param aData The data for the new visuals.
+ * @param aDataID The data id for the new visual tree.
+ * @param aOldDataID The data id of the visual tree to be replaced.
+ */
+ virtual void replaceVisualTree( IAlfVariantType& aData,
+ uint aDataID, uint aOldDataID ) = 0;
+
+ /**
+ *
+ *
+ * @since S60 ?S60_version
+ * @param aParentBranch
+ * @param aStartIndex
+ * @param aOffset
+ * @param aOldParentDataId
+ * @param aParentDataID
+ * @return void
+ */
+ virtual void updateDataIDs( IAlfBranch& aParentBranch, int aStartIndex,
+ int aOffset, uint aOldParentDataId,
+ uint aParentDataID ) = 0;
+
+ /**
+ * Get the default parent layout for the visual trees created by this element.
+ * The default parent layout is used for all root level elements (@see RootElement()).
+ *
+ * @since S60 ?S60_version
+ * @param aParentDataID The data id associated with the parent element instance.
+ * @return The default layout for the visual trees created by this element, or NULL
+ * if the default layout does not exist.
+ */
+ virtual CAlfLayout* defaultParentLayout(uint aParentDataID) = 0;
+
+ /**
+ * Find a visual according to the name of the visual and the data id
+ * used to create the visual tree.
+ *
+ * @param aName The name of the visual.
+ * @param aDataID The data id associated with the visual tree.
+ * @return The default layout for the visual trees created by this element.
+ */
+ virtual CAlfVisual* findVisual(const char* aName, uint aDataID) = 0;
+
+ /**
+ * Get the data id of a visual tree created by this element.
+ *
+ * @param aVisual The root of the visual tree.
+ * @return The data id associated with the visual tree.
+ */
+ virtual uint dataID(const CAlfVisual& aVisual) const = 0;
+
+ /**
+ * Get the parent element of this element. Some elements may have
+ * child elements (@see CAlfRecyclingGridElement). In this case,
+ * the parent element is responsible for populating the child elements.
+ * Elements with no parent element are called root elements and
+ * populated directly by the control.
+ *
+ * @since S60 ?S60_version
+ * @return The parent element, or NULL if this is a root element.
+ */
+ virtual const IAlfElement* parentElement() const = 0 ;
+
+ /**
+ * Set the parent element for this element.
+ *
+ * @since S60 ?S60_version
+ * @param aParent The parent element of this element.
+ */
+ virtual void setParentElement(IAlfElement& aParent) = 0;
+
+ /**
+ * removes and destroys all the visuals
+ *
+ * @since S60 ?S60_version
+ * @param aTimeMilliseconds the animation time for remove.
+ */
+ virtual void removeAndDestroyVisuals( int aTimeMilliseconds ) = 0;
+
+ /**
+ * Checks if referred visual is part of this element.
+ *
+ * @since S60 ?S60_version
+ * @param aVisual reference to visual under inspection.
+ */
+ virtual bool contains(CAlfVisual& aVisual) const = 0;
+
+ /**
+ * Sets the visual template for the element. This element
+ * will acquire ownership of the visual template hierarchy
+ * under the given visual template.
+ * Call to this method cannot throw an exception.
+ *
+ * @since S60 ?S60_version
+ * @param aTemplate Root of the visual template hierarchy to be set
+ * into the widget element.
+ */
+ virtual void setVisualTemplate(IAlfVisualTemplate& aTemplate) throw() = 0;
+
+ /**
+ * Returns the root visual template of the visual template hierarchy
+ * owned by this element. Call to this method cannot throw an exception.
+ *
+ * @since S60 ?S60_version
+ * @param aType A descriptor to identify the type of the queried interface.
+ * @return The queried interface, or NULL if the interface is not
+ * supported or available.
+ */
+ virtual IAlfVisualTemplate* getVisualTemplate() const throw() = 0;
+
+ /**
+ * Destroyes the visual template object assigned to this element and the whole
+ * visual template hierarchy under it. Call to this method cannot throw an exception.
+ *
+ * @since S60 ?S60_version
+ */
+ virtual void destroyVisualTemplate() throw() = 0;
+
+ /**
+ * Removes the visual template from this element. Returns pointer to the removed visual
+ * template object. The ownership of the visual template object is transferred to the
+ * caller. Call to this method cannot throw an exception.
+ *
+ * @since S60 ?S60_version
+ *
+ * @return The visual template object that was owned by this element. NULL if no visual
+ * template hierarchy was owned by this element.
+ */
+ virtual IAlfVisualTemplate* removeVisualTemplate() throw() = 0;
+
+ /**
+ * Destructor
+ */
+ virtual ~IAlfElement(){}
+ };
+
+
+/**
+ * Placeholder for information required to instantiate an element
+ * 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 AlfElementInitData
+ {
+ /**
+ * Owner control for the element.
+ */
+ IAlfWidgetControl* mControl;
+ /**
+ * Element instance ID.This uniquely identifies every element instance
+ * and is its name. Also see AlfElement::name().
+ */
+ char* mElementId;
+
+ /**
+ * Pointer to node in declaration containing information for the element.
+ */
+ DuiNode* mNode;
+
+ /**
+ * Pointer to custom data passed via factory mechanism
+ * Not Owned.
+ */
+ AlfCustomInitDataBase* mCustomData;
+ };
+
+
+ } // namespace Alf
+#endif // I_ALFELEMENT_H
+
+// End of File