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 MCLFITEMLISTMODEL_H

    20 #define MCLFITEMLISTMODEL_H

    21 

    22 //  INCLUDES

    23 #include <CLFContentListing.hrh>

    24 #include <bamdesca.h>

    25 

    26 // DATA TYPES

    27 /**

    28 *  Content Listing Framework list model refresh type.

    29 */

    30 enum TCLFRefreshTypeFlags

    31     {

    32     /// Post filter is refreshed

    33     ECLFRefreshPostFilter   = 0x1,

    34     /// Grouping is refreshed

    35     ECLFRefreshGrouping     = 0x2,

    36     /// Sorting is refreshed

    37     ECLFRefreshSorting      = 0x4,

    38     /// All filters are used

    39     ECLFRefreshAll          = 0xFFFFFFFF

    40     };

    41 

    42 // FORWARD DECLARATIONS

    43 class MCLFItemListModelExt;

    44 class MCLFItem;

    45 class MCLFPostFilter;

    46 class MCLFCustomGrouper;

    47 class MCLFPostFilter;

    48 class MCLFSortingStyle;

    49 class MCLFCustomSorter;

    50 class TResourceReader;

    51 

    52 // CLASS DECLARATION

    53 

    54 /**

    55 *  List Model for Content Listing Framework.

    56 *  This model is used to list Content Listing items. These items provide

    57 *  infomation of media files on the device and one item represents one media

    58 *  file. The model can be manipulated by sorters, post filters and groupers.

    59 *  List Model is created by using Content Listing Engine.<br><br>

    60 *  Usage:

    61 *  @code

    62 *  // Create a new List Model instance

    63 *  MCLFItemListModel* listModel = iEngine->CreateListModelLC( *myObserver );

    64 *

    65 *  // Append music-type to wanted types array to exclude

    66 *  // all other files than music files from the list model

    67 *  RArray<TCLFMediaType> myMediaTypes;

    68 *  CleanupClosePushL( myMediaTypes );

    69 *  myMediaTypes.AppendL( ECLFMediaTypeMusic );

    70 *

    71 *  // Set wanted types with SetWantedMimeTypesL or/and SetWantedMediaTypesL.

    72 *  // You can add both if you want.

    73 *  listModel->SetWantedMediaTypesL( myMediaTypes.Array() );

    74 *  CleanupStack::PopAndDestroy( &myMediaTypes );

    75 *

    76 *  // Set sorting style (if you want to sort items)

    77 *  listModel->SetSortingStyle( mySortingStyle );

    78 *

    79 *  // You can also add post filter, custom sorter and custom grouper to model.

    80 *

    81 *  // Refresh the List Model.

    82 *  // The model will fetch items from server and use post filter to filter items,

    83 *  // grouping style or custom grouper to group items and finally sort items

    84 *  // with sorting style or custom sorter.

    85 *  listModel->RefreshL();

    86 *

    87 *  // You can also refresh the post filter and sorting only. This call does not

    88 *  // fetch items from the server. The model is only filtered and sorted.

    89 *  listModel->RefreshL( ECLFRefreshPostFilter | ECLFRefreshSorting );

    90 *  @endcode

    91 *

    92 *  @lib ContentListingFramework.lib

    93 *  @since S60 3.1

    94 */

    95 class MCLFItemListModel

    96     {

    97     public:  // Constructors and destructor

    98 

    99         /**

   100         * Destructor.

   101         */

   102         virtual ~MCLFItemListModel() {}

   103 

   104     public: // New functions

   105 

   106         /**

   107         * Get Content Listing Framework item from the List Model.

   108         * @since S60 3.1

   109         * @pre aIndex >= 0 && aIndex < ItemCount()

   110         * @param aIndex Index of the item

   111         * @return Content Listing Framework item

   112         */

   113         virtual const MCLFItem& Item( TInt aIndex ) const = 0;

   114 

   115         /**

   116         * Get number of items that are in the model.

   117         * @since S60 3.1

   118         * @return Count of items

   119         */

   120         virtual TInt ItemCount() const = 0;

   121 

   122         /**

   123         * Activate or remove Sorting style.

   124         * Setting a new sorting style will remove all old secondary sorters.

   125         * Removing the sorting will also remove all secondary sorters too.

   126         * @since S60 3.1

   127         * @param aSortingStyle Sorting style to activate,

   128         *        if the pointer is NULL then sorting styles are removed

   129         */

   130         virtual void SetSortingStyle( MCLFSortingStyle* aSortingStyle ) = 0;

   131 

   132         /**

   133         * Append a secondary sorting style to the list model.

   134         * If an item doesn't have the field defined by primary or

   135         * any previous secondary sorting style, the items are sorted using

   136         * the next secondary sorting style. When a sorting style is

   137         * appended using this method, it becomes the least significant

   138         * sorting style until a new one is added after it.

   139         * Items with undefined fields are placed before or after items

   140         * with defined fields, depending on the undefined field position

   141         * setting in MCLFSortingStyle.

   142         * @since S60 3.1

   143         * @param aSortingStyle Secondary sorting style to add.

   144         */

   145         virtual void AppendSecondarySortingStyleL(

   146                                     MCLFSortingStyle& aSortingStyle ) = 0;

   147 

   148         /**

   149         * Activate or remove custom sorter.

   150         * Custom sorter will overwrite sorting style (if there is a sorting

   151         * style activated). See MCLFCustomSorter for an example implementation

   152         * of a custom sorter.

   153         * @since S60 3.1

   154         * @param aCustomSorter Custom sorter to activate.

   155         *        If the pointer is NULL, sorting style is used (if there is one

   156         *        activated)

   157         */

   158         virtual void SetCustomSorter( MCLFCustomSorter* aCustomSorter ) = 0;

   159 

   160         /**

   161         * Activate a grouping style for the List Model. Use ECLFNoGrouping as

   162         * the grouping style if you want to remove grouping.

   163         * Default grouping style is ECLFNoGrouping.

   164         * @since S60 3.1

   165         * @param aGrouping Grouping style to activate

   166         */

   167         virtual void SetGroupingStyle( TCLFGrouping aGrouping ) = 0;

   168 

   169         /**

   170         * Activate or remove custom grouper. See MCLFCustomGrouper for an example

   171         * implementation of a custom grouper.

   172         * Custom grouper will overwrite grouping style.

   173         * @since S60 3.1

   174         * @param aCustomGrouper Custom grouper to activate,

   175         *        if pointer is NULL then then grouping style is used

   176         */

   177         virtual void SetCustomGrouper( MCLFCustomGrouper* aCustomGrouper ) = 0;

   178 

   179         /**

   180         * Activate or remove post filter. Post filter removes items from the

   181         * List Model. See MCLFPostFilter for an example implementation of a

   182         * post filter.

   183         * @since S60 3.1

   184         * @param aPostFilter Post filter to activate,

   185         *        if pointer is NULL then active post filter will be removed.

   186         */

   187         virtual void SetPostFilter( MCLFPostFilter* aPostFilter ) = 0;

   188 

   189         /**

   190         * Wanted mime types of media files that will be requested to the model.

   191         * Overwrites old mime types if they were set.

   192         * @since S60 3.1

   193         * @param aMimeTypes List of wanted mime types. Mime types can contain

   194         *                   wildcard characters "*" and "?", where "*" matches

   195         *                   zero or more consecutive occurrences of any character

   196         *                   and "?" matches a single occurrence of any character

   197         */

   198         virtual void SetWantedMimeTypesL( const MDesCArray& aMimeTypes ) = 0;

   199 

   200         /**

   201         * Wanted mime types of media files that will be requested to the model.

   202         * Overwrites old mime types if they were set.

   203         * @since S60 3.1

   204         * @param aResource Resource reader to mime type list resource.

   205         *                  Use resource struct CLF_MIME_TYPE_ARRAY.

   206         */

   207         virtual void SetWantedMimeTypesL( TResourceReader& aResource ) = 0;

   208 

   209         /**

   210         * Wanted media types of media files that will be requested to the model.

   211         * Overwrites old media types if they were set.

   212         * @since S60 3.1

   213         * @param aMediaTypes List of wanted media types

   214         */

   215         virtual void SetWantedMediaTypesL(

   216                             const TArray<TInt>& aMediaTypes ) = 0;

   217 

   218 

   219         /**

   220         * Wanted media types of media files that will be requested to the model.

   221         * Overwrites old media types if they were set.

   222         * @since S60 3.1

   223         * @param aResource Resource reader to media type list resource.

   224         *                  Use resource struct CLF_MEDIA_TYPE_ARRAY

   225         */

   226         virtual void SetWantedMediaTypesL( TResourceReader& aResource ) = 0;

   227 

   228         /**

   229         * Refresh the model. This function is asynchronous (non-blocking) and

   230         * MCLFOperationObserver is called when the refresh operation is

   231         * completed. <br>

   232         * <br>

   233         * Operations in refresh are executed in the following order:<br>

   234         * 1. Model gets wanted items from server.

   235         *    Use SetWantedMediaTypesL and/or SetWantedMimeTypesL to define

   236         *    wanted items.<br>

   237         * 2. Model uses post filter to filter items.<br>

   238         * 3. Model groups items if grouping is selected.<br>

   239         * 4. Model sorting items.<br>

   240         * @since S60 3.1

   241         */

   242         virtual void RefreshL() = 0;

   243 

   244         /**

   245         * Refresh the model. This function is synchronous (blocking). Use

   246         * parameter(s) to define the type of refresh. See TCLFRefreshTypeFlags

   247         * for refresh flags.

   248         * @since S60 3.1

   249         * @param aRefreshType Flag(s) to use for refreshing.

   250         */

   251         virtual void RefreshL( TInt32 aRefreshType ) = 0;

   252 

   253         /**

   254         * Cancel asynchronous refresh operation.

   255         * @since S60 3.1

   256         */

   257         virtual void CancelRefresh() = 0;

   258 

   259     private: // Extension interface

   260 

   261         /**

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

   263         */

   264         virtual MCLFItemListModelExt* Extension() { return NULL; }

   265 

   266     };

   267 

   268 #endif      // MCLFITEMLISTMODEL_H

   269 

   270 // End of File