/*

* 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 <alf/ialfinterfacebase.h>

#include <alf/ialfmodel.h>

#include <alf/alftypes.h>

#include <mul/imulmodelbase.h>

#include <mul/imulwidgetdef.h>

#include <mul/imulwidget.h>

#include <mul/muldatapath.h>

#include <vector>

#include <memory>

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.

     * <b>Note:</b> 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.

      * <b>Note:</b> 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.

      * <b>Note:</b> 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.

      * <b>Note:</b> 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<MulVisualItem> 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. 

     * <b>Note:</b> 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.

	  *

	  * <B>Examples:</b>

	  * @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.

     *

	 * <B>Examples:</b>

	 * @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.

     *

	 * <B>Examples:</b>

	 * @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. 

	 *

	 * <B>Examples:</b>

	 * @code

     * Mark the selected item

     *

	 *      mListWidget->SetMarkedIndices( MulWidgetDef::EMulMark, itemIndex );

	 * @endcode

	 */ 

	virtual void SetMarkedIndices( MulWidgetDef::TMulWidgetMarkingType aType ,

								   const std::vector<int>& 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. 

     *

	 * <B>Examples:</b>

	 * @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. 

	 *

	 * <B>Examples:</b>

	 * @code

	 * Get the array of all marked items

	 *

	 *      std::vector<int> markedItems = mListWidget->MarkIndices();

	 * @endcode

	 */

	virtual const std::vector<int>& MarkedIndices( const MulDataPath& aPath = MulDataPath() ) = 0;    

    };

    } // namespace Alf

#endif // I_MULMODEL_H

//End of file