1 /*

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

    15 *

    16 */

    17 

    18 

    19 

    20 #ifndef CMPXCOLLECTIONPATH_H

    21 #define CMPXCOLLECTIONPATH_H

    22 

    23 #include <mpxcommonframeworkdefs.h>

    24 

    25 class RWriteStream;

    26 class RReadStream;

    27 class CMPXCollectionPathNode;

    28 class TMPXAttribute;

    29 

    30 /**

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

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

    33 *  items at this level.

    34 *

    35 *  @lib mpxcommon.lib

    36 */

    37 class CMPXCollectionPath : public CBase

    38     {

    39 public:

    40     /**

    41     *  Convenience enumeration to identify levels

    42     *  within a collection path.

    43     */

    44     enum TMPXCollectionPathLevel

    45         {

    46         ECollectionUid=0,

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

    48         };

    49 

    50     enum TMPXPathChangeResult

    51         {

    52         EPathUnchanged=0,

    53         EPathModified,

    54         EPathClipped

    55         };

    56 

    57     /**

    58     * Collection path change type.

    59     *

    60     */

    61      enum TMPXCollectionPathChange

    62         {

    63         EAdded,         // Item changed

    64         EDeleted,       // Item deleted

    65         EModified,      // Item modified

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

    67         };

    68 public:

    69     /**

    70     *  Two-phase constructor.

    71     *

    72     *  @since S60 3.2.3

    73     *  @param aPath reference to an existing collection path

    74     *  @return object created

    75     */

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

    77 

    78     /**

    79     *  Two-phase constructor.

    80     *

    81     *  @since S60 3.2.3

    82     *  @param aStream reference to a stream

    83     *  @return object created

    84     */

    85     IMPORT_C static CMPXCollectionPath* NewL(RReadStream& aStream);

    86 

    87     /**

    88     *  Two-phase constructor.

    89     *

    90     *  @since S60 3.2.3

    91     *  @return object created

    92     */

    93     IMPORT_C static CMPXCollectionPath* NewL();

    94 

    95     /**

    96     *  Destructor.

    97     *

    98     *  @since S60 3.2.3

    99     */

   100     IMPORT_C virtual ~CMPXCollectionPath();

   101 

   102 public: // Navigation through items at top level

   103     /**

   104     *  Go to next item.

   105     *

   106     *  @since S60 3.2.3

   107     *  @return ETrue if exists

   108     */

   109     IMPORT_C TBool operator++();

   110 

   111     /**

   112     *  Go to previous item.

   113     *

   114     *  @since S60 3.2.3

   115     *  @return ETrue if exists

   116     */

   117     IMPORT_C TBool operator--();

   118 

   119     /**

   120     *  Go to the first item.

   121     *

   122     *  @since S60 3.2.3

   123     */

   124     IMPORT_C void SetToFirst();

   125 

   126     /**

   127     *  Go to the last item.

   128     *

   129     *  @since S60 3.2.3

   130     */

   131     IMPORT_C void SetToLast();

   132 

   133     /**

   134     *  Go to specific item at top level.

   135     *

   136     *  @since S60 3.2.3

   137     *  @param aIndex index of the item

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

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

   140     */

   141     IMPORT_C void Set(TInt aIndex);

   142 

   143     /**

   144     *  Go to specific item at top level.

   145     *

   146     *  @since S60 3.2.3

   147     *  @param aId id of the item

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

   149     */

   150     IMPORT_C void Set(const TMPXItemId& aId);

   151 

   152     /**

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

   154     *

   155     *  @since S60 3.2.3

   156     *  @param aMode the open mode

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

   158     */

   159     IMPORT_C void Set(TMPXOpenMode aMode);

   160 

   161     /** 

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

   163     *

   164     *  @since S60 3.2.3

   165     *  @param aAttrs the open attributes

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

   167     *  @deprecated Use method CMPXCollectionPath::SetL(

   168     *    const TArray<TMPXAttribute>& aAttrs) instead.

   169     */

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

   171 

   172     /**

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

   174      *

   175      *  @since S60 3.2.3

   176      *  @param aAttrs the open attributes

   177      *  @leave system error code

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

   179      */

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

   181 

   182 public: // Selection of items at top level

   183 

   184     /**

   185     *  Select an item with the id in the path.

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

   187     *  be used.

   188     *

   189     *  @since S60 3.2.3

   190     *  @param aId ID of the item

   191     *  @panic USER 0 if aId is not found

   192     */

   193     IMPORT_C void SelectL(const TMPXItemId& aId);

   194 

   195     /**

   196     *  Select an item in the path.

   197     *

   198     *  @since S60 3.2.3

   199     *  @param aIndex index of the item

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

   201     *         if the operation fails

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

   203     */

   204     IMPORT_C void SelectL(TInt aIndex);

   205 

   206     /**

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

   208      *

   209      *  @since S60 3.2.3

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

   211      *         if the operation fails

   212      */

   213     IMPORT_C void SelectAllL();

   214 

   215     /**

   216     *  Deselects an item in the path.

   217     *

   218     *  @since S60 3.2.3

   219     *  @param aId ID of the item

   220     *  @panic USER 0, if aId was not selected

   221     */

   222     IMPORT_C void Deselect(const TMPXItemId& aId);

   223 

   224     /**

   225     *  Deselects an item in the path.

   226     *

   227     *  @since S60 3.2.3

   228     *  @param aIndex index of the item

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

   230     *  @panic USER 0, if aIndex was not selected

   231     */

   232     IMPORT_C void Deselect(TInt aIndex);

   233 

   234     /**

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

   236      *

   237      *  @since S60 3.2.3

   238      */

   239     IMPORT_C void DeselectAll();

   240 

   241     /**

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

   243     *

   244     *  @since S60 3.2.3

   245     *  @param aId ID of the item

   246     *  @panic USER 0, if aId was not selected

   247     */

   248     IMPORT_C void Remove(const TMPXItemId& aId);

   249 

   250     /**

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

   252     *

   253     *  @since S60 3.2.3

   254     *  @param aIndex index of the item

   255     *  @panic USER 0, if aIndex was not selected

   256     */

   257     IMPORT_C void Remove(TInt aIndex);

   258 

   259     /**

   260     *  Queries if item is selected.

   261     *

   262     *  @since S60 3.2.3

   263     *  @param aId ID of item

   264     *  @return whether selected

   265     */

   266     IMPORT_C TBool IsSelected(const TMPXItemId& aId) const;

   267 

   268     /**

   269     *  Queries if item is selected.

   270     *

   271     *  @since S60 3.2.3

   272     *  @param aIndex index of item

   273     *  @return whether selected

   274     */

   275     IMPORT_C TBool IsSelected(TInt aIndex) const;

   276 

   277     /**

   278     * Clears selection.

   279     *

   280     * @since S60 3.2.3

   281     */

   282     IMPORT_C void ClearSelection();

   283 

   284     /**

   285     * Array of currently selected indices.

   286     *

   287     * @since S60 3.2.3

   288     * @return current selected indices

   289     */

   290     IMPORT_C TArray<TInt> Selection() const;

   291 

   292     /**

   293     * Current selected ids.

   294     *

   295     * @since S60 3.2.3

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

   297     *        playlist can contains an item more than once.

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

   299     *        if the operation fails.

   300     */

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

   302 

   303     /**

   304     * Update the item ID for a particular item.

   305     *

   306     * @since S60 3.2.3

   307     * @param aIndex index to update

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

   309     */

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

   311 

   312 public: // Information about top level

   313 

   314     /**

   315     * Current index.

   316     *

   317     * @since S60 3.2.3

   318     * @return current index

   319     */

   320     IMPORT_C TInt Index() const;

   321 

   322     /**

   323     * Current ID.

   324     *

   325     * @since S60 3.2.3

   326     * @return current ID

   327     */

   328     IMPORT_C const TMPXItemId& Id() const;

   329 

   330     /**

   331     * Number of items at the top level.

   332     *

   333     * @since S60 3.2.3

   334     * @return the number of items

   335     */

   336     IMPORT_C TInt Count() const;

   337 

   338     /**

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

   340     *

   341     * @since S60 3.2.3

   342     * @return the open mode for next level

   343     */

   344     IMPORT_C TMPXOpenMode OpenNextMode() const;

   345 

   346     /**

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

   348     *

   349     * @since S60 3.2.3

   350     * @return the open mode for previous level

   351     */

   352     IMPORT_C TMPXOpenMode OpenPreviousMode() const;

   353 

   354     /**

   355     * Index from item id at the top level.

   356     *

   357     * @since S60 3.2.3

   358     * @param aId item id

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

   360     */

   361     IMPORT_C TInt IndexOfId(const TMPXItemId& aId) const;

   362 

   363     /**

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

   365     *

   366     * @since S60 3.2.3

   367     * @return TMPXItemId if aIndex is valid

   368               KMPXInvalidItemId if invalid

   369     */

   370     IMPORT_C const TMPXItemId& IdOfIndex( TInt aIndex ) const;

   371 

   372     /**

   373     * Open attributes for next level.

   374     *

   375     * @since S60 3.2.3

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

   377     */

   378     IMPORT_C const TArray<TMPXAttribute> OpenAttributes() const;

   379 

   380     /**

   381     * Retrieve a TArray of the top level items.

   382     *

   383     * @since S60 3.2.3

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

   385     * @return TArray,

   386     */

   387     IMPORT_C const TArray<TMPXItemId> Items() const;

   388 

   389 public: // Information about other levels

   390 

   391     /**

   392     * Return item index at a specific level.

   393     *

   394     * @since S60 3.2.3

   395     * @param aLevel level of depth

   396     * @return the index of item

   397     */

   398     IMPORT_C TInt Index(TInt aLevel) const;

   399 

   400     /**

   401     * Return item id at a specific level.

   402     *

   403     * @since S60 3.2.3

   404     * @param aLevel level of depth

   405     * @return the id of item

   406     */

   407     IMPORT_C const TMPXItemId& Id(TInt aLevel) const;

   408 

   409 public: // functions about levels

   410 

   411     /**

   412     * Number of levels into the collection.

   413     *

   414     * @since S60 3.2.3

   415     * @return the levels count

   416     */

   417     IMPORT_C TInt Levels() const;

   418 

   419     /**

   420     * Back a level.

   421     *

   422     * @since S60 3.2.3

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

   424     */

   425     IMPORT_C void Back();

   426 

   427     /**

   428     * Append a level.

   429     *

   430     * @since S60 3.2.3

   431     * @param aIds IDs of items at this level

   432     */

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

   434 

   435     /**

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

   437     *

   438     * @since S60 3.2.3

   439     * @param aId id of item at this level

   440     */

   441     IMPORT_C void AppendL(const TMPXItemId& aId);

   442 

   443     /**

   444     * Insert an id at top level.

   445     *

   446     * @since S60 3.2.3

   447     * @param aId the id to be inserted

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

   449     *        relative to zero.

   450     * @leave Leave with system errror code

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

   452     *        at top top level

   453     */

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

   455 

   456     /**

   457     * Resets the collection path object.

   458     * removes all node arrays.

   459     * removes all top level ids.

   460     * removes all selection ids.

   461     *

   462     * @since S60 3.2.3

   463     */

   464     IMPORT_C void Reset();

   465 

   466     /*

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

   468     *

   469     * @since S60 3.2.3

   470     * @return CMPXCollectionPath* ownership transferred

   471     */

   472     IMPORT_C CMPXCollectionPath* ContainerPathL() const;

   473 

   474 public:  // Handle update

   475     /**

   476     * Handle collection change.

   477     *

   478     * @since S60 3.2.3

   479     * @param aCollectionId collection id of changes

   480     * @param aId Id of item change

   481     * @param aDeprecatedId old Id of the item changed

   482     * @param aChange change type

   483     * @param aSelection, on return contains the valid selection

   484     *                    if the path is invalidated

   485     * @return TMPXPathChangeResult

   486     *

   487     */

   488     IMPORT_C TInt HandleChange(

   489                          const TUid& aCollectionId,

   490                          const TMPXItemId& aId,

   491                          const TMPXItemId& aDeprecatedId,

   492                          CMPXCollectionPath::TMPXCollectionPathChange aChange,

   493                          TInt& aSelection);

   494 

   495 public:

   496 

   497     /**

   498     * Externalize a object of this class to steam.

   499     *

   500     * @since S60 3.2.3

   501     * @param aStream write stream

   502     */

   503     IMPORT_C void ExternalizeL(RWriteStream& aStream) const;

   504 

   505     /**

   506     * Internalize a object of this class from steam.

   507     *

   508     * @since S60 3.2.3

   509     * @param aStream read stream

   510     */

   511     IMPORT_C void InternalizeL(RReadStream& aStream);

   512 

   513 private:

   514 

   515     /**

   516     * C++ default constructor.

   517     *

   518     * @since S60 3.2.3

   519     */

   520     CMPXCollectionPath();

   521 

   522     /**

   523     * 2nd phase constructor.

   524     *

   525     * @since S60 3.2.3

   526     * @param aPath collection path

   527     */

   528     void ConstructL(const CMPXCollectionPath& aPath);

   529 

   530     /**

   531     * 2nd phase constructor.

   532     *

   533     * @since S60 3.2.3

   534     */

   535     void ConstructL();

   536 

   537     /**

   538     * 2nd phase constructor.

   539     *

   540     * @since S60 3.2.3

   541     * @param aStream stream

   542     */

   543     void ConstructL(RReadStream& aStream);

   544 

   545     /**

   546     * The top level node of the path.

   547     *

   548     * @since S60 3.2.3

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

   550     * @return the top level

   551     */

   552     CMPXCollectionPathNode& TopLevel();

   553 

   554     /**

   555     * The top level node of the path.

   556     *

   557     * @since S60 3.2.3

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

   559     * @return the top level

   560     */

   561     const CMPXCollectionPathNode& TopLevel() const;

   562 

   563 private:

   564     /// Node of path levels

   565     RPointerArray<CMPXCollectionPathNode> iNodeArray;

   566     /// Additional info of Top Level

   567     RArray<TMPXItemId> iIds; // item ids of top level

   568     RArray<TInt> iSelection; // selected item indices of top level, sorted array

   569     TMPXItemId   iInvalidId;

   570     };

   571 

   572 #endif // CMPXCOLLECTIONPATH_H