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
25class QImage;
26class QPaintDevice;
27class QPolygonF;
28class QRect;
29class QRectF;
30class QString;
31
32
33namespace Marble
34{
35
36class ViewportParams;
37class GeoPainterPrivate;
38class GeoDataCoordinates;
39class GeoDataLineString;
40class GeoDataLinearRing;
41class GeoDataPoint;
42class 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
98class 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.