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