/*
* Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies). 
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
* which accompanies this distribution, and is available
* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description: 
*
*/


#ifndef MCLFITEMLISTMODEL_H
#define MCLFITEMLISTMODEL_H

//  INCLUDES
#include <CLFContentListing.hrh>
#include <bamdesca.h>

// DATA TYPES
/**
*  Content Listing Framework list model refresh type.
*/
enum TCLFRefreshTypeFlags
    {
    /// Post filter is refreshed
    ECLFRefreshPostFilter   = 0x1,
    /// Grouping is refreshed
    ECLFRefreshGrouping     = 0x2,
    /// Sorting is refreshed
    ECLFRefreshSorting      = 0x4,
    /// All filters are used
    ECLFRefreshAll          = 0xFFFFFFFF
    };

// FORWARD DECLARATIONS
class MCLFItemListModelExt;
class MCLFItem;
class MCLFPostFilter;
class MCLFCustomGrouper;
class MCLFPostFilter;
class MCLFSortingStyle;
class MCLFCustomSorter;
class TResourceReader;

// CLASS DECLARATION

/**
*  List Model for Content Listing Framework.
*  This model is used to list Content Listing items. These items provide
*  infomation of media files on the device and one item represents one media
*  file. The model can be manipulated by sorters, post filters and groupers.
*  List Model is created by using Content Listing Engine.<br><br>
*  Usage:
*  @code
*  // Create a new List Model instance
*  MCLFItemListModel* listModel = iEngine->CreateListModelLC( *myObserver );
*
*  // Append music-type to wanted types array to exclude
*  // all other files than music files from the list model
*  RArray<TCLFMediaType> myMediaTypes;
*  CleanupClosePushL( myMediaTypes );
*  myMediaTypes.AppendL( ECLFMediaTypeMusic );
*
*  // Set wanted types with SetWantedMimeTypesL or/and SetWantedMediaTypesL.
*  // You can add both if you want.
*  listModel->SetWantedMediaTypesL( myMediaTypes.Array() );
*  CleanupStack::PopAndDestroy( &myMediaTypes );
*
*  // Set sorting style (if you want to sort items)
*  listModel->SetSortingStyle( mySortingStyle );
*
*  // You can also add post filter, custom sorter and custom grouper to model.
*
*  // Refresh the List Model.
*  // The model will fetch items from server and use post filter to filter items,
*  // grouping style or custom grouper to group items and finally sort items
*  // with sorting style or custom sorter.
*  listModel->RefreshL();
*
*  // You can also refresh the post filter and sorting only. This call does not
*  // fetch items from the server. The model is only filtered and sorted.
*  listModel->RefreshL( ECLFRefreshPostFilter | ECLFRefreshSorting );
*  @endcode
*
*  @lib ContentListingFramework.lib
*  @since S60 3.1
*/
class MCLFItemListModel
    {
    public:  // Constructors and destructor

        /**
        * Destructor.
        */
        virtual ~MCLFItemListModel() {}

    public: // New functions

        /**
        * Get Content Listing Framework item from the List Model.
        * @since S60 3.1
        * @pre aIndex >= 0 && aIndex < ItemCount()
        * @param aIndex Index of the item
        * @return Content Listing Framework item
        */
        virtual const MCLFItem& Item( TInt aIndex ) const = 0;

        /**
        * Get number of items that are in the model.
        * @since S60 3.1
        * @return Count of items
        */
        virtual TInt ItemCount() const = 0;

        /**
        * Activate or remove Sorting style.
        * Setting a new sorting style will remove all old secondary sorters.
        * Removing the sorting will also remove all secondary sorters too.
        * @since S60 3.1
        * @param aSortingStyle Sorting style to activate,
        *        if the pointer is NULL then sorting styles are removed
        */
        virtual void SetSortingStyle( MCLFSortingStyle* aSortingStyle ) = 0;

        /**
        * Append a secondary sorting style to the list model.
        * If an item doesn't have the field defined by primary or
        * any previous secondary sorting style, the items are sorted using
        * the next secondary sorting style. When a sorting style is
        * appended using this method, it becomes the least significant
        * sorting style until a new one is added after it.
        * Items with undefined fields are placed before or after items
        * with defined fields, depending on the undefined field position
        * setting in MCLFSortingStyle.
        * @since S60 3.1
        * @param aSortingStyle Secondary sorting style to add.
        */
        virtual void AppendSecondarySortingStyleL(
                                    MCLFSortingStyle& aSortingStyle ) = 0;

        /**
        * Activate or remove custom sorter.
        * Custom sorter will overwrite sorting style (if there is a sorting
        * style activated). See MCLFCustomSorter for an example implementation
        * of a custom sorter.
        * @since S60 3.1
        * @param aCustomSorter Custom sorter to activate.
        *        If the pointer is NULL, sorting style is used (if there is one
        *        activated)
        */
        virtual void SetCustomSorter( MCLFCustomSorter* aCustomSorter ) = 0;

        /**
        * Activate a grouping style for the List Model. Use ECLFNoGrouping as
        * the grouping style if you want to remove grouping.
        * Default grouping style is ECLFNoGrouping.
        * @since S60 3.1
        * @param aGrouping Grouping style to activate
        */
        virtual void SetGroupingStyle( TCLFGrouping aGrouping ) = 0;

        /**
        * Activate or remove custom grouper. See MCLFCustomGrouper for an example
        * implementation of a custom grouper.
        * Custom grouper will overwrite grouping style.
        * @since S60 3.1
        * @param aCustomGrouper Custom grouper to activate,
        *        if pointer is NULL then then grouping style is used
        */
        virtual void SetCustomGrouper( MCLFCustomGrouper* aCustomGrouper ) = 0;

        /**
        * Activate or remove post filter. Post filter removes items from the
        * List Model. See MCLFPostFilter for an example implementation of a
        * post filter.
        * @since S60 3.1
        * @param aPostFilter Post filter to activate,
        *        if pointer is NULL then active post filter will be removed.
        */
        virtual void SetPostFilter( MCLFPostFilter* aPostFilter ) = 0;

        /**
        * Wanted mime types of media files that will be requested to the model.
        * Overwrites old mime types if they were set.
        * @since S60 3.1
        * @param aMimeTypes List of wanted mime types. Mime types can contain
        *                   wildcard characters "*" and "?", where "*" matches
        *                   zero or more consecutive occurrences of any character
        *                   and "?" matches a single occurrence of any character
        */
        virtual void SetWantedMimeTypesL( const MDesCArray& aMimeTypes ) = 0;

        /**
        * Wanted mime types of media files that will be requested to the model.
        * Overwrites old mime types if they were set.
        * @since S60 3.1
        * @param aResource Resource reader to mime type list resource.
        *                  Use resource struct CLF_MIME_TYPE_ARRAY.
        */
        virtual void SetWantedMimeTypesL( TResourceReader& aResource ) = 0;

        /**
        * Wanted media types of media files that will be requested to the model.
        * Overwrites old media types if they were set.
        * @since S60 3.1
        * @param aMediaTypes List of wanted media types
        */
        virtual void SetWantedMediaTypesL(
                            const TArray<TInt>& aMediaTypes ) = 0;


        /**
        * Wanted media types of media files that will be requested to the model.
        * Overwrites old media types if they were set.
        * @since S60 3.1
        * @param aResource Resource reader to media type list resource.
        *                  Use resource struct CLF_MEDIA_TYPE_ARRAY
        */
        virtual void SetWantedMediaTypesL( TResourceReader& aResource ) = 0;

        /**
        * Refresh the model. This function is asynchronous (non-blocking) and
        * MCLFOperationObserver is called when the refresh operation is
        * completed. <br>
        * <br>
        * Operations in refresh are executed in the following order:<br>
        * 1. Model gets wanted items from server.
        *    Use SetWantedMediaTypesL and/or SetWantedMimeTypesL to define
        *    wanted items.<br>
        * 2. Model uses post filter to filter items.<br>
        * 3. Model groups items if grouping is selected.<br>
        * 4. Model sorting items.<br>
        * @since S60 3.1
        */
        virtual void RefreshL() = 0;

        /**
        * Refresh the model. This function is synchronous (blocking). Use
        * parameter(s) to define the type of refresh. See TCLFRefreshTypeFlags
        * for refresh flags.
        * @since S60 3.1
        * @param aRefreshType Flag(s) to use for refreshing.
        */
        virtual void RefreshL( TInt32 aRefreshType ) = 0;

        /**
        * Cancel asynchronous refresh operation.
        * @since S60 3.1
        */
        virtual void CancelRefresh() = 0;

    private: // Extension interface

        /**
        * This member is internal and not intended for use.
        */
        virtual MCLFItemListModelExt* Extension() { return NULL; }

    };

#endif      // MCLFITEMLISTMODEL_H

// End of File