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 "coordinates/geocoordinate.h"
32 #include "coordinates/scenecoordinate.h"
36 class FriendItemsHandler;
37 class GPSLocationItem;
42 class OwnLocationItem;
48 * Logic for controlling map functionality. Does also include static methods for
49 * converting coordinates.
51 * @author Sami Rämö - sami.ramo (at) ixonos.com
52 * @author Jussi Laitinen - jussi.laitinen (at) ixonos.com
53 * @author Pekka Nissinen - pekka.nissinen (at) ixonos.com
54 * @author Ville Tiensuu - ville.tiensuu (at) ixonos.com
56 class MapEngine : public QObject
64 * @param parent Parent
66 MapEngine(QObject *parent = 0);
70 * Saves view of the map to settings file
74 /*******************************************************************************
75 * MEMBER FUNCTIONS AND SLOTS
76 ******************************************************************************/
79 * @brief Coordinates of the current center point
81 * @return Current coordinates
83 GeoCoordinate centerGeoCoordinate();
87 // * @brief Convert latitude and longitude to scene coordinates.
89 // * @param latLonCoordinate latitude and longitude values
90 // * @return scene coordinate
92 // static QPoint convertLatLonToSceneCoordinate(GeoCoordinate latLonCoordinate);
95 // * @brief converts scene coordinates to latitude and longitude
97 // * @param zoomLevel current zoom level
98 // * @param sceneCoordinate that will be converted
100 // GeoCoordinate convertSceneCoordinateToLatLon(int zoomLevel, QPoint sceneCoordinate);
103 * @brief Convert MapScene coordinate to tile x & y numbers.
105 * @param zoomLevel ZoomLevel
106 * @param sceneCoordinate MapScene coordinate
107 * @return tile x & y numbers
109 static QPoint convertSceneCoordinateToTileNumber(int zoomLevel, SceneCoordinate sceneCoordinate);
112 * @brief Convert tile x & y numbers to MapScene coordinates
114 * @param zoomLevel Zoom level
115 * @param tileNumber x & y numbers of the tile
116 * @return Scene coordinate
118 static SceneCoordinate convertTileNumberToSceneCoordinate(int zoomLevel, QPoint tileNumber);
121 * @brief Calculate great-circle distance between two geographic coordinates
123 * Calculate great-circle distance between two given geographic locations using
126 * @param firstLocation Coordinates of the first location
127 * @param secondLocation Coordinates of the second location
128 * @return qreal Distance in kilometers
130 qreal greatCircleDistance(GeoCoordinate firstLocation, GeoCoordinate secondLocation);
133 * @brief Set initial values for the map
135 * Set initial location and zoom level from the settings, if available, or use the default
136 * values set in the constructor. Signals locationChanged() and zoomLevelChanged() are emitted,
137 * so init should be called after those signals are connected.
142 * @brief Return given value translated between min and max
144 * If given value is not inside the given range (min <= value <= max), then the allowed range
145 * is adder or subtracted until the value does fit in the range.
147 * @param value Value to be normalized
148 * @param min Minimum allowed value
149 * @param max Maximum allowed value
150 * @return value which is moved to be inside the given limits
152 static int normalize(int value, int min, int max);
155 * @brief Getter for scene
157 * @return QGraphicsScene
159 QGraphicsScene* scene();
162 * @brief Sets new zoom level
164 * @return newZoomLevel value that is set to new zoom level
166 void setZoomLevel(const int newZoomLevel);
169 * @brief Return tile path created from tile values.
171 * @param zoomLevel tile's zoom level
172 * @param x tile's x value
173 * @param y tile's y value
174 * @return QString tile path
176 static QString tilePath(int zoomLevel, int x, int y);
179 * @brief Maximum number of individual tiles per side at given zoom level
181 * @param zoomLevel Zoom level
182 * @return amount of tiles per side at given zoom level
184 static int tilesPerSide(int zoomLevel);
188 * @brief Center smoothly to given latitude and longitude coordinates.
190 * @param latLonCoordinate Latitude & longitude coordinates for location
192 void centerToCoordinates(GeoCoordinate latLonCoordinate);
195 * @brief Slot to catch user own location data
197 * @param user User info
199 void receiveOwnLocation(User *user);
202 * @brief Set auto centering.
204 * @param enabled true if enabled, false otherwise
206 void setAutoCentering(bool enabled);
209 * @brief Slot for enabling / disabling GPS
211 * GPS location item is disabled or enabled based on GPS state
213 * @param enabled True is GPS is enabled, otherwise false
215 void setGPSEnabled(bool enabled);
218 * @brief Calculate maximum value for tile in this zoom level.
220 * @param zoomLevel zoom level
221 * @return int tile's maximum value
223 static int tileMaxIndex(int zoomLevel);
226 * @brief Slot for view resizing.
228 * @param size view size
230 void viewResized(const QSize &size);
234 * @brief Calculate grid of tile coordinates from current scene coordinate.
236 * Grid size is calculated from view size and scene's current center coordinate.
238 * @param sceneCoordinate scene's current center coordinate
239 * @return QRect grid of tile coordinates
241 QRect calculateTileGrid(SceneCoordinate sceneCoordinate);
244 * @brief Request disabling of auto centering if centered too far from the real location.
246 * @param sceneCoordinate scene's center coordinate
248 void disableAutoCenteringIfRequired(SceneCoordinate sceneCoordinate);
251 * @brief Get new tiles.
253 * Calculates which tiles has to be fetched. Does emit fetchImage for tiles which
254 * aren't already in the scene.
255 * @param sceneCoordinate scene's center coordinate
257 void getTiles(SceneCoordinate sceneCoordinate);
260 * @brief Check if auto centering is enabled
262 * @return true if enabled, false otherwise
264 bool isAutoCenteringEnabled();
267 * @brief Check if center tile has changed.
269 * @param sceneCoordinate scene's center coordinate
270 * @return bool true if center tile changed, false otherwise
272 bool isCenterTileChanged(SceneCoordinate sceneCoordinate);
275 * @brief Calculate scale at the map center of the map in meters/pixel
277 * @return qreal Scale of the map in meters/pixel
279 qreal sceneResolution();
282 * @brief Set size of tiles grid based on view size
284 * @param viewSize Current view size
286 void setTilesGridSize(const QSize &viewSize);
289 * @brief Updates the current view rect including margins
291 * Calculates tiles rect in scene based on m_viewTilesGrid and
292 * calls MapScene::viewRectUpdated()
294 void updateViewTilesSceneRect();
297 * @brief This method is ran always when the map is zoomed
299 * This method is the right place for all actions which must be done when ever map is zoomed.
305 * @brief This slot is called after friend items position have been updated
307 * Does run MapScene::spanItems()
309 void friendsPositionsUpdated();
312 * @brief Slot for GPS position updates
314 * GPS location item is updated and map centered to new location (if automatic
315 * centering is enabled).
317 * @param position New coordinates from GPS
318 * @param accuracy Accuracy of the GPS fix
320 void gpsPositionUpdate(GeoCoordinate position, qreal accuracy);
323 * @brief Slot for received map tile images
325 * Does receive map tile images from MapFetcher. Calls MapScene::addTile() for creating and adding
326 * the actual MapTile object to the MapScene.
328 * Tile is added also to outside the world horizontal limits, if required, for spanning the map.
330 * @param zoomLevel Zoom level
331 * @param x Tile x index
332 * @param y Tile y index
333 * @param image Received pixmap
335 void mapImageReceived(int zoomLevel, int x, int y, const QPixmap &image);
338 * @brief Called when MapScroller state is changed
340 * Does check if the smooth scroll effect was interrupted and should the auto centering
341 * feature to be disabled.
343 * @param newState New state
345 void scrollerStateChanged(QAbstractAnimation::State newState);
348 * @brief Scroll smoothly to given scene position
350 * @param scenePosition Target position in the scene
352 void scrollToPosition(SceneCoordinate scenePosition);
355 * @brief Set center point in the scene
357 * Does emit locationChanged signal.
358 * @param scenePosition Scene coordinates for new position
360 void setCenterPosition(SceneCoordinate scenePosition);
363 * @brief Slot for actions after view zoom is finished
365 * Does run removeOutOfViewTiles
367 void viewZoomFinished();
370 * @brief Slot for zooming in
375 * @brief Slot for zooming out
379 /*******************************************************************************
381 ******************************************************************************/
384 * @brief Signals error
386 * @param context error context
387 * @param error error code
389 void error(const int context, const int error);
392 * @brief Signal for image fetching.
394 * @param zoomLevel Zoom level
395 * @param x Tile x index
396 * @param y Tile y index
398 void fetchImage(int zoomLevel, int x, int y);
401 * @brief Signal when friend image is ready
405 void friendImageReady(User *user);
408 * @brief Signal when friend list locations are fetched
410 * @param friendsList Friends list data
412 void friendsLocationsReady(QList<User *> &friendsList);
415 * @brief Request view centering to new locaiton
417 * @param sceneCoordinate New scene coordinates
419 void locationChanged(SceneCoordinate sceneCoordinate);
422 * @brief Signal is emitted when location item is clicked.
424 * @param userIDs list of friends user IDs in the group
426 void locationItemClicked(const QList<QString> &userIDs);
429 * @brief Signal to notify map scrolling.
431 void mapScrolledManually();
434 * @brief Signal to notify when map is zoomed in to the maxmimum.
436 void maxZoomLevelReached();
439 * @brief Signal to notify when map is zoomed out to the minimum.
441 void minZoomLevelReached();
444 * @brief Signal to pass the scale of the map to map scale
446 void newMapResolution(qreal scale);
449 * @brief Request view changing zoom level
451 * @param newZoomLevel New zoom level
453 void zoomLevelChanged(int newZoomLevel);
455 /*******************************************************************************
457 ******************************************************************************/
459 bool m_autoCenteringEnabled; ///< Auto centering enabled
460 bool m_scrollStartedByGps; ///< Smooth scroll is started by GPS?
461 bool m_smoothScrollRunning; ///< Smooth scroll is running?
462 bool m_zoomedIn; ///< Flag for checking if zoomed in when zoom is finished
464 int m_zoomLevel; ///< Current zoom level
466 QPoint m_centerTile; ///< Current center tile
467 SceneCoordinate m_lastAutomaticPosition; ///< Last automatically set position in scene coordinate
468 SceneCoordinate m_sceneCoordinate; ///< Current center coordinate
470 QRect m_viewTilesGrid; ///< Current grid of tiles in view (includes margin)
472 QSize m_tilesGridSize; ///< Current size of the tiles grid
473 QSize m_viewSize; ///< Current view size
475 FriendItemsHandler *m_friendItemsHandler; ///< Handler for friend and group items
476 GPSLocationItem *m_gpsLocationItem; ///< Item pointing current location from GPS
477 MapFetcher *m_mapFetcher; ///< Fetcher for map tiles
478 MapScene *m_mapScene; ///< Scene for map tiles
479 MapScroller *m_scroller; ///< Kinetic scroller
480 OwnLocationItem *m_ownLocation; ///< Item to show own location
483 #endif // MAPENGINE_H