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