5 * @image html img/widget/map/preview-00.png
6 * @image latex img/widget/map/preview-00.eps
8 * This is a widget specifically for displaying a map. It uses basically
9 * OpenStreetMap provider http://www.openstreetmap.org/,
10 * but custom providers can be added.
12 * It supports some basic but yet nice features:
14 * @li markers with content to be displayed when user clicks over it
15 * @li group of markers
18 * Smart callbacks one can listen to:
20 * - "clicked" - This is called when a user has clicked the map without
22 * - "press" - This is called when a user has pressed down on the map.
23 * - "longpressed" - This is called when a user has pressed down on the map
24 * for a long time without dragging around.
25 * - "clicked,double" - This is called when a user has double-clicked
27 * - "load,detail" - Map detailed data load begins.
28 * - "loaded,detail" - This is called when all currently visible parts of
30 * - "zoom,start" - Zoom animation started.
31 * - "zoom,stop" - Zoom animation stopped.
32 * - "zoom,change" - Zoom changed when using an auto zoom mode.
33 * - "scroll" - the content has been scrolled (moved).
34 * - "scroll,anim,start" - scrolling animation has started.
35 * - "scroll,anim,stop" - scrolling animation has stopped.
36 * - "scroll,drag,start" - dragging the contents around has started.
37 * - "scroll,drag,stop" - dragging the contents around has stopped.
38 * - "downloaded" - This is called when all currently required map images
40 * - "route,load" - This is called when route request begins.
41 * - "route,loaded" - This is called when route request ends.
42 * - "name,load" - This is called when name request begins.
43 * - "name,loaded- This is called when name request ends.
45 * Available style for map widget:
48 * Available style for markers:
53 * Available style for marker bubble:
57 * @li @ref map_example_01
58 * @li @ref map_example_02
59 * @li @ref map_example_03
68 * Set map's zoom behavior. It can be set to manual or automatic.
70 * Default value is #ELM_MAP_ZOOM_MODE_MANUAL.
72 * Values <b> don't </b> work as bitmask, only one can be chosen.
74 * @note Valid sizes are 2^zoom, consequently the map may be smaller
75 * than the scroller view.
77 * @see elm_map_zoom_mode_set()
78 * @see elm_map_zoom_mode_get()
84 ELM_MAP_ZOOM_MODE_MANUAL, /**< Zoom controlled manually by elm_map_zoom_set(). It's set by default. */
85 ELM_MAP_ZOOM_MODE_AUTO_FIT, /**< Zoom until map fits inside the scroll frame with no pixels outside this area. */
86 ELM_MAP_ZOOM_MODE_AUTO_FILL, /**< Zoom until map fills scroll, ensuring no pixels are left unfilled. */
87 ELM_MAP_ZOOM_MODE_LAST
91 * Set route service to be used. By default used source is
92 * #ELM_MAP_ROUTE_SOURCE_YOURS.
94 * @see elm_map_route_source_set()
95 * @see elm_map_route_source_get()
101 ELM_MAP_ROUTE_SOURCE_YOURS, /**< Routing service http://www.yournavigation.org/ . Set by default.*/
102 ELM_MAP_ROUTE_SOURCE_MONAV, /**< MoNav offers exact routing without heuristic assumptions. Its routing core is based on Contraction Hierarchies. It's not working with Map yet. */
103 ELM_MAP_ROUTE_SOURCE_ORS, /**< Open Route Service: http://www.openrouteservice.org/ . It's not working with Map yet. */
104 ELM_MAP_ROUTE_SOURCE_LAST
105 } Elm_Map_Route_Sources;
109 ELM_MAP_NAME_SOURCE_NOMINATIM,
110 ELM_MAP_NAME_SOURCE_LAST
111 } Elm_Map_Name_Sources;
114 * Set type of transport used on route.
116 * @see elm_map_route_add()
122 ELM_MAP_ROUTE_TYPE_MOTOCAR, /**< Route should consider an automobile will be used. */
123 ELM_MAP_ROUTE_TYPE_BICYCLE, /**< Route should consider a bicycle will be used by the user. */
124 ELM_MAP_ROUTE_TYPE_FOOT, /**< Route should consider user will be walking. */
125 ELM_MAP_ROUTE_TYPE_LAST
126 } Elm_Map_Route_Type;
129 * Set the routing method, what should be prioritized, time or distance.
131 * @see elm_map_route_add()
137 ELM_MAP_ROUTE_METHOD_FASTEST, /**< Route should prioritize time. */
138 ELM_MAP_ROUTE_METHOD_SHORTEST, /**< Route should prioritized distance. */
139 ELM_MAP_ROUTE_METHOD_LAST
140 } Elm_Map_Route_Method;
144 ELM_MAP_NAME_METHOD_SEARCH,
145 ELM_MAP_NAME_METHOD_REVERSE,
146 ELM_MAP_NAME_METHOD_LAST
147 } Elm_Map_Name_Method;
149 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(). */
150 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(). */
151 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(). */
152 typedef struct _Elm_Map_Route Elm_Map_Route; /**< A route to be shown in the map. Can be created with elm_map_route_add() and deleted with elm_map_route_remove(). */
153 typedef struct _Elm_Map_Name Elm_Map_Name; /**< A handle for specific coordinates. */
154 typedef struct _Elm_Map_Track Elm_Map_Track;
156 typedef Evas_Object *(*ElmMapMarkerGetFunc)(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. */
157 typedef void (*ElmMapMarkerDelFunc)(Evas_Object *obj, Elm_Map_Marker *marker, void *data, Evas_Object *o); /**< Function to delete bubble content for marker classes. */
158 typedef Evas_Object *(*ElmMapMarkerIconGetFunc)(Evas_Object *obj, Elm_Map_Marker *marker, void *data); /**< Icon fetching class function for marker classes. */
159 typedef Evas_Object *(*ElmMapGroupIconGetFunc)(Evas_Object *obj, void *data); /**< Icon fetching class function for markers group classes. */
161 typedef char *(*ElmMapModuleSourceFunc)(void);
162 typedef int (*ElmMapModuleZoomMinFunc)(void);
163 typedef int (*ElmMapModuleZoomMaxFunc)(void);
164 typedef char *(*ElmMapModuleUrlFunc)(Evas_Object *obj, int x, int y, int zoom);
165 typedef int (*ElmMapModuleRouteSourceFunc)(void);
166 typedef char *(*ElmMapModuleRouteUrlFunc)(Evas_Object *obj, char *type_name, int method, double flon, double flat, double tlon, double tlat);
167 typedef char *(*ElmMapModuleNameUrlFunc)(Evas_Object *obj, int method, char *name, double lon, double lat);
168 typedef Eina_Bool (*ElmMapModuleGeoIntoCoordFunc)(const Evas_Object *obj, int zoom, double lon, double lat, int size, int *x, int *y);
169 typedef Eina_Bool (*ElmMapModuleCoordIntoGeoFunc)(const Evas_Object *obj, int zoom, int x, int y, int size, double *lon, double *lat);
172 * Add a new map widget to the given parent Elementary (container) object.
174 * @param parent The parent object.
175 * @return a new map widget handle or @c NULL, on errors.
177 * This function inserts a new map widget on the canvas.
181 EAPI Evas_Object *elm_map_add(Evas_Object *parent);
184 * Set the zoom level of the map.
186 * @param obj The map object.
187 * @param zoom The zoom level to set.
189 * This sets the zoom level.
191 * It will respect limits defined by elm_map_source_zoom_min_set() and
192 * elm_map_source_zoom_max_set().
194 * By default these values are 0 (world map) and 18 (maximum zoom).
196 * This function should be used when zoom mode is set to
197 * #ELM_MAP_ZOOM_MODE_MANUAL. This is the default mode, and can be set
198 * with elm_map_zoom_mode_set().
200 * @see elm_map_zoom_mode_set().
201 * @see elm_map_zoom_get().
205 EAPI void elm_map_zoom_set(Evas_Object *obj, int zoom);
208 * Get the zoom level of the map.
210 * @param obj The map object.
211 * @return The current zoom level.
213 * This returns the current zoom level of the map object.
215 * Note that if you set the fill mode to other than #ELM_MAP_ZOOM_MODE_MANUAL
216 * (which is the default), the zoom level may be changed at any time by the
217 * map object itself to account for map size and map viewport size.
219 * @see elm_map_zoom_set() for details.
223 EAPI int elm_map_zoom_get(const Evas_Object *obj);
226 * Set the zoom mode used by the map object.
228 * @param obj The map object.
229 * @param mode The zoom mode of the map, being it one of
230 * #ELM_MAP_ZOOM_MODE_MANUAL (default), #ELM_MAP_ZOOM_MODE_AUTO_FIT,
231 * or #ELM_MAP_ZOOM_MODE_AUTO_FILL.
233 * This sets the zoom mode to manual or one of the automatic levels.
234 * Manual (#ELM_MAP_ZOOM_MODE_MANUAL) means that zoom is set manually by
235 * elm_map_zoom_set() and will stay at that level until changed by code
236 * or until zoom mode is changed. This is the default mode.
238 * The Automatic modes will allow the map object to automatically
239 * adjust zoom mode based on properties. #ELM_MAP_ZOOM_MODE_AUTO_FIT will
240 * adjust zoom so the map fits inside the scroll frame with no pixels
241 * outside this area. #ELM_MAP_ZOOM_MODE_AUTO_FILL will be similar but
242 * ensure no pixels within the frame are left unfilled. Do not forget that
243 * the valid sizes are 2^zoom, consequently the map may be smaller than
246 * @see elm_map_zoom_set()
250 EAPI void elm_map_zoom_mode_set(Evas_Object *obj, Elm_Map_Zoom_Mode mode);
253 * Get the zoom mode used by the map object.
255 * @param obj The map object.
256 * @return The zoom mode of the map, being it one of
257 * #ELM_MAP_ZOOM_MODE_MANUAL (default), #ELM_MAP_ZOOM_MODE_AUTO_FIT,
258 * or #ELM_MAP_ZOOM_MODE_AUTO_FILL.
260 * This function returns the current zoom mode used by the map object.
262 * @see elm_map_zoom_mode_set() for more details.
266 EAPI Elm_Map_Zoom_Mode elm_map_zoom_mode_get(const Evas_Object *obj);
269 * Get the current geographic coordinates of the map.
271 * @param obj The map object.
272 * @param lon Pointer where to store longitude.
273 * @param lat Pointer where to store latitude.
275 * This gets the current center coordinates of the map object. It can be
276 * set by elm_map_geo_region_bring_in() and elm_map_geo_region_show().
278 * @see elm_map_geo_region_bring_in()
279 * @see elm_map_geo_region_show()
283 EAPI void elm_map_geo_region_get(const Evas_Object *obj, double *lon, double *lat);
286 * Animatedly bring in given coordinates to the center of the map.
288 * @param obj The map object.
289 * @param lon Longitude to center at.
290 * @param lat Latitude to center at.
292 * This causes map to jump to the given @p lat and @p lon coordinates
293 * and show it (by scrolling) in the center of the viewport, if it is not
294 * already centered. This will use animation to do so and take a period
295 * of time to complete.
297 * @see elm_map_geo_region_show() for a function to avoid animation.
298 * @see elm_map_geo_region_get()
302 EAPI void elm_map_geo_region_bring_in(Evas_Object *obj, double lon, double lat);
305 * Show the given coordinates at the center of the map, @b immediately.
307 * @param obj The map object.
308 * @param lon Longitude to center at.
309 * @param lat Latitude to center at.
311 * This causes map to @b redraw its viewport's contents to the
312 * region containing the given @p lat and @p lon, that will be moved to the
315 * @see elm_map_geo_region_bring_in() for a function to move with animation.
316 * @see elm_map_geo_region_get()
320 EAPI void elm_map_geo_region_show(Evas_Object *obj, double lon, double lat);
323 * Pause or unpause the map.
325 * @param obj The map object.
326 * @param paused Use @c EINA_TRUE to pause the map @p obj or @c EINA_FALSE
329 * This sets the paused state to on (@c EINA_TRUE) or off (@c EINA_FALSE)
332 * The default is off.
334 * This will stop zooming using animation, changing zoom levels will
335 * change instantly. This will stop any existing animations that are running.
337 * @see elm_map_paused_get()
341 EAPI void elm_map_paused_set(Evas_Object *obj, Eina_Bool paused);
344 * Get a value whether map is paused or not.
346 * @param obj The map object.
347 * @return @c EINA_TRUE means map is pause. @c EINA_FALSE indicates
348 * it is not. If @p obj is @c NULL, @c EINA_FALSE is returned.
350 * This gets the current paused state for the map object.
352 * @see elm_map_paused_set() for details.
356 EAPI Eina_Bool elm_map_paused_get(const Evas_Object *obj);
359 * Set to show markers during zoom level changes or not.
361 * @param obj The map object.
362 * @param paused Use @c EINA_TRUE to @b not show markers or @c EINA_FALSE
365 * This sets the paused state to on (@c EINA_TRUE) or off (@c EINA_FALSE)
368 * The default is off.
370 * This will stop zooming using animation, changing zoom levels will
371 * change instantly. This will stop any existing animations that are running.
373 * This sets the paused state to on (@c EINA_TRUE) or off (@c EINA_FALSE)
376 * The default is off.
378 * Enabling it will force the map to stop displaying the markers during
379 * zoom level changes. Set to on if you have a large number of markers.
381 * @see elm_map_paused_markers_get()
385 EAPI void elm_map_paused_markers_set(Evas_Object *obj, Eina_Bool paused);
388 * Get a value whether markers will be displayed on zoom level changes or not
390 * @param obj The map object.
391 * @return @c EINA_TRUE means map @b won't display markers or @c EINA_FALSE
392 * indicates it will. If @p obj is @c NULL, @c EINA_FALSE is returned.
394 * This gets the current markers paused state for the map object.
396 * @see elm_map_paused_markers_set() for details.
400 EAPI Eina_Bool elm_map_paused_markers_get(const Evas_Object *obj);
403 * Get the information of downloading status.
405 * @param obj The map object.
406 * @param try_num Pointer where to store number of tiles being downloaded.
407 * @param finish_num Pointer where to store number of tiles successfully
410 * This gets the current downloading status for the map object, the number
411 * of tiles being downloaded and the number of tiles already downloaded.
415 EAPI void elm_map_utils_downloading_status_get(const Evas_Object *obj, int *try_num, int *finish_num);
418 * Convert a pixel coordinate (x,y) into a geographic coordinate
419 * (longitude, latitude).
421 * @param obj The map object.
422 * @param x the coordinate.
423 * @param y the coordinate.
424 * @param size the size in pixels of the map.
425 * The map is a square and generally his size is : pow(2.0, zoom)*256.
426 * @param lon Pointer where to store the longitude that correspond to x.
427 * @param lat Pointer where to store the latitude that correspond to y.
429 * @note Origin pixel point is the top left corner of the viewport.
430 * Map zoom and size are taken on account.
432 * @see elm_map_utils_convert_geo_into_coord() if you need the inverse.
436 EAPI void elm_map_utils_convert_coord_into_geo(const Evas_Object *obj, int x, int y, int size, double *lon, double *lat);
439 * Convert a geographic coordinate (longitude, latitude) into a pixel
442 * @param obj The map object.
443 * @param lon the longitude.
444 * @param lat the latitude.
445 * @param size the size in pixels of the map. The map is a square
446 * and generally his size is : pow(2.0, zoom)*256.
447 * @param x Pointer where to store the horizontal pixel coordinate that
448 * correspond to the longitude.
449 * @param y Pointer where to store the vertical pixel coordinate that
450 * correspond to the latitude.
452 * @note Origin pixel point is the top left corner of the viewport.
453 * Map zoom and size are taken on account.
455 * @see elm_map_utils_convert_coord_into_geo() if you need the inverse.
459 EAPI void elm_map_utils_convert_geo_into_coord(const Evas_Object *obj, double lon, double lat, int size, int *x, int *y);
462 * Convert a geographic coordinate (longitude, latitude) into a name
465 * @param obj The map object.
466 * @param lon the longitude.
467 * @param lat the latitude.
468 * @return name A #Elm_Map_Name handle for this coordinate.
470 * To get the string for this address, elm_map_name_address_get()
473 * @see elm_map_utils_convert_name_into_coord() if you need the inverse.
477 EAPI Elm_Map_Name *elm_map_utils_convert_coord_into_name(const Evas_Object *obj, double lon, double lat);
480 * Convert a name (address) into a geographic coordinate
481 * (longitude, latitude).
483 * @param obj The map object.
484 * @param name The address.
485 * @return name A #Elm_Map_Name handle for this address.
487 * To get the longitude and latitude, elm_map_name_region_get()
490 * @see elm_map_utils_convert_coord_into_name() if you need the inverse.
494 EAPI Elm_Map_Name *elm_map_utils_convert_name_into_coord(const Evas_Object *obj, char *address);
497 * Convert canvas coordinates into a geographic coordinate
498 * (longitude, latitude).
500 * @param obj The map object.
501 * @param x horizontal coordinate of the point to convert.
502 * @param y vertical coordinate of the point to convert.
503 * @param lon A pointer to the longitude.
504 * @param lat A pointer to the latitude.
506 * This gets longitude and latitude from canvas x, y coordinates. The canvas
507 * coordinates mean x, y coordinate from current viewport.
508 * elm_map_utils_convert_coord_into_geo() internally to get the geographic
511 * see elm_map_rotate_get()
512 * see elm_map_utils_convert_coord_into_geo()
516 EAPI void elm_map_canvas_to_geo_convert(const Evas_Object *obj, const Evas_Coord x, const Evas_Coord y, double *lon, double *lat);
519 * Add a new marker to the map object.
521 * @param obj The map object.
522 * @param lon The longitude of the marker.
523 * @param lat The latitude of the marker.
524 * @param class The class, to use when marker @b isn't grouped to others.
525 * @param class_group The class group, to use when marker is grouped to others
526 * @param data The data passed to the callbacks.
528 * @return The created marker or @c NULL upon failure.
530 * A marker will be created and shown in a specific point of the map, defined
531 * by @p lon and @p lat.
533 * It will be displayed using style defined by @p class when this marker
534 * is displayed alone (not grouped). A new class can be created with
535 * elm_map_marker_class_new().
537 * If the marker is grouped to other markers, it will be displayed with
538 * style defined by @p class_group. Markers with the same group are grouped
539 * if they are close. A new group class can be created with
540 * elm_map_marker_group_class_new().
542 * Markers created with this method can be deleted with
543 * elm_map_marker_remove().
545 * A marker can have associated content to be displayed by a bubble,
546 * when a user click over it, as well as an icon. These objects will
547 * be fetch using class' callback functions.
549 * @see elm_map_marker_class_new()
550 * @see elm_map_marker_group_class_new()
551 * @see elm_map_marker_remove()
555 EAPI Elm_Map_Marker *elm_map_marker_add(Evas_Object *obj, double lon, double lat, Elm_Map_Marker_Class *clas, Elm_Map_Group_Class *clas_group, void *data);
558 * Set the maximum numbers of markers' content to be displayed in a group.
560 * @param obj The map object.
561 * @param max The maximum numbers of items displayed in a bubble.
563 * A bubble will be displayed when the user clicks over the group,
564 * and will place the content of markers that belong to this group
567 * A group can have a long list of markers, consequently the creation
568 * of the content of the bubble can be very slow.
570 * In order to avoid this, a maximum number of items is displayed
573 * By default this number is 30.
575 * Marker with the same group class are grouped if they are close.
577 * @see elm_map_marker_add()
581 EAPI void elm_map_max_marker_per_group_set(Evas_Object *obj, int max);
584 * Remove a marker from the map.
586 * @param marker The marker to remove.
588 * @see elm_map_marker_add()
592 EAPI void elm_map_marker_remove(Elm_Map_Marker *marker);
595 * Get the current coordinates of the marker.
597 * @param marker marker.
598 * @param lat Pointer where to store the marker's latitude.
599 * @param lon Pointer where to store the marker's longitude.
601 * These values are set when adding markers, with function
602 * elm_map_marker_add().
604 * @see elm_map_marker_add()
608 EAPI void elm_map_marker_region_get(const Elm_Map_Marker *marker, double *lon, double *lat);
611 * Animatedly bring in given marker to the center of the map.
613 * @param marker The marker to center at.
615 * This causes map to jump to the given @p marker's coordinates
616 * and show it (by scrolling) in the center of the viewport, if it is not
617 * already centered. This will use animation to do so and take a period
618 * of time to complete.
620 * @see elm_map_marker_show() for a function to avoid animation.
621 * @see elm_map_marker_region_get()
625 EAPI void elm_map_marker_bring_in(Elm_Map_Marker *marker);
628 * Show the given marker at the center of the map, @b immediately.
630 * @param marker The marker to center at.
632 * This causes map to @b redraw its viewport's contents to the
633 * region containing the given @p marker's coordinates, that will be
634 * moved to the center of the map.
636 * @see elm_map_marker_bring_in() for a function to move with animation.
637 * @see elm_map_markers_list_show() if more than one marker need to be
639 * @see elm_map_marker_region_get()
643 EAPI void elm_map_marker_show(Elm_Map_Marker *marker);
646 * Move and zoom the map to display a list of markers.
648 * @param markers A list of #Elm_Map_Marker handles.
650 * The map will be centered on the center point of the markers in the list.
651 * Then the map will be zoomed in order to fit the markers using the maximum
652 * zoom which allows display of all the markers.
654 * @warning All the markers should belong to the same map object.
656 * @see elm_map_marker_show() to show a single marker.
657 * @see elm_map_marker_bring_in()
661 EAPI void elm_map_markers_list_show(Eina_List *markers);
664 * Get the Evas object returned by the ElmMapMarkerGetFunc callback
666 * @param marker The marker which content should be returned.
667 * @return Return the evas object if it exists, else @c NULL.
669 * To set callback function #ElmMapMarkerGetFunc for the marker class,
670 * elm_map_marker_class_get_cb_set() should be used.
672 * This content is what will be inside the bubble that will be displayed
673 * when an user clicks over the marker.
675 * This returns the actual Evas object used to be placed inside
676 * the bubble. This may be @c NULL, as it may
677 * not have been created or may have been deleted, at any time, by
678 * the map. <b>Do not modify this object</b> (move, resize,
679 * show, hide, etc.), as the map is controlling it. This
680 * function is for querying, emitting custom signals or hooking
681 * lower level callbacks for events on that object. Do not delete
682 * this object under any circumstances.
686 EAPI Evas_Object *elm_map_marker_object_get(const Elm_Map_Marker *marker);
691 * @param marker The marker to be updated.
693 * If a content is set to this marker, it will call function to delete it,
694 * #ElmMapMarkerDelFunc, and then will fetch the content again with
695 * #ElmMapMarkerGetFunc.
697 * These functions are set for the marker class with
698 * elm_map_marker_class_get_cb_set() and elm_map_marker_class_del_cb_set().
702 EAPI void elm_map_marker_update(Elm_Map_Marker *marker);
705 * Close all the bubbles opened by the user.
707 * @param obj The map object.
709 * A bubble is displayed with a content fetched with #ElmMapMarkerGetFunc
710 * when the user clicks on a marker.
712 * This functions is set for the marker class with
713 * elm_map_marker_class_get_cb_set().
717 EAPI void elm_map_bubbles_close(Evas_Object *obj);
720 * Create a new group class.
722 * @param obj The map object.
723 * @return Returns the new group class.
725 * Each marker must be associated to a group class. Markers in the same
726 * group are grouped if they are close.
728 * The group class defines the style of the marker when a marker is grouped
729 * to others markers. When it is alone, another class will be used.
731 * A group class will need to be provided when creating a marker with
732 * elm_map_marker_add().
734 * Some properties and functions can be set by class, as:
735 * - style, with elm_map_group_class_style_set()
736 * - data - to be associated to the group class. It can be set using
737 * elm_map_group_class_data_set().
738 * - min zoom to display markers, set with
739 * elm_map_group_class_zoom_displayed_set().
740 * - max zoom to group markers, set using
741 * elm_map_group_class_zoom_grouped_set().
742 * - visibility - set if markers will be visible or not, set with
743 * elm_map_group_class_hide_set().
744 * - #ElmMapGroupIconGetFunc - used to fetch icon for markers group classes.
745 * It can be set using elm_map_group_class_icon_cb_set().
747 * @see elm_map_marker_add()
748 * @see elm_map_group_class_style_set()
749 * @see elm_map_group_class_data_set()
750 * @see elm_map_group_class_zoom_displayed_set()
751 * @see elm_map_group_class_zoom_grouped_set()
752 * @see elm_map_group_class_hide_set()
753 * @see elm_map_group_class_icon_cb_set()
757 EAPI Elm_Map_Group_Class *elm_map_group_class_new(Evas_Object *obj);
760 * Set the marker's style of a group class.
762 * @param class The group class.
763 * @param style The style to be used by markers.
765 * Each marker must be associated to a group class, and will use the style
766 * defined by such class when grouped to other markers.
768 * The following styles are provided by default theme:
769 * @li @c radio - blue circle
770 * @li @c radio2 - green circle
773 * @see elm_map_group_class_new() for more details.
774 * @see elm_map_marker_add()
778 EAPI void elm_map_group_class_style_set(Elm_Map_Group_Class *clas, const char *style);
781 * Set the icon callback function of a group class.
783 * @param class The group class.
784 * @param icon_get The callback function that will return the icon.
786 * Each marker must be associated to a group class, and it can display a
787 * custom icon. The function @p icon_get must return this icon.
789 * @see elm_map_group_class_new() for more details.
790 * @see elm_map_marker_add()
794 EAPI void elm_map_group_class_icon_cb_set(Elm_Map_Group_Class *clas, ElmMapGroupIconGetFunc icon_get);
797 * Set the data associated to the group class.
799 * @param class The group class.
800 * @param data The new user data.
802 * This data will be passed for callback functions, like icon get callback,
803 * that can be set with elm_map_group_class_icon_cb_set().
805 * If a data was previously set, the object will lose the pointer for it,
806 * so if needs to be freed, you must do it yourself.
808 * @see elm_map_group_class_new() for more details.
809 * @see elm_map_group_class_icon_cb_set()
810 * @see elm_map_marker_add()
814 EAPI void elm_map_group_class_data_set(Elm_Map_Group_Class *clas, void *data);
817 * Set the minimum zoom from where the markers are displayed.
819 * @param clas The group class.
820 * @param zoom The minimum zoom.
822 * Markers only will be displayed when the map is displayed at @p zoom
825 * @see elm_map_group_class_new() for more details.
826 * @see elm_map_marker_add()
830 EAPI void elm_map_group_class_zoom_displayed_set(Elm_Map_Group_Class *clas, int zoom);
833 * Set the zoom from where the markers are no more grouped.
835 * @param clas The group class.
836 * @param zoom The maximum zoom.
838 * Markers only will be grouped when the map is displayed at
841 * @see elm_map_group_class_new() for more details.
842 * @see elm_map_marker_add()
846 EAPI void elm_map_group_class_zoom_grouped_set(Elm_Map_Group_Class *clas, int zoom);
849 * Set if the markers associated to the group class @p clas are hidden or not.
851 * @param clas The group class.
852 * @param hide Use @c EINA_TRUE to hide markers or @c EINA_FALSE
855 * If @p hide is @c EINA_TRUE the markers will be hidden, but default
860 EAPI void elm_map_group_class_hide_set(Evas_Object *obj, Elm_Map_Group_Class *clas, Eina_Bool hide);
863 * Create a new marker class.
865 * @param obj The map object.
866 * @return Returns the new group class.
868 * Each marker must be associated to a class.
870 * The marker class defines the style of the marker when a marker is
871 * displayed alone, i.e., not grouped to to others markers. When grouped
872 * it will use group class style.
874 * A marker class will need to be provided when creating a marker with
875 * elm_map_marker_add().
877 * Some properties and functions can be set by class, as:
878 * - style, with elm_map_marker_class_style_set()
879 * - #ElmMapMarkerIconGetFunc - used to fetch icon for markers classes.
880 * It can be set using elm_map_marker_class_icon_cb_set().
881 * - #ElmMapMarkerGetFunc - used to fetch bubble content for marker classes.
882 * Set using elm_map_marker_class_get_cb_set().
883 * - #ElmMapMarkerDelFunc - used to delete bubble content for marker classes.
884 * Set using elm_map_marker_class_del_cb_set().
886 * @see elm_map_marker_add()
887 * @see elm_map_marker_class_style_set()
888 * @see elm_map_marker_class_icon_cb_set()
889 * @see elm_map_marker_class_get_cb_set()
890 * @see elm_map_marker_class_del_cb_set()
894 EAPI Elm_Map_Marker_Class *elm_map_marker_class_new(Evas_Object *obj);
897 * Set the marker's style of a marker class.
899 * @param clas The marker class.
900 * @param style The style to be used by markers.
902 * Each marker must be associated to a marker class, and will use the style
903 * defined by such class when alone, i.e., @b not grouped to other markers.
905 * The following styles are provided by default theme:
910 * @see elm_map_marker_class_new() for more details.
911 * @see elm_map_marker_add()
915 EAPI void elm_map_marker_class_style_set(Elm_Map_Marker_Class *clas, const char *style);
918 * Set the icon callback function of a marker class.
920 * @param clas The marker class.
921 * @param icon_get The callback function that will return the icon.
923 * Each marker must be associated to a marker class, and it can display a
924 * custom icon. The function @p icon_get must return this icon.
926 * @see elm_map_marker_class_new() for more details.
927 * @see elm_map_marker_add()
931 EAPI void elm_map_marker_class_icon_cb_set(Elm_Map_Marker_Class *clas, ElmMapMarkerIconGetFunc icon_get);
934 * Set the bubble content callback function of a marker class.
936 * @param clas The marker class.
937 * @param get The callback function that will return the content.
939 * Each marker must be associated to a marker class, and it can display a
940 * a content on a bubble that opens when the user click over the marker.
941 * The function @p get must return this content object.
943 * If this content will need to be deleted, elm_map_marker_class_del_cb_set()
946 * @see elm_map_marker_class_new() for more details.
947 * @see elm_map_marker_class_del_cb_set()
948 * @see elm_map_marker_add()
952 EAPI void elm_map_marker_class_get_cb_set(Elm_Map_Marker_Class *clas, ElmMapMarkerGetFunc get);
955 * Set the callback function used to delete bubble content of a marker class.
957 * @param clas The marker class.
958 * @param del The callback function that will delete the content.
960 * Each marker must be associated to a marker class, and it can display a
961 * a content on a bubble that opens when the user click over the marker.
962 * The function to return such content can be set with
963 * elm_map_marker_class_get_cb_set().
965 * If this content must be freed, a callback function need to be
966 * set for that task with this function.
968 * If this callback is defined it will have to delete (or not) the
969 * object inside, but if the callback is not defined the object will be
970 * destroyed with evas_object_del().
972 * @see elm_map_marker_class_new() for more details.
973 * @see elm_map_marker_class_get_cb_set()
974 * @see elm_map_marker_add()
978 EAPI void elm_map_marker_class_del_cb_set(Elm_Map_Marker_Class *clas, ElmMapMarkerDelFunc del);
981 * Get the list of available sources.
983 * @param obj The map object.
984 * @return The source names list.
986 * It will provide a list with all available sources, that can be set as
987 * current source with elm_map_source_name_set(), or get with
988 * elm_map_source_name_get().
996 * @see elm_map_source_name_set() for more details.
997 * @see elm_map_source_name_get()
1001 EAPI const char **elm_map_source_names_get(const Evas_Object *obj);
1004 * Set the source of the map.
1006 * @param obj The map object.
1007 * @param source The source to be used.
1009 * Map widget retrieves images that composes the map from a web service.
1010 * This web service can be set with this method.
1012 * A different service can return a different maps with different
1013 * information and it can use different zoom values.
1015 * The @p source_name need to match one of the names provided by
1016 * elm_map_source_names_get().
1018 * The current source can be get using elm_map_source_name_get().
1020 * @see elm_map_source_names_get()
1021 * @see elm_map_source_name_get()
1026 EAPI void elm_map_source_name_set(Evas_Object *obj, const char *source_name);
1029 * Get the name of currently used source.
1031 * @param obj The map object.
1032 * @return Returns the name of the source in use.
1034 * @see elm_map_source_name_set() for more details.
1038 EAPI const char *elm_map_source_name_get(const Evas_Object *obj);
1041 * Set the source of the route service to be used by the map.
1043 * @param obj The map object.
1044 * @param source The route service to be used, being it one of
1045 * #ELM_MAP_ROUTE_SOURCE_YOURS (default), #ELM_MAP_ROUTE_SOURCE_MONAV,
1046 * and #ELM_MAP_ROUTE_SOURCE_ORS.
1048 * Each one has its own algorithm, so the route retrieved may
1049 * differ depending on the source route. Now, only the default is working.
1051 * #ELM_MAP_ROUTE_SOURCE_YOURS is the routing service provided at
1052 * http://www.yournavigation.org/.
1054 * #ELM_MAP_ROUTE_SOURCE_MONAV, offers exact routing without heuristic
1055 * assumptions. Its routing core is based on Contraction Hierarchies.
1057 * #ELM_MAP_ROUTE_SOURCE_ORS, is provided at http://www.openrouteservice.org/
1059 * @see elm_map_route_source_get().
1063 EAPI void elm_map_route_source_set(Evas_Object *obj, Elm_Map_Route_Sources source);
1066 * Get the current route source.
1068 * @param obj The map object.
1069 * @return The source of the route service used by the map.
1071 * @see elm_map_route_source_set() for details.
1075 EAPI Elm_Map_Route_Sources elm_map_route_source_get(const Evas_Object *obj);
1078 * Set the minimum zoom of the source.
1080 * @param obj The map object.
1081 * @param zoom New minimum zoom value to be used.
1083 * By default, it's 0.
1087 EAPI void elm_map_source_zoom_min_set(Evas_Object *obj, int zoom);
1090 * Get the minimum zoom of the source.
1092 * @param obj The map object.
1093 * @return Returns the minimum zoom of the source.
1095 * @see elm_map_source_zoom_min_set() for details.
1099 EAPI int elm_map_source_zoom_min_get(const Evas_Object *obj);
1102 * Set the maximum zoom of the source.
1104 * @param obj The map object.
1105 * @param zoom New maximum zoom value to be used.
1107 * By default, it's 18.
1111 EAPI void elm_map_source_zoom_max_set(Evas_Object *obj, int zoom);
1114 * Get the maximum zoom of the source.
1116 * @param obj The map object.
1117 * @return Returns the maximum zoom of the source.
1119 * @see elm_map_source_zoom_min_set() for details.
1123 EAPI int elm_map_source_zoom_max_get(const Evas_Object *obj);
1126 * Set the user agent used by the map object to access routing services.
1128 * @param obj The map object.
1129 * @param user_agent The user agent to be used by the map.
1131 * User agent is a client application implementing a network protocol used
1132 * in communications within a client–server distributed computing system
1134 * The @p user_agent identification string will transmitted in a header
1135 * field @c User-Agent.
1137 * @see elm_map_user_agent_get()
1141 EAPI void elm_map_user_agent_set(Evas_Object *obj, const char *user_agent);
1144 * Get the user agent used by the map object.
1146 * @param obj The map object.
1147 * @return The user agent identification string used by the map.
1149 * @see elm_map_user_agent_set() for details.
1153 EAPI const char *elm_map_user_agent_get(const Evas_Object *obj);
1156 * Add a new route to the map object.
1158 * @param obj The map object.
1159 * @param type The type of transport to be considered when tracing a route.
1160 * @param method The routing method, what should be prioritized.
1161 * @param flon The start longitude.
1162 * @param flat The start latitude.
1163 * @param tlon The destination longitude.
1164 * @param tlat The destination latitude.
1166 * @return The created route or @c NULL upon failure.
1168 * A route will be traced by point on coordinates (@p flat, @p flon)
1169 * to point on coordinates (@p tlat, @p tlon), using the route service
1170 * set with elm_map_route_source_set().
1172 * It will take @p type on consideration to define the route,
1173 * depending if the user will be walking or driving, the route may vary.
1174 * One of #ELM_MAP_ROUTE_TYPE_MOTOCAR, #ELM_MAP_ROUTE_TYPE_BICYCLE, or
1175 * #ELM_MAP_ROUTE_TYPE_FOOT need to be used.
1177 * Another parameter is what the route should prioritize, the minor distance
1178 * or the less time to be spend on the route. So @p method should be one
1179 * of #ELM_MAP_ROUTE_METHOD_SHORTEST or #ELM_MAP_ROUTE_METHOD_FASTEST.
1181 * Routes created with this method can be deleted with
1182 * elm_map_route_remove(), colored with elm_map_route_color_set(),
1183 * and distance can be get with elm_map_route_distance_get().
1185 * @see elm_map_route_remove()
1186 * @see elm_map_route_color_set()
1187 * @see elm_map_route_distance_get()
1188 * @see elm_map_route_source_set()
1192 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);
1195 * Remove a route from the map.
1197 * @param route The route to remove.
1199 * @see elm_map_route_add()
1203 EAPI void elm_map_route_remove(Elm_Map_Route *route);
1206 * Set the route color.
1208 * @param route The route object.
1209 * @param r Red channel value, from 0 to 255.
1210 * @param g Green channel value, from 0 to 255.
1211 * @param b Blue channel value, from 0 to 255.
1212 * @param a Alpha channel value, from 0 to 255.
1214 * It uses an additive color model, so each color channel represents
1215 * how much of each primary colors must to be used. 0 represents
1216 * absence of this color, so if all of the three are set to 0,
1217 * the color will be black.
1219 * These component values should be integers in the range 0 to 255,
1220 * (single 8-bit byte).
1222 * This sets the color used for the route. By default, it is set to
1223 * solid red (r = 255, g = 0, b = 0, a = 255).
1225 * For alpha channel, 0 represents completely transparent, and 255, opaque.
1227 * @see elm_map_route_color_get()
1231 EAPI void elm_map_route_color_set(Elm_Map_Route *route, int r, int g, int b, int a);
1234 * Get the route color.
1236 * @param route The route object.
1237 * @param r Pointer where to store the red channel value.
1238 * @param g Pointer where to store the green channel value.
1239 * @param b Pointer where to store the blue channel value.
1240 * @param a Pointer where to store the alpha channel value.
1242 * @see elm_map_route_color_set() for details.
1246 EAPI void elm_map_route_color_get(const Elm_Map_Route *route, int *r, int *g, int *b, int *a);
1249 * Get the route distance in kilometers.
1251 * @param route The route object.
1252 * @return The distance of route (unit : km).
1256 EAPI double elm_map_route_distance_get(const Elm_Map_Route *route);
1259 * Get the information of route nodes.
1261 * @param route The route object.
1262 * @return Returns a string with the nodes of route.
1266 EAPI const char *elm_map_route_node_get(const Elm_Map_Route *route);
1269 * Get the information of route waypoint.
1271 * @param route the route object.
1272 * @return Returns a string with information about waypoint of route.
1276 EAPI const char *elm_map_route_waypoint_get(const Elm_Map_Route *route);
1279 * Get the address of the name.
1281 * @param name The name handle.
1282 * @return Returns the address string of @p name.
1284 * This gets the coordinates of the @p name, created with one of the
1285 * conversion functions.
1287 * @see elm_map_utils_convert_name_into_coord()
1288 * @see elm_map_utils_convert_coord_into_name()
1292 EAPI const char *elm_map_name_address_get(const Elm_Map_Name *name);
1295 * Get the current coordinates of the name.
1297 * @param name The name handle.
1298 * @param lat Pointer where to store the latitude.
1299 * @param lon Pointer where to store The longitude.
1301 * This gets the coordinates of the @p name, created with one of the
1302 * conversion functions.
1304 * @see elm_map_utils_convert_name_into_coord()
1305 * @see elm_map_utils_convert_coord_into_name()
1309 EAPI void elm_map_name_region_get(const Elm_Map_Name *name, double *lon, double *lat);
1312 * Remove a name from the map.
1314 * @param name The name to remove.
1316 * Basically the struct handled by @p name will be freed, so conversions
1317 * between address and coordinates will be lost.
1319 * @see elm_map_utils_convert_name_into_coord()
1320 * @see elm_map_utils_convert_coord_into_name()
1324 EAPI void elm_map_name_remove(Elm_Map_Name *name);
1329 * @param obj The map object.
1330 * @param degree Angle from 0.0 to 360.0 to rotate around Z axis.
1331 * @param cx Rotation's center horizontal position.
1332 * @param cy Rotation's center vertical position.
1334 * @see elm_map_rotate_get()
1338 EAPI void elm_map_rotate_set(Evas_Object *obj, double degree, Evas_Coord cx, Evas_Coord cy);
1341 * Get the rotate degree of the map
1343 * @param obj The map object
1344 * @param degree Pointer where to store degrees from 0.0 to 360.0
1345 * to rotate around Z axis.
1346 * @param cx Pointer where to store rotation's center horizontal position.
1347 * @param cy Pointer where to store rotation's center vertical position.
1349 * @see elm_map_rotate_set() to set map rotation.
1353 EAPI void elm_map_rotate_get(const Evas_Object *obj, double *degree, Evas_Coord *cx, Evas_Coord *cy);
1356 * Enable or disable mouse wheel to be used to zoom in / out the map.
1358 * @param obj The map object.
1359 * @param disabled Use @c EINA_TRUE to disable mouse wheel or @c EINA_FALSE
1362 * Mouse wheel can be used for the user to zoom in or zoom out the map.
1364 * It's disabled by default.
1366 * @see elm_map_wheel_disabled_get()
1370 EAPI void elm_map_wheel_disabled_set(Evas_Object *obj, Eina_Bool disabled);
1373 * Get a value whether mouse wheel is enabled or not.
1375 * @param obj The map object.
1376 * @return @c EINA_TRUE means map is disabled. @c EINA_FALSE indicates
1377 * it is enabled. If @p obj is @c NULL, @c EINA_FALSE is returned.
1379 * Mouse wheel can be used for the user to zoom in or zoom out the map.
1381 * @see elm_map_wheel_disabled_set() for details.
1385 EAPI Eina_Bool elm_map_wheel_disabled_get(const Evas_Object *obj);
1389 * Add a track on the map
1391 * @param obj The map object.
1392 * @param emap The emap route object.
1393 * @return The route object. This is an elm object of type Route.
1395 * @see elm_route_add() for details.
1399 EAPI Evas_Object *elm_map_track_add(Evas_Object *obj, EMap_Route *emap);
1403 * Remove a track from the map
1405 * @param obj The map object.
1406 * @param route The track to remove.
1410 EAPI void elm_map_track_remove(Evas_Object *obj, Evas_Object *route);