1 /* |
|
2 * Copyright (c) 2005-2006 Nokia Corporation and/or its subsidiary(-ies). |
|
3 * All rights reserved. |
|
4 * This component and the accompanying materials are made available |
|
5 * under the terms of "Eclipse Public License v1.0" |
|
6 * which accompanies this distribution, and is available |
|
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
8 * |
|
9 * Initial Contributors: |
|
10 * Nokia Corporation - initial contribution. |
|
11 * |
|
12 * Contributors: |
|
13 * |
|
14 * Description: CMnMapView class |
|
15 * |
|
16 */ |
|
17 |
|
18 |
|
19 #ifndef MN_MAPVIEW_H |
|
20 #define MN_MAPVIEW_H |
|
21 |
|
22 #include <e32base.h> |
|
23 #include <EPos_Landmarks.h> |
|
24 #include <lbsposition.h> |
|
25 |
|
26 class RFs; |
|
27 class CApaServerAppExitMonitor; |
|
28 class MAknServerAppExitObserver; |
|
29 class CMnProvider; |
|
30 class CPosLandmark; |
|
31 class RMnMapViewServiceClient; |
|
32 |
|
33 /** @brief Provides access to map view features. |
|
34 * |
|
35 * The ShowMapL() method allows to show map of some area, which can be specified |
|
36 * by SetMapAreaL(). ShowCurrentLocationL() opens a map with current location |
|
37 * in the center. SelectFromMapL() allows to ask user to select some location |
|
38 * from the map. Client can request that some landmarks should be drawn on the map, |
|
39 * when it is shown, by using AddLandmarksToShowL. |
|
40 * Subsequent calls to this method will add landmarks to show list. To reset the |
|
41 * list, call @ref ResetLandmarksToShow. |
|
42 * |
|
43 * Two overloads of AddLandmarksToShowL exist for linked and not linked landmarks. |
|
44 * The linked landmark is the one, which has its landmark ID set. |
|
45 * Linked landmarks are sent to Provider Application along with their |
|
46 * landmark database URI, which allows Provider Application to get full category |
|
47 * information of the landmark. |
|
48 * |
|
49 * To create an instance of the class, use @ref NewL or @ref NewChainedL methods. They |
|
50 * require instance of CMnProvider, defined in Map and Navigation Provider Discovery API. |
|
51 * |
|
52 * Asynchronous operations can be cancelled by @ref Cancel(). |
|
53 * Only one asynchronous request can be issued at a time, otherwise client |
|
54 * will be panicked with KMnPanicDuplicateRequest. |
|
55 * |
|
56 * @since 3.1 |
|
57 * @lib mnclientlib.dll |
|
58 * @ingroup MapNavAPI |
|
59 */ |
|
60 class CMnMapView : public CBase |
|
61 { |
|
62 public : |
|
63 |
|
64 /** Type for bitmap of flags defined by TOption */ |
|
65 typedef TUint32 TOptions; |
|
66 |
|
67 /** @brief Map view options */ |
|
68 enum TOption |
|
69 { |
|
70 /** Default value */ |
|
71 EOptionNone, |
|
72 /** Defines that only landmarks specified by AddLandmarksToShowL |
|
73 * are allowed to be selected by user. */ |
|
74 EOptionRestrictSelection |
|
75 }; |
|
76 |
|
77 /** @brief Defines whether current location shall be marked on map */ |
|
78 enum TCurrentLocationOption |
|
79 { |
|
80 /** Current location is not shown (default). */ |
|
81 ECurrentLocationDisabled, |
|
82 /** Current location is shown only if it's within visible area */ |
|
83 ECurrentLocationEnabled, |
|
84 /** Current location is visible always. Provider Application selects |
|
85 appropriate zoom (and position, if area center is not specified) |
|
86 to make sure current location is visible. */ |
|
87 ECurrentLocationShowAlways |
|
88 }; |
|
89 |
|
90 /** @brief Defines type of selection result */ |
|
91 enum TSelectionResultType |
|
92 { |
|
93 /** Undefined result */ |
|
94 ESelectionNone, |
|
95 /** Free location has been selected. |
|
96 * Use @ref RetrieveSelectionResultL() to |
|
97 * get result of selection. */ |
|
98 ESelectionFreeLandmark, |
|
99 /** One of landmarks passed by instance has been selected. |
|
100 * Use @ref RetrieveSelectionResultL(TInt&) to |
|
101 * get result of selection. */ |
|
102 ESelectionLandmarkIndex, |
|
103 /** One of landmarks passed as landmark ID and database URI has been selected. |
|
104 * Use @ref RetrieveSelectionResultL(TPosLmItemId&, HBufC*&) to |
|
105 * get result of selection. */ |
|
106 ESelectionLinkedLandmark |
|
107 }; |
|
108 |
|
109 /** Destructor */ |
|
110 virtual ~CMnMapView(); |
|
111 |
|
112 /** @brief Creates new instance of the class. Provider Application |
|
113 * will be executed standalone. |
|
114 * |
|
115 * @param[in] aProvider Provider Application to be used for showing map. |
|
116 * @return Pointer to new instance of the class. |
|
117 * |
|
118 * @leave KErrNotSupported Selected Provider Application does not support |
|
119 * map view services (@ref CMnProvider::EServiceMapView). |
|
120 */ |
|
121 IMPORT_C static CMnMapView* NewL( CMnProvider& aProvider ); |
|
122 |
|
123 /** @brief Creates new instance of the class. Provider Application |
|
124 * will be executed chained (unless Provider Application defines that |
|
125 * it should be started in background). |
|
126 * |
|
127 * @param[in] aProvider Provider Application to be used for showing map. |
|
128 * @return Pointer to new instance of the class. |
|
129 * |
|
130 * @leave KErrNotSupported Selected Provider Application does not support |
|
131 * map view services (@ref CMnProvider::EServiceMapView). |
|
132 */ |
|
133 IMPORT_C static CMnMapView* NewChainedL( CMnProvider& aProvider ); |
|
134 |
|
135 /** @brief Shows map on the screen. |
|
136 * |
|
137 * This method completes as soon as request reaches Provider |
|
138 * Application. Map is shown then in Provider Application's process. |
|
139 * |
|
140 * If map area is specified by SetMapAreaL(), then this area of map |
|
141 * will be visible, when it is shown. |
|
142 * Otherwise, if only list of landmarks to show is specified, |
|
143 * then area covering all landmarks is visible. |
|
144 * If Current Location Option is set to @ref |
|
145 * ECurrentLocationShowAlways, then it may modify visible area. |
|
146 * |
|
147 * If neither area nor landmarks are specified, and current location |
|
148 * option is not "always", then simply last shown map (as determined by selected |
|
149 * provider application) is shown. If map was never shown before, then |
|
150 * Provider Application shows map from its default position. |
|
151 */ |
|
152 IMPORT_C void ShowMapL(); |
|
153 |
|
154 /** @brief Shows map on the screen, with current location in the center. |
|
155 * |
|
156 * This method completes as soon as request reaches Provider |
|
157 * Application. Map is shown then in Provider Application's process. |
|
158 * |
|
159 * Same options are applied to this method as to ShowMapL() |
|
160 * (with the exception that area center point is ignored) |
|
161 */ |
|
162 IMPORT_C void ShowCurrentLocationL(); |
|
163 |
|
164 /** @brief Shows map on the screen and asks user to select a position. |
|
165 * |
|
166 * If EOptionsRestrictSelection option is set, then user can select |
|
167 * only those landmarks, which are specified with one of AddLandmarksToShowL |
|
168 * overrides. Otherwise any location is allowed to be selected. |
|
169 * |
|
170 * User is shown a view with default selection request text. This text |
|
171 * can be overridden with SetCustomRequestTextL(). |
|
172 * |
|
173 * See SelectionResultType() for how to retrieve selection result. |
|
174 * |
|
175 * This is asynchronous request and can be cancelled with Cancel(). |
|
176 * |
|
177 * This method can leave in case of memory lack or other system error. |
|
178 * If it leaves, no asynchronous request is outstanding. |
|
179 * |
|
180 * @param[out] aStatus Status of asynchronous operation. Contains error code, |
|
181 * when request is completed: KErrNone, if user has made |
|
182 * selection, KErrCancel - if request is cancelled, or user |
|
183 * refused to make selection. KErrArgument if no landmarks to |
|
184 * be shown are specified and ERestrictSelection is set. |
|
185 * Otherwise any of system-wide error codes. |
|
186 * |
|
187 * @panic "MnClientPanic"-KMnPanicDuplicateRequest if new asynchronous request |
|
188 * is issued before previous one is completed. |
|
189 */ |
|
190 IMPORT_C void SelectFromMapL( TRequestStatus& aStatus ); |
|
191 |
|
192 /** @brief Adds linked landmarks to the list of landmarks to be shown on map. |
|
193 * |
|
194 * Landmarks are passed along with URL of the database, where they reside. |
|
195 * This allows to utilize category information from landmarks. |
|
196 * If landmarks from several databases shall be shown, call this method |
|
197 * for every such database. All landmarks are added to a single list. |
|
198 * To clear that list, call ResetLandmarksToShow(). |
|
199 * |
|
200 * @param[in] aDatabaseUri A database, to which belong landmarks, listed |
|
201 * in aLandmarkIds parameter. |
|
202 * @param[in] aLandmarkIds IDs of landmarks to add to show list. |
|
203 * |
|
204 * @leave KErrLocked Asynchronous request (SelectFromMapL) is outstanding. |
|
205 */ |
|
206 IMPORT_C void AddLandmarksToShowL( |
|
207 const TDesC& aDatabaseUri, |
|
208 RArray<TPosLmItemId>& aLandmarkIds ); |
|
209 |
|
210 /** @brief Adds landmarks to the list of landmarks to be shown on map. |
|
211 * |
|
212 * Landmarks are passed as instances. This variant is |
|
213 * for passing landmarks, which are not stored in databases. |
|
214 * |
|
215 * All landmarks are added to a single list. |
|
216 * To clear that list, call ResetLandmarksToShow(). |
|
217 * |
|
218 * With large amount of landmarks, it is recommended to use overload, |
|
219 * which accepts linked landmarks, if possible. |
|
220 * |
|
221 * @param[in] aLandmarks Array of landmarks to add to show list. |
|
222 * |
|
223 * @leave KErrLocked Asynchronous request (SelectFromMapL) is outstanding. |
|
224 */ |
|
225 IMPORT_C void AddLandmarksToShowL( RPointerArray<CPosLandmark>& aLandmarks ); |
|
226 |
|
227 /** @brief Adds landmarks to the list of landmarks to be shown on map. |
|
228 * |
|
229 * Landmarks are passed as packed instances (see @p PosLandmarkSeriazation from |
|
230 * Landmarks API). This overload is for passing landmarks, which are not stored |
|
231 * in databases. It is more efficient than |
|
232 * AddLandmarksToShowL( RPointerArray<CPosLandmark>& ) in terms of memory usage, |
|
233 * if client already possess landmarks in packed form. |
|
234 * |
|
235 * All landmarks are added to a single list. |
|
236 * To clear that list, call ResetLandmarksToShow(). |
|
237 * |
|
238 * With large amount of landmarks, it is recommended to use overload, |
|
239 * which accepts linked landmarks, if possible. |
|
240 * |
|
241 * @param[in] aPackedLandmarks Array of landmarks to add to show list. |
|
242 * |
|
243 * @leave KErrLocked Asynchronous request (SelectFromMapL) is outstanding. |
|
244 */ |
|
245 IMPORT_C void AddLandmarksToShowL( RArray<TPtrC8>& aPackedLandmarks ); |
|
246 |
|
247 /** @brief Clears the list of landmarks to be shown on map. |
|
248 * This call has no effect during the time when asynchronous request |
|
249 * (SelectFromMapL) is outstanding. |
|
250 */ |
|
251 IMPORT_C void ResetLandmarksToShow(); |
|
252 |
|
253 /** @brief Defines the map area to be shown. |
|
254 * @param[in] aCentralPoint Point on the Earth to be shown in the center |
|
255 * of map view. This setting is ignored, when |
|
256 * ShowCurrentLocationL() is called. |
|
257 * @param aRadius Radius in meters of the area around central point, |
|
258 * which should be visible, when map is shown. |
|
259 * If this setting is too small, then |
|
260 * Provider Application selects smallest possible |
|
261 * radius (maximum zoom). |
|
262 * If NaN, then Provider Application automatically |
|
263 * selects appropriate zoom. This setting is ignored if |
|
264 * ECurrentLocationShowAlways is set. |
|
265 */ |
|
266 IMPORT_C void SetMapAreaL( const TCoordinate& aCentralPoint, TReal aRadius ); |
|
267 |
|
268 /** @brief Clears map area setting. */ |
|
269 IMPORT_C void ResetMapArea(); |
|
270 |
|
271 /** @brief Specifies custom request text for SelectFromMapL() request. |
|
272 * |
|
273 * If not specified, than default request text will be used (as |
|
274 * defined in UI specification). |
|
275 * New setting will have effect only for next map display request. |
|
276 * |
|
277 * @param[in] aCustomText Text to be shown as selection request to user. |
|
278 */ |
|
279 IMPORT_C void SetCustomRequestTextL(const TDesC& aCustomText); |
|
280 |
|
281 /** @brief Specifies that default request text shall be used |
|
282 * starting from next SelectFromMapL() request. |
|
283 */ |
|
284 IMPORT_C void SetUseDefaultRequestText(); |
|
285 |
|
286 /** @brief Specifies how current location is shown on map. |
|
287 * New setting will have effect only for next map display request. |
|
288 * @param aCurrentLocationOption One of TCurrentLocationOption values. |
|
289 */ |
|
290 IMPORT_C void SetCurrentLocationOption( |
|
291 TCurrentLocationOption aCurrentLocationOption ); |
|
292 |
|
293 /** @brief Retrieves current state of current location option. |
|
294 * @return One of TCurrentLocationOption values. |
|
295 */ |
|
296 IMPORT_C TCurrentLocationOption CurrentLocationOption() const; |
|
297 |
|
298 /** @brief Sets map view options. |
|
299 * New settings will have effect only for next map display request. |
|
300 * @param aOptions Bitmap of TOption values. |
|
301 */ |
|
302 IMPORT_C void SetOptions( TOptions aOptions ); |
|
303 |
|
304 /** @brief Retrieves current map view options. |
|
305 * @return Bitmap of TOption values. |
|
306 */ |
|
307 IMPORT_C TOptions Options() const; |
|
308 |
|
309 /** @brief Returns type of selection result |
|
310 * @return One of @ref TSelectionResultType values. |
|
311 */ |
|
312 IMPORT_C TSelectionResultType SelectionResultType() const; |
|
313 |
|
314 /** @brief Retrieves selection result as landmark instance. |
|
315 * @return Landmark with information about selected location. Client takes ownership. |
|
316 * @leave KErrNotFound Result is not available or is of other type. |
|
317 * See @ref SelectionResultType() for details. |
|
318 * |
|
319 * @see SelectionResultType() |
|
320 * @see RetrieveSelectionResultL(TInt&) |
|
321 * @see RetrieveSelectionResultL(TPosLmItemId&, HBufC*&) |
|
322 */ |
|
323 IMPORT_C CPosLandmark* RetrieveSelectionResultL(); |
|
324 |
|
325 /** @brief Retrieves selection result as index of given landmark instance. |
|
326 * @param[out] aLandmarkIndex Index of a landmark passed as instance, |
|
327 * which has been selected. |
|
328 * @leave KErrNotFound Result is not available or is of other type. |
|
329 * See @ref SelectionResultType() for details. |
|
330 * |
|
331 * @see SelectionResultType() |
|
332 * @see RetrieveSelectionResultL() |
|
333 * @see RetrieveSelectionResultL(TPosLmItemId&, HBufC*&) |
|
334 */ |
|
335 IMPORT_C void RetrieveSelectionResultL( TInt& aLandmarkIndex ); |
|
336 |
|
337 /** @brief Retrieves ID of selected landmark. |
|
338 * @param[out] aLandmarkId On return, ID of selected landmark in the database, |
|
339 * specified by aDatabaseUri. |
|
340 * @param[out] aDatabaseUri On return, URI of the database of selected landmark. |
|
341 Client takes ownership. |
|
342 * @leave KErrNotFound Result is not available or is of other type. |
|
343 * See @ref SelectionResultType() for details. |
|
344 * |
|
345 * @see SelectionResultType() |
|
346 * @see RetrieveSelectionResultL() |
|
347 * @see RetrieveSelectionResultL(TInt&) |
|
348 */ |
|
349 IMPORT_C void RetrieveSelectionResultL( TPosLmItemId& aLandmarkId, HBufC*& aDatabaseUri ); |
|
350 |
|
351 /** @brief Cancels current outstanding asynchronous request. */ |
|
352 IMPORT_C void Cancel(); |
|
353 |
|
354 /** @brief Sets observer of provider application lifetime. |
|
355 * Client will receive exit event from provider application. |
|
356 * By default exit events from provider application are not monitored. |
|
357 * @param[in] aObserver Exit observer. |
|
358 * @leave KErrAlreadyExists if observer is already set. |
|
359 */ |
|
360 IMPORT_C void SetExitObserverL( MAknServerAppExitObserver& aObserver ); |
|
361 |
|
362 /** @brief Removes observer of provider application lifetime. */ |
|
363 IMPORT_C void RemoveExitObserver(); |
|
364 |
|
365 private : |
|
366 /** C++ constructor */ |
|
367 CMnMapView(); |
|
368 CMnMapView( const CMnMapView& ); //prevent default copy constructor |
|
369 CMnMapView& operator=( const CMnMapView& ); //prevent default assignment operator |
|
370 |
|
371 void ConstructCommonL( CMnProvider& aProvider ); |
|
372 void ConstructNewL( CMnProvider& aProvider ); |
|
373 void ConstructChainedL( CMnProvider& aProvider ); |
|
374 void PostConstructL(); |
|
375 |
|
376 HBufC* LoadResourceTextL( |
|
377 RFs& aFsSession, |
|
378 const TDesC& aRscFile, |
|
379 TInt aResourceId ); |
|
380 |
|
381 private : |
|
382 TOptions iOptions; |
|
383 TCurrentLocationOption iCurrentLocationOption; |
|
384 TCoordinate iCentralPoint; |
|
385 TReal iRadius; |
|
386 |
|
387 HBufC* iDefaultRequestText; |
|
388 |
|
389 RMnMapViewServiceClient* iSession; |
|
390 CApaServerAppExitMonitor* iExitMonitor; |
|
391 }; |
|
392 |
|
393 #endif // MN_MAPVIEW_H |
|