/*

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

* All rights reserved.

* This component and the accompanying materials are made available

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

* which accompanies this distribution, and is available

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

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:    Reader interface of media item lists 

*

*/

#ifndef M_GLXMEDIALIST_H

#define M_GLXMEDIALIST_H

#include <mpxcollectionpath.h>

#include <mpxfilter.h>

#include <mpxcommand.h>

#include <glxhierarchyid.h>

#include <glxlistdefs.h>

#include "glxmedia.h" // For TGlxMediaId

#include "glxmedialistid.h" 

// Forward declarations

class MMPXCollection;

class MGlxMediaListObserver;

class MGlxFetchContext;

/**

 *  MGlxMediaList

 *

 *  Interface for reading lists of media items

 *

 *  @lib glxmedialists.lib

 */

class MGlxMediaList

    {

public:

    /**

     * Returns a new/existing media list interface.

     *

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

     * are the same.  Otherwise a new instance is returned

     *

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

     * is ignored.

     *

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

     *

     * @param aPath Path to the collection

     * @param aHierarchyId Id of the client hierarchy

     * @param aFilter Filter on the collection

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

     */

    IMPORT_C static MGlxMediaList* InstanceL(const CMPXCollectionPath& aPath, 

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

    /**

     * Releases a media list interface

     */

    virtual void Close() = 0;

    /**

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

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

     * ones.

     *

     * @return Unique id of this interface

     */

    virtual TGlxMediaListId Id() const = 0;

    /**

     * Count of media items in the list

     *

     * @return Count of media items

     */

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

    /**

     * Current focus position 

     * 

     * @return Index of focused item

     */

    virtual TInt FocusIndex() const = 0;

    /**

     * Sets the focus. 

     * The implementation of this function is required to call 

     * MGlxMediaListObserver::HandleFocusChangedL for all added

     * observers. Calling this function will cause the item window

     * to be updated and potentially properties and thumbnails

     * to be loaded.

     *

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

     * @param aValue value of the focus change

     */

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

    /**

     * Media item at index.

     * It is not legal to access items outside the preload 

     * (or visible) range.

     *

     * @param aIndex index of the item in the list

     * @return Media item pointer

     */

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

    /**

     * Item index by media item id

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

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

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

     *

     * @param aId Unique id of the media item

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

     */

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

    /**

     * Add an observer that observes changes to the list.

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

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

     * focus changes.

     *

     * @param aObserver The observer

     */

    virtual void AddMediaListObserverL(MGlxMediaListObserver* aObserver) = 0;

    /**

     * Removes a media item list observer from the observer list

     *

     * @param aObserver The observer

     */

    virtual void RemoveMediaListObserver(MGlxMediaListObserver* aObserver) = 0;

    /**

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

     * @param aContext context to register

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

     */

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

    /**

     * Removes an existing context

     *

     * @param aContext Pointer of the context to be removed

     */

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

    /**

     * Sets the specified contexts as highest priority contexts. Other 

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

     * less priority than the specified contexts.

     *

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

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

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

     */

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

    /**

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

     */

    virtual MMPXCollection& Collection() const = 0;

    /**

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

     *

     * @return CMPXCollectionPath* representing current path

     */

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

    /**

     * Determines if an item has been selected

     *

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

     * @return Boolean indication of the item selection

     */

    virtual TBool IsSelected(TInt aIndex) const = 0;

    /**

     * Item selection/deselection

     *

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

     * @param aSelected Boolean to indicate selection/deselection

     */

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

    /**

     * Selection count

     *

     * @return TInt count of selected items

     */

    virtual TInt SelectionCount() const = 0;

    /**

     * Selected item index from selection

     *

     * @param aSelectionIndex Index in selection array

     * @return TInt item index from selection

     */

    virtual TInt SelectedItemIndex(TInt aSelectionIndex) const = 0;

    /**

     * Sends a command to the collection

     *

     * @param aCommand MPX command from a command handler

     */

    virtual void CommandL(CMPXCommand& aCommand) = 0;

    /**

     * Cancels a command on the collection

     */

    virtual void CancelCommand() = 0;

    /**

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

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

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

     * merge the filters

     *

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

     */

    virtual void SetFilterL(CMPXFilter* aFilter) = 0;

    /**

     * Filter on the collection

     *

     * @return CMPXFilter on the collection

     */

    virtual CMPXFilter* Filter() const = 0;

    /**

     * The Id Space Id of the media list.

     *

     * @param aIndex index of the item in the list

     * @return The Id Space of the media list

     */

    virtual TGlxIdSpaceId IdSpaceId(TInt aIndex) const = 0;

    /**

     * Returns ETrue if the media list has been

     * populated else EFalse

     */

    virtual TBool IsPopulated() const = 0;

    /**

     * Adds a static item and takes ownership

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

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

     *       the object is free to be modified.

     * @param aStaticItem Static item to be added

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

     */

    virtual void AddStaticItemL( CGlxMedia* aStaticItem,

        NGlxListDefs::TInsertionPosition aTargetPosition ) = 0;

	/**

	  * Remove static item from the list.

	  * @param aItemId Id of item to remove

	  */

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

    /**

     * Enables or disables static items

     * @param aEnabled true if static items should be enabled

     *                 false if static items should be disabled

     */

    virtual void SetStaticItemsEnabled( TBool aEnabled ) = 0;

    /**

     * Tests if static items are enabled.

     * @return ETrue if static items are enabled

     */

    virtual TBool IsStaticItemsEnabled() const = 0;

    /**

     * Sets the initial focus position, first or last item

     * @param aFocusInitialPosition initial focus on first or last item

     */

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

    /**

     * Resets the focus to the initial position

     */

    virtual void ResetFocus() = 0;

    /**

     * Unmarks all items in the medialist.

     * @param aList Reference to Medialist items.

     */

    IMPORT_C static void UnmarkAllL( MGlxMediaList& aList );

    /**

     * Sets the dataWindow position. 

     * The implementation of this function is required for the

     * item window to be updated while blocky iterator is used 

     * and potentially properties and thumbnails to be loaded.

     *

     * @param aIndex value of the dataWindow change

     */

    virtual void SetVisibleWindowIndexL( TInt aIndex) = 0;

    /**

     * Current visible dataWindow position 

     */

    virtual TInt VisibleWindowIndex() const = 0;

    virtual ~MGlxMediaList() {};

    /**

     * Cancel the pending requests 

     */

    virtual void CancelPreviousRequests() = 0;

    };

#endif // M_GLXMEDIALIST_H