diff -r 4ea6f81c838a -r 0e9bb658ef58 mmuifw_plat/mul_datamodel_api/inc/mul/imulmodel.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mmuifw_plat/mul_datamodel_api/inc/mul/imulmodel.h Wed Sep 01 12:23:18 2010 +0100 @@ -0,0 +1,332 @@ +/* +* Copyright (c) 2007-2008 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: Interface for model +* +*/ + + +#ifndef I_MULMODEL_H +#define I_MULMODEL_H + +//Includes +#include +#include +#include +#include +#include +#include +#include +#include +#include + +namespace osncore + { + class UString; + } +using namespace osncore; + +namespace Alf + { + +namespace mulmodel + { + static const IfId Ident= + { + 0, "mulmodel" + }; + + static const char* const KBaseElementName = "base" ; + static const char* const KItemElementName = "item" ; + } + +// Forward Declarations +class MulVisualItem; +class MulDataPath; +class IMulModelProvider; + +/*! @class IMulModel +* +* @brief An interface for the data model. +* +* Client that creates the model own the model. +* Client can use this interface to update data model. +* +*/ +class IMulModel : public IMulModelBase, public IAlfModel + { + +public: + + /** + * Getter for the type identifier of this interface. + * + * @return A descriptor to identify the type of this interface. + */ + static inline const IfId& type() + { + return mulmodel::Ident; + } + + /** + * Virtual destructor. + */ + virtual ~IMulModel() {} + + /** + * Informs the data model that new items have been added to client's + * internal model. Data model is expected to sync its indices as a + * result. + * Note: This API will never give an exception. + * + * @param aIndex Position where items were inserted. + * @param aCount Number of items inserted. + * @param aPath Path of parent item in the data hierarchy. + * Default is Null path i.e. no parent. + */ + virtual void Insert( int aIndex, int aCount, + const MulDataPath& aPath = MulDataPath() ) = 0 ; + + /** + * Informs the data model that items have been removed from the client's. + * internal data model. Data model is expected to sync its indices as a + * result. + * Note: This API will never give an exception. + * + * @param aIndex Position from where items have to be removed. + * @param aCount Number of items to be removed.\ + * @param aPath Path of parent item in the data hierarchy. + * Default is Null path i.e. no parent. + */ + virtual void Remove( int aIndex, int aCount, + const MulDataPath& aPath = MulDataPath() ) = 0; + + /** + * Informs the data model that an item has been updated in the client's + * internal model. Data model will use to input to determine whether + * a visualization change is required. If yes, the model will request the + * provider for updated data. + * Note: This API will never give an exception. + * + * @param aIndex Position from where items have to be updated. + * @param aCount Number of items to be updated. + * @param aPath Path of parent item in the data hierarchy. + * Default is Null path i.e. no parent. + */ + virtual void Update( int aIndex, int aCount, + const MulDataPath& aPath = MulDataPath() ) = 0; + + /** + * A refresh data request. Informs that the data model has to be + * repopulated with mentioned number of items. So the data model + * will remove all the existing data and issue request to the + * provider for new data. + * Note: This API will never give an exception. + * + * @param aCount Number of items to be repopulated. + * @param aPath Path of parent item in the data hierarchy. + * Default is Null path i.e. no parent. + */ + virtual void Refresh( int aCount, const MulDataPath& aPath = MulDataPath() ) = 0; + + /** + * Provide data for the specified item. This is a unified API for + * adding & updating data. + * + * @param aIndex Position of item to be updated. + * @param aVisualItem Collection of attributes. Ownership is transfered. + * @param aPath Path of parent item in the data hierarchy. + * Default is Null path i.e. no parent. + * @throw Invalid Argument, in case index is out of bound or visual + * item is NULL. + * @throw Logic Error, in case item could not be updated. + */ + virtual void SetData( int aIndex, std::auto_ptr aVisualItem, + const MulDataPath& aPath = MulDataPath() ) = 0; + + /** + * Get the data for item at the specified index. + * + * @param aIndex Position of item in the data model. + * @param aPath Path of parent item in the data hierarchy. + * Default is Null path i.e. no parent. + * @return A constant reference to the data at the given index. + * @throw Invalid Argument, in case index is out of bound. + */ + virtual const MulVisualItem* Data( int aIndex, + const MulDataPath& aPath = MulDataPath() ) const = 0; + + /** + * Get the count of items in the model. + * + * @param aPath Path of parent item in the data hierarchy. + * Default is Null path i.e. no parent. + * @return Count of items in the model. + */ + virtual int Count( const MulDataPath& aPath = MulDataPath() ) const = 0; + + /** + * Set the data provider for the model. + * Note: This API will be removed in future. + * Clients would be able to specify the provider to the model at + * the time of the construction. + * + * @param aDataProvider Handle to the data provider. + * @throw Logic Error, in case same accessor object is passed again. + */ + virtual void SetDataProvider( const IMulModelProvider& aDataProvider ) = 0; + + /** + * Set the default logical template id for widget elements. + * Logical templates map to visualization of the element(s). + * + * @param aTemplateId Logical template id for the widget elements. + */ + virtual void SetTemplate( mulwidget::TLogicalTemplate aDefaultTemplate ) = 0; + + /** + * Set the logical template id for a specific widget element. + * Logical templates map to visualization of the element. + * + * @param aItemIndex Unique id of item of which template needs to be applied. + * @param aTemplateId Logical template id for the widget element. + * @param aPath Path of parent item in the data hierarchy. + * Default is Null path i.e. no parent. + * @throw Invalid Argument, in case index is out of bound. + */ + virtual void SetTemplate( int aItemIndex, mulwidget::TLogicalTemplate aDefaultTemplate , + const MulDataPath& aPath = MulDataPath() )=0; + + /** + * Set the data window/cache size of the Data model. + * This API can be used to over-ride the data window size of the data model + * already set by the widget. This can be used by clients to set the buffer + * size different from what the widget has specified. + * + * @param aSize Size of buffer. + * @throw Invalid Argument, incase the buffer size is negative. + */ + virtual void SetDataWindow( int aSize ) = 0; + + /** + * Get the buffer size defined for the data model. + * + * @return Size of data window. + */ + virtual int DataWindow( ) const = 0; + + /** + * Set highlighted item in the model. + * + * @param aItemIndex Index of item. + * @param aPath Path of parent item in the data hierarchy. + * Default is Null path i.e. no parent. + * + * Examples: + * @code + * Set index of the item to be highlighted. + * + * mListWidget->SetHighlight(highlight); + * @endcode + */ + virtual void SetHighlight( int aItemIndex, const MulDataPath& aPath = MulDataPath() ) = 0; + + /** + * Get the index of the current highlighted item from the model. + * + * @return Highlighted item index. + * + * Examples: + * @code + * Get index of the highlighted item. + * + * int highlight = mListWidget->Highlight(); + * @endcode + */ + virtual int Highlight() = 0; + + /** + * Get the index of the current highlighted item along with the path + * of the root item in the data hierarchy. + * + * @param aPath Path of parent item in the data hierarchy. Out parameter. + * @return Highlighted item index. + * + * Examples: + * @code + * Get index of the highlighted item. + * + * int highlight = mListWidget->Highlight(); + * @endcode + */ + virtual int Highlight( MulDataPath& aPath ) = 0; + + /** + * Function for setting the item(s) Marked or Unmarked. For mark and + * unmark operations, indices of items should be provided. + * + * @param aType Type of marking operation to be performed. + * @param aItemsIndex Indices of the items to be changed + * @throw Invalid Argument, if type is specified as mark-all and unmark-all. + * + * Examples: + * @code + * Mark the selected item + * + * mListWidget->SetMarkedIndices( MulWidgetDef::EMulMark, itemIndex ); + * @endcode + */ + virtual void SetMarkedIndices( MulWidgetDef::TMulWidgetMarkingType aType , + const std::vector& aItemsIndex, + const MulDataPath& aPath = MulDataPath() ) = 0; + + /** + * Function for setting the item(s) Marked or Unmarked. + * For mark all and unmark all operations use this overloaded version. + * + * @param aType Type of marking operation to be performed. + * @throw Invalid Argument, if type is specified as mark and unmark. + * + * Examples: + * @code + * Mark all items + * + * mListWidget->SetSelection( MulWidgetDef::EMulMarkAll ); + * @endcode + */ + virtual void SetMarkedIndices( + MulWidgetDef::TMulWidgetMarkingType aType = MulWidgetDef::EMulMarkAll + ) = 0; + + /** + * Gets the indices of the currently marked items. + * + * @return Array of maked indices. This would return an empty container if no items are marked. + * + * Examples: + * @code + * Get the array of all marked items + * + * std::vector markedItems = mListWidget->MarkIndices(); + * @endcode + */ + virtual const std::vector& MarkedIndices( const MulDataPath& aPath = MulDataPath() ) = 0; + + }; + + } // namespace Alf + +#endif // I_MULMODEL_H + +//End of file +