Warning: That file was not part of the compilation database. It may have many parsing errors.
1 | // |
---|---|
2 | // This file is part of the Marble Virtual Globe. |
3 | // |
4 | // This program is free software licensed under the GNU LGPL. You can |
5 | // find a copy of this license in LICENSE.txt in the top directory of |
6 | // the source code. |
7 | // |
8 | // Copyright 2008-2009 Torsten Rahn <tackat@kde.org> |
9 | // |
10 | |
11 | #ifndef MARBLE_GEOPAINTER_H |
12 | #define MARBLE_GEOPAINTER_H |
13 | |
14 | |
15 | #include "marble_export.h" |
16 | |
17 | #include <QSize> |
18 | #include <QRegion> |
19 | |
20 | // Marble |
21 | #include "MarbleGlobal.h" |
22 | #include "ClipPainter.h" |
23 | |
24 | |
25 | class QImage; |
26 | class QPaintDevice; |
27 | class QPolygonF; |
28 | class QRect; |
29 | class QRectF; |
30 | class QString; |
31 | |
32 | |
33 | namespace Marble |
34 | { |
35 | |
36 | class ViewportParams; |
37 | class GeoPainterPrivate; |
38 | class GeoDataCoordinates; |
39 | class GeoDataLineString; |
40 | class GeoDataLinearRing; |
41 | class GeoDataPoint; |
42 | class GeoDataPolygon; |
43 | |
44 | |
45 | /*! |
46 | \class GeoPainter |
47 | \brief A painter that allows to draw geometric primitives on the map. |
48 | |
49 | This class allows application developers to draw simple geometric shapes |
50 | and objects onto the map. |
51 | |
52 | The API is modeled after the QPainter API. |
53 | |
54 | The GeoPainter provides a wide range of methods that are using geographic |
55 | ("geodesic") coordinates to position the item. |
56 | For example a point or the nodes of a polygon can fully be described in |
57 | geographic coordinates. |
58 | |
59 | In all these cases the position of the object is specified in geographic |
60 | coordinates. |
61 | |
62 | There are however some cases where there are two viable cases: |
63 | \li the shape of the object could still use screen coordinates (like a label |
64 | or an icon). |
65 | \li Alternatively the shape of the object can get projected according |
66 | to the current projection (e.g. a texture projected onto the spherical |
67 | surface) |
68 | |
69 | If screen coordinates are used then e.g. width and height are assumed to be |
70 | expressed in pixels, otherwise degrees are used. |
71 | |
72 | Painter transformations (e.g. translate) always happen in screen |
73 | coordinates. |
74 | |
75 | Like in QPainter drawing objects onto a widget should always considered to |
76 | be a volatile operation. This means that e.g. placemarks don't get added to |
77 | the globe permanently. |
78 | So the drawing needs to be done on every repaint to prevent that drawings |
79 | will disappear during the next paint event. |
80 | |
81 | So if you want to add placemarks to your map widget permanently (i.e. you |
82 | don't want to take care of repainting) then you need to use other solutions |
83 | such as the KML import of the Marble framework or Marble's GeoGraphicsItems. |
84 | |
85 | \note By default the GeoPainter automatically filters geographical content |
86 | in order to provide fast painting: |
87 | \li Geographically positioned objects which are outside the viewport are not |
88 | drawn at all. |
89 | Parts of objects which are specified through geographic coordinates |
90 | (like polygons, ellipses etc.) get cut off if they are not placed within the |
91 | viewport. |
92 | \li Objects which have a shape that is specified through geographic |
93 | coordinates get filtered according to the viewport resolution: |
94 | If the object is much smaller than a pixel then it won't get drawn at all. |
95 | */ |
96 | |
97 | |
98 | class MARBLE_EXPORT GeoPainter : public ClipPainter |
99 | { |
100 | public: |
101 | |
102 | /*! |
103 | \brief Creates a new geo painter. |
104 | |
105 | To create a geo painter it's necessary to provide \a paintDevice |
106 | as a canvas and the viewportParams to specify the map projection |
107 | inside the viewport. |
108 | */ |
109 | GeoPainter( QPaintDevice * paintDevice, |
110 | const ViewportParams *viewportParams, |
111 | MapQuality mapQuality = NormalQuality ); |
112 | |
113 | |
114 | /*! |
115 | \brief Destroys the geo painter. |
116 | */ |
117 | ~GeoPainter(); |
118 | |
119 | |
120 | /*! |
121 | \brief Returns the map quality. |
122 | \return The map quality that got assigned to the painter. |
123 | */ |
124 | MapQuality mapQuality() const; |
125 | |
126 | |
127 | /*! |
128 | \brief Draws a text annotation that points to a geodesic position. |
129 | |
130 | The annotation consists of a bubble with the specified \a text inside. |
131 | By choosing an appropriate pen for the painter it's possible to change |
132 | the color and line style of the bubble outline and the text. The brush |
133 | chosen for the painter is used to paint the background of the bubble |
134 | |
135 | The optional parameters which describe the layout of the bubble are |
136 | similar to those used by QPainter::drawRoundRect(). |
137 | Unlike in QPainter the rounded corners are not specified in percentage |
138 | but in pixels to provide for optimal aesthetics. |
139 | By choosing a positive or negative bubbleOffset it's possible to |
140 | place the annotation on top, bottom, left or right of the annotated |
141 | position. |
142 | |
143 | \param position The geodesic position |
144 | \param text The text contained by the bubble |
145 | \param bubbleSize The size of the bubble that holds the annotation text. |
146 | A height of 0 can be used to have the height calculated |
147 | automatically to fit the needed text height. |
148 | \param bubbleOffsetX The x-axis offset between the annotated position and |
149 | the "root" of the speech bubble's "arrow". |
150 | \param bubbleOffsetY The y-axis offset between the annotated position and |
151 | the "root" of the speech bubble's "arrow". |
152 | \param xRnd Specifies the geometry of the rounded corners in pixels along |
153 | the x-axis. |
154 | \param yRnd Specifies the geometry of the rounded corners in pixels along |
155 | the y-axis. |
156 | |
157 | \see GeoDataCoordinates |
158 | */ |
159 | void drawAnnotation( const GeoDataCoordinates & position, |
160 | const QString & text, |
161 | QSizeF bubbleSize = QSizeF( 130, 100 ), |
162 | qreal bubbleOffsetX = -10, qreal bubbleOffsetY = -30, |
163 | qreal xRnd = 5, qreal yRnd = 5 ); |
164 | |
165 | |
166 | /*! |
167 | \brief Draws a single point at a given geographic position. |
168 | The point is drawn using the painter's pen color. |
169 | |
170 | \see GeoDataCoordinates |
171 | */ |
172 | void drawPoint ( const GeoDataCoordinates & position ); |
173 | |
174 | |
175 | /*! |
176 | \brief Creates a region for a given geographic position. |
177 | |
178 | A QRegion object is created that represents the area covered by |
179 | GeoPainter::drawPoint( GeoDataCoordinates ). It can be used e.g. for |
180 | input event handling of objects that have been painted using |
181 | GeoPainter::drawPoint( GeoDataCoordinates ). |
182 | |
183 | The width allows to set the "stroke width" for the region. For input |
184 | event handling it's always advisable to use a width that is slightly |
185 | bigger than the width of the painter's pen. |
186 | |
187 | \see GeoDataCoordinates |
188 | */ |
189 | QRegion regionFromPoint ( const GeoDataCoordinates & position, |
190 | qreal strokeWidth = 3) const; |
191 | |
192 | |
193 | /*! |
194 | \brief Draws a single point at a given geographic position. |
195 | The point is drawn using the painter's pen color. |
196 | |
197 | \see GeoDataPoint |
198 | */ |
199 | void drawPoint ( const GeoDataPoint & point ); |
200 | |
201 | |
202 | /*! |
203 | \brief Create a region for a given geographic position. |
204 | |
205 | A QRegion object is created that represents the area covered by |
206 | GeoPainter::drawPoint( GeoDataPoint ). It can be used e.g. for |
207 | input event handling of objects that have been painted using |
208 | GeoPainter::drawPoint( GeoDataPoint ). |
209 | |
210 | The width allows to set the "stroke width" for the region. For input |
211 | event handling it's always advisable to use a width that is slightly |
212 | bigger than the width of the painter's pen. |
213 | */ |
214 | QRegion regionFromPoint ( const GeoDataPoint & point, |
215 | qreal strokeWidth = 3) const; |
216 | |
217 | |
218 | /*! |
219 | \brief Draws the given text at a given geographic position. |
220 | The \a text is drawn starting at the given \a position using the painter's |
221 | font property. The text rendering is performed in screen coordinates and is |
222 | not subject to the current projection. |
223 | */ |
224 | void drawText ( const GeoDataCoordinates & position, const QString & text ); |
225 | |
226 | |
227 | /*! |
228 | \brief Draws an ellipse at the given position. |
229 | The ellipse is placed with its center located at the given \a centerPosition. |
230 | |
231 | For the outline it uses the painter's pen and for the background the |
232 | painter's brush. |
233 | |
234 | If \a isGeoProjected is true then the outline of the ellipse is drawn |
235 | in geographic coordinates. In this case the \a width and the \a height |
236 | are interpreted to be degrees. |
237 | If \a isGeoProjected is false then the outline of the ellipse is drawn |
238 | in screen coordinates. In this case the \a width and the \a height |
239 | are interpreted to be pixels. |
240 | |
241 | \see GeoDataCoordinates |
242 | */ |
243 | void drawEllipse ( const GeoDataCoordinates & centerPosition, |
244 | qreal width, qreal height, bool isGeoProjected = false ); |
245 | |
246 | |
247 | /*! |
248 | \brief Creates a region for an ellipse at a given position |
249 | |
250 | A QRegion object is created that represents the area covered by |
251 | GeoPainter::drawEllipse(). As such it can be used e.g. for input event |
252 | handling for objects that have been painted using GeoPainter::drawEllipse(). |
253 | |
254 | The \a strokeWidth allows to extrude the QRegion by half the amount of |
255 | "stroke width" pixels. For input event handling it's always advisable to use |
256 | a width that is slightly bigger than the width of the painter's pen. |
257 | |
258 | \see GeoDataCoordinates |
259 | */ |
260 | QRegion regionFromEllipse ( const GeoDataCoordinates & centerPosition, |
261 | qreal width, qreal height, bool isGeoProjected = false, |
262 | qreal strokeWidth = 3 ) const; |
263 | |
264 | |
265 | /*! |
266 | \brief Draws an image at the given position. |
267 | The image is placed with its center located at the given \a centerPosition. |
268 | |
269 | The image rendering is performed in screen coordinates and is |
270 | not subject to the current projection. |
271 | |
272 | \see GeoDataCoordinates |
273 | */ |
274 | void drawImage ( const GeoDataCoordinates & centerPosition, |
275 | const QImage & image /* , bool isGeoProjected = false */ ); |
276 | |
277 | |
278 | /*! |
279 | \brief Draws a pixmap at the given position. |
280 | The pixmap is placed with its center located at the given \a centerPosition. |
281 | |
282 | The image rendering is performed in screen coordinates and is |
283 | not subject to the current projection. |
284 | |
285 | \see GeoDataCoordinates |
286 | */ |
287 | void drawPixmap ( const GeoDataCoordinates & centerPosition, |
288 | const QPixmap & pixmap /*, bool isGeoProjected = false */ ); |
289 | |
290 | |
291 | /*! |
292 | \brief Draws a given line string (a "polyline"). |
293 | |
294 | The \a lineString is drawn using the current pen. It's possible to |
295 | provide a \a labelText for the \a lineString. The text is rendered using |
296 | the painter's font property. |
297 | The position of the \a labelText can be specified using the |
298 | \a labelPositionFlags. |
299 | |
300 | \see GeoDataLineString |
301 | */ |
302 | void drawPolyline ( const GeoDataLineString & lineString, |
303 | const QString& labelText = QString(), |
304 | LabelPositionFlags labelPositionFlags = LineCenter ); |
305 | |
306 | |
307 | /*! |
308 | \brief Creates a region for a given line string (a "polyline"). |
309 | |
310 | A QRegion object is created that represents the area covered by |
311 | GeoPainter::drawPolyline( GeoDataLineString ). As such it can be used |
312 | e.g. for input event handling for objects that have been painted using |
313 | GeoPainter::drawPolyline( GeoDataLineString ). |
314 | |
315 | The \a strokeWidth allows to extrude the QRegion by half the amount of |
316 | "stroke width" pixels. For input event handling it's always advisable to use |
317 | a width that is slightly bigger than the width of the painter's pen. |
318 | |
319 | \see GeoDataLineString |
320 | */ |
321 | QRegion regionFromPolyline ( const GeoDataLineString & lineString, |
322 | qreal strokeWidth = 3 ) const; |
323 | |
324 | |
325 | /*! |
326 | \brief Draws a given linear ring (a "polygon without holes"). |
327 | |
328 | The outline of the \a linearRing is drawn using the current pen. The |
329 | background is painted using the current brush of the painter. |
330 | Like in QPainter::drawPolygon() the \a fillRule specifies the |
331 | fill algorithm that is used to fill the polygon. |
332 | |
333 | \see GeoDataLinearRing |
334 | */ |
335 | void drawPolygon ( const GeoDataLinearRing & linearRing, |
336 | Qt::FillRule fillRule = Qt::OddEvenFill ); |
337 | |
338 | |
339 | /*! |
340 | \brief Creates a region for a given linear ring (a "polygon without holes"). |
341 | |
342 | A QRegion object is created that represents the area covered by |
343 | GeoPainter::drawPolygon( GeoDataLinearRing ). As such it can be used |
344 | e.g. for input event handling for objects that have been painted using |
345 | GeoPainter::drawPolygon( GeoDataLinearRing ). |
346 | |
347 | Like in drawPolygon() the \a fillRule specifies the fill algorithm that is |
348 | used to fill the polygon. |
349 | |
350 | The \a strokeWidth allows to extrude the QRegion by half the amount of |
351 | "stroke width" pixels. For input event handling it's always advisable to use |
352 | a width that is slightly bigger than the width of the painter's pen. |
353 | |
354 | For the polygon case a "cosmetic" strokeWidth of zero should provide the |
355 | best performance. |
356 | |
357 | \see GeoDataLinearRing |
358 | */ |
359 | QRegion regionFromPolygon ( const GeoDataLinearRing & linearRing, |
360 | Qt::FillRule fillRule, qreal strokeWidth = 3 ) const; |
361 | |
362 | |
363 | /*! |
364 | \brief Draws a given polygon (which may contain holes). |
365 | |
366 | The outline of the \a polygon is drawn using the current pen. The |
367 | background is painted using the current brush of the painter. |
368 | Like in QPainter::drawPolygon() the \a fillRule specifies the |
369 | fill algorithm that is used to fill the polygon. |
370 | |
371 | \see GeoDataPolygon |
372 | */ |
373 | void drawPolygon ( const GeoDataPolygon & polygon, |
374 | Qt::FillRule fillRule = Qt::OddEvenFill ); |
375 | |
376 | |
377 | /*! |
378 | \brief Draws a rectangle at the given position. |
379 | The rectangle is placed with its center located at the given |
380 | \a centerPosition. |
381 | |
382 | For the outline it uses the painter's pen and for the background the |
383 | painter's brush. |
384 | |
385 | If \a isGeoProjected is true then the outline of the rectangle is drawn |
386 | in geographic coordinates. In this case the \a width and the \a height |
387 | are interpreted to be degrees. |
388 | If \a isGeoProjected is false then the outline of the rectangle is drawn |
389 | in screen coordinates. In this case the \a width and the \a height |
390 | are interpreted to be pixels. |
391 | |
392 | \see GeoDataCoordinates |
393 | */ |
394 | void drawRect ( const GeoDataCoordinates & centerPosition, |
395 | qreal width, qreal height, |
396 | bool isGeoProjected = false ); |
397 | |
398 | |
399 | /*! |
400 | \brief Creates a region for a rectangle at a given position. |
401 | |
402 | A QRegion object is created that represents the area covered by |
403 | GeoPainter::drawRect(). This can be used e.g. for input event handling |
404 | for objects that have been painted using GeoPainter::drawRect(). |
405 | |
406 | The isGeoProjected parameter is used the same way as for |
407 | GeoPainter::drawRect(). |
408 | |
409 | The \a strokeWidth allows to extrude the QRegion by half the amount of |
410 | "stroke width" pixels. For input event handling it's always advisable to use |
411 | a width that is slightly bigger than the width of the painter's pen. This is |
412 | especially true for small objects. |
413 | |
414 | \see GeoDataCoordinates |
415 | */ |
416 | QRegion regionFromRect ( const GeoDataCoordinates & centerPosition, |
417 | qreal width, qreal height, |
418 | bool isGeoProjected = false, |
419 | qreal strokeWidth = 3 ) const; |
420 | |
421 | |
422 | /*! |
423 | \brief Draws a rectangle with rounded corners at the given position. |
424 | The rectangle is placed with its center located at the given |
425 | \a centerPosition. |
426 | |
427 | For the outline it uses the painter's pen and for the background the |
428 | painter's brush. |
429 | Unlike in QPainter::drawRoundedRect() the rounded corners are not specified |
430 | in percentage but in pixels to provide for optimal aesthetics. |
431 | |
432 | \param width Width of the rectangle in pixels |
433 | \param height Height of the rectangle in pixels |
434 | \param xRnd Specifies the geometry of the rounded corners in pixels along |
435 | the x-axis. |
436 | \param yRnd Specifies the geometry of the rounded corners in pixels along |
437 | the y-axis. |
438 | |
439 | \see GeoDataCoordinates |
440 | */ |
441 | void drawRoundRect ( const GeoDataCoordinates & centerPosition, |
442 | int width, int height, |
443 | int xRnd = 25, int yRnd = 25 ); |
444 | |
445 | |
446 | |
447 | // Reenabling QPainter+ClipPainter methods. |
448 | using QPainter::drawText; |
449 | using QPainter::drawEllipse; |
450 | using QPainter::drawImage; |
451 | using QPainter::drawPixmap; |
452 | using QPainter::drawPoint; |
453 | using ClipPainter::drawPolyline; |
454 | using ClipPainter::drawPolygon; |
455 | using QPainter::drawRect; |
456 | using QPainter::drawRoundedRect; |
457 | |
458 | private: |
459 | Q_DISABLE_COPY( GeoPainter ) |
460 | GeoPainterPrivate * const d; |
461 | }; |
462 | |
463 | } |
464 | |
465 | #endif |
466 |
Warning: That file was not part of the compilation database. It may have many parsing errors.