1 /*

     2 * Copyright (c) 2008-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:    Reader interface of media item lists 

    15 *

    16 */

    17 

    18 

    19 

    20 

    21 #ifndef M_GLXMEDIALIST_H

    22 #define M_GLXMEDIALIST_H

    23 

    24 #include <mpxcollectionpath.h>

    25 #include <mpxfilter.h>

    26 #include <mpxcommand.h>

    27 

    28 #include <glxhierarchyid.h>

    29 #include <glxlistdefs.h>

    30 

    31 #include "glxmedia.h" // For TGlxMediaId

    32 #include "glxmedialistid.h" 

    33 

    34 // Forward declarations

    35 class MMPXCollection;

    36 class MGlxMediaListObserver;

    37 class MGlxFetchContext;

    38 

    39 /**

    40  *  MGlxMediaList

    41  *

    42  *  Interface for reading lists of media items

    43  *

    44  *  @lib glxmedialists.lib

    45  */

    46 class MGlxMediaList

    47     {

    48 public:

    49     /**

    50      * Returns a new/existing media list interface.

    51      *

    52      * Returns an existing instance if and only if the hierarchy id and path

    53      * are the same.  Otherwise a new instance is returned

    54      *

    55      * Filter is only used when a new media list is created, otherwise it

    56      * is ignored.

    57      *

    58      * The new/existing media list is set as highest priority list

    59      *

    60      * @param aPath Path to the collection

    61      * @param aHierarchyId Id of the client hierarchy

    62      * @param aFilter Filter on the collection

    63      * @return Media list interface (does not pass ownership)

    64      */

    65     IMPORT_C static MGlxMediaList* InstanceL(const CMPXCollectionPath& aPath, 

    66         const TGlxHierarchyId& aHierarchyId = KGlxIdNone, CMPXFilter* aFilter = NULL);

    67 

    68     /**

    69      * Releases a media list interface

    70      */

    71     virtual void Close() = 0;

    72 

    73     /**

    74      * Id of this reader interface. The id of each _existing_ reader interface 

    75      * is guaranteed to be unique, but new readers can reuse the ids of deleted

    76      * ones.

    77      *

    78      * @return Unique id of this interface

    79      */

    80     virtual TGlxMediaListId Id() const = 0;

    81 

    82     /**

    83      * Count of media items in the list

    84      *

    85      * @return Count of media items

    86      */

    87     virtual TInt Count(NGlxListDefs::TCountType aType = NGlxListDefs::ECountAll) const = 0;

    88 

    89     /**

    90      * Current focus position 

    91      * 

    92      * @return Index of focused item

    93      */

    94     virtual TInt FocusIndex() const = 0;

    95 

    96     /**

    97      * Sets the focus. 

    98      * The implementation of this function is required to call 

    99      * MGlxMediaListObserver::HandleFocusChangedL for all added

   100      * observers. Calling this function will cause the item window

   101      * to be updated and potentially properties and thumbnails

   102      * to be loaded.

   103      *

   104      * @param aType whether the focus change is absolute or relative

   105      * @param aValue value of the focus change

   106      */

   107     virtual void SetFocusL(NGlxListDefs::TFocusSetType aType, TInt aValue) = 0;

   108 

   109     /**

   110      * Media item at index.

   111      * It is not legal to access items outside the preload 

   112      * (or visible) range.

   113      *

   114      * @param aIndex index of the item in the list

   115      * @return Media item pointer

   116      */

   117     virtual const TGlxMedia& Item(TInt aIndex) const = 0;

   118 

   119     /**

   120      * Item index by media item id

   121      * If the item is not within the preload (or visible) range 

   122      * returns KErrNotFound. The item may still exist in the full 

   123      * list. This behavior can be changed, if there is a use case.

   124      *

   125      * @param aId Unique id of the media item

   126      * @return Index of the item in the list or KErrNotFound

   127      */

   128     virtual TInt Index(const TGlxIdSpaceId& aIdSpaceId, const TGlxMediaId& aId) const = 0;

   129 

   130     /**

   131      * Add an observer that observes changes to the list.

   132      * This observer will be informed whenever the items in the list 

   133      * change, more items get added, or items get deleted, or the 

   134      * focus changes.

   135      *

   136      * @param aObserver The observer

   137      */

   138     virtual void AddMediaListObserverL(MGlxMediaListObserver* aObserver) = 0;

   139 

   140     /**

   141      * Removes a media item list observer from the observer list

   142      *

   143      * @param aObserver The observer

   144      */

   145     virtual void RemoveMediaListObserver(MGlxMediaListObserver* aObserver) = 0;

   146 

   147     /**

   148      * Registers a context that affects the behavior of attribute and thumbnail loading.

   149      * @param aContext context to register

   150      * @param aPriority priority of the context. The higher the more important.

   151      */

   152     virtual void AddContextL(const MGlxFetchContext* aContext, TInt aPriority) = 0;

   153 

   154     /**

   155      * Removes an existing context

   156      *

   157      * @param aContext Pointer of the context to be removed

   158      */

   159     virtual void RemoveContext(const MGlxFetchContext* aContext) = 0;

   160 

   161     /**

   162      * Sets the specified contexts as highest priority contexts. Other 

   163      * contexts will retain their relative priority order, but will have 

   164      * less priority than the specified contexts.

   165      *

   166      * @param aContextIds Ids of the contexts to be set as highest priority.

   167      *		  Id at index 0 in the array is set to be the highest priority,

   168      *		  Id at index 1, the second highest, etc.

   169      */

   170 //	virtual void SetContextAsHighestPriority(RArray<TGlxMediaListContextId> aContextIds) = 0;

   171 	

   172     /**

   173      * @returns the MPX collection utility that is bound to this list

   174      */

   175     virtual MMPXCollection& Collection() const = 0;

   176 

   177     /**

   178      * Current path, including selection.  Ownership passed to caller.

   179      *

   180      * @return CMPXCollectionPath* representing current path

   181      */

   182     virtual CMPXCollectionPath* PathLC(NGlxListDefs::TPathType aType = NGlxListDefs::EPathAllOrSelection) const = 0;

   183 

   184     /**

   185      * Determines if an item has been selected

   186      *

   187      * @param aIndex Index of the item to be checked for selection

   188      * @return Boolean indication of the item selection

   189      */

   190     virtual TBool IsSelected(TInt aIndex) const = 0;

   191 

   192     /**

   193      * Item selection/deselection

   194      *

   195      * @param aIndex Index of the item to be selected/deselected

   196      * @param aSelected Boolean to indicate selection/deselection

   197      */

   198     virtual void SetSelectedL(TInt aIndex, TBool aSelected) = 0;

   199 

   200     /**

   201      * Selection count

   202      *

   203      * @return TInt count of selected items

   204      */

   205     virtual TInt SelectionCount() const = 0;

   206 

   207     /**

   208      * Selected item index from selection

   209      *

   210      * @param aSelectionIndex Index in selection array

   211      * @return TInt item index from selection

   212      */

   213     virtual TInt SelectedItemIndex(TInt aSelectionIndex) const = 0;

   214 

   215     /**

   216      * Sends a command to the collection

   217      *

   218      * @param aCommand MPX command from a command handler

   219      */

   220     virtual void CommandL(CMPXCommand& aCommand) = 0;

   221 

   222     /**

   223      * Cancels a command on the collection

   224      */

   225     virtual void CancelCommand() = 0;

   226 

   227     /**

   228      * Sets a filter on the collection.  The filter will replace any existing

   229      * filter applied on the collection.  If a client needs an aggregate filter,

   230      * they will need to obtain the currently applied filter using Filter() and

   231      * merge the filters

   232      *

   233      * @param aFilter MPX filter on the collection.  Ownership passed to media list

   234      */

   235     virtual void SetFilterL(CMPXFilter* aFilter) = 0;

   236 

   237     /**

   238      * Filter on the collection

   239      *

   240      * @return CMPXFilter on the collection

   241      */

   242     virtual CMPXFilter* Filter() const = 0;

   243 

   244     /**

   245      * The Id Space Id of the media list.

   246      *

   247      * @param aIndex index of the item in the list

   248      * @return The Id Space of the media list

   249      */

   250     virtual TGlxIdSpaceId IdSpaceId(TInt aIndex) const = 0;

   251     

   252     /**

   253      * Returns ETrue if the media list has been

   254      * populated else EFalse

   255      */

   256     virtual TBool IsPopulated() const = 0;

   257     		

   258     /**

   259      * Adds a static item and takes ownership

   260      * Note: In case of a leave, aStaticItem may have been modified.

   261      *       It is assumed that since ownership of the static item is passed,

   262      *       the object is free to be modified.

   263      * @param aStaticItem Static item to be added

   264      * @param aTargetPosition Whether to be added at beginning or end

   265      */

   266     virtual void AddStaticItemL( CGlxMedia* aStaticItem,

   267         NGlxListDefs::TInsertionPosition aTargetPosition ) = 0;

   268 

   269 	/**

   270 	  * Remove static item from the list.

   271 	  * @param aItemId Id of item to remove

   272 	  */

   273 	virtual void RemoveStaticItem(const TGlxMediaId& aItemId) = 0;

   274 	

   275     /**

   276      * Enables or disables static items

   277      * @param aEnabled true if static items should be enabled

   278      *                 false if static items should be disabled

   279      */

   280     virtual void SetStaticItemsEnabled( TBool aEnabled ) = 0;

   281 

   282     /**

   283      * Tests if static items are enabled.

   284      * @return ETrue if static items are enabled

   285      */

   286     virtual TBool IsStaticItemsEnabled() const = 0;

   287     

   288     /**

   289      * Sets the initial focus position, first or last item

   290      * @param aFocusInitialPosition initial focus on first or last item

   291      */

   292     virtual void SetFocusInitialPosition(NGlxListDefs::TFocusInitialPosition aFocusInitialPosition) = 0;

   293 

   294     /**

   295      * Resets the focus to the initial position

   296      */

   297     virtual void ResetFocus() = 0;

   298 

   299     /**

   300      * Unmarks all items in the medialist.

   301      * @param aList Reference to Medialist items.

   302      */

   303     IMPORT_C static void UnmarkAllL( MGlxMediaList& aList );

   304     

   305     /**

   306      * Sets the dataWindow position. 

   307      * The implementation of this function is required for the

   308      * item window to be updated while blocky iterator is used 

   309      * and potentially properties and thumbnails to be loaded.

   310      *

   311      * @param aIndex value of the dataWindow change

   312      */

   313     virtual void SetVisibleWindowIndexL( TInt aIndex) = 0;

   314     

   315     /**

   316      * Current visible dataWindow position 

   317      */

   318     virtual TInt VisibleWindowIndex() const = 0;

   319     

   320     virtual ~MGlxMediaList() {};

   321 

   322     /**

   323      * Cancel the pending requests 

   324      */

   325     virtual void CancelPreviousRequests() = 0;

   326     };

   327 

   328 #endif // M_GLXMEDIALIST_H

   329