1 /*

     2 * Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: 

    15 *

    16 */

    17 

    18 

    19 #ifndef MCLFCUSTOMGROUPER_H

    20 #define MCLFCUSTOMGROUPER_H

    21 

    22 //  INCLUDES

    23 #include <e32std.h>

    24 

    25 // FORWARD DECLARATIONS

    26 class MCLFCustomGrouperExt;

    27 class MCLFItem;

    28 

    29 // CLASS DECLARATION

    30 

    31 /**

    32 *  Custom grouper interface of Content Listing Framework.

    33 *  With this interface, client can add own custom grouper

    34 *  to its List Model. Custom grouper is used for grouping list model items.

    35 *  For example, List Model of music files can be grouped by genre or artist

    36 *  name by using this interface.

    37 *  Use ContentListingFactory to create items for new groups (MCLFModifiableItem).

    38 *  <br><br>

    39 *  Example:

    40 *  @code

    41 *  // This grouper will overwrite the source list and add three items to model.

    42 *  void CMyGrouper::GroupItemsL( const TArray<MCLFItem*>& aSourceList,

    43 *                                RPointerArray<MCLFItem>& aGroupedList )

    44 *      {

    45 *      _LIT( KTest, "test" );

    46 *      MCLFModifiableItem* item = ContentListingFactory::NewModifiableItemLC();

    47 *      item->AddFieldL( ECLFFieldIdName, KTest );

    48 *      aGroupedList.AppendL( item );

    49 *      CleanupStack::Pop(); // item

    50 *

    51 *      _LIT( KTest1, "test1" );

    52 *      item = ContentListingFactory::NewModifiableItemLC();

    53 *      item->AddFieldL( ECLFFieldIdName, KTest1 );

    54 *      aGroupedList.AppendL( item );

    55 *      CleanupStack::Pop(); // item

    56 *

    57 *      _LIT( KTest2, "test2" );

    58 *      item = ContentListingFactory::NewModifiableItemLC();

    59 *      item->AddFieldL( ECLFFieldIdName, KTest2 );

    60 *      aGroupedList.AppendL( item );

    61 *      CleanupStack::Pop(); // item

    62 *      }

    63 *  @endcode

    64 *

    65 *  Custom grouper is activated and removed by calling method

    66 *  MCLFItemListModel::SetCustomGrouper

    67 *

    68 *  @lib ContentListingFramework.lib

    69 *  @since S60 3.1

    70 */

    71 class MCLFCustomGrouper

    72     {

    73     public: // New functions

    74 

    75         /**

    76         * Abstract method for grouping Content Listing Framework items of

    77         * list models. This method is called when the grouping process is

    78         * executed by refreshing the model.

    79         * @since S60 3.1

    80         * @param aSourceList Source list. Contains all items that are in

    81         *        the list model when the grouping process starts.

    82         * @param aGroupedList Grouped/destination list. While grouping, each

    83         *        group should be added to this list. The list model will

    84         *        contain only these items when the grouping process is

    85         *        finished.

    86         */

    87         virtual void GroupItemsL( const TArray<MCLFItem*>& aSourceList,

    88                                   RPointerArray<MCLFItem>& aGroupedList ) = 0;

    89 

    90     protected:

    91 

    92         /**

    93         * Destructor.

    94         */

    95         virtual ~MCLFCustomGrouper() {}

    96 

    97     private: // Extension interface

    98 

    99         /**

   100         * This member is internal and not intended for use.

   101         */

   102         virtual MCLFCustomGrouperExt* Extension() { return NULL; }

   103 

   104     };

   105 

   106 #endif      // MCLFCUSTOMGROUPER_H

   107 

   108 // End of File