/*

* Copyright (c) 2002 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of the License "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:  Declaration of FavouritesItemList

*

*/

#ifndef FAVOURITES_ITEM_LIST_H

#define FAVOURITES_ITEM_LIST_H

// INCLUDE FILES

#include <e32base.h>

// CONSTANTS

// FORWARD DECLARATION

class CFavouritesItem;

class RWriteStream;

class RReadStream;

// CLASS DECLARATION

/**

* CFavouritesItemList is the Array of CFavouritesItem-s. 

* Items are owned and deleted upon destruction.

* Note: using this array downcasted to its base can result in leaks.

* Delete method of base class is not virtual!

*/

class CFavouritesItemList: public CArrayPtrFlat<CFavouritesItem>

    {

    public:     // Constructor and destructor

        /**

        * Constructor.

        * @since 0.9       

        */

        IMPORT_C CFavouritesItemList();

        /**

        * Destructor. Elements are destroyed.

        * @since 0.9       

        */

        IMPORT_C virtual ~CFavouritesItemList();

    public:     // new methods

        /**

        * Remove and destroy an element. Invalid params will Panic.

        * @since 0.9       

        * @param aIndex Index of element to delete.

        * @return void 

        */

        IMPORT_C void Delete( TInt aIndex );

        /**

        * Remove and destroy elements. Invalid params Panic.

        * @since 0.9       

        * @param aIndex Index of start element to delete.

        * @param aCount Number of items to delete.

        * @return void

        */

        IMPORT_C void Delete( TInt aIndex, TInt aCount );

    public:     // Sorting

        /**

        * Comparison function type; compare two items. Should leave in error.

        * @since 0.9       

        * @param aLeft item to compare to aRight.

        * @param aRight Item to compare to aLeft.

        * @return

        *   - negative value, if aLeft is less than aRight;

        *   - 0,              if aLeft equals to aRight;

        *   - positive value, if aLeft is greater than aRight.

        */

        typedef TInt (*ComparisonFuncL)

            ( const CFavouritesItem& aLeft, const CFavouritesItem& aRight );

        /**

        * Sort the list using bubble-sort.

        * @since 0.9       

        * @param aCompareItemsL Function to be used two elements.

        */

        IMPORT_C void SortL( ComparisonFuncL aCompareItemsL );

    public:     // Uid <--> array index conversion

        /**

        * Convert Uid to index.

        * @since 0.9       

        * @param aUid Uid to convert.

        * @return Index for this Uid, or -KErrNotFound if not found.

        */

        IMPORT_C TInt UidToIndex( TInt aUid ) const;

        /**

        * Convert index to Uid.

        * @since 0.9       

        * @param aIndex Index to convert.

        * @return Uid for this index, or KFavouritesNullUid if not found.

        */

        IMPORT_C TInt IndexToUid( TInt aIndex ) const;

        /**

        * Get pointer to item having aUid.

        * @since 0.9       

        * @param aUid Uid of item to look for.

        * @return Pointer to item having aUid, or NULL if there is no such

        * item. Item is still owned by the list.

        */

        IMPORT_C const CFavouritesItem* ItemByUid( TInt aUid ) const;

    public:     // (But not exported:) Streaming

        /**

        * Externalize into a stream.

        * @since 0.9       

        * @param aStream The stream to externalize to.

        */

        void ExternalizeL( RWriteStream& aStream ) const;

        /**

        * Internalize from a stream. Existing data is kept, new ones appended.

        * @since 0.9       

        * @param aStream The stream to externalize from.

        */

        void InternalizeL( RReadStream& aStream );

    };

#endif

// End of file