--- /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 <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);
+
+ /**
+ * 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<CMPXCollectionPathNode> iNodeArray;
+ /// Additional info of Top Level
+ RArray<TMPXItemId> iIds; // item ids of top level
+ RArray<TInt> iSelection; // selected item indices of top level, sorted array
+ TMPXItemId iInvalidId;
+ };
+
+#endif // CMPXCOLLECTIONPATH_H