5 * @image html map_inheritance_tree.png
6 * @image latex map_inheritance_tree.eps
8 * @image html img/widget/map/preview-00.png
9 * @image latex img/widget/map/preview-00.eps
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.
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
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.
25 * Smart callbacks one can listen to:
26 * - @c "clicked" - This is called when a user has clicked the map without
28 * - @c "clicked,double" - This is called when a user has double-clicked
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
54 * Available style for map widget:
57 * Available style for markers:
62 * Available style for marker bubble:
66 * @li @ref map_example_01
67 * @li @ref map_example_02
68 * @li @ref map_example_03
77 * Set map's zoom behavior. It can be set to manual or automatic.
79 * Default value is #ELM_MAP_ZOOM_MODE_MANUAL.
81 * Values <b> don't </b> work as bitmask, only one can be chosen.
83 * @note Valid sizes are 2^zoom, consequently the map may be smaller
84 * than the scroller view.
86 * @see elm_map_zoom_mode_set()
87 * @see elm_map_zoom_mode_get()
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
100 * Set type of a external source (provider).
102 * @see elm_map_sources_get()
103 * @see elm_map_source_get()
104 * @see elm_map_source_set()
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;
117 * Set type of transport used on route.
119 * @see elm_map_route_add()
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;
132 * Set the routing method, what should be prioritized, time or distance.
134 * @see elm_map_route_add()
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;
146 * Set the name search method.
148 * This is for name module interface.
154 ELM_MAP_NAME_METHOD_SEARCH,
155 ELM_MAP_NAME_METHOD_REVERSE,
156 ELM_MAP_NAME_METHOD_LAST
157 } Elm_Map_Name_Method;
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().
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()
171 typedef enum _Elm_Map_Overlay_Type
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
184 } Elm_Map_Overlay_Type;
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(). */
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. */
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. */
205 * Add a new map widget to the given parent Elementary (container) object.
207 * @param parent The parent object.
208 * @return a new map widget handle or @c NULL, on errors.
210 * This function inserts a new map widget on the canvas.
214 EAPI Evas_Object *elm_map_add(Evas_Object *parent);
217 * Set the zoom level of the map.
219 * @param obj The map object.
220 * @param zoom The zoom level to set.
222 * This sets the zoom level.
224 * It will respect limits defined by elm_map_zoom_min_set() and
225 * elm_map_zoom_max_set().
227 * By default these values are 0 (world map) and 18 (maximum zoom).
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().
232 * @see elm_map_zoom_mode_set()
233 * @see elm_map_zoom_get()
237 EAPI void elm_map_zoom_set(Evas_Object *obj, int zoom);
240 * Get the zoom level of the map.
242 * @param obj The map object.
243 * @return The current zoom level.
245 * This returns the current zoom level of the map object.
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.
251 * @see elm_map_zoom_set() for details.
255 EAPI int elm_map_zoom_get(const Evas_Object *obj);
258 * Set the zoom mode used by the map object.
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.
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.
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
277 * @see elm_map_zoom_set()
281 EAPI void elm_map_zoom_mode_set(Evas_Object *obj, Elm_Map_Zoom_Mode mode);
284 * Get the zoom mode used by the map object.
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.
290 * This function returns the current zoom mode used by the map object.
292 * @see elm_map_zoom_mode_set() for more details.
296 EAPI Elm_Map_Zoom_Mode elm_map_zoom_mode_get(const Evas_Object *obj);
299 * Set the minimum zoom of the source.
301 * @param obj The map object.
302 * @param zoom New minimum zoom value to be used.
304 * @see elm_map_zoom_min_get() for details.
308 EAPI void elm_map_zoom_min_set(Evas_Object *obj, int zoom);
311 * Get the minimum zoom of the source.
313 * @param obj The map object.
314 * @return Returns the minimum zoom of the source.
316 * @see elm_map_zoom_min_set() for details.
320 EAPI int elm_map_zoom_min_get(const Evas_Object *obj);
323 * Set the maximum zoom of the source.
325 * @param obj The map object.
326 * @param zoom New maximum zoom value to be used.
328 * @see elm_map_zoom_max_get() for details.
332 EAPI void elm_map_zoom_max_set(Evas_Object *obj, int zoom);
335 * Get the maximum zoom of the source.
337 * @param obj The map object.
338 * @return Returns the maximum zoom of the source.
340 * @see elm_map_zoom_max_set() for details.
344 EAPI int elm_map_zoom_max_get(const Evas_Object *obj);
347 * Get the current geographic coordinates of the map.
349 * @param obj The map object.
350 * @param lon Pointer to store longitude.
351 * @param lat Pointer to store latitude.
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().
356 * @see elm_map_region_bring_in()
357 * @see elm_map_region_show()
361 EAPI void elm_map_region_get(const Evas_Object *obj, double *lon, double *lat);
364 * Animatedly bring in given coordinates to the center of the map.
366 * @param obj The map object.
367 * @param lon Longitude to center at.
368 * @param lat Latitude to center at.
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.
375 * @see elm_map_region_show() for a function to avoid animation.
376 * @see elm_map_region_get()
380 EAPI void elm_map_region_bring_in(Evas_Object *obj, double lon, double lat);
383 * Show the given coordinates at the center of the map, @b immediately.
385 * @param obj The map object.
386 * @param lon Longitude to center at.
387 * @param lat Latitude to center at.
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
393 * @see elm_map_region_bring_in() for a function to move with animation.
394 * @see elm_map_region_get()
398 EAPI void elm_map_region_show(Evas_Object *obj, double lon, double lat);
401 * Convert canvas coordinates into geographic coordinates
402 * (longitude, latitude).
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.
410 * This gets longitude and latitude from canvas x, y coordinates. The canvas
411 * coordinates mean x, y coordinate from current viewport.
413 * see elm_map_region_to_canvas_convert()
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);
420 * Convert geographic coordinates (longitude, latitude)
421 * into canvas coordinates.
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.
429 * This gets canvas x, y coordinates from longitude and latitude. The canvas
430 * coordinates mean x, y coordinate from current viewport.
432 * see elm_map_canvas_to_region_convert()
436 EAPI void elm_map_region_to_canvas_convert(const Evas_Object *obj, double lon, double lat, Evas_Coord *x, Evas_Coord *y);
439 * Pause or unpause the map.
441 * @param obj The map object.
442 * @param paused Use @c EINA_TRUE to pause the map @p obj or @c EINA_FALSE
445 * This sets the paused state to on (@c EINA_TRUE) or off (@c EINA_FALSE)
448 * The default is off.
450 * This will stop zooming using animation, changing zoom levels will
451 * change instantly. This will stop any existing animations that are running.
453 * @see elm_map_paused_get()
457 EAPI void elm_map_paused_set(Evas_Object *obj, Eina_Bool paused);
460 * Get a value whether map is paused or not.
462 * @param obj The map object.
463 * @return @c EINA_TRUE means map is pause. @c EINA_FALSE indicates
466 * This gets the current paused state for the map object.
468 * @see elm_map_paused_set() for details.
472 EAPI Eina_Bool elm_map_paused_get(const Evas_Object *obj);
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.
482 * @see elm_map_rotate_get()
486 EAPI void elm_map_rotate_set(Evas_Object *obj, double degree, Evas_Coord cx, Evas_Coord cy);
489 * Get the rotate degree of the map
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.
497 * @see elm_map_rotate_set() to set map rotation.
501 EAPI void elm_map_rotate_get(const Evas_Object *obj, double *degree, Evas_Coord *cx, Evas_Coord *cy);
504 * Enable or disable mouse wheel to be used to zoom in / out the map.
506 * @param obj The map object.
507 * @param disabled Use @c EINA_TRUE to disable mouse wheel or @c EINA_FALSE
510 * Mouse wheel can be used for the user to zoom in or zoom out the map.
512 * It's disabled by default.
514 * @see elm_map_wheel_disabled_get()
518 EAPI void elm_map_wheel_disabled_set(Evas_Object *obj, Eina_Bool disabled);
521 * Get a value whether mouse wheel is enabled or not.
523 * @param obj The map object.
524 * @return @c EINA_TRUE means map is disabled. @c EINA_FALSE indicates
527 * Mouse wheel can be used for the user to zoom in or zoom out the map.
529 * @see elm_map_wheel_disabled_set() for details.
533 EAPI Eina_Bool elm_map_wheel_disabled_get(const Evas_Object *obj);
536 * Set the user agent used by the map object to access routing services.
538 * @param obj The map object.
539 * @param user_agent The user agent to be used by the map.
541 * User agent is a client application implementing a network protocol used
542 * in communications within a client–server distributed computing system
544 * The @p user_agent identification string will transmitted in a header
545 * field @c User-Agent.
547 * @see elm_map_user_agent_get()
551 EAPI void elm_map_user_agent_set(Evas_Object *obj, const char *user_agent);
554 * Get the user agent used by the map object.
556 * @param obj The map object.
557 * @return The user agent identification string used by the map.
559 * @see elm_map_user_agent_set() for details.
563 EAPI const char *elm_map_user_agent_get(const Evas_Object *obj);
567 * Add a new overlay to the map object. This overlay has a default type.
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.
574 * A overlay will be created and shown in a specific point of the map, defined
575 * by @p lon and @p lat.
577 * The created overlay has a default style layout before content or
579 * If content or icon is set, those are displayed instead of default style
581 * You can set by using elm_map_overlay_content_set() or
582 * elm_map_overlay_icon_set(). If NULL is set, default style
585 * Overlay created with this method can be deleted by elm_map_overlay_del().
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()
595 EAPI Elm_Map_Overlay * elm_map_overlay_add(Evas_Object *obj, double lon, double lat);
598 * Return all overlays in the map object.
600 * @param obj The map object to return overlays.
601 * @return The list of all overlays or @c NULL upon failure.
603 * This list includes group overlays also.
604 * So this can be changed dynamically while zooming and panning.
610 EAPI EAPI Eina_List * elm_map_overlays_get(Evas_Object *obj);
613 * Delete a overlay from the map. This function can delete all types
616 * @param overlay The overlay to be deleted.
618 * @see elm_map_overlay_add()
619 * @see elm_map_overlay_class_add()
620 * @see elm_map_overlay_bubble_add()
624 EAPI void elm_map_overlay_del(Elm_Map_Overlay *overlay);
627 * Get the overlay type.
629 * @param overlay The overlay to return type.
630 * @return Return the overlay type.
632 * This type is resolved when the overlay is created.
634 * @see elm_map_overlay_add()
635 * @see elm_map_overlay_class_add()
636 * @see elm_map_overlay_bubble_add()
640 EAPI Elm_Map_Overlay_Type elm_map_overlay_type_get(const Elm_Map_Overlay *overlay);
643 * Set a pointer of user data for a overlay.
645 * @param overlay The overlay to own the user data.
646 * @param data A pointer of user data
648 * @see elm_map_overlay_data_get()
652 EAPI void elm_map_overlay_data_set(Elm_Map_Overlay *overlay, void *data);
655 * Get the user data stored on a overlay.
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.
661 * @see elm_map_overlay_data_set()
665 EAPI void * elm_map_overlay_data_get(const Elm_Map_Overlay *overlay);
668 * Set if the overlay is hidden or not.
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.
673 * @see elm_map_overlay_hide_get()
677 EAPI void elm_map_overlay_hide_set(Elm_Map_Overlay *overlay, Eina_Bool hide);
680 * Get a value whether the overlay is hidden or not.
682 * @param overlay The overlay to return the hidden state.
683 * @return @c EINA_TRUE means the overlay is hidden. @c EINA_FALSE indicates
686 * This gets the current hidden state for the overlay.
688 * @see elm_map_overlay_hide_set()
692 EAPI Eina_Bool elm_map_overlay_hide_get(const Elm_Map_Overlay *overlay);
695 * Set the minimum zoom from where the overlay is displayed.
697 * @param overlay The overlay to be set the minimum zoom.
698 * @param zoom The minimum zoom.
700 * The overlay only will be displayed when the map is displayed at @p zoom
703 * @see elm_map_overlay_displayed_zoom_min_get()
707 EAPI void elm_map_overlay_displayed_zoom_min_set(Elm_Map_Overlay *overlay, int zoom);
710 * Get the minimum zoom from where the overlay is displayed.
712 * @param overlay The overlay to return the minimum zoom.
713 * @return zoom The minimum zoom.
715 * @see elm_map_overlay_displayed_zoom_min_set()
719 EAPI int elm_map_overlay_displayed_zoom_min_get(const Elm_Map_Overlay *overlay);
722 * Pause or unpause the overlay.
724 * @param overlay The overlay to be paused.
725 * @param paused Use @c EINA_TRUE to pause the @p overlay or @c EINA_FALSE
728 * This sets the paused state to on (@c EINA_TRUE) or off (@c EINA_FALSE)
731 * The default is off.
733 * This will stop moving the overlay coordinates instantly.
734 * even if map being scrolled or zoomed.
736 * @see elm_map_overlay_paused_get()
740 EAPI void elm_map_overlay_paused_set(Elm_Map_Overlay *overlay, Eina_Bool paused);
743 * Get a value whether the overlay is paused or not.
745 * @param overlay The overlay to return paused state.
746 * @return @c EINA_TRUE means overlay is paused. @c EINA_FALSE indicates
749 * This gets the current paused state for the overlay.
751 * @see elm_map_overlay_paused_set()
755 EAPI Eina_Bool elm_map_overlay_paused_get(const Elm_Map_Overlay *overlay);
758 * Get a value whether the overlay is visible or not.
760 * @param overlay The overlay to return visible state.
761 * @return @c EINA_TRUE means overlay is visible. @c EINA_FALSE indicates
764 * The visible of the overlay can not be set.
765 * This value can be changed dynamically while zooming and panning
771 EAPI Eina_Bool elm_map_overlay_visible_get(const Elm_Map_Overlay *overlay);
774 * Set the content object of the overlay.
776 * @param overlay The overlay to be set the content.
777 * @param obj The evas object will be used to display the overlay.
779 * Only default and class type overlay support this function.
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.),
784 * You can only resize this.
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.
790 * If @p obj is @c NULL, content inside the overlay is deleted.
792 * @see elm_map_overlay_content_get()
796 EAPI void elm_map_overlay_content_set(Elm_Map_Overlay *overlay, Evas_Object *obj);
799 * Get the content object.
801 * @param overlay The overlay to return the content.
802 * @return Return the evas object if it exists, else @c NULL.
804 * Only default and class type overlay support this function.
806 * Returned content is what being inside the overlay that being displayed.
808 * <b> Do not modify this object</b> (move, show, hide, del, etc.).
809 * You can only resize this.
811 * The content can be set by elm_map_overlay_content_set().
813 * @see elm_map_overlay_content_set()
817 EAPI const Evas_Object * elm_map_overlay_content_get(const Elm_Map_Overlay *overlay);
820 * Set a icon of the overlay.
822 * @param overlay The overlay to be set the icon.
823 * @param icon The icon will be used to display the overlay.
825 * Only default and class type overlay support this function.
827 * <b> Do not modify this object</b> (move, show, hide, resize, del, etc.),
830 * If icon is set, default style layout will not be used.
832 * If @p icon is @c NULL, icon inside the overlay will be deleted.
834 * @see elm_map_overlay_icon_get()
838 EAPI void elm_map_overlay_icon_set(Elm_Map_Overlay *overlay, Evas_Object *icon);
841 * Get the icon object.
843 * @param overlay The overlay to return the icon.
844 * @return Return the icon object if it exists, else @c NULL.
846 * Only default and class type overlay support this function.
848 * Returned icon is what being inside the overlay that being displayed.
850 * <b> Do not modify this icon </b> (move, show, hide, resize, del, etc.).
852 * The icon can be set by elm_map_overlay_icon_set().
854 * @see elm_map_overlay_icon_set()
858 EAPI const Evas_Object * elm_map_overlay_icon_get(const Elm_Map_Overlay *overlay);
861 * Set the geographic coordinates of the overlay.
863 * @param overlay The overlay to be set geographic coordinates.
864 * @param lon Longitude to be set.
865 * @param lat Latitude to be set.
867 * Only default and bubble type overlay support this function.
869 * This sets the center coordinates of the overlay. It can be
870 * get by elm_map_overlay_region_get().
872 * @see elm_map_overlay_region_get()
876 EAPI void elm_map_overlay_region_set(Elm_Map_Overlay *overlay, double lon, double lat);
879 * Get the geographic coordinates of the overlay.
881 * @param overlay The overlay to return geographic coordinates.
882 * @param lon Pointer to store longitude.
883 * @param lat Pointer to store latitude.
885 * Only default and bubble type overlay support this function.
887 * This returns the center coordinates of the overlay. It can be
888 * set by elm_map_overlay_region_set().
890 * @see elm_map_overlay_region_set()
894 EAPI void elm_map_overlay_region_get(const Elm_Map_Overlay *overlay, double *lon, double *lat);
898 * Set the object color of the overlay.
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.
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.
911 * These component values should be integers in the range 0 to 255,
912 * (single 8-bit byte).
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).
917 * For alpha channel, 0 represents completely transparent, and 255, opaque.
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.
922 * @see elm_map_overlay_color_get()
926 EAPI void elm_map_overlay_color_set(Elm_Map_Overlay *overlay, int r, int g, int b, int a);
929 * Get the object color of the overlay.
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.
937 * @see elm_map_overlay_color_set()
941 EAPI void elm_map_overlay_color_get(const Elm_Map_Overlay *overlay, int *r, int *g, int *b, int *a);
944 * Show the given overlay at the center of the map, immediately.
946 * @param overlay The overlay to be center at.
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.
952 * @see elm_map_overlays_show() if more than one overlay need to be displayed.
956 EAPI void elm_map_overlay_show(Elm_Map_Overlay *overlay);
959 * Move and zoom the map to display a list of overlays.
961 * @param overlays A list of #Elm_Map_Overlay handles.
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.
967 * @warning All the overlays should belong to the same map object.
969 * @see elm_map_overlay_show() to show a single overlay.
973 EAPI void elm_map_overlays_show(Eina_List *overlays);
976 * Set the get callback function of the overlay.
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.
982 * If the overlay is clicked, the callback wll be called.
983 * The clicked overlay is returned by callback.
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.
988 * You can delete this callback function by setting @c NULL.
992 EAPI void elm_map_overlay_get_cb_set(Elm_Map_Overlay *overlay, Elm_Map_Overlay_Get_Cb get_cb, void *data);
995 * Set the get callback function to call when the overlay is deleted.
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.
1001 * If the overlay is deleted, the callback wll be called.
1002 * The deleted overlay is returned by callback.
1004 * You can delete this callback function by setting @c NULL.
1010 EAPI void elm_map_overlay_del_cb_set(Elm_Map_Overlay *overlay, Elm_Map_Overlay_Del_Cb del_cb, void *data);
1013 * Add a new class overlay to the map object.
1014 * This overlay has a class type.
1016 * @param obj The map object to add a new overlay.
1017 * @return The created overlay or @c NULL upon failure.
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.
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.
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.
1031 * @see elm_map_overlay_del()
1032 * @see elm_map_overlay_add()
1033 * @see elm_map_overlay_bubble_add()
1037 EAPI Elm_Map_Overlay * elm_map_overlay_class_add(Evas_Object *obj);
1040 * Add a new overlay member to the class overlay.
1042 * @param clas The class overlay to add a new overlay.
1043 * @param overlay The overlay to be added to the class overlay.
1045 * @see elm_map_overlay_class_remove()
1049 EAPI void elm_map_overlay_class_append(Elm_Map_Overlay *clas, Elm_Map_Overlay *overlay);
1052 * Remove a overlay from the class.
1054 * @param clas The class overlay to delete the overlay.
1055 * @param overlay The overlay to be deleted from the class overlay.
1057 * @see elm_map_overlay_class_append()
1061 EAPI void elm_map_overlay_class_remove(Elm_Map_Overlay *clas, Elm_Map_Overlay *overlay);
1064 * Set the maximum zoom from where the overlay members in the class can be
1067 * @param clas The overlay class has overlay members.
1068 * @param zoom The maximum zoom.
1070 * Overlay members in the class only will be grouped when the map
1071 * is displayed at less than @p zoom.
1073 * @see elm_map_overlay_class_zoom_max_get()
1077 EAPI void elm_map_overlay_class_zoom_max_set(Elm_Map_Overlay *clas, int zoom);
1080 * Get the maximum zoom from where the overlay members in the class can be
1083 * @param clas The overlay class has overlay members.
1085 * @return The maximum zoom.
1087 * @see elm_map_overlay_class_zoom_max_set()
1091 EAPI int elm_map_overlay_class_zoom_max_get(const Elm_Map_Overlay *clas);
1094 * Get the overlay members of the group overlay.
1096 * @param grp The group overlay has overlay members.
1098 * @return The list of group overlay members.
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.
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.
1108 * @see elm_map_overlay_class_add()
1112 EAPI Eina_List * elm_map_overlay_group_members_get(const Elm_Map_Overlay *grp);
1115 * Add a new bubble overlay to the map object.
1116 * This overlay has a bubble type.
1118 * @param obj The map object to add a new overlay.
1119 * @return The created overlay or @c NULL upon failure.
1121 * A bubble will not be displayed before geographic coordinates are set or
1122 * any other overlays are followed.
1124 * This overlay has a bubble style layout and icon or content can not
1127 * Overlay created with this method can be deleted with elm_map_overlay_del().
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()
1137 EAPI Elm_Map_Overlay * elm_map_overlay_bubble_add(Evas_Object *obj);
1140 * Follow a other overlay.
1142 * @param bubble The bubble overlay to follow a parent overlay.
1143 * @param parent The parent overlay to be followed by the bubble overlay.
1145 * Bubble overlay will follow the parent overlay's movement (hide, show, move).
1147 * @see elm_map_overlay_bubble_add()
1151 EAPI void elm_map_overlay_bubble_follow(Elm_Map_Overlay *bubble, const Elm_Map_Overlay *parent);
1154 * Add a content object to the bubble overlay.
1156 * @param bubble The bubble overlay to add a content.
1157 * @param content The content to be added to the bubble overlay.
1159 * Added contents will be displayed inside the bubble overlay.
1161 * @see elm_map_overlay_bubble_content_clear()
1165 EAPI void elm_map_overlay_bubble_content_append(Elm_Map_Overlay *bubble, Evas_Object *content);
1168 * Clear all contents inside the bubble overlay.
1170 * @param bubble The bubble overlay to clear the contents.
1172 * This will delete all contents inside the bubble overlay.
1174 * @see elm_map_overlay_bubble_content_append()
1178 EAPI void elm_map_overlay_bubble_content_clear(Elm_Map_Overlay *bubble);
1181 * Add a new route overlay to the map object.
1182 * This overlay has a route type.
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.
1188 * This overlay has a route style layout and icon or content can not
1191 * The color scheme can be changed by elm_map_overlay_content_set().
1193 * Overlay created with this method can be deleted with elm_map_overlay_del().
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()
1202 EAPI Elm_Map_Overlay * elm_map_overlay_route_add(Evas_Object *obj, const Elm_Map_Route *route);
1205 * Add a new line overlay to the map object.
1206 * This overlay has a line type.
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.
1215 * Overlay created with this method can be deleted with elm_map_overlay_del().
1217 * @see elm_map_overlay_del()
1221 EAPI Elm_Map_Overlay * elm_map_overlay_line_add(Evas_Object *obj, double flon, double flat, double tlon, double tlat);
1224 * Add a new polygon overlay to the map object.
1225 * This overlay has a polygon type.
1227 * @param obj The map object to add a new overlay.
1228 * @return The created overlay or @c NULL upon failure.
1230 * At least 3 regions should be added to show the polygon overlay.
1232 * Overlay created with this method can be deleted with elm_map_overlay_del().
1234 * @see elm_map_overlay_polygon_region_add()
1235 * @see elm_map_overlay_del()
1239 EAPI Elm_Map_Overlay * elm_map_overlay_polygon_add(Evas_Object *obj);
1242 * Add a geographic coordinates to the polygon overlay.
1244 * @param overlay The polygon overlay to get a region.
1245 * @param lon The longitude.
1246 * @param lat The latitude.
1248 * At least 3 regions should be added to show the polygon overlay.
1250 * Overlay created with this method can be deleted with elm_map_overlay_del().
1252 * @see elm_map_overlay_polygon_add()
1253 * @see elm_map_overlay_del()
1257 EAPI void elm_map_overlay_polygon_region_add(Elm_Map_Overlay *overlay, double lon, double lat);
1260 * Add a new circle overlay to the map object.
1261 * This overlay has a circle type.
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.
1269 * Overlay created with this method can be deleted with elm_map_overlay_del().
1271 * @see elm_map_overlay_del()
1275 EAPI Elm_Map_Overlay * elm_map_overlay_circle_add(Evas_Object *obj, double lon, double lat, double radius);
1278 * Add a new scale overlay to the map object.
1279 * This overlay has a scale type.
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.
1286 * The scale overlay shows the ratio of a distance on the map to the corresponding distance.
1288 * Overlay created with this method can be deleted with elm_map_overlay_del().
1290 * @see elm_map_overlay_del()
1294 EAPI Elm_Map_Overlay * elm_map_overlay_scale_add(Evas_Object *obj, Evas_Coord x, Evas_Coord y);
1297 * Get the information of tile load status.
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.
1303 * This gets the current tile loaded status for the map object.
1307 EAPI void elm_map_tile_load_status_get(const Evas_Object *obj, int *try_num, int *finish_num);
1310 * Get the names of available sources for a specific type.
1312 * @param obj The map object.
1313 * @param type source type.
1314 * @return The char pointer array of source names.
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().
1320 * At least available sources of tile type:
1326 * At least available sources of route type:
1329 * At least available sources of name type:
1332 * @see elm_map_source_set()
1333 * @see elm_map_source_get()
1337 EAPI const char **elm_map_sources_get(const Evas_Object *obj, Elm_Map_Source_Type type);
1340 * Set the current source of the map for a specific type.
1342 * @param obj The map object.
1343 * @param type source type.
1344 * @param source_name The source to be used.
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.
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.
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.
1360 * The @p source_name need to match one of the names provided by
1361 * elm_map_sources_get().
1363 * The current source can be get using elm_map_source_get().
1365 * @see elm_map_sources_get()
1366 * @see elm_map_source_get()
1370 EAPI void elm_map_source_set(Evas_Object *obj, Elm_Map_Source_Type type, const char *source_name);
1373 * Get the name of currently used source for a specific type.
1375 * @param obj The map object.
1376 * @param type source type.
1377 * @return Returns the name of the source in use.
1379 * @see elm_map_sources_get()
1380 * @see elm_map_source_set()
1384 EAPI const char *elm_map_source_get(const Evas_Object *obj, Elm_Map_Source_Type type);
1387 * Get the names of available engines.
1389 * @param obj The map object.
1390 * @return The char pointer array of engine names.
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().
1396 * Defaultly tile engine is implemented.
1398 * @see elm_map_engine_set()
1399 * @see elm_map_engine_get()
1403 EAPI const char **elm_map_engines_get(const Evas_Object *obj);
1406 * Set the current engine of the map.
1408 * @param obj The map object.
1409 * @param engine_name The engine to be used.
1411 * The @p engine_name need to match one of the names provided by
1412 * elm_map_engines_get().
1414 * The current engine can be get using elm_map_engine_get().
1416 * Defaultly tile engine is used.
1418 * @see elm_map_engines_get()
1419 * @see elm_map_engine_get()
1423 EAPI void elm_map_engine_set(Evas_Object *obj, const char *engine_name);
1426 * Get the name of currently used engine.
1428 * @param obj The map object.
1429 * @return Returns the name of the engine in use.
1431 * @see elm_map_engines_get()
1432 * @see elm_map_engine_set()
1437 EAPI const char *elm_map_engine_get(const Evas_Object *obj);
1441 * Add a new route to the map object.
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.
1453 * @return The created route or @c NULL upon failure.
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().
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.
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.
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().
1472 * @see elm_map_route_del()
1473 * @see elm_map_route_distance_get()
1474 * @see elm_map_source_set()
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);
1481 * Remove a route from the map.
1483 * @param route The route to remove.
1485 * @see elm_map_route_add()
1489 EAPI void elm_map_route_del(Elm_Map_Route *route);
1492 * Get the route distance in kilometers.
1494 * @param route The route object.
1495 * @return The distance of route (unit : km).
1499 EAPI double elm_map_route_distance_get(const Elm_Map_Route *route);
1502 * Get the information of route nodes.
1504 * @param route The route object.
1505 * @return Returns a string with the nodes of route.
1509 EAPI const char *elm_map_route_node_get(const Elm_Map_Route *route);
1512 * Get the information of route waypoint.
1514 * @param route the route object.
1515 * @return Returns a string with information about waypoint of route.
1519 EAPI const char *elm_map_route_waypoint_get(const Elm_Map_Route *route);
1522 * Request a address or geographic coordinates(longitude, latitude)
1523 * from a given address or geographic coordinate(longitude, latitude).
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.
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.
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.
1540 * To get the longitude and latitude, elm_map_name_region_get()
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);
1548 * Request a list of addresses corresponding to a given name
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.
1555 * If you want to search address from a name.
1561 EAPI void elm_map_name_search(const Evas_Object *obj, const char *address, Elm_Map_Name_List_Cb name_cb, void *data);
1564 * Get the address of the name.
1566 * @param name The name handle.
1567 * @return Returns the address string of @p name.
1569 * This gets the coordinates of the @p name, created with one of the
1570 * conversion functions.
1572 * @see elm_map_name_add()
1576 EAPI const char *elm_map_name_address_get(const Elm_Map_Name *name);
1579 * Get the current coordinates of the name.
1581 * @param name The name handle.
1582 * @param lat Pointer to store the latitude.
1583 * @param lon Pointer to store The longitude.
1585 * This gets the coordinates of the @p name, created with one of the
1586 * conversion functions.
1588 * @see elm_map_name_add()
1592 EAPI void elm_map_name_region_get(const Elm_Map_Name *name, double *lon, double *lat);
1595 * Remove a name from the map.
1597 * @param name The name to remove.
1599 * Basically the struct handled by @p name will be freed, so conversions
1600 * between address and coordinates will be lost.
1602 * @see elm_map_name_add()
1606 EAPI void elm_map_name_del(Elm_Map_Name *name);
1609 * Add a track on the map
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.
1615 * @see elm_route_add() for details.
1619 EAPI Evas_Object *elm_map_track_add(Evas_Object *obj, void *emap);
1622 * Remove a track from the map
1624 * @param obj The map object.
1625 * @param route The track to remove.
1629 EAPI void elm_map_track_remove(Evas_Object *obj, Evas_Object *route);