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 #include "wmwidgetorderdata.h"

    26 

    27 // FORWARD DECLARATIONS

    28 class RFs;

    29 

    30 // CLASS DECLARATION

    31 /**

    32  *  CWmPersistentWidgetOrder

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

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

    35  * in sorting a pointer array of CWmWidgetData.

    36  */

    37 NONSHARABLE_CLASS( CWmPersistentWidgetOrder ) : public CBase

    38     {

    39 

    40 public: // Constructors and destructor

    41     /** 

    42      * static constructor.

    43      */

    44     static CWmPersistentWidgetOrder* NewL( RFs& aFs );

    45 

    46     /** Destructor. */

    47     ~CWmPersistentWidgetOrder();

    48 

    49 private: // private construction

    50 

    51     /**

    52      * constructor

    53      */

    54     CWmPersistentWidgetOrder( RFs& aFs );

    55 

    56     /**

    57      * 2nd phase constructor

    58      */

    59     void ConstructL();

    60 

    61 

    62 public: // API

    63 

    64     /**

    65      * Loads the persistent widget list from storage.

    66      * This is typically done once after construction.

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

    68      */

    69     void LoadL();

    70 

    71     /**

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

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

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

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

    76      * 

    77      * @param aArray the array of widget daya types

    78      */

    79     void StoreL( const ROrderArray& aArray );

    80 

    81     /**

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

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

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

    85      * there must be something persisted.

    86      * 

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

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

    89      */

    90     TInt IndexOf( const CWmWidgetData& aWidgetData ) const;

    91 

    92     /**

    93      * Retrieves an index of given widget order object within the order list.

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

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

    96      * there must be something persisted.

    97      * 

    98      * @param aWidgetOrder data to seek index of in the sorted order

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

   100      */

   101     TInt IndexOf( const CWmWidgetOrderData& aWidgetOrder ) const;

   102     

   103     /**

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

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

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

   107      */

   108     TBool IsEmpty() const;

   109 

   110 protected:

   111 

   112     /**

   113      * Cleans up the array

   114      */

   115     void CleanupArray();

   116 

   117     /**

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

   119      * in host process private directory.

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

   121      */

   122     void GetStoreFileNameL( TDes& aPathBuf );

   123 

   124     /**

   125      * Unique tag of a widget

   126      */

   127     class Tag

   128         {

   129         public:

   130             /** constructs a tag from parameters */

   131             Tag( TInt32 aUid, HBufC16* aPublisherId );

   132 

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

   134             TBool Matches( const CWmWidgetData& aWidgetData ) const;

   135 

   136             /** compares a tag agains a widget order */

   137             TBool Matches( const CWmWidgetOrderData& aWidgetOrder ) const;

   138                         

   139             /** widget uid */

   140             TInt32 iUid;

   141 

   142             /** widget publisher id */

   143             HBufC16* iPublisherId;

   144         };

   145 

   146 private: // data members

   147 

   148     /** the file session */

   149     RFs& iFs;

   150 

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

   152     RArray<Tag> iTagArray;

   153 

   154     };

   155 

   156 

   157 #endif // WMPERSISTENTWIDGETORDER_H