diff -r 000000000000 -r a2952bb97e68 mmappfw_plat/mpx_common_api/inc/mpxcollectionpath.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mmappfw_plat/mpx_common_api/inc/mpxcollectionpath.h Thu Dec 17 08:55:47 2009 +0200 @@ -0,0 +1,572 @@ +/* +* 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 + +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& aAttrs) instead. + */ + IMPORT_C void Set(const TArray& 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& 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 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& 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 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 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& 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); + + /** + * 2nd phase constructor. + * + * @since S60 3.2.3 + */ + void ConstructL(); + + /** + * 2nd phase constructor. + * + * @since S60 3.2.3 + * @param aStream stream + */ + void ConstructL(RReadStream& aStream); + + /** + * The top level node of the path. + * + * @since S60 3.2.3 + * @panic USER 0 if no level in the path + * @return the top level + */ + CMPXCollectionPathNode& TopLevel(); + + /** + * The top level node of the path. + * + * @since S60 3.2.3 + * @panic USER 0 if no level in the path + * @return the top level + */ + const CMPXCollectionPathNode& TopLevel() const; + +private: + /// Node of path levels + RPointerArray iNodeArray; + /// Additional info of Top Level + RArray iIds; // item ids of top level + RArray iSelection; // selected item indices of top level, sorted array + TMPXItemId iInvalidId; + }; + +#endif // CMPXCOLLECTIONPATH_H