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