src/lib/elm_map.h

   1    /**
   2     * @defgroup Map Map
   3     * @ingroup Elementary
   4     *
   5     * @image html img/widget/map/preview-00.png
   6     * @image latex img/widget/map/preview-00.eps
   7     *
   8     * This is a widget specifically for displaying a map. It uses basically
   9     * OpenStreetMap provider http://www.openstreetmap.org/,
  10     * but custom providers can be added.
  11     *
  12     * It supports some basic but yet nice features:
  13     * @li zoom and scroll
  14     * @li markers with content to be displayed when user clicks over it
  15     * @li group of markers
  16     * @li routes
  17     *
  18     * Smart callbacks one can listen to:
  19     *
  20     * - "clicked" - This is called when a user has clicked the map without
  21     *   dragging around.
  22     * - "press" - This is called when a user has pressed down on the map.
  23     * - "longpressed" - This is called when a user has pressed down on the map
  24     *   for a long time without dragging around.
  25     * - "clicked,double" - This is called when a user has double-clicked
  26     *   the map.
  27     * - "load,detail" - Map detailed data load begins.
  28     * - "loaded,detail" - This is called when all currently visible parts of
  29     *   the map are loaded.
  30     * - "zoom,start" - Zoom animation started.
  31     * - "zoom,stop" - Zoom animation stopped.
  32     * - "zoom,change" - Zoom changed when using an auto zoom mode.
  33     * - "scroll" - the content has been scrolled (moved).
  34     * - "scroll,anim,start" - scrolling animation has started.
  35     * - "scroll,anim,stop" - scrolling animation has stopped.
  36     * - "scroll,drag,start" - dragging the contents around has started.
  37     * - "scroll,drag,stop" - dragging the contents around has stopped.
  38     * - "downloaded" - This is called when all currently required map images
  39     *   are downloaded.
  40     * - "route,load" - This is called when route request begins.
  41     * - "route,loaded" - This is called when route request ends.
  42     * - "name,load" - This is called when name request begins.
  43     * - "name,loaded- This is called when name request ends.
  44     *
  45     * Available style for map widget:
  46     * - @c "default"
  47     *
  48     * Available style for markers:
  49     * - @c "radio"
  50     * - @c "radio2"
  51     * - @c "empty"
  52     *
  53     * Available style for marker bubble:
  54     * - @c "default"
  55     *
  56     * List of examples:
  57     * @li @ref map_example_01
  58     * @li @ref map_example_02
  59     * @li @ref map_example_03
  60     */
  61
  62    /**
  63     * @addtogroup Map
  64     * @{
  65     */
  66
  67    /**
  68     * @enum _Elm_Map_Zoom_Mode
  69     * @typedef Elm_Map_Zoom_Mode
  70     *
  71     * Set map's zoom behavior. It can be set to manual or automatic.
  72     *
  73     * Default value is #ELM_MAP_ZOOM_MODE_MANUAL.
  74     *
  75     * Values <b> don't </b> work as bitmask, only one can be choosen.
  76     *
  77     * @note Valid sizes are 2^zoom, consequently the map may be smaller
  78     * than the scroller view.
  79     *
  80     * @see elm_map_zoom_mode_set()
  81     * @see elm_map_zoom_mode_get()
  82     *
  83     * @ingroup Map
  84     */
  85    typedef enum _Elm_Map_Zoom_Mode
  86      {
  87         ELM_MAP_ZOOM_MODE_MANUAL, /**< Zoom controlled manually by elm_map_zoom_set(). It's set by default. */
  88         ELM_MAP_ZOOM_MODE_AUTO_FIT, /**< Zoom until map fits inside the scroll frame with no pixels outside this area. */
  89         ELM_MAP_ZOOM_MODE_AUTO_FILL, /**< Zoom until map fills scroll, ensuring no pixels are left unfilled. */
  90         ELM_MAP_ZOOM_MODE_LAST
  91      } Elm_Map_Zoom_Mode;
  92
  93    /**
  94     * @enum _Elm_Map_Route_Sources
  95     * @typedef Elm_Map_Route_Sources
  96     *
  97     * Set route service to be used. By default used source is
  98     * #ELM_MAP_ROUTE_SOURCE_YOURS.
  99     *
 100     * @see elm_map_route_source_set()
 101     * @see elm_map_route_source_get()
 102     *
 103     * @ingroup Map
 104     */
 105    typedef enum _Elm_Map_Route_Sources
 106      {
 107         ELM_MAP_ROUTE_SOURCE_YOURS, /**< Routing service http://www.yournavigation.org/ . Set by default.*/
 108         ELM_MAP_ROUTE_SOURCE_MONAV, /**< MoNav offers exact routing without heuristic assumptions. Its routing core is based on Contraction Hierarchies. It's not working with Map yet. */
 109         ELM_MAP_ROUTE_SOURCE_ORS, /**< Open Route Service: http://www.openrouteservice.org/ . It's not working with Map yet. */
 110         ELM_MAP_ROUTE_SOURCE_LAST
 111      } Elm_Map_Route_Sources;
 112
 113    typedef enum _Elm_Map_Name_Sources
 114      {
 115         ELM_MAP_NAME_SOURCE_NOMINATIM,
 116         ELM_MAP_NAME_SOURCE_LAST
 117      } Elm_Map_Name_Sources;
 118
 119    /**
 120     * @enum _Elm_Map_Route_Type
 121     * @typedef Elm_Map_Route_Type
 122     *
 123     * Set type of transport used on route.
 124     *
 125     * @see elm_map_route_add()
 126     *
 127     * @ingroup Map
 128     */
 129    typedef enum _Elm_Map_Route_Type
 130      {
 131         ELM_MAP_ROUTE_TYPE_MOTOCAR, /**< Route should consider an automobile will be used. */
 132         ELM_MAP_ROUTE_TYPE_BICYCLE, /**< Route should consider a bicycle will be used by the user. */
 133         ELM_MAP_ROUTE_TYPE_FOOT, /**< Route should consider user will be walking. */
 134         ELM_MAP_ROUTE_TYPE_LAST
 135      } Elm_Map_Route_Type;
 136
 137    /**
 138     * @enum _Elm_Map_Route_Method
 139     * @typedef Elm_Map_Route_Method
 140     *
 141     * Set the routing method, what should be priorized, time or distance.
 142     *
 143     * @see elm_map_route_add()
 144     *
 145     * @ingroup Map
 146     */
 147    typedef enum _Elm_Map_Route_Method
 148      {
 149         ELM_MAP_ROUTE_METHOD_FASTEST, /**< Route should priorize time. */
 150         ELM_MAP_ROUTE_METHOD_SHORTEST, /**< Route should priorize distance. */
 151         ELM_MAP_ROUTE_METHOD_LAST
 152      } Elm_Map_Route_Method;
 153
 154    typedef enum _Elm_Map_Name_Method
 155      {
 156         ELM_MAP_NAME_METHOD_SEARCH,
 157         ELM_MAP_NAME_METHOD_REVERSE,
 158         ELM_MAP_NAME_METHOD_LAST
 159      } Elm_Map_Name_Method;
 160
 161    typedef struct _Elm_Map_Marker          Elm_Map_Marker; /**< A marker to be shown in a specific point of the map. Can be created with elm_map_marker_add() and deleted with elm_map_marker_remove(). */
 162    typedef struct _Elm_Map_Marker_Class    Elm_Map_Marker_Class; /**< Each marker must be associated to a class. It's required to add a mark. The class defines the style of the marker when a marker is displayed alone (not grouped). A new class can be created with elm_map_marker_class_new(). */
 163    typedef struct _Elm_Map_Group_Class     Elm_Map_Group_Class; /**< Each marker must be associated to a group class. It's required to add a mark. The group class defines the style of the marker when a marker is grouped to other markers. Markers with the same group are grouped if they are close. A new group class can be created with elm_map_marker_group_class_new(). */
 164    typedef struct _Elm_Map_Route           Elm_Map_Route; /**< A route to be shown in the map. Can be created with elm_map_route_add() and deleted with elm_map_route_remove(). */
 165    typedef struct _Elm_Map_Name            Elm_Map_Name; /**< A handle for specific coordinates. */
 166    typedef struct _Elm_Map_Track           Elm_Map_Track;
 167
 168    typedef Evas_Object *(*ElmMapMarkerGetFunc)      (Evas_Object *obj, Elm_Map_Marker *marker, void *data); /**< Bubble content fetching class function for marker classes. When the user click on a marker, a bubble is displayed with a content. */
 169    typedef void         (*ElmMapMarkerDelFunc)      (Evas_Object *obj, Elm_Map_Marker *marker, void *data, Evas_Object *o); /**< Function to delete bubble content for marker classes. */
 170    typedef Evas_Object *(*ElmMapMarkerIconGetFunc)  (Evas_Object *obj, Elm_Map_Marker *marker, void *data); /**< Icon fetching class function for marker classes. */
 171    typedef Evas_Object *(*ElmMapGroupIconGetFunc)   (Evas_Object *obj, void *data); /**< Icon fetching class function for markers group classes. */
 172
 173    typedef char        *(*ElmMapModuleSourceFunc) (void);
 174    typedef int          (*ElmMapModuleZoomMinFunc) (void);
 175    typedef int          (*ElmMapModuleZoomMaxFunc) (void);
 176    typedef char        *(*ElmMapModuleUrlFunc) (Evas_Object *obj, int x, int y, int zoom);
 177    typedef int          (*ElmMapModuleRouteSourceFunc) (void);
 178    typedef char        *(*ElmMapModuleRouteUrlFunc) (Evas_Object *obj, char *type_name, int method, double flon, double flat, double tlon, double tlat);
 179    typedef char        *(*ElmMapModuleNameUrlFunc) (Evas_Object *obj, int method, char *name, double lon, double lat);
 180    typedef Eina_Bool    (*ElmMapModuleGeoIntoCoordFunc) (const Evas_Object *obj, int zoom, double lon, double lat, int size, int *x, int *y);
 181    typedef Eina_Bool    (*ElmMapModuleCoordIntoGeoFunc) (const Evas_Object *obj, int zoom, int x, int y, int size, double *lon, double *lat);
 182
 183    /**
 184     * Add a new map widget to the given parent Elementary (container) object.
 185     *
 186     * @param parent The parent object.
 187     * @return a new map widget handle or @c NULL, on errors.
 188     *
 189     * This function inserts a new map widget on the canvas.
 190     *
 191     * @ingroup Map
 192     */
 193    EAPI Evas_Object          *elm_map_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
 194
 195    /**
 196     * Set the zoom level of the map.
 197     *
 198     * @param obj The map object.
 199     * @param zoom The zoom level to set.
 200     *
 201     * This sets the zoom level.
 202     *
 203     * It will respect limits defined by elm_map_source_zoom_min_set() and
 204     * elm_map_source_zoom_max_set().
 205     *
 206     * By default these values are 0 (world map) and 18 (maximum zoom).
 207     *
 208     * This function should be used when zoom mode is set to
 209     * #ELM_MAP_ZOOM_MODE_MANUAL. This is the default mode, and can be set
 210     * with elm_map_zoom_mode_set().
 211     *
 212     * @see elm_map_zoom_mode_set().
 213     * @see elm_map_zoom_get().
 214     *
 215     * @ingroup Map
 216     */
 217    EAPI void                  elm_map_zoom_set(Evas_Object *obj, int zoom) EINA_ARG_NONNULL(1);
 218
 219    /**
 220     * Get the zoom level of the map.
 221     *
 222     * @param obj The map object.
 223     * @return The current zoom level.
 224     *
 225     * This returns the current zoom level of the map object.
 226     *
 227     * Note that if you set the fill mode to other than #ELM_MAP_ZOOM_MODE_MANUAL
 228     * (which is the default), the zoom level may be changed at any time by the
 229     * map object itself to account for map size and map viewport size.
 230     *
 231     * @see elm_map_zoom_set() for details.
 232     *
 233     * @ingroup Map
 234     */
 235    EAPI int                   elm_map_zoom_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 236
 237    /**
 238     * Set the zoom mode used by the map object.
 239     *
 240     * @param obj The map object.
 241     * @param mode The zoom mode of the map, being it one of
 242     * #ELM_MAP_ZOOM_MODE_MANUAL (default), #ELM_MAP_ZOOM_MODE_AUTO_FIT,
 243     * or #ELM_MAP_ZOOM_MODE_AUTO_FILL.
 244     *
 245     * This sets the zoom mode to manual or one of the automatic levels.
 246     * Manual (#ELM_MAP_ZOOM_MODE_MANUAL) means that zoom is set manually by
 247     * elm_map_zoom_set() and will stay at that level until changed by code
 248     * or until zoom mode is changed. This is the default mode.
 249     *
 250     * The Automatic modes will allow the map object to automatically
 251     * adjust zoom mode based on properties. #ELM_MAP_ZOOM_MODE_AUTO_FIT will
 252     * adjust zoom so the map fits inside the scroll frame with no pixels
 253     * outside this area. #ELM_MAP_ZOOM_MODE_AUTO_FILL will be similar but
 254     * ensure no pixels within the frame are left unfilled. Do not forget that
 255     * the valid sizes are 2^zoom, consequently the map may be smaller than
 256     * the scroller view.
 257     *
 258     * @see elm_map_zoom_set()
 259     *
 260     * @ingroup Map
 261     */
 262    EAPI void                  elm_map_zoom_mode_set(Evas_Object *obj, Elm_Map_Zoom_Mode mode) EINA_ARG_NONNULL(1);
 263
 264    /**
 265     * Get the zoom mode used by the map object.
 266     *
 267     * @param obj The map object.
 268     * @return The zoom mode of the map, being it one of
 269     * #ELM_MAP_ZOOM_MODE_MANUAL (default), #ELM_MAP_ZOOM_MODE_AUTO_FIT,
 270     * or #ELM_MAP_ZOOM_MODE_AUTO_FILL.
 271     *
 272     * This function returns the current zoom mode used by the map object.
 273     *
 274     * @see elm_map_zoom_mode_set() for more details.
 275     *
 276     * @ingroup Map
 277     */
 278    EAPI Elm_Map_Zoom_Mode     elm_map_zoom_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 279
 280    /**
 281     * Get the current coordinates of the map.
 282     *
 283     * @param obj The map object.
 284     * @param lon Pointer where to store longitude.
 285     * @param lat Pointer where to store latitude.
 286     *
 287     * This gets the current center coordinates of the map object. It can be
 288     * set by elm_map_geo_region_bring_in() and elm_map_geo_region_show().
 289     *
 290     * @see elm_map_geo_region_bring_in()
 291     * @see elm_map_geo_region_show()
 292     *
 293     * @ingroup Map
 294     */
 295    EAPI void                  elm_map_geo_region_get(const Evas_Object *obj, double *lon, double *lat) EINA_ARG_NONNULL(1);
 296
 297    /**
 298     * Animatedly bring in given coordinates to the center of the map.
 299     *
 300     * @param obj The map object.
 301     * @param lon Longitude to center at.
 302     * @param lat Latitude to center at.
 303     *
 304     * This causes map to jump to the given @p lat and @p lon coordinates
 305     * and show it (by scrolling) in the center of the viewport, if it is not
 306     * already centered. This will use animation to do so and take a period
 307     * of time to complete.
 308     *
 309     * @see elm_map_geo_region_show() for a function to avoid animation.
 310     * @see elm_map_geo_region_get()
 311     *
 312     * @ingroup Map
 313     */
 314    EAPI void                  elm_map_geo_region_bring_in(Evas_Object *obj, double lon, double lat) EINA_ARG_NONNULL(1);
 315
 316    /**
 317     * Show the given coordinates at the center of the map, @b immediately.
 318     *
 319     * @param obj The map object.
 320     * @param lon Longitude to center at.
 321     * @param lat Latitude to center at.
 322     *
 323     * This causes map to @b redraw its viewport's contents to the
 324     * region contining the given @p lat and @p lon, that will be moved to the
 325     * center of the map.
 326     *
 327     * @see elm_map_geo_region_bring_in() for a function to move with animation.
 328     * @see elm_map_geo_region_get()
 329     *
 330     * @ingroup Map
 331     */
 332    EAPI void                  elm_map_geo_region_show(Evas_Object *obj, double lon, double lat) EINA_ARG_NONNULL(1);
 333
 334    /**
 335     * Pause or unpause the map.
 336     *
 337     * @param obj The map object.
 338     * @param paused Use @c EINA_TRUE to pause the map @p obj or @c EINA_FALSE
 339     * to unpause it.
 340     *
 341     * This sets the paused state to on (@c EINA_TRUE) or off (@c EINA_FALSE)
 342     * for map.
 343     *
 344     * The default is off.
 345     *
 346     * This will stop zooming using animation, changing zoom levels will
 347     * change instantly. This will stop any existing animations that are running.
 348     *
 349     * @see elm_map_paused_get()
 350     *
 351     * @ingroup Map
 352     */
 353    EAPI void                  elm_map_paused_set(Evas_Object *obj, Eina_Bool paused) EINA_ARG_NONNULL(1);
 354
 355    /**
 356     * Get a value whether map is paused or not.
 357     *
 358     * @param obj The map object.
 359     * @return @c EINA_TRUE means map is pause. @c EINA_FALSE indicates
 360     * it is not. If @p obj is @c NULL, @c EINA_FALSE is returned.
 361     *
 362     * This gets the current paused state for the map object.
 363     *
 364     * @see elm_map_paused_set() for details.
 365     *
 366     * @ingroup Map
 367     */
 368    EAPI Eina_Bool             elm_map_paused_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 369
 370    /**
 371     * Set to show markers during zoom level changes or not.
 372     *
 373     * @param obj The map object.
 374     * @param paused Use @c EINA_TRUE to @b not show markers or @c EINA_FALSE
 375     * to show them.
 376     *
 377     * This sets the paused state to on (@c EINA_TRUE) or off (@c EINA_FALSE)
 378     * for map.
 379     *
 380     * The default is off.
 381     *
 382     * This will stop zooming using animation, changing zoom levels will
 383     * change instantly. This will stop any existing animations that are running.
 384     *
 385     * This sets the paused state to on (@c EINA_TRUE) or off (@c EINA_FALSE)
 386     * for the markers.
 387     *
 388     * The default  is off.
 389     *
 390     * Enabling it will force the map to stop displaying the markers during
 391     * zoom level changes. Set to on if you have a large number of markers.
 392     *
 393     * @see elm_map_paused_markers_get()
 394     *
 395     * @ingroup Map
 396     */
 397    EAPI void                  elm_map_paused_markers_set(Evas_Object *obj, Eina_Bool paused) EINA_ARG_NONNULL(1);
 398
 399    /**
 400     * Get a value whether markers will be displayed on zoom level changes or not
 401     *
 402     * @param obj The map object.
 403     * @return @c EINA_TRUE means map @b won't display markers or @c EINA_FALSE
 404     * indicates it will. If @p obj is @c NULL, @c EINA_FALSE is returned.
 405     *
 406     * This gets the current markers paused state for the map object.
 407     *
 408     * @see elm_map_paused_markers_set() for details.
 409     *
 410     * @ingroup Map
 411     */
 412    EAPI Eina_Bool             elm_map_paused_markers_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 413
 414    /**
 415     * Get the information of downloading status.
 416     *
 417     * @param obj The map object.
 418     * @param try_num Pointer where to store number of tiles being downloaded.
 419     * @param finish_num Pointer where to store number of tiles successfully
 420     * downloaded.
 421     *
 422     * This gets the current downloading status for the map object, the number
 423     * of tiles being downloaded and the number of tiles already downloaded.
 424     *
 425     * @ingroup Map
 426     */
 427    EAPI void                  elm_map_utils_downloading_status_get(const Evas_Object *obj, int *try_num, int *finish_num) EINA_ARG_NONNULL(1, 2, 3);
 428
 429    /**
 430     * Convert a pixel coordinate (x,y) into a geographic coordinate
 431     * (longitude, latitude).
 432     *
 433     * @param obj The map object.
 434     * @param x the coordinate.
 435     * @param y the coordinate.
 436     * @param size the size in pixels of the map.
 437     * The map is a square and generally his size is : pow(2.0, zoom)*256.
 438     * @param lon Pointer where to store the longitude that correspond to x.
 439     * @param lat Pointer where to store the latitude that correspond to y.
 440     *
 441     * @note Origin pixel point is the top left corner of the viewport.
 442     * Map zoom and size are taken on account.
 443     *
 444     * @see elm_map_utils_convert_geo_into_coord() if you need the inverse.
 445     *
 446     * @ingroup Map
 447     */
 448    EAPI void                  elm_map_utils_convert_coord_into_geo(const Evas_Object *obj, int x, int y, int size, double *lon, double *lat) EINA_ARG_NONNULL(1, 5, 6);
 449
 450    /**
 451     * Convert a geographic coordinate (longitude, latitude) into a pixel
 452     * coordinate (x, y).
 453     *
 454     * @param obj The map object.
 455     * @param lon the longitude.
 456     * @param lat the latitude.
 457     * @param size the size in pixels of the map. The map is a square
 458     * and generally his size is : pow(2.0, zoom)*256.
 459     * @param x Pointer where to store the horizontal pixel coordinate that
 460     * correspond to the longitude.
 461     * @param y Pointer where to store the vertical pixel coordinate that
 462     * correspond to the latitude.
 463     *
 464     * @note Origin pixel point is the top left corner of the viewport.
 465     * Map zoom and size are taken on account.
 466     *
 467     * @see elm_map_utils_convert_coord_into_geo() if you need the inverse.
 468     *
 469     * @ingroup Map
 470     */
 471    EAPI void                  elm_map_utils_convert_geo_into_coord(const Evas_Object *obj, double lon, double lat, int size, int *x, int *y) EINA_ARG_NONNULL(1, 5, 6);
 472
 473    /**
 474     * Convert a geographic coordinate (longitude, latitude) into a name
 475     * (address).
 476     *
 477     * @param obj The map object.
 478     * @param lon the longitude.
 479     * @param lat the latitude.
 480     * @return name A #Elm_Map_Name handle for this coordinate.
 481     *
 482     * To get the string for this address, elm_map_name_address_get()
 483     * should be used.
 484     *
 485     * @see elm_map_utils_convert_name_into_coord() if you need the inverse.
 486     *
 487     * @ingroup Map
 488     */
 489    EAPI Elm_Map_Name         *elm_map_utils_convert_coord_into_name(const Evas_Object *obj, double lon, double lat) EINA_ARG_NONNULL(1);
 490
 491    /**
 492     * Convert a name (address) into a geographic coordinate
 493     * (longitude, latitude).
 494     *
 495     * @param obj The map object.
 496     * @param name The address.
 497     * @return name A #Elm_Map_Name handle for this address.
 498     *
 499     * To get the longitude and latitude, elm_map_name_region_get()
 500     * should be used.
 501     *
 502     * @see elm_map_utils_convert_coord_into_name() if you need the inverse.
 503     *
 504     * @ingroup Map
 505     */
 506    EAPI Elm_Map_Name         *elm_map_utils_convert_name_into_coord(const Evas_Object *obj, char *address) EINA_ARG_NONNULL(1, 2);
 507
 508    /**
 509     * Convert a pixel coordinate into a rotated pixel coordinate.
 510     *
 511     * @param obj The map object.
 512     * @param x horizontal coordinate of the point to rotate.
 513     * @param y vertical coordinate of the point to rotate.
 514     * @param cx rotation's center horizontal position.
 515     * @param cy rotation's center vertical position.
 516     * @param degree amount of degrees from 0.0 to 360.0 to rotate arount Z axis.
 517     * @param xx Pointer where to store rotated x.
 518     * @param yy Pointer where to store rotated y.
 519     *
 520     * @ingroup Map
 521     */
 522    EAPI void                  elm_map_utils_rotate_coord(const Evas_Object *obj, const Evas_Coord x, const Evas_Coord y, const Evas_Coord cx, const Evas_Coord cy, const double degree, Evas_Coord *xx, Evas_Coord *yy) EINA_ARG_NONNULL(1);
 523
 524    /**
 525     * Add a new marker to the map object.
 526     *
 527     * @param obj The map object.
 528     * @param lon The longitude of the marker.
 529     * @param lat The latitude of the marker.
 530     * @param clas The class, to use when marker @b isn't grouped to others.
 531     * @param clas_group The class group, to use when marker is grouped to others
 532     * @param data The data passed to the callbacks.
 533     *
 534     * @return The created marker or @c NULL upon failure.
 535     *
 536     * A marker will be created and shown in a specific point of the map, defined
 537     * by @p lon and @p lat.
 538     *
 539     * It will be displayed using style defined by @p class when this marker
 540     * is displayed alone (not grouped). A new class can be created with
 541     * elm_map_marker_class_new().
 542     *
 543     * If the marker is grouped to other markers, it will be displayed with
 544     * style defined by @p class_group. Markers with the same group are grouped
 545     * if they are close. A new group class can be created with
 546     * elm_map_marker_group_class_new().
 547     *
 548     * Markers created with this method can be deleted with
 549     * elm_map_marker_remove().
 550     *
 551     * A marker can have associated content to be displayed by a bubble,
 552     * when a user click over it, as well as an icon. These objects will
 553     * be fetch using class' callback functions.
 554     *
 555     * @see elm_map_marker_class_new()
 556     * @see elm_map_marker_group_class_new()
 557     * @see elm_map_marker_remove()
 558     *
 559     * @ingroup Map
 560     */
 561    EAPI Elm_Map_Marker       *elm_map_marker_add(Evas_Object *obj, double lon, double lat, Elm_Map_Marker_Class *clas, Elm_Map_Group_Class *clas_group, void *data) EINA_ARG_NONNULL(1, 4, 5);
 562
 563    /**
 564     * Set the maximum numbers of markers' content to be displayed in a group.
 565     *
 566     * @param obj The map object.
 567     * @param max The maximum numbers of items displayed in a bubble.
 568     *
 569     * A bubble will be displayed when the user clicks over the group,
 570     * and will place the content of markers that belong to this group
 571     * inside it.
 572     *
 573     * A group can have a long list of markers, consequently the creation
 574     * of the content of the bubble can be very slow.
 575     *
 576     * In order to avoid this, a maximum number of items is displayed
 577     * in a bubble.
 578     *
 579     * By default this number is 30.
 580     *
 581     * Marker with the same group class are grouped if they are close.
 582     *
 583     * @see elm_map_marker_add()
 584     *
 585     * @ingroup Map
 586     */
 587    EAPI void                  elm_map_max_marker_per_group_set(Evas_Object *obj, int max) EINA_ARG_NONNULL(1);
 588
 589    /**
 590     * Remove a marker from the map.
 591     *
 592     * @param marker The marker to remove.
 593     *
 594     * @see elm_map_marker_add()
 595     *
 596     * @ingroup Map
 597     */
 598    EAPI void                  elm_map_marker_remove(Elm_Map_Marker *marker) EINA_ARG_NONNULL(1);
 599
 600    /**
 601     * Get the current coordinates of the marker.
 602     *
 603     * @param marker marker.
 604     * @param lat Pointer where to store the marker's latitude.
 605     * @param lon Pointer where to store the marker's longitude.
 606     *
 607     * These values are set when adding markers, with function
 608     * elm_map_marker_add().
 609     *
 610     * @see elm_map_marker_add()
 611     *
 612     * @ingroup Map
 613     */
 614    EAPI void                  elm_map_marker_region_get(const Elm_Map_Marker *marker, double *lon, double *lat) EINA_ARG_NONNULL(1);
 615
 616    /**
 617     * Animatedly bring in given marker to the center of the map.
 618     *
 619     * @param marker The marker to center at.
 620     *
 621     * This causes map to jump to the given @p marker's coordinates
 622     * and show it (by scrolling) in the center of the viewport, if it is not
 623     * already centered. This will use animation to do so and take a period
 624     * of time to complete.
 625     *
 626     * @see elm_map_marker_show() for a function to avoid animation.
 627     * @see elm_map_marker_region_get()
 628     *
 629     * @ingroup Map
 630     */
 631    EAPI void                  elm_map_marker_bring_in(Elm_Map_Marker *marker) EINA_ARG_NONNULL(1);
 632
 633    /**
 634     * Show the given marker at the center of the map, @b immediately.
 635     *
 636     * @param marker The marker to center at.
 637     *
 638     * This causes map to @b redraw its viewport's contents to the
 639     * region contining the given @p marker's coordinates, that will be
 640     * moved to the center of the map.
 641     *
 642     * @see elm_map_marker_bring_in() for a function to move with animation.
 643     * @see elm_map_markers_list_show() if more than one marker need to be
 644     * displayed.
 645     * @see elm_map_marker_region_get()
 646     *
 647     * @ingroup Map
 648     */
 649    EAPI void                  elm_map_marker_show(Elm_Map_Marker *marker) EINA_ARG_NONNULL(1);
 650
 651    /**
 652     * Move and zoom the map to display a list of markers.
 653     *
 654     * @param markers A list of #Elm_Map_Marker handles.
 655     *
 656     * The map will be centered on the center point of the markers in the list.
 657     * Then the map will be zoomed in order to fit the markers using the maximum
 658     * zoom which allows display of all the markers.
 659     *
 660     * @warning All the markers should belong to the same map object.
 661     *
 662     * @see elm_map_marker_show() to show a single marker.
 663     * @see elm_map_marker_bring_in()
 664     *
 665     * @ingroup Map
 666     */
 667    EAPI void                  elm_map_markers_list_show(Eina_List *markers) EINA_ARG_NONNULL(1);
 668
 669    /**
 670     * Get the Evas object returned by the ElmMapMarkerGetFunc callback
 671     *
 672     * @param marker The marker wich content should be returned.
 673     * @return Return the evas object if it exists, else @c NULL.
 674     *
 675     * To set callback function #ElmMapMarkerGetFunc for the marker class,
 676     * elm_map_marker_class_get_cb_set() should be used.
 677     *
 678     * This content is what will be inside the bubble that will be displayed
 679     * when an user clicks over the marker.
 680     *
 681     * This returns the actual Evas object used to be placed inside
 682     * the bubble. This may be @c NULL, as it may
 683     * not have been created or may have been deleted, at any time, by
 684     * the map. <b>Do not modify this object</b> (move, resize,
 685     * show, hide, etc.), as the map is controlling it. This
 686     * function is for querying, emitting custom signals or hooking
 687     * lower level callbacks for events on that object. Do not delete
 688     * this object under any circumstances.
 689     *
 690     * @ingroup Map
 691     */
 692    EAPI Evas_Object          *elm_map_marker_object_get(const Elm_Map_Marker *marker) EINA_ARG_NONNULL(1);
 693
 694    /**
 695     * Update the marker
 696     *
 697     * @param marker The marker to be updated.
 698     *
 699     * If a content is set to this marker, it will call function to delete it,
 700     * #ElmMapMarkerDelFunc, and then will fetch the content again with
 701     * #ElmMapMarkerGetFunc.
 702     *
 703     * These functions are set for the marker class with
 704     * elm_map_marker_class_get_cb_set() and elm_map_marker_class_del_cb_set().
 705     *
 706     * @ingroup Map
 707     */
 708    EAPI void                  elm_map_marker_update(Elm_Map_Marker *marker) EINA_ARG_NONNULL(1);
 709
 710    /**
 711     * Close all the bubbles opened by the user.
 712     *
 713     * @param obj The map object.
 714     *
 715     * A bubble is displayed with a content fetched with #ElmMapMarkerGetFunc
 716     * when the user clicks on a marker.
 717     *
 718     * This functions is set for the marker class with
 719     * elm_map_marker_class_get_cb_set().
 720     *
 721     * @ingroup Map
 722     */
 723    EAPI void                  elm_map_bubbles_close(Evas_Object *obj) EINA_ARG_NONNULL(1);
 724
 725    /**
 726     * Create a new group class.
 727     *
 728     * @param obj The map object.
 729     * @return Returns the new group class.
 730     *
 731     * Each marker must be associated to a group class. Markers in the same
 732     * group are grouped if they are close.
 733     *
 734     * The group class defines the style of the marker when a marker is grouped
 735     * to others markers. When it is alone, another class will be used.
 736     *
 737     * A group class will need to be provided when creating a marker with
 738     * elm_map_marker_add().
 739     *
 740     * Some properties and functions can be set by class, as:
 741     * - style, with elm_map_group_class_style_set()
 742     * - data - to be associated to the group class. It can be set using
 743     *   elm_map_group_class_data_set().
 744     * - min zoom to display markers, set with
 745     *   elm_map_group_class_zoom_displayed_set().
 746     * - max zoom to group markers, set using
 747     *   elm_map_group_class_zoom_grouped_set().
 748     * - visibility - set if markers will be visible or not, set with
 749     *   elm_map_group_class_hide_set().
 750     * - #ElmMapGroupIconGetFunc - used to fetch icon for markers group classes.
 751     *   It can be set using elm_map_group_class_icon_cb_set().
 752     *
 753     * @see elm_map_marker_add()
 754     * @see elm_map_group_class_style_set()
 755     * @see elm_map_group_class_data_set()
 756     * @see elm_map_group_class_zoom_displayed_set()
 757     * @see elm_map_group_class_zoom_grouped_set()
 758     * @see elm_map_group_class_hide_set()
 759     * @see elm_map_group_class_icon_cb_set()
 760     *
 761     * @ingroup Map
 762     */
 763    EAPI Elm_Map_Group_Class  *elm_map_group_class_new(Evas_Object *obj) EINA_ARG_NONNULL(1);
 764
 765    /**
 766     * Set the marker's style of a group class.
 767     *
 768     * @param clas The group class.
 769     * @param style The style to be used by markers.
 770     *
 771     * Each marker must be associated to a group class, and will use the style
 772     * defined by such class when grouped to other markers.
 773     *
 774     * The following styles are provided by default theme:
 775     * @li @c radio - blue circle
 776     * @li @c radio2 - green circle
 777     * @li @c empty
 778     *
 779     * @see elm_map_group_class_new() for more details.
 780     * @see elm_map_marker_add()
 781     *
 782     * @ingroup Map
 783     */
 784    EAPI void                  elm_map_group_class_style_set(Elm_Map_Group_Class *clas, const char *style) EINA_ARG_NONNULL(1);
 785
 786    /**
 787     * Set the icon callback function of a group class.
 788     *
 789     * @param clas The group class.
 790     * @param icon_get The callback function that will return the icon.
 791     *
 792     * Each marker must be associated to a group class, and it can display a
 793     * custom icon. The function @p icon_get must return this icon.
 794     *
 795     * @see elm_map_group_class_new() for more details.
 796     * @see elm_map_marker_add()
 797     *
 798     * @ingroup Map
 799     */
 800    EAPI void                  elm_map_group_class_icon_cb_set(Elm_Map_Group_Class *clas, ElmMapGroupIconGetFunc icon_get) EINA_ARG_NONNULL(1);
 801
 802    /**
 803     * Set the data associated to the group class.
 804     *
 805     * @param clas The group class.
 806     * @param data The new user data.
 807     *
 808     * This data will be passed for callback functions, like icon get callback,
 809     * that can be set with elm_map_group_class_icon_cb_set().
 810     *
 811     * If a data was previously set, the object will lose the pointer for it,
 812     * so if needs to be freed, you must do it yourself.
 813     *
 814     * @see elm_map_group_class_new() for more details.
 815     * @see elm_map_group_class_icon_cb_set()
 816     * @see elm_map_marker_add()
 817     *
 818     * @ingroup Map
 819     */
 820    EAPI void                  elm_map_group_class_data_set(Elm_Map_Group_Class *clas, void *data) EINA_ARG_NONNULL(1);
 821
 822    /**
 823     * Set the minimum zoom from where the markers are displayed.
 824     *
 825     * @param clas The group class.
 826     * @param zoom The minimum zoom.
 827     *
 828     * Markers only will be displayed when the map is displayed at @p zoom
 829     * or bigger.
 830     *
 831     * @see elm_map_group_class_new() for more details.
 832     * @see elm_map_marker_add()
 833     *
 834     * @ingroup Map
 835     */
 836    EAPI void                  elm_map_group_class_zoom_displayed_set(Elm_Map_Group_Class *clas, int zoom) EINA_ARG_NONNULL(1);
 837
 838    /**
 839     * Set the zoom from where the markers are no more grouped.
 840     *
 841     * @param clas The group class.
 842     * @param zoom The maximum zoom.
 843     *
 844     * Markers only will be grouped when the map is displayed at
 845     * less than @p zoom.
 846     *
 847     * @see elm_map_group_class_new() for more details.
 848     * @see elm_map_marker_add()
 849     *
 850     * @ingroup Map
 851     */
 852    EAPI void                  elm_map_group_class_zoom_grouped_set(Elm_Map_Group_Class *clas, int zoom) EINA_ARG_NONNULL(1);
 853
 854    /**
 855     * Set if the markers associated to the group class @clas are hidden or not.
 856     *
 857     * @param clas The group class.
 858     * @param hide Use @c EINA_TRUE to hide markers or @c EINA_FALSE
 859     * to show them.
 860     *
 861     * If @p hide is @c EINA_TRUE the markers will be hidden, but default
 862     * is to show them.
 863     *
 864     * @ingroup Map
 865     */
 866    EAPI void                  elm_map_group_class_hide_set(Evas_Object *obj, Elm_Map_Group_Class *clas, Eina_Bool hide) EINA_ARG_NONNULL(1, 2);
 867
 868    /**
 869     * Create a new marker class.
 870     *
 871     * @param obj The map object.
 872     * @return Returns the new group class.
 873     *
 874     * Each marker must be associated to a class.
 875     *
 876     * The marker class defines the style of the marker when a marker is
 877     * displayed alone, i.e., not grouped to to others markers. When grouped
 878     * it will use group class style.
 879     *
 880     * A marker class will need to be provided when creating a marker with
 881     * elm_map_marker_add().
 882     *
 883     * Some properties and functions can be set by class, as:
 884     * - style, with elm_map_marker_class_style_set()
 885     * - #ElmMapMarkerIconGetFunc - used to fetch icon for markers classes.
 886     *   It can be set using elm_map_marker_class_icon_cb_set().
 887     * - #ElmMapMarkerGetFunc - used to fetch bubble content for marker classes.
 888     *   Set using elm_map_marker_class_get_cb_set().
 889     * - #ElmMapMarkerDelFunc - used to delete bubble content for marker classes.
 890     *   Set using elm_map_marker_class_del_cb_set().
 891     *
 892     * @see elm_map_marker_add()
 893     * @see elm_map_marker_class_style_set()
 894     * @see elm_map_marker_class_icon_cb_set()
 895     * @see elm_map_marker_class_get_cb_set()
 896     * @see elm_map_marker_class_del_cb_set()
 897     *
 898     * @ingroup Map
 899     */
 900    EAPI Elm_Map_Marker_Class *elm_map_marker_class_new(Evas_Object *obj) EINA_ARG_NONNULL(1);
 901
 902    /**
 903     * Set the marker's style of a marker class.
 904     *
 905     * @param clas The marker class.
 906     * @param style The style to be used by markers.
 907     *
 908     * Each marker must be associated to a marker class, and will use the style
 909     * defined by such class when alone, i.e., @b not grouped to other markers.
 910     *
 911     * The following styles are provided by default theme:
 912     * @li @c radio
 913     * @li @c radio2
 914     * @li @c empty
 915     *
 916     * @see elm_map_marker_class_new() for more details.
 917     * @see elm_map_marker_add()
 918     *
 919     * @ingroup Map
 920     */
 921    EAPI void                  elm_map_marker_class_style_set(Elm_Map_Marker_Class *clas, const char *style) EINA_ARG_NONNULL(1);
 922
 923    /**
 924     * Set the icon callback function of a marker class.
 925     *
 926     * @param clas The marker class.
 927     * @param icon_get The callback function that will return the icon.
 928     *
 929     * Each marker must be associated to a marker class, and it can display a
 930     * custom icon. The function @p icon_get must return this icon.
 931     *
 932     * @see elm_map_marker_class_new() for more details.
 933     * @see elm_map_marker_add()
 934     *
 935     * @ingroup Map
 936     */
 937    EAPI void                  elm_map_marker_class_icon_cb_set(Elm_Map_Marker_Class *clas, ElmMapMarkerIconGetFunc icon_get) EINA_ARG_NONNULL(1);
 938
 939    /**
 940     * Set the bubble content callback function of a marker class.
 941     *
 942     * @param clas The marker class.
 943     * @param get The callback function that will return the content.
 944     *
 945     * Each marker must be associated to a marker class, and it can display a
 946     * a content on a bubble that opens when the user click over the marker.
 947     * The function @p get must return this content object.
 948     *
 949     * If this content will need to be deleted, elm_map_marker_class_del_cb_set()
 950     * can be used.
 951     *
 952     * @see elm_map_marker_class_new() for more details.
 953     * @see elm_map_marker_class_del_cb_set()
 954     * @see elm_map_marker_add()
 955     *
 956     * @ingroup Map
 957     */
 958    EAPI void                  elm_map_marker_class_get_cb_set(Elm_Map_Marker_Class *clas, ElmMapMarkerGetFunc get) EINA_ARG_NONNULL(1);
 959
 960    /**
 961     * Set the callback function used to delete bubble content of a marker class.
 962     *
 963     * @param clas The marker class.
 964     * @param del The callback function that will delete the content.
 965     *
 966     * Each marker must be associated to a marker class, and it can display a
 967     * a content on a bubble that opens when the user click over the marker.
 968     * The function to return such content can be set with
 969     * elm_map_marker_class_get_cb_set().
 970     *
 971     * If this content must be freed, a callback function need to be
 972     * set for that task with this function.
 973     *
 974     * If this callback is defined it will have to delete (or not) the
 975     * object inside, but if the callback is not defined the object will be
 976     * destroyed with evas_object_del().
 977     *
 978     * @see elm_map_marker_class_new() for more details.
 979     * @see elm_map_marker_class_get_cb_set()
 980     * @see elm_map_marker_add()
 981     *
 982     * @ingroup Map
 983     */
 984    EAPI void                  elm_map_marker_class_del_cb_set(Elm_Map_Marker_Class *clas, ElmMapMarkerDelFunc del) EINA_ARG_NONNULL(1);
 985
 986    /**
 987     * Get the list of available sources.
 988     *
 989     * @param obj The map object.
 990     * @return The source names list.
 991     *
 992     * It will provide a list with all available sources, that can be set as
 993     * current source with elm_map_source_name_set(), or get with
 994     * elm_map_source_name_get().
 995     *
 996     * Available sources:
 997     * @li "Mapnik"
 998     * @li "Osmarender"
 999     * @li "CycleMap"
1000     * @li "Maplint"
1001     *
1002     * @see elm_map_source_name_set() for more details.
1003     * @see elm_map_source_name_get()
1004     *
1005     * @ingroup Map
1006     */
1007    EAPI const char          **elm_map_source_names_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
1008
1009    /**
1010     * Set the source of the map.
1011     *
1012     * @param obj The map object.
1013     * @param source The source to be used.
1014     *
1015     * Map widget retrieves images that composes the map from a web service.
1016     * This web service can be set with this method.
1017     *
1018     * A different service can return a different maps with different
1019     * information and it can use different zoom values.
1020     *
1021     * The @p source_name need to match one of the names provided by
1022     * elm_map_source_names_get().
1023     *
1024     * The current source can be get using elm_map_source_name_get().
1025     *
1026     * @see elm_map_source_names_get()
1027     * @see elm_map_source_name_get()
1028     *
1029     *
1030     * @ingroup Map
1031     */
1032    EAPI void                  elm_map_source_name_set(Evas_Object *obj, const char *source_name) EINA_ARG_NONNULL(1);
1033
1034    /**
1035     * Get the name of currently used source.
1036     *
1037     * @param obj The map object.
1038     * @return Returns the name of the source in use.
1039     *
1040     * @see elm_map_source_name_set() for more details.
1041     *
1042     * @ingroup Map
1043     */
1044    EAPI const char           *elm_map_source_name_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
1045
1046    /**
1047     * Set the source of the route service to be used by the map.
1048     *
1049     * @param obj The map object.
1050     * @param source The route service to be used, being it one of
1051     * #ELM_MAP_ROUTE_SOURCE_YOURS (default), #ELM_MAP_ROUTE_SOURCE_MONAV,
1052     * and #ELM_MAP_ROUTE_SOURCE_ORS.
1053     *
1054     * Each one has its own algorithm, so the route retrieved may
1055     * differ depending on the source route. Now, only the default is working.
1056     *
1057     * #ELM_MAP_ROUTE_SOURCE_YOURS is the routing service provided at
1058     * http://www.yournavigation.org/.
1059     *
1060     * #ELM_MAP_ROUTE_SOURCE_MONAV, offers exact routing without heuristic
1061     * assumptions. Its routing core is based on Contraction Hierarchies.
1062     *
1063     * #ELM_MAP_ROUTE_SOURCE_ORS, is provided at http://www.openrouteservice.org/
1064     *
1065     * @see elm_map_route_source_get().
1066     *
1067     * @ingroup Map
1068     */
1069    EAPI void                  elm_map_route_source_set(Evas_Object *obj, Elm_Map_Route_Sources source) EINA_ARG_NONNULL(1);
1070
1071    /**
1072     * Get the current route source.
1073     *
1074     * @param obj The map object.
1075     * @return The source of the route service used by the map.
1076     *
1077     * @see elm_map_route_source_set() for details.
1078     *
1079     * @ingroup Map
1080     */
1081    EAPI Elm_Map_Route_Sources elm_map_route_source_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
1082
1083    /**
1084     * Set the minimum zoom of the source.
1085     *
1086     * @param obj The map object.
1087     * @param zoom New minimum zoom value to be used.
1088     *
1089     * By default, it's 0.
1090     *
1091     * @ingroup Map
1092     */
1093    EAPI void                  elm_map_source_zoom_min_set(Evas_Object *obj, int zoom) EINA_ARG_NONNULL(1);
1094
1095    /**
1096     * Get the minimum zoom of the source.
1097     *
1098     * @param obj The map object.
1099     * @return Returns the minimum zoom of the source.
1100     *
1101     * @see elm_map_source_zoom_min_set() for details.
1102     *
1103     * @ingroup Map
1104     */
1105    EAPI int                   elm_map_source_zoom_min_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
1106
1107    /**
1108     * Set the maximum zoom of the source.
1109     *
1110     * @param obj The map object.
1111     * @param zoom New maximum zoom value to be used.
1112     *
1113     * By default, it's 18.
1114     *
1115     * @ingroup Map
1116     */
1117    EAPI void                  elm_map_source_zoom_max_set(Evas_Object *obj, int zoom) EINA_ARG_NONNULL(1);
1118
1119    /**
1120     * Get the maximum zoom of the source.
1121     *
1122     * @param obj The map object.
1123     * @return Returns the maximum zoom of the source.
1124     *
1125     * @see elm_map_source_zoom_min_set() for details.
1126     *
1127     * @ingroup Map
1128     */
1129    EAPI int                   elm_map_source_zoom_max_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
1130
1131    /**
1132     * Set the user agent used by the map object to access routing services.
1133     *
1134     * @param obj The map object.
1135     * @param user_agent The user agent to be used by the map.
1136     *
1137     * User agent is a client application implementing a network protocol used
1138     * in communications within a client–server distributed computing system
1139     *
1140     * The @p user_agent identification string will transmitted in a header
1141     * field @c User-Agent.
1142     *
1143     * @see elm_map_user_agent_get()
1144     *
1145     * @ingroup Map
1146     */
1147    EAPI void                  elm_map_user_agent_set(Evas_Object *obj, const char *user_agent) EINA_ARG_NONNULL(1, 2);
1148
1149    /**
1150     * Get the user agent used by the map object.
1151     *
1152     * @param obj The map object.
1153     * @return The user agent identification string used by the map.
1154     *
1155     * @see elm_map_user_agent_set() for details.
1156     *
1157     * @ingroup Map
1158     */
1159    EAPI const char           *elm_map_user_agent_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
1160
1161    /**
1162     * Add a new route to the map object.
1163     *
1164     * @param obj The map object.
1165     * @param type The type of transport to be considered when tracing a route.
1166     * @param method The routing method, what should be priorized.
1167     * @param flon The start longitude.
1168     * @param flat The start latitude.
1169     * @param tlon The destination longitude.
1170     * @param tlat The destination latitude.
1171     *
1172     * @return The created route or @c NULL upon failure.
1173     *
1174     * A route will be traced by point on coordinates (@p flat, @p flon)
1175     * to point on coordinates (@p tlat, @p tlon), using the route service
1176     * set with elm_map_route_source_set().
1177     *
1178     * It will take @p type on consideration to define the route,
1179     * depending if the user will be walking or driving, the route may vary.
1180     * One of #ELM_MAP_ROUTE_TYPE_MOTOCAR, #ELM_MAP_ROUTE_TYPE_BICYCLE, or
1181     * #ELM_MAP_ROUTE_TYPE_FOOT need to be used.
1182     *
1183     * Another parameter is what the route should priorize, the minor distance
1184     * or the less time to be spend on the route. So @p method should be one
1185     * of #ELM_MAP_ROUTE_METHOD_SHORTEST or #ELM_MAP_ROUTE_METHOD_FASTEST.
1186     *
1187     * Routes created with this method can be deleted with
1188     * elm_map_route_remove(), colored with elm_map_route_color_set(),
1189     * and distance can be get with elm_map_route_distance_get().
1190     *
1191     * @see elm_map_route_remove()
1192     * @see elm_map_route_color_set()
1193     * @see elm_map_route_distance_get()
1194     * @see elm_map_route_source_set()
1195     *
1196     * @ingroup Map
1197     */
1198    EAPI Elm_Map_Route        *elm_map_route_add(Evas_Object *obj, Elm_Map_Route_Type type, Elm_Map_Route_Method method, double flon, double flat, double tlon, double tlat) EINA_ARG_NONNULL(1);
1199
1200    /**
1201     * Remove a route from the map.
1202     *
1203     * @param route The route to remove.
1204     *
1205     * @see elm_map_route_add()
1206     *
1207     * @ingroup Map
1208     */
1209    EAPI void                  elm_map_route_remove(Elm_Map_Route *route) EINA_ARG_NONNULL(1);
1210
1211    /**
1212     * Set the route color.
1213     *
1214     * @param route The route object.
1215     * @param r Red channel value, from 0 to 255.
1216     * @param g Green channel value, from 0 to 255.
1217     * @param b Blue channel value, from 0 to 255.
1218     * @param a Alpha channel value, from 0 to 255.
1219     *
1220     * It uses an additive color model, so each color channel represents
1221     * how much of each primary colors must to be used. 0 represents
1222     * ausence of this color, so if all of the three are set to 0,
1223     * the color will be black.
1224     *
1225     * These component values should be integers in the range 0 to 255,
1226     * (single 8-bit byte).
1227     *
1228     * This sets the color used for the route. By default, it is set to
1229     * solid red (r = 255, g = 0, b = 0, a = 255).
1230     *
1231     * For alpha channel, 0 represents completely transparent, and 255, opaque.
1232     *
1233     * @see elm_map_route_color_get()
1234     *
1235     * @ingroup Map
1236     */
1237    EAPI void                  elm_map_route_color_set(Elm_Map_Route *route, int r, int g , int b, int a) EINA_ARG_NONNULL(1);
1238
1239    /**
1240     * Get the route color.
1241     *
1242     * @param route The route object.
1243     * @param r Pointer where to store the red channel value.
1244     * @param g Pointer where to store the green channel value.
1245     * @param b Pointer where to store the blue channel value.
1246     * @param a Pointer where to store the alpha channel value.
1247     *
1248     * @see elm_map_route_color_set() for details.
1249     *
1250     * @ingroup Map
1251     */
1252    EAPI void                  elm_map_route_color_get(const Elm_Map_Route *route, int *r, int *g , int *b, int *a) EINA_ARG_NONNULL(1);
1253
1254    /**
1255     * Get the route distance in kilometers.
1256     *
1257     * @param route The route object.
1258     * @return The distance of route (unit : km).
1259     *
1260     * @ingroup Map
1261     */
1262    EAPI double                elm_map_route_distance_get(const Elm_Map_Route *route) EINA_ARG_NONNULL(1);
1263
1264    /**
1265     * Get the information of route nodes.
1266     *
1267     * @param route The route object.
1268     * @return Returns a string with the nodes of route.
1269     *
1270     * @ingroup Map
1271     */
1272    EAPI const char           *elm_map_route_node_get(const Elm_Map_Route *route) EINA_ARG_NONNULL(1);
1273
1274    /**
1275     * Get the information of route waypoint.
1276     *
1277     * @param route the route object.
1278     * @return Returns a string with information about waypoint of route.
1279     *
1280     * @ingroup Map
1281     */
1282    EAPI const char           *elm_map_route_waypoint_get(const Elm_Map_Route *route) EINA_ARG_NONNULL(1);
1283
1284    /**
1285     * Get the address of the name.
1286     *
1287     * @param name The name handle.
1288     * @return Returns the address string of @p name.
1289     *
1290     * This gets the coordinates of the @p name, created with one of the
1291     * conversion functions.
1292     *
1293     * @see elm_map_utils_convert_name_into_coord()
1294     * @see elm_map_utils_convert_coord_into_name()
1295     *
1296     * @ingroup Map
1297     */
1298    EAPI const char           *elm_map_name_address_get(const Elm_Map_Name *name) EINA_ARG_NONNULL(1);
1299
1300    /**
1301     * Get the current coordinates of the name.
1302     *
1303     * @param name The name handle.
1304     * @param lat Pointer where to store the latitude.
1305     * @param lon Pointer where to store The longitude.
1306     *
1307     * This gets the coordinates of the @p name, created with one of the
1308     * conversion functions.
1309     *
1310     * @see elm_map_utils_convert_name_into_coord()
1311     * @see elm_map_utils_convert_coord_into_name()
1312     *
1313     * @ingroup Map
1314     */
1315    EAPI void                  elm_map_name_region_get(const Elm_Map_Name *name, double *lon, double *lat) EINA_ARG_NONNULL(1);
1316
1317    /**
1318     * Remove a name from the map.
1319     *
1320     * @param name The name to remove.
1321     *
1322     * Basically the struct handled by @p name will be freed, so convertions
1323     * between address and coordinates will be lost.
1324     *
1325     * @see elm_map_utils_convert_name_into_coord()
1326     * @see elm_map_utils_convert_coord_into_name()
1327     *
1328     * @ingroup Map
1329     */
1330    EAPI void                  elm_map_name_remove(Elm_Map_Name *name) EINA_ARG_NONNULL(1);
1331
1332    /**
1333     * Rotate the map.
1334     *
1335     * @param obj The map object.
1336     * @param degree Angle from 0.0 to 360.0 to rotate arount Z axis.
1337     * @param cx Rotation's center horizontal position.
1338     * @param cy Rotation's center vertical position.
1339     *
1340     * @see elm_map_rotate_get()
1341     *
1342     * @ingroup Map
1343     */
1344    EAPI void                  elm_map_rotate_set(Evas_Object *obj, double degree, Evas_Coord cx, Evas_Coord cy) EINA_ARG_NONNULL(1);
1345
1346    /**
1347     * Get the rotate degree of the map
1348     *
1349     * @param obj The map object
1350     * @param degree Pointer where to store degrees from 0.0 to 360.0
1351     * to rotate arount Z axis.
1352     * @param cx Pointer where to store rotation's center horizontal position.
1353     * @param cy Pointer where to store rotation's center vertical position.
1354     *
1355     * @see elm_map_rotate_set() to set map rotation.
1356     *
1357     * @ingroup Map
1358     */
1359    EAPI void                  elm_map_rotate_get(const Evas_Object *obj, double *degree, Evas_Coord *cx, Evas_Coord *cy) EINA_ARG_NONNULL(1, 2, 3, 4);
1360
1361    /**
1362     * Enable or disable mouse wheel to be used to zoom in / out the map.
1363     *
1364     * @param obj The map object.
1365     * @param disabled Use @c EINA_TRUE to disable mouse wheel or @c EINA_FALSE
1366     * to enable it.
1367     *
1368     * Mouse wheel can be used for the user to zoom in or zoom out the map.
1369     *
1370     * It's disabled by default.
1371     *
1372     * @see elm_map_wheel_disabled_get()
1373     *
1374     * @ingroup Map
1375     */
1376    EAPI void                  elm_map_wheel_disabled_set(Evas_Object *obj, Eina_Bool disabled) EINA_ARG_NONNULL(1);
1377
1378    /**
1379     * Get a value whether mouse wheel is enabled or not.
1380     *
1381     * @param obj The map object.
1382     * @return @c EINA_TRUE means map is disabled. @c EINA_FALSE indicates
1383     * it is enabled. If @p obj is @c NULL, @c EINA_FALSE is returned.
1384     *
1385     * Mouse wheel can be used for the user to zoom in or zoom out the map.
1386     *
1387     * @see elm_map_wheel_disabled_set() for details.
1388     *
1389     * @ingroup Map
1390     */
1391    EAPI Eina_Bool             elm_map_wheel_disabled_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
1392
1393 #ifdef ELM_EMAP
1394    /**
1395     * Add a track on the map
1396     *
1397     * @param obj The map object.
1398     * @param emap The emap route object.
1399     * @return The route object. This is an elm object of type Route.
1400     *
1401     * @see elm_route_add() for details.
1402     *
1403     * @ingroup Map
1404     */
1405    EAPI Evas_Object          *elm_map_track_add(Evas_Object *obj, EMap_Route *emap) EINA_ARG_NONNULL(1);
1406 #endif
1407
1408    /**
1409     * Remove a track from the map
1410     *
1411     * @param obj The map object.
1412     * @param route The track to remove.
1413     *
1414     * @ingroup Map
1415     */
1416    EAPI void                  elm_map_track_remove(Evas_Object *obj, Evas_Object *route) EINA_ARG_NONNULL(1);
1417
1418    /**
1419     * @}
1420     */