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