1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/mw/EPos_CPosLmDisplayData.h Wed Mar 31 12:33:34 2010 +0100
1.3 @@ -0,0 +1,184 @@
1.4 +/*
1.5 +* Copyright (c) 2005-2006 Nokia Corporation and/or its subsidiary(-ies).
1.6 +* All rights reserved.
1.7 +* This component and the accompanying materials are made available
1.8 +* under the terms of "Eclipse Public License v1.0"
1.9 +* which accompanies this distribution, and is available
1.10 +* at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.11 +*
1.12 +* Initial Contributors:
1.13 +* Nokia Corporation - initial contribution.
1.14 +*
1.15 +* Contributors:
1.16 +*
1.17 +* Description: CPosLmDisplayData class
1.18 +*
1.19 +*/
1.20 +
1.21 +
1.22 +#ifndef CPOSLMDISPLAYDATA_H
1.23 +#define CPOSLMDISPLAYDATA_H
1.24 +
1.25 +#include <e32base.h>
1.26 +
1.27 +const TInt KPosLmNoNewItems = -1;
1.28 +
1.29 +class CPosLmDisplayItem;
1.30 +class CPosLmPartialReadParameters;
1.31 +
1.32 +/**
1.33 +* Displayable data collection.
1.34 +*
1.35 +* A displayable data collection consists of displayable items
1.36 +* (@ref CPosLmDisplayItem). A displayable data collection either
1.37 +* consists of landmark items (if a landmark search has been started)
1.38 +* or category items (if a category search has been started).
1.39 +* Items of different types cannot be mixed in the collection.
1.40 +*
1.41 +* Displayable data is used in @ref CPosLandmarkSearch and
1.42 +* @ref CPosLmMultiDbSearch to hold search results. The collection is
1.43 +* populated with new results every time the next search step is executed.
1.44 +* Displayable items contain full or partial
1.45 +* (see @ref CPosLandmarkDatabase::SetPartialReadParameters)
1.46 +* landmark data or full category data, and can be used to display search
1.47 +* results already during the search and also after it has completed.
1.48 +*
1.49 +* Note: The single class instance may only be used by one search
1.50 +* instance at a time.
1.51 +*
1.52 +* @lib eposlmsearchlib.lib
1.53 +* @since S60 3.0
1.54 +*/
1.55 +class CPosLmDisplayData : public CBase
1.56 + {
1.57 + public:
1.58 +
1.59 + /**
1.60 + * Two-phased constructor.
1.61 + *
1.62 + * @returns A new instance of this class.
1.63 + */
1.64 + IMPORT_C static CPosLmDisplayData* NewL();
1.65 +
1.66 + /**
1.67 + * Destructor.
1.68 + */
1.69 + virtual ~CPosLmDisplayData();
1.70 +
1.71 + public:
1.72 +
1.73 + /**
1.74 + * Returns the index of the next match found during current asynchronous
1.75 + * search operation. If the search is executed synchronously, then all
1.76 + * indexes of the matches found during the search are returned one
1.77 + * by one.
1.78 + *
1.79 + * After each search step, the new item indexes are returned in
1.80 + * ascending order according to the specified sort preference in
1.81 + * the search.
1.82 + *
1.83 + * @return The item index or @p KPosLmNoNewItems when no new items
1.84 + * are available.
1.85 + */
1.86 + IMPORT_C TInt NewItemIndex();
1.87 +
1.88 + /**
1.89 + * Returns the number of items in the collection.
1.90 + *
1.91 + * @return The number of items.
1.92 + */
1.93 + IMPORT_C TInt Count() const;
1.94 +
1.95 + /**
1.96 + * Resets the collection and deletes all contained items.
1.97 + */
1.98 + IMPORT_C void Reset();
1.99 +
1.100 + /**
1.101 + * Returns the displayable item specified by index.
1.102 + * The index must be strictly less than @ref Count and not less than 0.
1.103 + *
1.104 + * @param[in] aItemIndex A displayable item index.
1.105 + * @return A displayable item.
1.106 + *
1.107 + * @panic "Landmarks Client"-EPosInvalidIndex
1.108 + * Item index is beyond valid range.
1.109 + */
1.110 + IMPORT_C CPosLmDisplayItem& DisplayItem( TInt aItemIndex ) const;
1.111 +
1.112 + /**
1.113 + * Sets the partial read parameters for this display data.
1.114 + *
1.115 + * Partial read parameters are used to define which landmark data should
1.116 + * be read during a landmark search. If no partial read parameters are
1.117 + * set, the whole landmark will be read.
1.118 + *
1.119 + * This function only affects the searches which are started after
1.120 + * it is called. The current search is not affected.
1.121 + *
1.122 + * If landmarks are sorted by name, the name will always be a part of
1.123 + * the landmark in the display data, even if it is not requested.
1.124 + *
1.125 + * Note: Partial read parameters are only used for landmark searches.
1.126 + *
1.127 + * @param[in] aPartialSettings The partial read parameters.
1.128 + */
1.129 + IMPORT_C void SetPartialReadParametersL(
1.130 + const CPosLmPartialReadParameters& aPartialSettings
1.131 + );
1.132 +
1.133 + /**
1.134 + * Unsets the partial read parameters for this display data.
1.135 + *
1.136 + * This means that from now on all landmarks added to this display data
1.137 + * instance will contain all information.
1.138 + *
1.139 + * To have any affect, this function must be called before a search is
1.140 + * started. If it is called during a search, it will only affect
1.141 + * the next search.
1.142 + *
1.143 + * Note: Partial read parameters will only have effect on landmarks
1.144 + * searches.
1.145 + */
1.146 + IMPORT_C void UnsetPartialReadParameters();
1.147 +
1.148 + /** @internal */
1.149 + /* Returns the partial read parameters set for this display data.
1.150 + *
1.151 + * @return Partial read parameters or NULL if not set.
1.152 + */
1.153 + CPosLmPartialReadParameters* PartialReadParameters() const;
1.154 +
1.155 + /** @internal */
1.156 + /* Returns a reference to all the displayable items.
1.157 + * This array owns its displayable items.
1.158 + *
1.159 + * @return The items array.
1.160 + */
1.161 + RPointerArray<CPosLmDisplayItem>& DisplayItems();
1.162 +
1.163 + /** @internal */
1.164 + /* Returns a reference to the new displayable items.
1.165 + * This array does not own its displayable items.
1.166 + * New displayable items are always a subset of all displayable items.
1.167 + *
1.168 + * @return The new item indexes array.
1.169 + */
1.170 + RPointerArray<CPosLmDisplayItem>& NewDisplayItems();
1.171 +
1.172 + private:
1.173 +
1.174 + // C++ constructor.
1.175 + CPosLmDisplayData();
1.176 +
1.177 + private:
1.178 +
1.179 + RPointerArray<CPosLmDisplayItem> iDisplayItems;
1.180 + RPointerArray<CPosLmDisplayItem> iNewDisplayItems;
1.181 + CPosLmPartialReadParameters* iPartialParameters;
1.182 +
1.183 + };
1.184 +
1.185 +#endif // CPOSLMDISPLAYDATA_H
1.186 +
1.187 +