1 /*

     2 * Copyright (c) 2009 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:

    15 * Defines an ordered list of widget id's with persistence capability

    16 *

    17 */

    18 

    19 #ifndef WMPERSISTENTWIDGETORDER_H

    20 #define WMPERSISTENTWIDGETORDER_H

    21 

    22 // INCLUDES

    23 #include <e32base.h>

    24 #include "wmwidgetdata.h"

    25 

    26 // FORWARD DECLARATIONS

    27 class RFs;

    28 

    29 // CLASS DECLARATION

    30 /**

    31  *  CWmPersistentWidgetOrder

    32  * This class is an ordered list of widget identifiers. The list can be

    33  * serialised and extract from stream and persisted. The list can be used

    34  * in sorting a pointer array of CWmWidgetData.

    35  */

    36 NONSHARABLE_CLASS( CWmPersistentWidgetOrder ) : public CBase

    37     {

    38 

    39 public: // Constructors and destructor

    40     /** 

    41      * static constructor.

    42      */

    43     static CWmPersistentWidgetOrder* NewL( RFs& aFs );

    44 

    45     /** Destructor. */

    46     ~CWmPersistentWidgetOrder();

    47 

    48 private: // private construction

    49 

    50     /**

    51      * constructor

    52      */

    53     CWmPersistentWidgetOrder( RFs& aFs );

    54 

    55     /**

    56      * 2nd phase constructor

    57      */

    58     void ConstructL();

    59 

    60 

    61 public: // API

    62 

    63     /**

    64      * Loads the persistent widget list from storage.

    65      * This is typically done once after construction.

    66      * The instance can now be used to sort widget data.

    67      */

    68     void LoadL();

    69   

    70     /**

    71      * Stores a sorted array of WmWidgetData types. Note that

    72      * the order will be directly stored and a copy will not

    73      * be kept locally, so this instance can not be used to

    74      * sort widget data until LoadL() is called.

    75      * 

    76      * @param aArray the array of widget daya types

    77      */

    78     void StoreL( const RWidgetDataValues& aArray );

    79 

    80     /**

    81      * Retrieves an index of given widget data object within the list.

    82      * This index can be used to sort and organise. Note that LoadL()

    83      * must be used prior to calling this method, and before that

    84      * there must be something persisted.

    85      * 

    86      * @param aWidgetData data to seek index of in the sorted order

    87      * @return the index found, or KErrNotFound if widget is new

    88      */

    89     TInt IndexOf( const CWmWidgetData& aWidgetData ) const;

    90 

    91     /**

    92      * checks if the persistent widget order is empty. In this case it does

    93      * not make any sense to use the object to sort anything.

    94      * Note that before loading the object is always empty.

    95      */

    96     TBool IsEmpty() const;

    97 

    98 protected:

    99 

   100     /**

   101      * Cleans up the array

   102      */

   103     void CleanupArray();

   104 

   105     /**

   106      * build the storage file path and name. The storage file will be located

   107      * in host process private directory.

   108      * @param aPathBuf a buffer to receive the complete file path

   109      */

   110     void GetStoreFileNameL( TDes& aPathBuf );

   111 

   112     /**

   113      * Unique tag of a widget

   114      */

   115     class Tag

   116         {

   117         public:

   118             /** constructs a tag from parameters */

   119             Tag( TInt32 aUid, HBufC16* aPublisherId );

   120 

   121             /** compares a tag agains a widget data */

   122             TBool Matches( const CWmWidgetData& aWidgetData ) const;

   123 

   124             /** widget uid */

   125             TInt32 iUid;

   126 

   127             /** widget publisher id */

   128             HBufC16* iPublisherId;

   129         };

   130 

   131 private: // data members

   132 

   133     /** the file session */

   134     RFs& iFs;

   135 

   136     /** array of widget tags for sorting */

   137     RArray<Tag> iTagArray;

   138 

   139     };

   140 

   141 

   142 #endif // WMPERSISTENTWIDGETORDER_H