src/lib/elm_map.h

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