/*
* 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