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