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