/*
* 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 MCLFCUSTOMGROUPER_H
#define MCLFCUSTOMGROUPER_H

//  INCLUDES
#include <e32std.h>

// FORWARD DECLARATIONS
class MCLFCustomGrouperExt;
class MCLFItem;

// CLASS DECLARATION

/**
*  Custom grouper interface of Content Listing Framework.
*  With this interface, client can add own custom grouper
*  to its List Model. Custom grouper is used for grouping list model items.
*  For example, List Model of music files can be grouped by genre or artist
*  name by using this interface.
*  Use ContentListingFactory to create items for new groups (MCLFModifiableItem).
*  <br><br>
*  Example:
*  @code
*  // This grouper will overwrite the source list and add three items to model.
*  void CMyGrouper::GroupItemsL( const TArray<MCLFItem*>& aSourceList,
*                                RPointerArray<MCLFItem>& aGroupedList )
*      {
*      _LIT( KTest, "test" );
*      MCLFModifiableItem* item = ContentListingFactory::NewModifiableItemLC();
*      item->AddFieldL( ECLFFieldIdName, KTest );
*      aGroupedList.AppendL( item );
*      CleanupStack::Pop(); // item
*
*      _LIT( KTest1, "test1" );
*      item = ContentListingFactory::NewModifiableItemLC();
*      item->AddFieldL( ECLFFieldIdName, KTest1 );
*      aGroupedList.AppendL( item );
*      CleanupStack::Pop(); // item
*
*      _LIT( KTest2, "test2" );
*      item = ContentListingFactory::NewModifiableItemLC();
*      item->AddFieldL( ECLFFieldIdName, KTest2 );
*      aGroupedList.AppendL( item );
*      CleanupStack::Pop(); // item
*      }
*  @endcode
*
*  Custom grouper is activated and removed by calling method
*  MCLFItemListModel::SetCustomGrouper
*
*  @lib ContentListingFramework.lib
*  @since S60 3.1
*/
class MCLFCustomGrouper
    {
    public: // New functions

        /**
        * Abstract method for grouping Content Listing Framework items of
        * list models. This method is called when the grouping process is
        * executed by refreshing the model.
        * @since S60 3.1
        * @param aSourceList Source list. Contains all items that are in
        *        the list model when the grouping process starts.
        * @param aGroupedList Grouped/destination list. While grouping, each
        *        group should be added to this list. The list model will
        *        contain only these items when the grouping process is
        *        finished.
        */
        virtual void GroupItemsL( const TArray<MCLFItem*>& aSourceList,
                                  RPointerArray<MCLFItem>& aGroupedList ) = 0;

    protected:

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

    private: // Extension interface

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

    };

#endif      // MCLFCUSTOMGROUPER_H

// End of File