1 /* |
|
2 * Copyright (c) 2007 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: CMnMapImage class |
|
15 * |
|
16 */ |
|
17 |
|
18 |
|
19 #ifndef MN_MAPIMAGE_H_ |
|
20 #define MN_MAPIMAGE_H_ |
|
21 |
|
22 #include <e32base.h> |
|
23 #include <lbsposition.h> |
|
24 #include <mnmapimageparams.h> |
|
25 |
|
26 class CApaServerAppExitMonitor; |
|
27 class MAknServerAppExitObserver; |
|
28 class CMnProvider; |
|
29 class RMnMapImageServiceClient; |
|
30 class CMnMapImage; |
|
31 class CFbsBitmap; |
|
32 class CMnCoordinateConverterBase; |
|
33 |
|
34 /** Abstract class to be inherited by classes, which want to receive |
|
35 * notification, when image rendering is completed. |
|
36 * @see CMnMapImage |
|
37 * @since 5.0 */ |
|
38 class MMnMapImageRenderCallback |
|
39 { |
|
40 public: |
|
41 /** This callback is called when CMnMapImage has completed rendering |
|
42 * map image. It is not called if rendering was cancelled by client. |
|
43 * @param aStatus Result of the rendering operation: |
|
44 * - @p KErrNone - rendering was completed successfully. |
|
45 * - @p KErrNotSupported - rendering is not possible in specified area |
|
46 * or one of mandatory options are not supported (see @ref TShowOption). |
|
47 * - Other system-wide error codes also possible. |
|
48 * @param aMapImage Instance of CMnMapImage, through which the request has |
|
49 * been issued. */ |
|
50 virtual void HandleRenderingCompletedL( TInt aStatus, CMnMapImage& aMapImage ) = 0; |
|
51 }; |
|
52 |
|
53 /** Provides access to map image rendering features. |
|
54 * |
|
55 * The RenderL() method allows to get bitmap image of some area, which is specified |
|
56 * by SetCenterPoint() and SetScale(). Size of the bitmap is defined by SetSize(). |
|
57 * |
|
58 * To create an instance of the class, use @ref NewL method. It |
|
59 * requires instance of CMnProvider, defined in Map and Navigation Provider Discovery API. |
|
60 * |
|
61 * Only one asynchronous request can be issued at a time, otherwise client |
|
62 * will be panicked with KMnPanicDuplicateRequest. |
|
63 * |
|
64 * @since 5.0 |
|
65 * @lib mnclientlib.dll |
|
66 * @ingroup MapNavAPI |
|
67 */ |
|
68 class CMnMapImage : public CBase |
|
69 { |
|
70 public: |
|
71 |
|
72 /** Creates new instance of the class. Provider Application |
|
73 * will be executed standalone. |
|
74 * |
|
75 * @param[in] aProvider Provider Application to be used for map rendering. |
|
76 * @return Pointer to new instance of the class. |
|
77 * |
|
78 * @leave KErrNotSupported Selected Provider Application does not support |
|
79 * map image services (@ref CMnProvider::EServiceMapImage). */ |
|
80 IMPORT_C static CMnMapImage* NewL( CMnProvider& aProvider ); |
|
81 |
|
82 /** Destructor */ |
|
83 virtual ~CMnMapImage(); |
|
84 |
|
85 enum TShowOption |
|
86 { |
|
87 /** No options set, just plain image is requested. */ |
|
88 EShowOptionNone = 0x00, |
|
89 |
|
90 /** Texts such as street, city, country names should be drawn */ |
|
91 EShowOptionText = 0x01, |
|
92 |
|
93 /** POIs should be marked on the map */ |
|
94 EShowOptionPois = 0x02, |
|
95 |
|
96 /** Landmarks should be marked on the map */ |
|
97 EShowOptionLandmarks = 0x04, |
|
98 |
|
99 /** Current location should be marked on the map. |
|
100 * Client must have Location capability, otherwise |
|
101 * this option will be ignored. */ |
|
102 EShowOptionCurrentLocation = 0x08, |
|
103 |
|
104 /** Country borders should be shown */ |
|
105 EShowOptionCountryBorders = 0x10, |
|
106 |
|
107 /** If this flag is set, it is required to draw |
|
108 * items specified by other flags, otherwise all |
|
109 * of them are optional. */ |
|
110 EShowOptionsMandatory = 0xF000 |
|
111 }; |
|
112 |
|
113 /** Type for bitmap of options defined in @ref TShowOption */ |
|
114 typedef TUint32 TShowOptions; |
|
115 |
|
116 /** Returns what types of map images are supported by provider |
|
117 * application given at construction (see NewL()). |
|
118 * @return Bitmap of values defined by @ref TMapImageType. */ |
|
119 IMPORT_C TMnMapImageParams::TMapImageTypes SupportedImageTypes(); |
|
120 |
|
121 /** Returns map image parameters object. |
|
122 * Client can modify it, but all modification will be |
|
123 * applied only for next and following RenderL requests. |
|
124 * @return Modifiable map image parameters object */ |
|
125 IMPORT_C TMnMapImageParams& MapImageParams(); |
|
126 |
|
127 /** @overload |
|
128 * @return Non-modifiable map image parameters object */ |
|
129 IMPORT_C const TMnMapImageParams& MapImageParams() const; |
|
130 |
|
131 /** Sets all map image drawing parameters at once. |
|
132 * New options will be applied only for next and following |
|
133 * RenderL requests. |
|
134 * @param aImageParams Image parameters to take into use for |
|
135 * following RenderL requests */ |
|
136 IMPORT_C void SetMapImageParams( TMnMapImageParams& aImageParams ); |
|
137 |
|
138 /** Specifies the origin of image in the target bitmap, see |
|
139 * RenderL(). By default it is TPoint( 0, 0 ), i.e. left top |
|
140 * corner of the bitmap. |
|
141 * This setting takes effect only from next RenderL request. |
|
142 * @param[in] aOrigin Origin of the map in the target bitmap.*/ |
|
143 IMPORT_C void SetTargetOrigin( const TPoint& aOrigin ); |
|
144 |
|
145 /** Returns current setting of map image origin in target bitmap. |
|
146 * @returns Origin of map image in the target bitmap.*/ |
|
147 IMPORT_C TPoint TargetOrigin(); |
|
148 |
|
149 /** Sets additional options to be used in rendering. Renderer will |
|
150 * take them into account if possible. |
|
151 * This setting takes effect only from next RenderL request. |
|
152 * @param[in] aOptions Bitmap of options defined in @ref TOption. */ |
|
153 IMPORT_C void SetShowOptions( const TShowOptions& aOptions ); |
|
154 |
|
155 /** Returns additional options set to be used in rendering. |
|
156 * @return Bitmap of options defined in @ref TShowOption. */ |
|
157 IMPORT_C TShowOptions ShowOptions() const; |
|
158 |
|
159 /** Intiates rendering of map image. |
|
160 * This is asynchronous request, which completion is informed via |
|
161 * aStatus parameter. Client should use active object to wait for completion. |
|
162 * |
|
163 * This function may leave if some error occurs during initiating of the request. |
|
164 * If so, then no asynchronous request will be left ongoing. |
|
165 * |
|
166 * @param[in,out] aBitmap Bitmap object, which the map image will be drawn into. |
|
167 * Its size in pixels must be sufficient to fit the image |
|
168 * defined by @ref SetSize() taking @ref SetTargetOrigin() |
|
169 * into account as well. |
|
170 * @param[out] aStatus This status will be completed, when rendering is finished. |
|
171 * - @p KErrNone - rendering was completed successfully. |
|
172 * - @p KErrNotSupported - rendering is not possible in specified area |
|
173 * or one of mandatory options are not supported (see @ref TShowOption). |
|
174 * - Other system-wide error codes also possible. |
|
175 * |
|
176 * @leave KErrArgument |
|
177 * - If target bitmap size is too small. |
|
178 * - If requested image type is not supported by provider application |
|
179 * |
|
180 * @panic "MnPanicClient"-KMnPanicDuplicateRequest if request is already |
|
181 * ongoing. */ |
|
182 IMPORT_C void RenderL( CFbsBitmap& aBitmap, TRequestStatus& aStatus ); |
|
183 |
|
184 /** Intiates rendering of map image. |
|
185 * This is asynchronous request, which completion is informed via aCallback. |
|
186 * |
|
187 * Client must provide callback as class derived from MMnMapImageRenderCallback. |
|
188 * This is asynchronous request also. An active object will be executed to handle |
|
189 * completion of rendering request, so client must have active scheduler installed. |
|
190 * |
|
191 * This function may leave if some error occurs during initiating of the request. |
|
192 * If so, then no asynchronous request will be left ongoing. |
|
193 * |
|
194 * @param[in,out] aBitmap Bitmap object, which the map image will be drawn into. |
|
195 * Its size in pixels must be sufficient to fit the image |
|
196 * defined by @ref SetSize() taking @ref SetTargetOrigin() |
|
197 * into account as well. |
|
198 * @param[in] aCallback Callback object to call when rendering is completed. |
|
199 * See @ref MMnMapImageRenderCallback::HandleRenderingCompletedL for details |
|
200 * on possible operation result error codes. |
|
201 * |
|
202 * @leave KErrArgument |
|
203 * - If target bitmap size is too small. |
|
204 * - If requested image type is not supported by provider application |
|
205 * |
|
206 * @panic "MnPanicClient"-KMnPanicDuplicateRequest if request is already |
|
207 * ongoing. */ |
|
208 IMPORT_C void RenderL( CFbsBitmap& aBitmap, MMnMapImageRenderCallback& aCallback ); |
|
209 |
|
210 /** Cancels current ongoing asynchronous rendering request. |
|
211 * Note that callback, set in @ref RenderL(CFbsBitmap&, MMnMapImageRenderCallback&) |
|
212 * is <i>not</i> called, if request is cancelled. */ |
|
213 IMPORT_C void CancelRendering(); |
|
214 |
|
215 /** Calculates coordinate in pixels of the point corresponding to given |
|
216 * world coordinate. |
|
217 * |
|
218 * Given world coordinate is allowed to be beyond |
|
219 * image borders. In that case negative values in result value |
|
220 * describe point to the left of left border and/or above top border of the |
|
221 * image and values bigger than width or height describe point to the right |
|
222 * of right image border or below its bottom border. |
|
223 * |
|
224 * Sometimes such calculation is not possible (e.e given world coordinate |
|
225 * is not part of the image) and this function returns @c KErrUnknown. |
|
226 * |
|
227 * Map image parameters are necessary be set in order for this function |
|
228 * to operate successfully. Default values are not sufficient, so client |
|
229 * is responsible to override them before calling this method. Note though, |
|
230 * that it is not required to call RenderL before calling this method. |
|
231 * |
|
232 * @param[in] aWorldCoordinate World coordinate (in WGS-84) |
|
233 * @param[out] aImagePoint On successful return, coordinate of corresponding |
|
234 * pixel in image relative to image top left corner. |
|
235 * @return Error code of the operation: |
|
236 * - @c KErrNone if calculation is successful |
|
237 * - @c KErrArgument if map image parameters in are invalid. |
|
238 * - @c KErrUnknown if calculation is not possible */ |
|
239 IMPORT_C TInt GetImageCoordinate( |
|
240 const TCoordinate& aWorldCoordinate, |
|
241 TPoint& aImagePoint ) const; |
|
242 |
|
243 /** Calculates world coordinate of the given image point. |
|
244 * |
|
245 * Given image point coordinate must be within the rectangle |
|
246 * ( TPoint( 0, 0 ), @ref Size() ). |
|
247 * |
|
248 * Map image parameters are necessary be set in order for this function |
|
249 * to operate successfully. Default values are not sufficient, so client |
|
250 * is responsible to override them before calling this method. Note though, |
|
251 * that it is not required to call RenderL before calling this method. |
|
252 * |
|
253 * Sometimes such calculation is not possible (e.g. given image coordinate |
|
254 * does not match any world coordinate) and this function returns @c KErrUnknown. |
|
255 * |
|
256 * @param[in] aImagePoint Coordinate of a point on map image in pixels, |
|
257 * relative to image top left corner. |
|
258 * @param[out] aWorldCoordinate On successful return, corresponding |
|
259 * world coordinate (in WGS-84). |
|
260 * @return Error code of the operation: |
|
261 * - @c KErrNone if calculation is successful |
|
262 * - @c KErrArgument if image coordinate is out of bounds |
|
263 * - @c KErrArgument if map image parameters in are invalid. |
|
264 * - @c KErrUnknown if calculation is not possible */ |
|
265 IMPORT_C TInt GetWorldCoordinate( |
|
266 const TPoint& aImagePoint, |
|
267 TCoordinate& aWorldCoordinate ) const; |
|
268 |
|
269 /** Sets observer of provider application lifetime. |
|
270 * Client will receive exit event from provider application. |
|
271 * By default exit events from provider application are not monitored. |
|
272 * @param[in] aObserver Exit observer. |
|
273 * @leave KErrAlreadyExists if observer is already set. |
|
274 */ |
|
275 IMPORT_C void SetExitObserverL( MAknServerAppExitObserver& aObserver ); |
|
276 |
|
277 /** Removes observer of provider application lifetime. */ |
|
278 IMPORT_C void RemoveExitObserver(); |
|
279 |
|
280 protected: |
|
281 CMnMapImage(); |
|
282 void ConstructL( CMnProvider& aProvider ); |
|
283 |
|
284 private: |
|
285 TUint32 iProviderFeatures; |
|
286 |
|
287 TPoint iTargetOrigin; |
|
288 TMnMapImageParams iMapImageParams; |
|
289 TShowOptions iShowOptions; |
|
290 |
|
291 RMnMapImageServiceClient* iSession; |
|
292 CApaServerAppExitMonitor* iExitMonitor; |
|
293 CActive* iActiveCallback; |
|
294 |
|
295 CMnCoordinateConverterBase* iCoordConverter; |
|
296 }; |
|
297 |
|
298 #endif /*MN_MAPIMAGE_H_*/ |
|