inc/engine/maps/GeoTiledMap.h

   1 /*
   2  * Copyright (C) 2013 HERE Global B.V. All rights reserved.
   3  * This software, including documentation, is protected by copyright controlled by
   4  * HERE Global B.V. (“Software”). All rights are reserved. Copying, including reproducing,
   5  * storing, adapting or translating, any or all of this material requires the prior
   6  * written consent of HERE Global B.V. You may use this
   7  * Software in accordance with the terms and conditions defined in the
   8  * HERE Location Platform Services Terms and Conditions, available at
   9  * http://developer.here.com/terms-conditions-base
  10  *
  11  * As an additional permission to the above, you may distribute Software,
  12  * in object code format as part of an Application, according to, and subject to, terms and
  13  * conditions defined in the Tizen Software Development kit (“SDK”) License Agreement.
  14  * You may distribute such object code format Application under terms of your choice,
  15  * provided that the header and source files of the Software have not been modified.
  16  */
  17
  18 #ifndef GEOTILEDMAP_H
  19 #define GEOTILEDMAP_H
  20
  21 #include <vector>
  22 #include <tr1/functional>
  23
  24 #include "common/HereMaps_global.h"
  25
  26 #ifndef TIZEN_MIGRATION
  27 #include <FUi.h>
  28 #include <FGraphics.h>
  29 #include <FGrpColor.h>
  30 #endif
  31
  32 #include "maps/DrawableBitmap.h"
  33 #ifdef TIZEN_MIGRATION
  34 #include "graphic/Dimension.h"
  35 #include "graphic/Point.h"
  36 #include "graphic/Color.h"
  37 #include <Evas_GL.h>
  38
  39 using namespace Tizen::Maps;
  40 #endif
  41
  42 HERE_MAPS_BEGIN_NAMESPACE
  43
  44 class GeoTile;
  45 class ErrorBase;
  46 class GeoMapObject;
  47 class GeoCoordinates;
  48 class TileFetcherReply;
  49 class GeoProjectionNode;
  50 class GeoMapObjectMarker;
  51 class GeoProviderManager;
  52
  53
  54 /**
  55  * This class encapsulates a tiled map. The map is composed of square bitmap
  56  * tiles retrieved from a grid that represents the normalized Mercator
  57  * projection (see also <code>GeoTile</code>). The class supports a number of
  58  * map types (for example normal, terrain, satellite, etc.) and provides methods
  59  * to control the map size, orientation (heading), zoom level, and managing
  60  * objects such as markers, polylines and polygons that can be superimposed on
  61  * the map.
  62  *
  63  * \ingroup maps
  64  */
  65 class EXPORT_API GeoTiledMap
  66 {
  67 public:
  68
  69     /**
  70      * This enumeration defines identifiers for supported map types.
  71      */
  72     enum MapType
  73     {
  74         MT_Normal_Day = 0,              ///< Indicates a normal (street/physical
  75                                         ///  day map.
  76         MT_Satellite_Day,               ///< Indicates a satellite day map.
  77         MT_Terrain_Day,                 ///< Indicates a terrain day map.
  78         MT_Hybrid_Day,                  ///< Indicates a hybrid day map
  79                                         ///  (satellite, with roads and labels).
  80 #ifdef TIZEN_MIGRATION
  81         MT_Normal_Day_Grey,
  82         MT_Normal_Day_Transit,
  83         MT_Normal_Night_Transit,
  84         MT_Normal_Traffic_Day,
  85         MT_Normal_Traffic_Night,
  86         MT_Normal_Day_Custom,
  87         MT_Normal_Night,
  88         MT_Normal_Night_Grey,
  89         MT_Pedestrian_Day,
  90         MT_Pedestrian_Day_Mobile,
  91         MT_Pedestrian_Night,
  92         MT_Pedestrian_Night_Mobile,
  93         MT_Carnav_Day_Grey,
  94         MT_Normal_Day_Mobile,
  95         MT_Normal_Day_Grey_Mobile,
  96         MT_Normal_Day_Transit_Mobile,
  97         MT_Normal_Night_Transit_Mobile,
  98         MT_Normal_Night_Mobile,
  99         MT_Normal_Night_Grey_Mobile,
 100         MT_Reduced_Day,
 101         MT_Reduced_Night,
 102         MT_Hybrid_Day_Transit,
 103         MT_Hybrid_Grey_Day,
 104         MT_Hybrid_Traffic_Day,
 105         MT_Hybrid_Day_Mobile,
 106         MT_Terrain_Day_Mobile,
 107 #endif
 108         MT_Last_Entry_Undefined         ///< Indicates that the map type is not
 109                                         ///  defined.
 110     };
 111
 112     /**
 113      * This enumeration defines identifiers for logo color.
 114      */
 115     enum LogoColor
 116     {
 117         LC_Blue = 0,  ///< Indicates that the color is blue.
 118         LC_White      ///< Indicates that the color is white.
 119     };
 120
 121     /**
 122      * This method is the default constructor.
 123      */
 124     GeoTiledMap();
 125
 126     /**
 127      * This method is the (virtual) destructor.
 128      */
 129     virtual ~GeoTiledMap();
 130
 131     /**
 132      * This method sets the size of the map.
 133      *
 134      * @param size A constant reference to an object specifying the size of the
 135      *        map in pixels (width and height).
 136      */
 137     void SetMapSize(const Tizen::Maps::Dimension& size);
 138
 139     /**
 140      * This method retrieves the map size.
 141      *
 142      * @return A constant reference to an object containing the width and height
 143      *        of the map in pixels.
 144      */
 145     const Tizen::Maps::Dimension& GetMapSize() const;
 146
 147     /**
 148      * This method sets the map zoom level.
 149      *
 150      * @param zoomLevel A value indicating the new zoom level.
 151      */
 152     #ifdef TIZEN_MIGRATION
 153     void SetZoomLevel(double zoomLevel, bool bUpdate=true);
 154     #else
 155     void SetZoomLevel(double zoomLevel);
 156     #endif
 157
 158     /**
 159      * This method retrieves the map zoom level.
 160      *
 161      * @return A value indicating the new zoom level.
 162      */
 163     double GetZoomLevel() const;
 164
 165     /**
 166      * This method retrieves the minimum map zoom level.
 167      *
 168      * @return A value indicating the minimum map zoom level.
 169      */
 170     double GetMinimumZoomLevel() const;
 171
 172 #ifdef TIZEN_CUSTOMIZATION
 173     /**
 174      * This method sets the minimum map zoom level.
 175      *
 176      * @return A value indicating the minimum map zoom level.
 177      */
 178     void SetMinimumZoomLevel(double zoom);
 179 #endif
 180
 181     /**
 182      * This method retrieves the maximum map zoom level.
 183      *
 184      * @return A value indicating the maximum map zoom level.
 185      */
 186     double GetMaximumZoomLevel() const;
 187
 188 #ifdef TIZEN_CUSTOMIZATION
 189     /**
 190      * This method sets the maximum map zoom level.
 191      *
 192      * @return A value indicating the maximum map zoom level.
 193      */
 194     void SetMaximumZoomLevel(double zoom);
 195 #endif
 196
 197     /**
 198      * This method pans the map the caller-specified number of pixels
 199      * horizontally and vertically.
 200      *
 201      * @param dx A value indicating the number of pixels to move the map along
 202      *        the horizontal axis.
 203      *
 204      * @param dy A value indicating the number of pixels to move the map along
 205      *        the vertical axis.
 206      */
 207     void Pan(int dx, int dy);
 208
 209     /**
 210      * This method sets the coordinates of the map center.
 211      *
 212      * @param center A constant reference to an object containing the new
 213      *        geographic coordinates of the map center.
 214      */
 215     void SetCenter(const GeoCoordinates& center);
 216
 217     /**
 218      * This method retrieves the coordinates of the map center.
 219      *
 220      * @return A constant reference to an object containing the
 221      *        geographic coordinates of the map center.
 222      */
 223     GeoCoordinates GetCenter() const;
 224
 225     /**
 226      * This method renders the given object invalid by resetting the drawable
 227      * object representing the map and resetting and reinitializing the tile
 228      * cache.
 229      */
 230     void Invalidate();
 231
 232     /**
 233      * This method invalidates (discards) all the map objects, including
 234      * markers.
 235      */
 236     void InvalidateMapObjects();
 237
 238 #ifdef TIZEN_SUPPORT_OPTIMIZATION_OF_REDRAWING
 239     /**
 240      * This method invalidates (discards) all the map markers.
 241      */
 242     void InvalidateMapMarkers();
 243 #endif
 244
 245     /**
 246      * This method invalidates (clears) the cache.
 247      */
 248     void ClearCache();
 249
 250     /**
 251      * This method clears all the map objects associated with the given tiled
 252      * map object.
 253      */
 254     void ClearMapObjects();
 255
 256     /**
 257      * This method converts the geographic location specified by the caller to
 258      * screen coordinates, taking into consideration the current zoom level and
 259      * the view area.
 260      *
 261      * @param coordinate A constant reference to an object containing the
 262      *        coordinates to convert.
 263      *
 264      * @return An object containing the x and y coordinates defining the screen
 265      *        location.
 266      */
 267     Tizen::Maps::Point CoordinateToScreenPosition(const GeoCoordinates& coordinate) const;
 268
 269     /**
 270      * This method converts the screen position specified by the caller to
 271      * geographic coordinates. The method is called, for example, when a marker
 272      * is being added to the map.
 273      *
 274      * @param screenPosition An object containing the x and y coordinates
 275      *        defining the screen location to convert.
 276      *
 277      * @return An object containing the geographic coordinates of corresponding
 278      *        to the received screen position.
 279      */
 280     GeoCoordinates ScreenPositionToCoordinate(const Tizen::Maps::Point& screenPosition) const;
 281
 282     //map objects support
 283     /**
 284      * This method adds an object to the map. The object is a marker, a polygon
 285      * or polyline, or a group of objects.
 286      *
 287      * @param obj A pointer to an object to add to the map. If the object does
 288      *        not exist (is <code>NULL</code>), the method has no effect.
 289      *
 290      * @param bTransferOwnership A Boolean value indicating if the ownership of
 291      *        the map object given in the first parameter should be transferred
 292      *        to this map instance (<code>true</code>, default) or not
 293      *        (<code>false</code>). The default behavior transfers the
 294      *        ownership, which means that the map object becomes responsible for
 295      *        deleting the markers.
 296      */
 297     void AddObject(GeoMapObject* obj, bool bTransferOwnership=true);
 298
 299     /**
 300      * This method removes the object specified by the caller from the map.
 301      *
 302      * @param obj A pointer to the object to remove from the map. If the object
 303      *        does not exist (is <code>NULL</code>), the method has no effect.
 304      *
 305      * @return Boolean value indicating if the removal of the object was
 306      *        successful (<code>true</code>) or not (<code>false</code>).
 307      */
 308     bool RemoveObject(GeoMapObject* obj);
 309
 310     /**
 311      * This method obtains a pointer to the map object located at the screen
 312      * position indicated by the caller.
 313      *
 314      * @param point A constant reference to an object containing the pixel
 315      *        coordinates of the screen position from which to get the map object.
 316      *
 317      * @return A pointer to the map object at the specified screen location,
 318      *        otherwise <code>NULL</code> if no map object is found.
 319      */
 320     GeoMapObject* GetObjectAtScreenPosition(const Tizen::Maps::Point& point) const;
 321
 322     /**
 323      * This method obtains a count of marker objects in the given tiled map.
 324      *
 325      * @return A value that indicates the number of marker objects.
 326      */
 327     size_t GetNumMarkerObjects() const;
 328
 329     /**
 330      * This method retrieves a pointer to a marker object at the index specified
 331      * by the caller.
 332      *
 333      * @param idx A value specifying the index of the marker object to
 334      *        retrieve.
 335      *
 336      * @return A pointer to the marker object at the specified index or
 337      *        <code>NULL</code> if the index is invalid.
 338      */
 339     GeoMapObjectMarker* GetMarkerObject(size_t idx) const;
 340
 341     //draws the map into the current OpenGl context
 342     /**
 343      * This method draws (renders and displays) a map image of the size
 344      * specified by the caller. The displayed map includes the required map
 345      * tiles as well as any objects such as markers, polygons and polylines.
 346      *
 347      * @param uWidth A value specifying the width of the map image.
 348      *
 349      * @param uHeight A value specifying the height of the map image.
 350      *
 351      * @return A Boolean, <code>true</code> if the map has been successfully
 352      *        pained, otherwise <code>false</code>.
 353      */
 354     bool PaintMap(unsigned int uWidth, unsigned int uHeight);
 355
 356     /**
 357      * This typedef defines a function object as a type. The function object can
 358      * be called when the map has been updated. A function object of this type
 359      * returns <code>void</code> and receives no arguments.
 360      */
 361 #ifdef TIZEN_MIGRATION
 362     typedef std::tr1::function<void (void *)> UpdateMapSignalFunctor;
 363 #else
 364     typedef std::tr1::function<void ()> UpdateMapSignalFunctor;
 365 #endif
 366
 367     /**
 368      * This method sets a callback to be invoked when the map has
 369      * been updated.
 370      *
 371      * @param slot A function object to be called when the map has
 372      *        been updated.
 373      */
 374      void SetUpdateMapSignal(UpdateMapSignalFunctor slot);
 375
 376      /**
 377       * This method sets the map type.
 378       *
 379       * @param aMapType A value indicating the new map type.
 380       */
 381     void SetMapType(MapType aMapType);
 382
 383      /**
 384       * This method retrieves the map type.
 385       *
 386       * @return A value indicating the current map type.
 387       */
 388     MapType GetMapType() const;
 389
 390     /*
 391      * Available language options are:
 392      * L"ara", L"chi", L"cht", L"dut", L"eng", L"ger", L"gle", L"fre", L"ita", L"spa", L"rus", L"pol", L"gre", L"wel"
 393      */
 394     /**
 395      * This method sets the language of the map.
 396      *
 397      * @param aMapLanguage A constant reference to a string containing a
 398      *        language code. The value of the string must be one of "ara"
 399      *        (Arabic), "chi" (Chinese), "cht" (Chinese-Taiwan), "dut" (Dutch),
 400      *        "eng" (English), "ger" (German), "gle" (Irish), "fre" (French),
 401      *        "ita" (Italian), "spa" (Spanish), "rus" (Russian), "pol" (Polish),
 402      *        "gre" (Greek), "wel" (Welsh)
 403      */
 404     void SetMapLanguage(const String& aMapLanguage);
 405
 406     /**
 407      * This method retrieves the current language of the map.
 408      *
 409      * @return A constant reference to a string containing the language code,
 410      *        which is one of "ara" (Arabic), "chi" (Chinese), "cht"
 411      *        (Chinese-Taiwan), "dut" (Dutch), "eng" (English), "ger" (German),
 412      *        "gle" (Irish), "fre" (French), "ita" (Italian), "spa" (Spanish),
 413      *        "rus" (Russian), "pol" (Polish), "gre" (Greek), "wel" (Welsh)
 414      */
 415     const String& GetMapLanguage() const;
 416
 417     /**
 418      * This method sets the size of the tiles used for rendering the map.
 419      *
 420      * @param uTileSizeInPX Specifies the width and the height of the tiles. Note that
 421      *        only 128 and 256 are supported as valid values.
 422      */
 423     void SetTileSize(unsigned int uTileSizeInPx);
 424
 425     /**
 426      * This method retrieves the size of the tiles, used for rendering the map.
 427      *
 428      * @return An unsigned integer indicating the size of the map tiles.
 429      */
 430     unsigned int GetTileSize() const;
 431
 432     /**
 433      * This method changes the background color of the map.
 434      * The background color is updated after refreshing the map.
 435      *
 436      * @param color A constant reference to an object representing the new map
 437      *        background color.
 438      */
 439     void SetBackgroundColor(const Tizen::Maps::Color& color);
 440
 441 #ifdef TIZEN_CUSTOMIZATION
 442     /**
 443      * This method retrieves the root tile, used for rendering the map.
 444      *
 445      * @return An pointer indicating the bitmap of the root tile.
 446      */
 447     DrawableBitmapPtr GetRootPixmap();
 448
 449     /**
 450      * This method sets a pointer of a structure of the Evas GL API object that
 451      *        contains the GL APIs to be used in Evas GL.
 452      *
 453      * @param __glapi A pointer to a structure of the Evas GL API object.
 454      */
 455     void SetEvasGlApi(Evas_GL_API *__glapi);
 456
 457     /**
 458      * This typedef defines a function object as a type. The function object can
 459      * be called when the map has been ready after initialized. A function object of
 460      * this type returns <code>void</code> and receives no arguments.
 461      */
 462     typedef void(*ReadyMapSignalFunctor)(void);
 463
 464     /**
 465      * This method sets a callback to be invoked when the map has
 466      * been ready after initialization.
 467      *
 468      * @param slot A function object to be called when the map has
 469      *        been ready after initialization.
 470      */
 471     void SetReadyMapSignal(ReadyMapSignalFunctor callback);
 472
 473     /**
 474      * This method sets the angle of the map.
 475      *
 476      * @param angle The angle of the map [-360~360].
 477      */
 478     void SetAngle(double angle);
 479
 480     /**
 481      * This method retrieves the angle of the map.
 482      *
 483      * @return A value indicating the angle of the map.
 484      */
 485     double GetAngle();
 486
 487     /**
 488      * This method sets a Boolean value indicating if the scale bar is enabled or not.
 489      *
 490      * @param enable <code>true</code> if the given status is enabled,
 491      *        otherwise <code>false</code>.
 492      */
 493     void SetScalebar(bool enable);
 494
 495     /**
 496      * This method retrieves a Boolean value indicating if the scale bar is enabled or not.
 497      *
 498      * @return <code>true</code> if the scale bar is enabled, otherwise <code>false</code>.
 499      */
 500     bool GetScalebar() const;
 501 #endif
 502
 503 #ifdef TIZEN_SUPPORT_TILE_FILE_CACHE
 504     /**
 505      * This method invalidates (clears) the file cache for tiles.
 506      */
 507     void ClearTileFileCache();
 508 #endif
 509
 510 private:
 511     bool HandleTileReady(int level, int x, int y, unsigned int uLevelProvider);
 512     bool DrawLogo(UInt uWidth, UInt uHeight, UInt aMapX = 0, UInt aMapY = 0);
 513
 514     void UpdateMapSignal();
 515     void UpdateProjectionNodes();
 516     float CreateProjectionTree(std::vector<GeoProjectionNode*>& result, GeoProjectionNode* node);
 517     void InitializeCache();
 518     void SortMarkers();
 519     int GetDisplayDPI() const;
 520     void ClearMarkers();
 521     void SetRootPixmap(DrawableBitmapPtr rootPixmap);
 522 #ifdef TIZEN_MIGRATION
 523     void ExtendLimitOfCachedTiles();
 524     bool DrawScalebar(UInt uWidth, UInt uHeight, UInt aMapX = 0, UInt aMapY = 0);
 525 #endif
 526
 527 private:
 528     friend class GeoMapObject;
 529     friend class GeoMapObjectMarker;
 530     friend class GeoProviderManager;
 531     friend class TestGeoTiledMap;
 532     HERE_MAPS_NO_COPY_NO_ASSIGN(GeoTiledMap);
 533
 534     class GeoTiledMapImpl;
 535     GeoTiledMapImpl *m_pImpl;
 536 };
 537
 538 HERE_MAPS_END_NAMESPACE
 539
 540 #endif // GEOTILEDMAPDATA_H