/*

* Copyright (c) 2006 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:  Encapsulates a path into a collection

*

*/

#ifndef CMPXCOLLECTIONPATH_H

#define CMPXCOLLECTIONPATH_H

#include <mpxcommonframeworkdefs.h>

class RWriteStream;

class RReadStream;

class CMPXCollectionPathNode;

class TMPXAttribute;

/**

*  Encapsulates a 'bookmark' to a specific collection entry, i.e. encapsulates

*  a specific path in a collection hierarchy; you can navigate through the

*  items at this level.

*

*  @lib mpxcommon.lib

*/

class CMPXCollectionPath : public CBase

    {

public:

    /**

    *  Convenience enumeration to identify levels

    *  within a collection path.

    */

    enum TMPXCollectionPathLevel

        {

        ECollectionUid=0,

        ECollectionRoot=0 // Use ECollectionRoot+1, +2, etc as for other levels

        };

    enum TMPXPathChangeResult

        {

        EPathUnchanged=0,

        EPathModified,

        EPathClipped

        };

    /**

    * Collection path change type.

    *

    */

     enum TMPXCollectionPathChange

        {

        EAdded,         // Item changed

        EDeleted,       // Item deleted

        EModified,      // Item modified

        EGroupModified  // A "Group" modified, e.g. a playlist, an artist, etc

        };

public:

    /**

    *  Two-phase constructor.

    *

    *  @since S60 3.2.3

    *  @param aPath reference to an existing collection path

    *  @return object created

    */

    IMPORT_C static CMPXCollectionPath* NewL(const CMPXCollectionPath& aPath);

    /**

    *  Two-phase constructor.

    *

    *  @since S60 3.2.3

    *  @param aStream reference to a stream

    *  @return object created

    */

    IMPORT_C static CMPXCollectionPath* NewL(RReadStream& aStream);

    /**

    *  Two-phase constructor.

    *

    *  @since S60 3.2.3

    *  @return object created

    */

    IMPORT_C static CMPXCollectionPath* NewL();

    /**

    *  Destructor.

    *

    *  @since S60 3.2.3

    */

    IMPORT_C virtual ~CMPXCollectionPath();

public: // Navigation through items at top level

    /**

    *  Go to next item.

    *

    *  @since S60 3.2.3

    *  @return ETrue if exists

    */

    IMPORT_C TBool operator++();

    /**

    *  Go to previous item.

    *

    *  @since S60 3.2.3

    *  @return ETrue if exists

    */

    IMPORT_C TBool operator--();

    /**

    *  Go to the first item.

    *

    *  @since S60 3.2.3

    */

    IMPORT_C void SetToFirst();

    /**

    *  Go to the last item.

    *

    *  @since S60 3.2.3

    */

    IMPORT_C void SetToLast();

    /**

    *  Go to specific item at top level.

    *

    *  @since S60 3.2.3

    *  @param aIndex index of the item

    *  @panic USER 130, if aIndex is out of bound

    *  @panic USER 0, if collection path is invalid(zero level)

    */

    IMPORT_C void Set(TInt aIndex);

    /**

    *  Go to specific item at top level.

    *

    *  @since S60 3.2.3

    *  @param aId id of the item

    *  @panic USER 0, if aId is invalid or invalid collection path

    */

    IMPORT_C void Set(const TMPXItemId& aId);

    /**

    *  Sets the open mode with which to navigate to the next level.

    *

    *  @since S60 3.2.3

    *  @param aMode the open mode

    *  @panic USER 0, if collection path is invalid(zero level)

    */

    IMPORT_C void Set(TMPXOpenMode aMode);

    /** 

    *  Sets the open attributes with which to navigate to the next level.

    *

    *  @since S60 3.2.3

    *  @param aAttrs the open attributes

    *  @panic USER 0, if collection path is invalid(zero level)

    *  @deprecated Use method CMPXCollectionPath::SetL(

    *    const TArray<TMPXAttribute>& aAttrs) instead.

    */

    IMPORT_C void Set(const TArray<TMPXAttribute>& aAttrs);

    /**

     *  Sets the open attributes with which to navigate to the next level.

     *

     *  @since S60 3.2.3

     *  @param aAttrs the open attributes

     *  @leave system error code

     *  @panic USER 0, if collection path is invalid(zero level)

     */

    IMPORT_C void SetL(const TArray<TMPXAttribute>& aAttrs);

public: // Selection of items at top level

    /**

    *  Select an item with the id in the path.

    *  If the id appears more than once in the path, Select(TInt aIndex) can

    *  be used.

    *

    *  @since S60 3.2.3

    *  @param aId ID of the item

    *  @panic USER 0 if aId is not found

    */

    IMPORT_C void SelectL(const TMPXItemId& aId);

    /**

    *  Select an item in the path.

    *

    *  @since S60 3.2.3

    *  @param aIndex index of the item

    *  @leave The function leaves with one of the system wide error codes,

    *         if the operation fails

    *  @panic USER 130, if aIndex is out of bound

    */

    IMPORT_C void SelectL(TInt aIndex);

    /**

     *  Select all of items at top level in the path.

     *

     *  @since S60 3.2.3

     *  @leave The function leaves with one of the system wide error codes,

     *         if the operation fails

     */

    IMPORT_C void SelectAllL();

    /**

    *  Deselects an item in the path.

    *

    *  @since S60 3.2.3

    *  @param aId ID of the item

    *  @panic USER 0, if aId was not selected

    */

    IMPORT_C void Deselect(const TMPXItemId& aId);

    /**

    *  Deselects an item in the path.

    *

    *  @since S60 3.2.3

    *  @param aIndex index of the item

    *  @panic USER 130, if aIndex is out of bound

    *  @panic USER 0, if aIndex was not selected

    */

    IMPORT_C void Deselect(TInt aIndex);

    /**

     *  Deselect all of items at top level in the path.

     *

     *  @since S60 3.2.3

     */

    IMPORT_C void DeselectAll();

    /**

    *  Removes an item in the path and adjust selection indices accordingly.

    *

    *  @since S60 3.2.3

    *  @param aId ID of the item

    *  @panic USER 0, if aId was not selected

    */

    IMPORT_C void Remove(const TMPXItemId& aId);

    /**

    *  Removes an item in the path and adjust selection indices accordingly.

    *

    *  @since S60 3.2.3

    *  @param aIndex index of the item

    *  @panic USER 0, if aIndex was not selected

    */

    IMPORT_C void Remove(TInt aIndex);

    /**

    *  Queries if item is selected.

    *

    *  @since S60 3.2.3

    *  @param aId ID of item

    *  @return whether selected

    */

    IMPORT_C TBool IsSelected(const TMPXItemId& aId) const;

    /**

    *  Queries if item is selected.

    *

    *  @since S60 3.2.3

    *  @param aIndex index of item

    *  @return whether selected

    */

    IMPORT_C TBool IsSelected(TInt aIndex) const;

    /**

    * Clears selection.

    *

    * @since S60 3.2.3

    */

    IMPORT_C void ClearSelection();

    /**

    * Array of currently selected indices.

    *

    * @since S60 3.2.3

    * @return current selected indices

    */

    IMPORT_C TArray<TInt> Selection() const;

    /**

    * Current selected ids.

    *

    * @since S60 3.2.3

    * @param aIds array of ids returned, id may be duplicated. e.g. music

    *        playlist can contains an item more than once.

    * @leave The function leaves with one of the system wide error codes,

    *        if the operation fails.

    */

    IMPORT_C void SelectionL(RArray<TMPXItemId>& aIds) const;

    /**

    * Update the item ID for a particular item.

    *

    * @since S60 3.2.3

    * @param aIndex index to update

    * @param aNewId the item id to set to the index

    */

    IMPORT_C void Update( TInt aIndex, TMPXItemId& aNewId );

public: // Information about top level

    /**

    * Current index.

    *

    * @since S60 3.2.3

    * @return current index

    */

    IMPORT_C TInt Index() const;

    /**

    * Current ID.

    *

    * @since S60 3.2.3

    * @return current ID

    */

    IMPORT_C const TMPXItemId& Id() const;

    /**

    * Number of items at the top level.

    *

    * @since S60 3.2.3

    * @return the number of items

    */

    IMPORT_C TInt Count() const;

    /**

    * The open mode with which to navigate to the next level.

    *

    * @since S60 3.2.3

    * @return the open mode for next level

    */

    IMPORT_C TMPXOpenMode OpenNextMode() const;

    /**

    * The open mode with which to navigate to the previous level.

    *

    * @since S60 3.2.3

    * @return the open mode for previous level

    */

    IMPORT_C TMPXOpenMode OpenPreviousMode() const;

    /**

    * Index from item id at the top level.

    *

    * @since S60 3.2.3

    * @param aId item id

    * @return index to the item with aId at the top level

    */

    IMPORT_C TInt IndexOfId(const TMPXItemId& aId) const;

    /**

    * Return the item id for the item at aIndex at the top level.

    *

    * @since S60 3.2.3

    * @return TMPXItemId if aIndex is valid

              KMPXInvalidItemId if invalid

    */

    IMPORT_C const TMPXItemId& IdOfIndex( TInt aIndex ) const;

    /**

    * Open attributes for next level.

    *

    * @since S60 3.2.3

    * @panic USER 0 if no level in the path

    */

    IMPORT_C const TArray<TMPXAttribute> OpenAttributes() const;

    /**

    * Retrieve a TArray of the top level items.

    *

    * @since S60 3.2.3

    * @panic USER 0 if no level in the path

    * @return TArray,

    */

    IMPORT_C const TArray<TMPXItemId> Items() const;

public: // Information about other levels

    /**

    * Return item index at a specific level.

    *

    * @since S60 3.2.3

    * @param aLevel level of depth

    * @return the index of item

    */

    IMPORT_C TInt Index(TInt aLevel) const;

    /**

    * Return item id at a specific level.

    *

    * @since S60 3.2.3

    * @param aLevel level of depth

    * @return the id of item

    */

    IMPORT_C const TMPXItemId& Id(TInt aLevel) const;

public: // functions about levels

    /**

    * Number of levels into the collection.

    *

    * @since S60 3.2.3

    * @return the levels count

    */

    IMPORT_C TInt Levels() const;

    /**

    * Back a level.

    *

    * @since S60 3.2.3

    * @panic USER 0 if no more level in the path

    */

    IMPORT_C void Back();

    /**

    * Append a level.

    *

    * @since S60 3.2.3

    * @param aIds IDs of items at this level

    */

    IMPORT_C void AppendL(const TArray<TMPXItemId>& aIds);

    /**

    * Append a level, where only single ID exists or is known.

    *

    * @since S60 3.2.3

    * @param aId id of item at this level

    */

    IMPORT_C void AppendL(const TMPXItemId& aId);

    /**

    * Insert an id at top level.

    *

    * @since S60 3.2.3

    * @param aId the id to be inserted

    * @param aPos the position where the id to be inserted. The position is

    *        relative to zero.

    * @leave Leave with system errror code

    * @panic USER 131 if a pos is negative or is greater than the number of ids

    *        at top top level

    */

    IMPORT_C void InsertL(const TMPXItemId& aId, TInt aPos);

    /**

    * Resets the collection path object.

    * removes all node arrays.

    * removes all top level ids.

    * removes all selection ids.

    *

    * @since S60 3.2.3

    */

    IMPORT_C void Reset();

    /*

    * Returns a collection path pointing to the container of this path.

    *

    * @since S60 3.2.3

    * @return CMPXCollectionPath* ownership transferred

    */

    IMPORT_C CMPXCollectionPath* ContainerPathL() const;

public:  // Handle update

    /**

    * Handle collection change.

    *

    * @since S60 3.2.3

    * @param aCollectionId collection id of changes

    * @param aId Id of item change

    * @param aDeprecatedId old Id of the item changed

    * @param aChange change type

    * @param aSelection, on return contains the valid selection

    *                    if the path is invalidated

    * @return TMPXPathChangeResult

    *

    */

    IMPORT_C TInt HandleChange(

                         const TUid& aCollectionId,

                         const TMPXItemId& aId,

                         const TMPXItemId& aDeprecatedId,

                         CMPXCollectionPath::TMPXCollectionPathChange aChange,

                         TInt& aSelection);

public:

    /**

    * Externalize a object of this class to steam.

    *

    * @since S60 3.2.3

    * @param aStream write stream

    */

    IMPORT_C void ExternalizeL(RWriteStream& aStream) const;

    /**

    * Internalize a object of this class from steam.

    *

    * @since S60 3.2.3

    * @param aStream read stream

    */

    IMPORT_C void InternalizeL(RReadStream& aStream);

private:

    /**

    * C++ default constructor.

    *

    * @since S60 3.2.3

    */

    CMPXCollectionPath();

    /**

    * 2nd phase constructor.

    *

    * @since S60 3.2.3

    * @param aPath collection path

    */

    void ConstructL(const CMPXCollectionPath& aPath);