Kgapi

staticmapurl.h
1/*
2 SPDX-FileCopyrightText: 2012 Jan Grulich <grulja@gmail.com>
3
4 SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
5*/
6
7#pragma once
8
9#include "kgapimaps_export.h"
10#include "staticmapmarker.h"
11#include "staticmappath.h"
12
13#include <QSize>
14#include <QUrl>
15
16#include <KContacts/Address>
17#include <KContacts/Geo>
18
19namespace KGAPI2
20{
21
22/**
23 * @brief A class to build a URL from StaticMapMarkers and StaticMapPaths to
24 * fetch a map tile.
25 *
26 * @author Jan Grulich <grulja@gmail.com>
27 * @since 0.4
28 */
29class KGAPIMAPS_EXPORT StaticMapUrl
30{
31public:
32 enum LocationType { Undefined = -1, String, KABCAddress, KABCGeo };
33
34 enum ImageFormat { PNG, PNG32, GIF, JPG, JPGBaseline };
35
36 enum MapType { Roadmap, Satellite, Terrain, Hybrid };
37
38 enum Scale { Normal = 1, TwiceBigger = 2 };
39
40 /**
41 * @brief Constructs an empty StaticMapUrl
42 */
43 explicit StaticMapUrl();
44
45 /**
46 * @brief Constructs a new StaticMapUrl
47 *
48 * @param location Location of map center in QString
49 * @param size Requested size of the map image
50 * @param zoom Zoom level of map
51 * @param sensor Sensor specifies whether the application requesting the
52 * static map is using a sensor to determine the user's location.
53 */
54 StaticMapUrl(const QString &location, const QSize &size, quint32 zoom, bool sensor);
55
56 /**
57 * @brief Constructs a new StaticMapUrl
58 *
59 * @param address Location of map center in KContacts::Address
60 * @param size Requested size of the map image
61 * @param zoom Zoom level of map
62 * @param sensor Sensor specifies whether the application requesting the
63 * static map is using a sensor to determine the user's location.
64 */
65 StaticMapUrl(const KContacts::Address &address, const QSize &size, quint32 zoom, bool sensor);
66
67 /**
68 * @brief Constructs a new StaticMapUrl
69 *
70 * @param geo Location of map center in KContacts::Geo
71 * @param size Requested size of the map image
72 * @param zoom Zoom level of map
73 * @param sensor Sensor specifies whether the application requesting the static map is
74 * using a sensor to determine the user's location.
75 */
76 StaticMapUrl(const KContacts::Geo &geo, const QSize &size, quint32 zoom, bool sensor);
77
78 /**
79 * @brief Copy constructor
80 */
81 StaticMapUrl(const StaticMapUrl &other);
82
83 /**
84 * @brief Destructor
85 */
86 virtual ~StaticMapUrl();
87
88 /**
89 * @brief Returns in which format the location is stored.
90 */
91 [[nodiscard]] LocationType locationType() const;
92
93 /**
94 * @brief Returns map image format
95 */
96 [[nodiscard]] ImageFormat format() const;
97
98 /**
99 * @brief Sets map image format (default is PNG)
100 *
101 * @param format
102 */
103 void setFormat(const ImageFormat format);
104
105 /**
106 * @brief Returns whether map url is valid
107 */
108 bool isValid() const;
109
110 /**
111 * @brief Returns map center in QString
112 *
113 * Returns empty QString if location is not defined in QString
114 */
115 [[nodiscard]] QString locationString() const;
116
117 /**
118 * @brief Defines center of the map
119 *
120 * @param location Location (required when no markers are present) of
121 * center of the map in QString
122 */
123 void setLocation(const QString &location);
124
125 /**
126 * @brief Returns map center in KContacts::Address
127 *
128 * Returns empty KContacts::Address if location is not defined in KContacts::Address
129 */
130 [[nodiscard]] KContacts::Address locationAddress() const;
131
132 /**
133 * @brief Defines center of the map
134 *
135 * @param address Location (required when no markers are present) of center
136 * of the map in KContacts::Address
137 */
138 void setLocation(const KContacts::Address &address);
139
140 /**
141 * @brief Returns map center in KContacts::Geo
142 *
143 * Returns invalid KContacts::Geo if location is not defined in KContacts::Geo
144 */
145 [[nodiscard]] KContacts::Geo locationGeo() const;
146
147 /**
148 * @brief Defines center of the map
149 *
150 * @param geo Location (required when no markers are present) of center
151 * of the map in KContacts::Geo
152 */
153 void setLocation(const KContacts::Geo &geo);
154
155 /**
156 * @brief Returns type of map
157 */
158 [[nodiscard]] MapType mapType() const;
159
160 /**
161 * @brief Sets type of map (roadmap by default)
162 *
163 * @param type
164 */
165 void setMapType(const MapType type);
166
167 /**
168 * @brief Returns list of markers
169 *
170 * Returns empty QList if no marker were added
171 */
172 [[nodiscard]] QList<StaticMapMarker> markers() const;
173
174 /**
175 * @brief Adds marker to map
176 *
177 * @param marker
178 */
179 void setMarker(const StaticMapMarker &marker);
180
181 /**
182 * @brief Adds markers to map
183 *
184 * @param markers
185 */
186 void setMarkers(const QList<StaticMapMarker> &markers);
187
188 /**
189 * @brief Returns list paths
190 *
191 * Returns empty QList if no path were added
192 */
193 [[nodiscard]] QList<StaticMapPath> paths() const;
194
195 /**
196 * @brief Adds path to map
197 *
198 * @param path
199 */
200 void setPath(const StaticMapPath &path);
201
202 /**
203 * @brief Adds paths to map
204 *
205 * @param paths
206 */
207 void setPaths(const QList<StaticMapPath> &paths);
208
209 /**
210 * @brief Returns size of map tile
211 */
212 [[nodiscard]] QSize size() const;
213
214 /**
215 * @brief Sets size of requested map tile.
216 *
217 * @param size Maximum size is 640x640
218 */
219 void setSize(const QSize &size);
220
221 /**
222 * @brief Returns scale of map
223 */
224 [[nodiscard]] Scale scale() const;
225
226 /**
227 * @brief Sets scale of map (default is 1)
228 *
229 * @param scale
230 */
231 void setScale(const Scale scale);
232
233 /**
234 * @brief Returns whether the application uses a sensor to determine user's
235 * location.
236 */
237 [[nodiscard]] bool sensorUsed() const;
238
239 /**
240 * @brief Sets whether the application uses a sensor to determine the user's
241 * location.
242 *
243 * @param sensor
244 */
245 void setSensorUsed(const bool sensor);
246
247 /**
248 * @brief Returns visible area in QString
249 *
250 * Returns empty QString if visible area is not defined in QString
251 */
252 [[nodiscard]] QString visibleLocationString() const;
253
254 /**
255 * @brief Sets visible location.
256 *
257 * You can use this instead of using center and zoom parameters.
258 *
259 * Specifies location that should remain visible on the map, though
260 * no markers or other indicators will be displayed. Use this parameter to
261 * ensure that certain features or map location are shown on the static map.
262 *
263 * @param location
264 */
265 void setVisibleLocation(const QString &location);
266
267 /**
268 * @brief Returns visible area in KContacts::Address
269 *
270 * Returns empty KContacts::Address if visible area is not defined in KContacts::Address
271 */
272 [[nodiscard]] KContacts::Address visibleLocationAddress() const;
273
274 /**
275 * @brief Sets visible location.
276 *
277 * You can use this instead of using center and zoom parameters.
278 *
279 * Visible specifies location that should remain visible on the map, though
280 * no markers or other indicators will be displayed. Use this parameter to
281 * ensure that certain features or map location are shown on the static map.
282 *
283 * @param address
284 */
285 void setVisibleLocation(const KContacts::Address &address);
286
287 /**
288 * @brief Returns visible area in KContacts::Geo
289 *
290 * Returns empty KContacts::Geo if visible area is not defined in KContacts::Geo
291 */
292 [[nodiscard]] KContacts::Geo visibleLocationGeo() const;
293
294 /**
295 * @brief Sets visible location.
296 *
297 * You can use this instead of using center and zoom parameters.
298 *
299 * Visible specifies location that should remain visible on the map, though
300 * no markers or other indicators will be displayed. Use this parameter to
301 * ensure that certain features or map location are shown on the static map.
302 *
303 * @param geo
304 */
305 void setVisibleLocation(const KContacts::Geo &geo);
306
307 /**
308 * @brief Returns type of visible location
309 */
310 [[nodiscard]] LocationType visibleLocationType() const;
311
312 /**
313 * @brief Returns zoom level of map
314 *
315 * Returns -1 if zoom level is not defined
316 */
317 [[nodiscard]] qint8 zoomLevel() const;
318
319 /**
320 * @brief Sets zoom level of the map
321 *
322 * @param zoom Zoom parameter can be in range 0 to 21 where 21 is maximum
323 * zoom level.
324 */
325 void setZoomLevel(const quint32 zoom);
326
327 /**
328 * @brief Returns constructed url from all defined parameters
329 */
330 [[nodiscard]] QUrl url() const;
331
332 /**
333 * @brief Assignment operator
334 */
335 StaticMapUrl &operator=(const StaticMapUrl &other);
336
337private:
338 class Private;
339 Private *const d;
340 friend class Private;
341};
342
343} // namespace KGAPI2
Represents marker with defined label, color, size and markers.
Represents path with defined locations, weight, color and color for filled area.
A class to build a URL from StaticMapMarkers and StaticMapPaths to fetch a map tile.
A job to fetch a single map tile described by a StaticMapUrl.
Definition blog.h:16
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jul 19 2024 11:58:18 by doxygen 1.11.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.