2 Situare - A location system for Facebook
3 Copyright (C) 2010 Ixonos Plc. Authors:
5 Sami Rämö - sami.ramo@ixonos.com
6 Jussi Laitinen - jussi.laitinen@ixonos.com
7 Pekka Nissinen - pekka.nissinen@ixonos.com
8 Ville Tiensuu - ville.tiensuu@ixonos.com
9 Henri Lampela - henri.lampela@ixonos.com
11 Situare is free software; you can redistribute it and/or
12 modify it under the terms of the GNU General Public License
13 version 2 as published by the Free Software Foundation.
15 Situare is distributed in the hope that it will be useful,
16 but WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 GNU General Public License for more details.
20 You should have received a copy of the GNU General Public License
21 along with Situare; if not, write to the Free Software
22 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
31 #include "routing/route.h"
32 #include "coordinates/geocoordinate.h"
33 #include "coordinates/scenecoordinate.h"
37 class FriendItemsHandler;
38 class GPSLocationItem;
44 class OwnLocationItem;
50 * Logic for controlling map functionality. Does also include static methods for
51 * converting coordinates.
53 * NOTE: MapEngine must have a view attached before using it!
55 * @author Sami Rämö - sami.ramo (at) ixonos.com
56 * @author Jussi Laitinen - jussi.laitinen (at) ixonos.com
57 * @author Pekka Nissinen - pekka.nissinen (at) ixonos.com
58 * @author Ville Tiensuu - ville.tiensuu (at) ixonos.com
60 class MapEngine : public QObject
68 * @param parent Parent
70 MapEngine(QObject *parent = 0);
74 * Saves view of the map to settings file
78 /*******************************************************************************
79 * MEMBER FUNCTIONS AND SLOTS
80 ******************************************************************************/
83 * @brief Coordinates of the current center point
85 * @return Current coordinates
87 GeoCoordinate centerGeoCoordinate();
90 * @brief Convert MapScene coordinate to tile x & y numbers.
92 * @param zoomLevel ZoomLevel
93 * @param coordinate MapScene coordinate
94 * @return tile x & y numbers
96 static QPoint convertSceneCoordinateToTileNumber(int zoomLevel, SceneCoordinate coordinate);
99 * @brief Set initial values for the map
101 * Set initial location and zoom level from the settings, if available, or use the default
102 * values set in the constructor. Signals locationChanged() and zoomLevelChanged() are emitted,
103 * so init should be called after those signals are connected.
108 * @brief Return given value translated between min and max
110 * If given value is not inside the given range (min <= value <= max), then the allowed range
111 * is adder or subtracted until the value does fit in the range.
113 * @param value Value to be normalized
114 * @param min Minimum allowed value
115 * @param max Maximum allowed value
116 * @return value which is moved to be inside the given limits
118 static int normalize(int value, int min, int max);
121 * @brief Getter for scene
123 * @return QGraphicsScene
125 QGraphicsScene* scene();
128 * @brief Sets new zoom level
130 * @return newZoomLevel value that is set to new zoom level
132 void setZoomLevel(const int newZoomLevel);
136 * @brief Center smoothly to given latitude and longitude coordinates.
138 * @param coordinate Latitude & longitude coordinates for location
140 void centerToCoordinates(GeoCoordinate coordinate);
143 * @brief Slot to catch user own location data
145 * @param user User info
147 void receiveOwnLocation(User *user);
150 * @brief Set auto centering.
152 * @param enabled true if enabled, false otherwise
154 void setAutoCentering(bool enabled);
157 * @brief Slot for enabling / disabling GPS
159 * GPS location item is disabled or enabled based on GPS state
161 * @param enabled True is GPS is enabled, otherwise false
163 void setGPSEnabled(bool enabled);
166 * @brief Slot for view resizing.
168 * @param size view size
170 void viewResized(const QSize &size);
174 * @brief Calculate grid of tile coordinates from current scene coordinate.
176 * Grid size is calculated from view size and scene's current center coordinate.
178 * @param coordinate scene's current center coordinate
179 * @return QRect grid of tile coordinates
181 QRect calculateTileGrid(SceneCoordinate coordinate);
184 * @brief Center and zoom to given rect
186 * Map is centered to center point of the rect and zoomed so that whole rect is visible
187 * as big as possible.
189 * @param rect Target rect
190 * @param useMargins true if margins should be added to rect, false otherwise
192 void centerAndZoomTo(QRect rect, bool useMargins = true);
195 * @brief Returns the rect of the current scene area drawn on the view
197 * @returns Rect of the current scene area drawn on the view
199 QRectF currentViewSceneRect() const;
202 * @brief Request disabling of auto centering if centered too far from the real location.
204 * @param coordinate scene's center coordinate
206 void disableAutoCenteringIfRequired(SceneCoordinate coordinate);
209 * @brief Get new tiles.
211 * Calculates which tiles has to be fetched. Does emit fetchImage for tiles which
212 * aren't already in the scene.
213 * @param coordinate scene's center coordinate
215 void getTiles(SceneCoordinate coordinate);
218 * @brief Check if auto centering is enabled
220 * @return true if enabled, false otherwise
222 bool isAutoCenteringEnabled();
225 * @brief Check if center tile has changed.
227 * @param coordinate scene's center coordinate
228 * @return bool true if center tile changed, false otherwise
230 bool isCenterTileChanged(SceneCoordinate coordinate);
233 * @brief Set size of tiles grid based on view size
235 * @param viewSize Current view size
237 void setTilesGridSize(const QSize &viewSize);
240 * @brief Updates direction and distance values to indicator button
242 * Calculate and update direction and distance values and send those to indicator button
244 void updateDirectionIndicator();
247 * @brief Updates the current view rect including margins
249 * Calculates tiles rect in scene based on m_viewTilesGrid and
250 * calls MapScene::viewRectUpdated()
252 void updateViewTilesSceneRect();
255 * @brief Calculate scale at the map center of the map in meters/pixel
257 * @return qreal Scale of the map in meters/pixel
259 qreal viewResolution();
262 * @brief This method is ran always when the map is zoomed
264 * This method is the right place for all actions which must be done when ever map is zoomed.
270 * @brief This slot is called after friend items position have been updated
272 * Does run MapScene::spanItems()
274 void friendsPositionsUpdated();
277 * @brief Slot for GPS position updates
279 * GPS location item is updated and map centered to new location (if automatic
280 * centering is enabled).
282 * @param position New coordinates from GPS
283 * @param accuracy Accuracy of the GPS fix
285 void gpsPositionUpdate(GeoCoordinate position, qreal accuracy);
288 * @brief Slot for received map tile images
290 * Does receive map tile images from MapFetcher. Calls MapScene::addTile() for creating and adding
291 * the actual MapTile object to the MapScene.
293 * Tile is added also to outside the world horizontal limits, if required, for spanning the map.
295 * @param zoomLevel Zoom level
296 * @param x Tile x index
297 * @param y Tile y index
298 * @param image Received pixmap
300 void mapImageReceived(int zoomLevel, int x, int y, const QPixmap &image);
303 * @brief Called when MapScroller state is changed
305 * Does check if the smooth scroll effect was interrupted and should the auto centering
306 * feature to be disabled.
308 * @param newState New state
310 void scrollerStateChanged(QAbstractAnimation::State newState);
313 * @brief Scroll smoothly to given scene position
315 * @param coordinate Target position in the scene
317 void scrollToPosition(SceneCoordinate coordinate);
320 * @brief Set center point in the scene
322 * Does emit locationChanged signal.
323 * @param coordinate Scene coordinates for new position
324 * @param isUserDragAction True if caused by user dragging action
326 void setCenterPosition(SceneCoordinate coordinate, bool isUserDragAction = false);
329 * @brief Builds and sets route, also centers it
331 * @param route Route route information
333 void setRoute(Route &route);
336 * @brief Shows map area defined by bounds.
338 * Calls centerAndZoomTo() with area defined by bounds.
339 * @param swBound south-west bound of location item
340 * @param neBound north-east bound of location item
342 void showMapArea(const GeoCoordinate &swBound, const GeoCoordinate &neBound);
345 * @brief Slot for actions after view zoom is finished
347 * Does run removeOutOfViewTiles
349 void viewZoomFinished();
352 * @brief Slot for zooming in
357 * @brief Slot for zooming out
361 /*******************************************************************************
363 ******************************************************************************/
366 * @brief Signal when direction and distance from current map center point to current GPS
367 * location is changed
369 * @param direction Direction in degrees
370 * @param distance Distance in meters
371 * @param draw Should the indicator triangle be drawn or not
373 void directionIndicatorValuesUpdate(qreal direction, qreal distance, bool draw);
376 * @brief Signals error
378 * @param context error context
379 * @param error error code
381 void error(const int context, const int error);
384 * @brief Signal for image fetching.
386 * @param zoomLevel Zoom level
387 * @param x Tile x index
388 * @param y Tile y index
390 void fetchImage(int zoomLevel, int x, int y);
393 * @brief Signal when friend image is ready
397 void friendImageReady(User *user);
400 * @brief Signal when friend list locations are fetched
402 * @param friendsList Friends list data
404 void friendsLocationsReady(QList<User *> &friendsList);
407 * @brief Request view centering to new locaiton
409 * @param coordinate New scene coordinates
410 * @param isUserDragAction True if caused by user dragging action
412 void locationChanged(SceneCoordinate coordinate, bool isUserDragAction);
415 * @brief Signal is emitted when location item is clicked.
417 * @param userIDs list of friends user IDs in the group
419 void locationItemClicked(const QList<QString> &userIDs);
422 * @brief Signal to notify map scrolling.
424 void mapScrolledManually();
427 * @brief Signal to notify when map is zoomed in to the maxmimum.
429 void maxZoomLevelReached();
432 * @brief Signal to notify when map is zoomed out to the minimum.
434 void minZoomLevelReached();
437 * @brief Signal to pass the scale of the map to map scale
439 void newMapResolution(qreal scale);
442 * @brief Request view changing zoom level
444 * @param newZoomLevel New zoom level
446 void zoomLevelChanged(int newZoomLevel);
448 /*******************************************************************************
450 ******************************************************************************/
452 bool m_autoCenteringEnabled; ///< Auto centering enabled
453 bool m_scrollStartedByGps; ///< Smooth scroll is started by GPS?
454 bool m_smoothScrollRunning; ///< Smooth scroll is running?
455 bool m_zoomedIn; ///< Flag for checking if zoomed in when zoom is finished
457 int m_zoomLevel; ///< Current zoom level
459 QPoint m_centerTile; ///< Current center tile
460 SceneCoordinate m_lastAutomaticPosition; ///< Last automatically set position in scene coordinate
461 SceneCoordinate m_sceneCoordinate; ///< Current center coordinate
463 QRect m_viewTilesGrid; ///< Current grid of tiles in view (includes margin)
465 QSize m_tilesGridSize; ///< Current size of the tiles grid
466 QSize m_viewSize; ///< Current view size
468 FriendItemsHandler *m_friendItemsHandler; ///< Handler for friend and group items
469 GeoCoordinate m_gpsPosition; ///< Latest GPS position
470 GPSLocationItem *m_gpsLocationItem; ///< Item pointing current location from GPS
471 MapFetcher *m_mapFetcher; ///< Fetcher for map tiles
472 MapRouteItem *m_mapRouteItem; ///< Map route item
473 MapScene *m_mapScene; ///< Scene for map tiles
474 MapScroller *m_scroller; ///< Kinetic scroller
475 OwnLocationItem *m_ownLocation; ///< Item to show own location
476 Route m_route; ///< Current route data
479 #endif // MAPENGINE_H