williamr@4: /* williamr@4: * Copyright (c) 2005-2006 Nokia Corporation and/or its subsidiary(-ies). williamr@4: * All rights reserved. williamr@4: * This component and the accompanying materials are made available williamr@4: * under the terms of "Eclipse Public License v1.0" williamr@4: * which accompanies this distribution, and is available williamr@4: * at the URL "http://www.eclipse.org/legal/epl-v10.html". williamr@4: * williamr@4: * Initial Contributors: williamr@4: * Nokia Corporation - initial contribution. williamr@4: * williamr@4: * Contributors: williamr@4: * williamr@4: * Description: CPosLmDisplayData class williamr@4: * williamr@4: */ williamr@4: williamr@4: williamr@4: #ifndef CPOSLMDISPLAYDATA_H williamr@4: #define CPOSLMDISPLAYDATA_H williamr@4: williamr@4: #include williamr@4: williamr@4: const TInt KPosLmNoNewItems = -1; williamr@4: williamr@4: class CPosLmDisplayItem; williamr@4: class CPosLmPartialReadParameters; williamr@4: williamr@4: /** williamr@4: * Displayable data collection. williamr@4: * williamr@4: * A displayable data collection consists of displayable items williamr@4: * (@ref CPosLmDisplayItem). A displayable data collection either williamr@4: * consists of landmark items (if a landmark search has been started) williamr@4: * or category items (if a category search has been started). williamr@4: * Items of different types cannot be mixed in the collection. williamr@4: * williamr@4: * Displayable data is used in @ref CPosLandmarkSearch and williamr@4: * @ref CPosLmMultiDbSearch to hold search results. The collection is williamr@4: * populated with new results every time the next search step is executed. williamr@4: * Displayable items contain full or partial williamr@4: * (see @ref CPosLandmarkDatabase::SetPartialReadParameters) williamr@4: * landmark data or full category data, and can be used to display search williamr@4: * results already during the search and also after it has completed. williamr@4: * williamr@4: * Note: The single class instance may only be used by one search williamr@4: * instance at a time. williamr@4: * williamr@4: * @lib eposlmsearchlib.lib williamr@4: * @since S60 3.0 williamr@4: */ williamr@4: class CPosLmDisplayData : public CBase williamr@4: { williamr@4: public: williamr@4: williamr@4: /** williamr@4: * Two-phased constructor. williamr@4: * williamr@4: * @returns A new instance of this class. williamr@4: */ williamr@4: IMPORT_C static CPosLmDisplayData* NewL(); williamr@4: williamr@4: /** williamr@4: * Destructor. williamr@4: */ williamr@4: virtual ~CPosLmDisplayData(); williamr@4: williamr@4: public: williamr@4: williamr@4: /** williamr@4: * Returns the index of the next match found during current asynchronous williamr@4: * search operation. If the search is executed synchronously, then all williamr@4: * indexes of the matches found during the search are returned one williamr@4: * by one. williamr@4: * williamr@4: * After each search step, the new item indexes are returned in williamr@4: * ascending order according to the specified sort preference in williamr@4: * the search. williamr@4: * williamr@4: * @return The item index or @p KPosLmNoNewItems when no new items williamr@4: * are available. williamr@4: */ williamr@4: IMPORT_C TInt NewItemIndex(); williamr@4: williamr@4: /** williamr@4: * Returns the number of items in the collection. williamr@4: * williamr@4: * @return The number of items. williamr@4: */ williamr@4: IMPORT_C TInt Count() const; williamr@4: williamr@4: /** williamr@4: * Resets the collection and deletes all contained items. williamr@4: */ williamr@4: IMPORT_C void Reset(); williamr@4: williamr@4: /** williamr@4: * Returns the displayable item specified by index. williamr@4: * The index must be strictly less than @ref Count and not less than 0. williamr@4: * williamr@4: * @param[in] aItemIndex A displayable item index. williamr@4: * @return A displayable item. williamr@4: * williamr@4: * @panic "Landmarks Client"-EPosInvalidIndex williamr@4: * Item index is beyond valid range. williamr@4: */ williamr@4: IMPORT_C CPosLmDisplayItem& DisplayItem( TInt aItemIndex ) const; williamr@4: williamr@4: /** williamr@4: * Sets the partial read parameters for this display data. williamr@4: * williamr@4: * Partial read parameters are used to define which landmark data should williamr@4: * be read during a landmark search. If no partial read parameters are williamr@4: * set, the whole landmark will be read. williamr@4: * williamr@4: * This function only affects the searches which are started after williamr@4: * it is called. The current search is not affected. williamr@4: * williamr@4: * If landmarks are sorted by name, the name will always be a part of williamr@4: * the landmark in the display data, even if it is not requested. williamr@4: * williamr@4: * Note: Partial read parameters are only used for landmark searches. williamr@4: * williamr@4: * @param[in] aPartialSettings The partial read parameters. williamr@4: */ williamr@4: IMPORT_C void SetPartialReadParametersL( williamr@4: const CPosLmPartialReadParameters& aPartialSettings williamr@4: ); williamr@4: williamr@4: /** williamr@4: * Unsets the partial read parameters for this display data. williamr@4: * williamr@4: * This means that from now on all landmarks added to this display data williamr@4: * instance will contain all information. williamr@4: * williamr@4: * To have any affect, this function must be called before a search is williamr@4: * started. If it is called during a search, it will only affect williamr@4: * the next search. williamr@4: * williamr@4: * Note: Partial read parameters will only have effect on landmarks williamr@4: * searches. williamr@4: */ williamr@4: IMPORT_C void UnsetPartialReadParameters(); williamr@4: williamr@4: /** @internal */ williamr@4: /* Returns the partial read parameters set for this display data. williamr@4: * williamr@4: * @return Partial read parameters or NULL if not set. williamr@4: */ williamr@4: CPosLmPartialReadParameters* PartialReadParameters() const; williamr@4: williamr@4: /** @internal */ williamr@4: /* Returns a reference to all the displayable items. williamr@4: * This array owns its displayable items. williamr@4: * williamr@4: * @return The items array. williamr@4: */ williamr@4: RPointerArray& DisplayItems(); williamr@4: williamr@4: /** @internal */ williamr@4: /* Returns a reference to the new displayable items. williamr@4: * This array does not own its displayable items. williamr@4: * New displayable items are always a subset of all displayable items. williamr@4: * williamr@4: * @return The new item indexes array. williamr@4: */ williamr@4: RPointerArray& NewDisplayItems(); williamr@4: williamr@4: private: williamr@4: williamr@4: // C++ constructor. williamr@4: CPosLmDisplayData(); williamr@4: williamr@4: private: williamr@4: williamr@4: RPointerArray iDisplayItems; williamr@4: RPointerArray iNewDisplayItems; williamr@4: CPosLmPartialReadParameters* iPartialParameters; williamr@4: williamr@4: }; williamr@4: williamr@4: #endif // CPOSLMDISPLAYDATA_H williamr@4: williamr@4: