/*

 * Copyright (c) 2005-2006 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:  CPosLmDisplayData class

 *

 */

 #ifndef CPOSLMDISPLAYDATA_H

 #define CPOSLMDISPLAYDATA_H

 #include <e32base.h>

 const TInt KPosLmNoNewItems = -1;

 class CPosLmDisplayItem;

 class CPosLmPartialReadParameters;

 /**

 * Displayable data collection.

 *

 * A displayable data collection consists of displayable items

 * (@ref CPosLmDisplayItem). A displayable data collection either

 * consists of landmark items (if a landmark search has been started)

 * or category items (if a category search has been started).

 * Items of different types cannot be mixed in the collection.

 *

 * Displayable data is used in @ref CPosLandmarkSearch and

 * @ref CPosLmMultiDbSearch to hold search results. The collection is

 * populated with new results every time the next search step is executed.

 * Displayable items contain full or partial 

 * (see @ref CPosLandmarkDatabase::SetPartialReadParameters)

 * landmark data or full category data, and can be used to display search

 * results already during the search and also after it has completed.

 *

 * Note: The single class instance may only be used by one search

 * instance at a time.

 *

 *  @lib eposlmsearchlib.lib

 *  @since S60 3.0

 */

 class CPosLmDisplayData : public CBase

     {

     public:

         /**

         * Two-phased constructor.

         *

         * @returns A new instance of this class.

         */

         IMPORT_C static CPosLmDisplayData* NewL();

         /**

         * Destructor.

         */

         virtual ~CPosLmDisplayData();

     public:

         /**

         * Returns the index of the next match found during current asynchronous

         * search operation. If the search is executed synchronously, then all

         * indexes of the matches found during the search are returned one

         * by one.

         *

         * After each search step, the new item indexes are returned in

         * ascending order according to the specified sort preference in

         * the search.

         *

         * @return The item index or @p KPosLmNoNewItems when no new items

         *   are available.

         */

         IMPORT_C TInt NewItemIndex();

         /**

         * Returns the number of items in the collection.

         *

         * @return The number of items.

         */

         IMPORT_C TInt Count() const;

         /**

         * Resets the collection and deletes all contained items.

         */

         IMPORT_C void Reset();

         /**

         * Returns the displayable item specified by index.

         * The index must be strictly less than @ref Count and not less than 0.

         *

         * @param[in] aItemIndex A displayable item index.

         * @return A displayable item.

         *

         * @panic "Landmarks Client"-EPosInvalidIndex

         *   Item index is beyond valid range.

         */

         IMPORT_C CPosLmDisplayItem& DisplayItem( TInt aItemIndex ) const;

         /**

         * Sets the partial read parameters for this display data.

         *

         * Partial read parameters are used to define which landmark data should

         * be read during a landmark search. If no partial read parameters are

         * set, the whole landmark will be read.

         *

         * This function only affects the searches which are started after

         * it is called. The current search is not affected.

         *

         * If landmarks are sorted by name, the name will always be a part of

         * the landmark in the display data, even if it is not requested.

         *

         * Note: Partial read parameters are only used for landmark searches.

         *

         * @param[in] aPartialSettings The partial read parameters.

         */

         IMPORT_C void SetPartialReadParametersL(

             const CPosLmPartialReadParameters& aPartialSettings

         );

         /**

         * Unsets the partial read parameters for this display data.

         *

         * This means that from now on all landmarks added to this display data

         * instance will contain all information.

         *

         * To have any affect, this function must be called before a search is

         * started. If it is called during a search, it will only affect

         * the next search.

         *

         * Note: Partial read parameters will only have effect on landmarks

         * searches.

         */

         IMPORT_C void UnsetPartialReadParameters();

         /** @internal */

         /* Returns the partial read parameters set for this display data.

         *

         * @return Partial read parameters or NULL if not set.

         */

         CPosLmPartialReadParameters* PartialReadParameters() const;

         /** @internal */

         /* Returns a reference to all the displayable items.

         * This array owns its displayable items.

         *

         * @return The items array.

         */

         RPointerArray<CPosLmDisplayItem>& DisplayItems();

         /** @internal */

         /* Returns a reference to the new displayable items.

         * This array does not own its displayable items.

         * New displayable items are always a subset of all displayable items.

         *

         * @return The new item indexes array.

         */

         RPointerArray<CPosLmDisplayItem>& NewDisplayItems();

     private:

         // C++ constructor.

         CPosLmDisplayData();

     private:

         RPointerArray<CPosLmDisplayItem> iDisplayItems;

         RPointerArray<CPosLmDisplayItem> iNewDisplayItems;

         CPosLmPartialReadParameters* iPartialParameters;

     };

 #endif      // CPOSLMDISPLAYDATA_H