/*
* Copyright (c) 2009 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:
* Defines an ordered list of widget id's with persistence capability
*
*/

#ifndef WMPERSISTENTWIDGETORDER_H
#define WMPERSISTENTWIDGETORDER_H

// INCLUDES
#include <e32base.h>
#include "wmwidgetdata.h"
#include "wmwidgetorderdata.h"

// FORWARD DECLARATIONS
class RFs;

// CLASS DECLARATION
/**
 *  CWmPersistentWidgetOrder
 * This class is an ordered list of widget identifiers. The list can be
 * serialised and extract from stream and persisted. The list can be used
 * in sorting a pointer array of CWmWidgetData.
 */
NONSHARABLE_CLASS( CWmPersistentWidgetOrder ) : public CBase
    {

public: // Constructors and destructor
    /** 
     * static constructor.
     */
    static CWmPersistentWidgetOrder* NewL( RFs& aFs );

    /** Destructor. */
    ~CWmPersistentWidgetOrder();

private: // private construction

    /**
     * constructor
     */
    CWmPersistentWidgetOrder( RFs& aFs );

    /**
     * 2nd phase constructor
     */
    void ConstructL();


public: // API

    /**
     * Loads the persistent widget list from storage.
     * This is typically done once after construction.
     * The instance can now be used to sort widget data.
     */
    void LoadL();

    /**
     * Stores a sorted array of WmWidgetData types. Note that
     * the order will be directly stored and a copy will not
     * be kept locally, so this instance can not be used to
     * sort widget data until LoadL() is called.
     * 
     * @param aArray the array of widget daya types
     */
    void StoreL( const ROrderArray& aArray );

    /**
     * Retrieves an index of given widget data object within the list.
     * This index can be used to sort and organise. Note that LoadL()
     * must be used prior to calling this method, and before that
     * there must be something persisted.
     * 
     * @param aWidgetData data to seek index of in the sorted order
     * @return the index found, or KErrNotFound if widget is new
     */
    TInt IndexOf( const CWmWidgetData& aWidgetData ) const;

    /**
     * Retrieves an index of given widget order object within the order list.
     * This index can be used to sort and organise. Note that LoadL()
     * must be used prior to calling this method, and before that
     * there must be something persisted.
     * 
     * @param aWidgetOrder data to seek index of in the sorted order
     * @return the index found, or KErrNotFound if widget is new
     */
    TInt IndexOf( const CWmWidgetOrderData& aWidgetOrder ) const;
    
    /**
     * checks if the persistent widget order is empty. In this case it does
     * not make any sense to use the object to sort anything.
     * Note that before loading the object is always empty.
     */
    TBool IsEmpty() const;

protected:

    /**
     * Cleans up the array
     */
    void CleanupArray();

    /**
     * build the storage file path and name. The storage file will be located
     * in host process private directory.
     * @param aPathBuf a buffer to receive the complete file path
     */
    void GetStoreFileNameL( TDes& aPathBuf );

    /**
     * Unique tag of a widget
     */
    class Tag
        {
        public:
            /** constructs a tag from parameters */
            Tag( TInt32 aUid, HBufC16* aPublisherId );

            /** compares a tag agains a widget data */
            TBool Matches( const CWmWidgetData& aWidgetData ) const;

            /** compares a tag agains a widget order */
            TBool Matches( const CWmWidgetOrderData& aWidgetOrder ) const;
                        
            /** widget uid */
            TInt32 iUid;

            /** widget publisher id */
            HBufC16* iPublisherId;
        };

private: // data members

    /** the file session */
    RFs& iFs;

    /** array of widget tags for sorting */
    RArray<Tag> iTagArray;

    };


#endif // WMPERSISTENTWIDGETORDER_H