135a99b96e4c0142ad5054bcc6f360552696b41b
[framework/uifw/elementary.git] / src / lib / elm_map.h
1 /**
2  * @defgroup Map Map
3  * @ingroup Elementary
4  *
5  * @image html img/widget/map/preview-00.png
6  * @image latex img/widget/map/preview-00.eps
7  *
8  * This is a widget specifically for displaying a map. It uses basically
9  * OpenStreetMap provider http://www.openstreetmap.org/,
10  * but custom providers can be added.
11  *
12  * It supports some basic but yet nice features:
13  * @li zoom and scroll
14  * @li markers with content to be displayed when user clicks over it
15  * @li group of markers
16  * @li routes
17  *
18  * Smart callbacks one can listen to:
19  *
20  * - "clicked" - This is called when a user has clicked the map without
21  *   dragging around.
22 <<<<<<< HEAD
23  * - "press" - This is called when a user has pressed down on the map.
24  * - "longpressed" - This is called when a user has pressed down on the map
25  *   for a long time without dragging around.
26  * - "clicked,double" - This is called when a user has double-clicked
27  *   the map.
28  * - "load,detail" - Map detailed data load begins.
29  * - "loaded,detail" - This is called when all currently visible parts of
30  *   the map are loaded.
31  * - "zoom,start" - Zoom animation started.
32  * - "zoom,stop" - Zoom animation stopped.
33  * - "zoom,change" - Zoom changed when using an auto zoom mode.
34  * - "scroll" - the content has been scrolled (moved).
35  * - "scroll,anim,start" - scrolling animation has started.
36  * - "scroll,anim,stop" - scrolling animation has stopped.
37  * - "scroll,drag,start" - dragging the contents around has started.
38  * - "scroll,drag,stop" - dragging the contents around has stopped.
39  * - "downloaded" - This is called when all currently required map images
40  *   are downloaded.
41  * - "route,load" - This is called when route request begins.
42  * - "route,loaded" - This is called when route request ends.
43  * - "name,load" - This is called when name request begins.
44  * - "name,loaded- This is called when name request ends.
45 =======
46  * - "clicked,double" - This is called when a user has double-clicked
47  *   the map.
48  * - "press" - This is called when a user has pressed down on the map.
49  * - "longpressed" - This is called when a user has pressed down on the map
50  *   for a long time without dragging around.
51  * - "scroll" - the content has been scrolled (moved).
52  * - "scroll,drag,start" - dragging the contents around has started.
53  * - "scroll,drag,stop" - dragging the contents around has stopped.
54  * - "scroll,anim,start" - scrolling animation has started.
55  * - "scroll,anim,stop" - scrolling animation has stopped.
56  * - "zoom,start" - Zoom animation started.
57  * - "zoom,stop" - Zoom animation stopped.
58  * - "zoom,change" - Zoom changed when using an auto zoom mode.
59  * - "tile,load" - A map tile image load begins.
60  * - "tile,loaded" -  A map tile image load ends.
61  * - "tile,loaded,fail" -  A map tile image load fails.
62  * - "route,load" - Route request begins.
63  * - "route,loaded" - Route request ends.
64  * - "route,loaded,fail" - Route request fails.
65  * - "name,load" - Name request begins.
66  * - "name,loaded" - Name request ends.
67  * - "name,loaded,fail" - Name request fails.
68  * - "overlay,clicked" - A overlay is clicked.
69 >>>>>>> remotes/origin/upstream
70  *
71  * Available style for map widget:
72  * - @c "default"
73  *
74  * Available style for markers:
75  * - @c "radio"
76  * - @c "radio2"
77  * - @c "empty"
78  *
79  * Available style for marker bubble:
80  * - @c "default"
81  *
82  * List of examples:
83  * @li @ref map_example_01
84  * @li @ref map_example_02
85  * @li @ref map_example_03
86  */
87
88 /**
89  * @addtogroup Map
90  * @{
91  */
92
93 /**
94  * Set map's zoom behavior. It can be set to manual or automatic.
95  *
96  * Default value is #ELM_MAP_ZOOM_MODE_MANUAL.
97  *
98 <<<<<<< HEAD
99  * Values <b> don't </b> work as bitmask, only one can be choosen.
100 =======
101  * Values <b> don't </b> work as bitmask, only one can be chosen.
102 >>>>>>> remotes/origin/upstream
103  *
104  * @note Valid sizes are 2^zoom, consequently the map may be smaller
105  * than the scroller view.
106  *
107  * @see elm_map_zoom_mode_set()
108  * @see elm_map_zoom_mode_get()
109  *
110  * @ingroup Map
111  */
112 typedef enum
113 {
114 <<<<<<< HEAD
115    ELM_MAP_ZOOM_MODE_MANUAL, /**< Zoom controlled manually by elm_map_zoom_set(). It's set by default. */
116    ELM_MAP_ZOOM_MODE_AUTO_FIT, /**< Zoom until map fits inside the scroll frame with no pixels outside this area. */
117    ELM_MAP_ZOOM_MODE_AUTO_FILL, /**< Zoom until map fills scroll, ensuring no pixels are left unfilled. */
118 =======
119    ELM_MAP_ZOOM_MODE_MANUAL,      /**< Zoom controlled manually by elm_map_zoom_set(). It's set by default. */
120    ELM_MAP_ZOOM_MODE_AUTO_FIT,    /**< Zoom until map fits inside the scroll frame with no pixels outside this area. */
121    ELM_MAP_ZOOM_MODE_AUTO_FILL,   /**< Zoom until map fills scroll, ensuring no pixels are left unfilled. */
122 >>>>>>> remotes/origin/upstream
123    ELM_MAP_ZOOM_MODE_LAST
124 } Elm_Map_Zoom_Mode;
125
126 /**
127 <<<<<<< HEAD
128  * Set route service to be used. By default used source is
129  * #ELM_MAP_ROUTE_SOURCE_YOURS.
130  *
131  * @see elm_map_route_source_set()
132  * @see elm_map_route_source_get()
133 =======
134  * Set type of a external source (provider).
135  *
136  * @see elm_map_sources_get()
137  * @see elm_map_source_get()
138  * @see elm_map_source_set()
139 >>>>>>> remotes/origin/upstream
140  *
141  * @ingroup Map
142  */
143 typedef enum
144 {
145 <<<<<<< HEAD
146    ELM_MAP_ROUTE_SOURCE_YOURS, /**< Routing service http://www.yournavigation.org/ . Set by default.*/
147    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. */
148    ELM_MAP_ROUTE_SOURCE_ORS, /**< Open Route Service: http://www.openrouteservice.org/ . It's not working with Map yet. */
149    ELM_MAP_ROUTE_SOURCE_LAST
150 } Elm_Map_Route_Sources;
151
152 typedef enum
153 {
154    ELM_MAP_NAME_SOURCE_NOMINATIM,
155    ELM_MAP_NAME_SOURCE_LAST
156 } Elm_Map_Name_Sources;
157 =======
158    ELM_MAP_SOURCE_TYPE_TILE,   /**< Map tile provider. */
159    ELM_MAP_SOURCE_TYPE_ROUTE,  /**< Route service provider. */
160    ELM_MAP_SOURCE_TYPE_NAME,   /**< Name service provider. */
161    ELM_MAP_SOURCE_TYPE_LAST
162 } Elm_Map_Source_Type;
163 >>>>>>> remotes/origin/upstream
164
165 /**
166  * Set type of transport used on route.
167  *
168  * @see elm_map_route_add()
169  *
170  * @ingroup Map
171  */
172 typedef enum
173 {
174 <<<<<<< HEAD
175    ELM_MAP_ROUTE_TYPE_MOTOCAR, /**< Route should consider an automobile will be used. */
176    ELM_MAP_ROUTE_TYPE_BICYCLE, /**< Route should consider a bicycle will be used by the user. */
177    ELM_MAP_ROUTE_TYPE_FOOT, /**< Route should consider user will be walking. */
178 =======
179    ELM_MAP_ROUTE_TYPE_MOTOCAR,   /**< Route should consider an automobile will be used. */
180    ELM_MAP_ROUTE_TYPE_BICYCLE,   /**< Route should consider a bicycle will be used by the user. */
181    ELM_MAP_ROUTE_TYPE_FOOT,      /**< Route should consider user will be walking. */
182 >>>>>>> remotes/origin/upstream
183    ELM_MAP_ROUTE_TYPE_LAST
184 } Elm_Map_Route_Type;
185
186 /**
187 <<<<<<< HEAD
188  * Set the routing method, what should be priorized, time or distance.
189 =======
190  * Set the routing method, what should be prioritized, time or distance.
191 >>>>>>> remotes/origin/upstream
192  *
193  * @see elm_map_route_add()
194  *
195  * @ingroup Map
196  */
197 typedef enum
198 {
199 <<<<<<< HEAD
200    ELM_MAP_ROUTE_METHOD_FASTEST, /**< Route should priorize time. */
201    ELM_MAP_ROUTE_METHOD_SHORTEST, /**< Route should priorize distance. */
202    ELM_MAP_ROUTE_METHOD_LAST
203 } Elm_Map_Route_Method;
204
205 =======
206    ELM_MAP_ROUTE_METHOD_FASTEST,  /**< Route should prioritize time. */
207    ELM_MAP_ROUTE_METHOD_SHORTEST, /**< Route should prioritized distance. */
208    ELM_MAP_ROUTE_METHOD_LAST
209 } Elm_Map_Route_Method;
210
211 /**
212  * Set the name search method.
213  *
214  * This is for name module interface.
215  *
216  * @ingroup Map
217  */
218 >>>>>>> remotes/origin/upstream
219 typedef enum
220 {
221    ELM_MAP_NAME_METHOD_SEARCH,
222    ELM_MAP_NAME_METHOD_REVERSE,
223    ELM_MAP_NAME_METHOD_LAST
224 } Elm_Map_Name_Method;
225
226 <<<<<<< HEAD
227 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(). */
228 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(). */
229 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(). */
230 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(). */
231 typedef struct _Elm_Map_Name         Elm_Map_Name; /**< A handle for specific coordinates. */
232 typedef struct _Elm_Map_Track        Elm_Map_Track;
233
234 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. */
235 typedef void                       (*ElmMapMarkerDelFunc)(Evas_Object *obj, Elm_Map_Marker *marker, void *data, Evas_Object *o); /**< Function to delete bubble content for marker classes. */
236 typedef Evas_Object               *(*ElmMapMarkerIconGetFunc)(Evas_Object *obj, Elm_Map_Marker *marker, void *data); /**< Icon fetching class function for marker classes. */
237 typedef Evas_Object               *(*ElmMapGroupIconGetFunc)(Evas_Object *obj, void *data); /**< Icon fetching class function for markers group classes. */
238
239 typedef char                      *(*ElmMapModuleSourceFunc)(void);
240 typedef int                        (*ElmMapModuleZoomMinFunc)(void);
241 typedef int                        (*ElmMapModuleZoomMaxFunc)(void);
242 typedef char                      *(*ElmMapModuleUrlFunc)(Evas_Object *obj, int x, int y, int zoom);
243 typedef int                        (*ElmMapModuleRouteSourceFunc)(void);
244 typedef char                      *(*ElmMapModuleRouteUrlFunc)(Evas_Object *obj, char *type_name, int method, double flon, double flat, double tlon, double tlat);
245 typedef char                      *(*ElmMapModuleNameUrlFunc)(Evas_Object *obj, int method, char *name, double lon, double lat);
246 typedef Eina_Bool                  (*ElmMapModuleGeoIntoCoordFunc)(const Evas_Object *obj, int zoom, double lon, double lat, int size, int *x, int *y);
247 typedef Eina_Bool                  (*ElmMapModuleCoordIntoGeoFunc)(const Evas_Object *obj, int zoom, int x, int y, int size, double *lon, double *lat);
248 =======
249 /**
250  * Set overlay type to be used. This type is resolved
251  * when the overlay is created.
252  * You can get this value by elm_map_overlay_type_get().
253  *
254  * @see elm_map_overlay_type_get()
255  * @see elm_map_overlay_add()
256  * @see elm_map_overlay_class_add()
257  * @see elm_map_overlay_bubble_add()
258  *
259  * @ingroup Map
260  */
261 typedef enum _Elm_Map_Overlay_Type
262 {
263    ELM_MAP_OVERLAY_TYPE_NONE = 0,
264    ELM_MAP_OVERLAY_TYPE_DEFAULT,
265    ELM_MAP_OVERLAY_TYPE_CLASS,
266    ELM_MAP_OVERLAY_TYPE_BUBBLE,
267    ELM_MAP_OVERLAY_TYPE_ROUTE
268 } Elm_Map_Overlay_Type;
269
270 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(). */
271 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(). */
272 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(). */
273 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(). */
274 typedef struct _Elm_Map_Name         Elm_Map_Name;         /**< A handle for specific coordinates. */
275 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(). */
276
277 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. */
278 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. */
279 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. */
280 typedef Evas_Object               *(*Elm_Map_Group_Icon_Get_Func)(Evas_Object *obj, void *data); /**< Icon fetching class function for markers group classes. */
281
282 typedef void                       (*Elm_Map_Overlay_Get_Cb)(void *data, Evas_Object *map, const Elm_Map_Overlay *overlay);   /**< Get callback function for the overlay. */
283 typedef void                       (*Elm_Map_Name_Cb)(void *data, Evas_Object *map, const Elm_Map_Name *name);                /**< Async-callback function for the name request. */
284 typedef void                       (*Elm_Map_Route_Cb)(void *data, Evas_Object *map, const Elm_Map_Route *route);             /**< Async-callback function for the route request. */
285 >>>>>>> remotes/origin/upstream
286
287 /**
288  * Add a new map widget to the given parent Elementary (container) object.
289  *
290  * @param parent The parent object.
291  * @return a new map widget handle or @c NULL, on errors.
292  *
293  * This function inserts a new map widget on the canvas.
294  *
295  * @ingroup Map
296  */
297 EAPI Evas_Object          *elm_map_add(Evas_Object *parent);
298
299 /**
300  * Set the zoom level of the map.
301  *
302  * @param obj The map object.
303  * @param zoom The zoom level to set.
304  *
305  * This sets the zoom level.
306  *
307 <<<<<<< HEAD
308  * It will respect limits defined by elm_map_source_zoom_min_set() and
309  * elm_map_source_zoom_max_set().
310 =======
311  * It will respect limits defined by elm_map_zoom_min_set() and
312  * elm_map_zoom_max_set().
313 >>>>>>> remotes/origin/upstream
314  *
315  * By default these values are 0 (world map) and 18 (maximum zoom).
316  *
317  * This function should be used when zoom mode is set to
318  * #ELM_MAP_ZOOM_MODE_MANUAL. This is the default mode, and can be set
319  * with elm_map_zoom_mode_set().
320  *
321 <<<<<<< HEAD
322  * @see elm_map_zoom_mode_set().
323  * @see elm_map_zoom_get().
324 =======
325  * @see elm_map_zoom_mode_set()
326  * @see elm_map_zoom_get()
327 >>>>>>> remotes/origin/upstream
328  *
329  * @ingroup Map
330  */
331 EAPI void                  elm_map_zoom_set(Evas_Object *obj, int zoom);
332
333 /**
334  * Get the zoom level of the map.
335  *
336  * @param obj The map object.
337  * @return The current zoom level.
338  *
339  * This returns the current zoom level of the map object.
340  *
341  * Note that if you set the fill mode to other than #ELM_MAP_ZOOM_MODE_MANUAL
342  * (which is the default), the zoom level may be changed at any time by the
343  * map object itself to account for map size and map viewport size.
344  *
345  * @see elm_map_zoom_set() for details.
346  *
347  * @ingroup Map
348  */
349 EAPI int                   elm_map_zoom_get(const Evas_Object *obj);
350
351 /**
352  * Set the zoom mode used by the map object.
353  *
354  * @param obj The map object.
355  * @param mode The zoom mode of the map, being it one of
356  * #ELM_MAP_ZOOM_MODE_MANUAL (default), #ELM_MAP_ZOOM_MODE_AUTO_FIT,
357  * or #ELM_MAP_ZOOM_MODE_AUTO_FILL.
358  *
359  * This sets the zoom mode to manual or one of the automatic levels.
360  * Manual (#ELM_MAP_ZOOM_MODE_MANUAL) means that zoom is set manually by
361  * elm_map_zoom_set() and will stay at that level until changed by code
362  * or until zoom mode is changed. This is the default mode.
363  *
364  * The Automatic modes will allow the map object to automatically
365  * adjust zoom mode based on properties. #ELM_MAP_ZOOM_MODE_AUTO_FIT will
366  * adjust zoom so the map fits inside the scroll frame with no pixels
367  * outside this area. #ELM_MAP_ZOOM_MODE_AUTO_FILL will be similar but
368  * ensure no pixels within the frame are left unfilled. Do not forget that
369  * the valid sizes are 2^zoom, consequently the map may be smaller than
370  * the scroller view.
371  *
372  * @see elm_map_zoom_set()
373  *
374  * @ingroup Map
375  */
376 EAPI void                  elm_map_zoom_mode_set(Evas_Object *obj, Elm_Map_Zoom_Mode mode);
377
378 /**
379  * Get the zoom mode used by the map object.
380  *
381  * @param obj The map object.
382  * @return The zoom mode of the map, being it one of
383  * #ELM_MAP_ZOOM_MODE_MANUAL (default), #ELM_MAP_ZOOM_MODE_AUTO_FIT,
384  * or #ELM_MAP_ZOOM_MODE_AUTO_FILL.
385  *
386  * This function returns the current zoom mode used by the map object.
387  *
388  * @see elm_map_zoom_mode_set() for more details.
389  *
390  * @ingroup Map
391  */
392 EAPI Elm_Map_Zoom_Mode     elm_map_zoom_mode_get(const Evas_Object *obj);
393
394 /**
395 <<<<<<< HEAD
396  * Get the current geographic coordinates of the map.
397  *
398  * @param obj The map object.
399  * @param lon Pointer where to store longitude.
400  * @param lat Pointer where to store latitude.
401  *
402  * This gets the current center coordinates of the map object. It can be
403  * set by elm_map_geo_region_bring_in() and elm_map_geo_region_show().
404  *
405  * @see elm_map_geo_region_bring_in()
406  * @see elm_map_geo_region_show()
407  *
408  * @ingroup Map
409  */
410 EAPI void                  elm_map_geo_region_get(const Evas_Object *obj, double *lon, double *lat);
411 =======
412  * Set the minimum zoom of the source.
413  *
414  * @param obj The map object.
415  * @param zoom New minimum zoom value to be used.
416  *
417  * By default, it's 0.
418  *
419  * @ingroup Map
420  */
421 EAPI void                  elm_map_zoom_min_set(Evas_Object *obj, int zoom);
422
423 /**
424  * Get the minimum zoom of the source.
425  *
426  * @param obj The map object.
427  * @return Returns the minimum zoom of the source.
428  *
429  * @see elm_map_zoom_min_set() for details.
430  *
431  * @ingroup Map
432  */
433 EAPI int                   elm_map_zoom_min_get(const Evas_Object *obj);
434
435 /**
436  * Set the maximum zoom of the source.
437  *
438  * @param obj The map object.
439  * @param zoom New maximum zoom value to be used.
440  *
441  * By default, it's 18.
442  *
443  * @ingroup Map
444  */
445 EAPI void                  elm_map_zoom_max_set(Evas_Object *obj, int zoom);
446
447 /**
448  * Get the maximum zoom of the source.
449  *
450  * @param obj The map object.
451  * @return Returns the maximum zoom of the source.
452  *
453  * @see elm_map_zoom_min_set() for details.
454  *
455  * @ingroup Map
456  */
457 EAPI int                   elm_map_zoom_max_get(const Evas_Object *obj);
458
459 /**
460  * Get the current geographic coordinates of the map.
461  *
462  * @param obj The map object.
463  * @param lon Pointer to store longitude.
464  * @param lat Pointer to store latitude.
465  *
466  * This gets the current center coordinates of the map object. It can be
467  * set by elm_map_region_bring_in() and elm_map_region_show().
468  *
469  * @see elm_map_region_bring_in()
470  * @see elm_map_region_show()
471  *
472  * @ingroup Map
473  */
474 EAPI void                  elm_map_region_get(const Evas_Object *obj, double *lon, double *lat);
475 >>>>>>> remotes/origin/upstream
476
477 /**
478  * Animatedly bring in given coordinates to the center of the map.
479  *
480  * @param obj The map object.
481  * @param lon Longitude to center at.
482  * @param lat Latitude to center at.
483  *
484  * This causes map to jump to the given @p lat and @p lon coordinates
485  * and show it (by scrolling) in the center of the viewport, if it is not
486  * already centered. This will use animation to do so and take a period
487  * of time to complete.
488  *
489 <<<<<<< HEAD
490  * @see elm_map_geo_region_show() for a function to avoid animation.
491  * @see elm_map_geo_region_get()
492  *
493  * @ingroup Map
494  */
495 EAPI void                  elm_map_geo_region_bring_in(Evas_Object *obj, double lon, double lat);
496 =======
497  * @see elm_map_region_show() for a function to avoid animation.
498  * @see elm_map_region_get()
499  *
500  * @ingroup Map
501  */
502 EAPI void                  elm_map_region_bring_in(Evas_Object *obj, double lon, double lat);
503 >>>>>>> remotes/origin/upstream
504
505 /**
506  * Show the given coordinates at the center of the map, @b immediately.
507  *
508  * @param obj The map object.
509  * @param lon Longitude to center at.
510  * @param lat Latitude to center at.
511  *
512  * This causes map to @b redraw its viewport's contents to the
513 <<<<<<< HEAD
514  * region contining the given @p lat and @p lon, that will be moved to the
515  * center of the map.
516  *
517  * @see elm_map_geo_region_bring_in() for a function to move with animation.
518  * @see elm_map_geo_region_get()
519  *
520  * @ingroup Map
521  */
522 EAPI void                  elm_map_geo_region_show(Evas_Object *obj, double lon, double lat);
523
524 /**
525  * Pause or unpause the map.
526  *
527  * @param obj The map object.
528  * @param paused Use @c EINA_TRUE to pause the map @p obj or @c EINA_FALSE
529  * to unpause it.
530  *
531  * This sets the paused state to on (@c EINA_TRUE) or off (@c EINA_FALSE)
532  * for map.
533  *
534  * The default is off.
535  *
536  * This will stop zooming using animation, changing zoom levels will
537  * change instantly. This will stop any existing animations that are running.
538  *
539  * @see elm_map_paused_get()
540  *
541  * @ingroup Map
542  */
543 EAPI void                  elm_map_paused_set(Evas_Object *obj, Eina_Bool paused);
544
545 /**
546  * Get a value whether map is paused or not.
547  *
548  * @param obj The map object.
549  * @return @c EINA_TRUE means map is pause. @c EINA_FALSE indicates
550  * it is not. If @p obj is @c NULL, @c EINA_FALSE is returned.
551  *
552  * This gets the current paused state for the map object.
553  *
554  * @see elm_map_paused_set() for details.
555  *
556  * @ingroup Map
557  */
558 EAPI Eina_Bool             elm_map_paused_get(const Evas_Object *obj);
559
560 /**
561  * Set to show markers during zoom level changes or not.
562  *
563  * @param obj The map object.
564  * @param paused Use @c EINA_TRUE to @b not show markers or @c EINA_FALSE
565  * to show them.
566 =======
567  * region containing the given @p lat and @p lon, that will be moved to the
568  * center of the map.
569  *
570  * @see elm_map_region_bring_in() for a function to move with animation.
571  * @see elm_map_region_get()
572  *
573  * @ingroup Map
574  */
575 EAPI void                  elm_map_region_show(Evas_Object *obj, double lon, double lat);
576
577 /**
578  * Convert canvas coordinates into geographic coordinates
579  * (longitude, latitude).
580  *
581  * @param obj The map object.
582  * @param x   horizontal coordinate of the point to convert.
583  * @param y   vertical coordinate of the point to convert.
584  * @param lon A pointer to the longitude.
585  * @param lat A pointer to the latitude.
586  *
587  * This gets longitude and latitude from canvas x, y coordinates. The canvas
588  * coordinates mean x, y coordinate from current viewport.
589  *
590  * see elm_map_region_to_canvas_convert()
591  *
592  * @ingroup Map
593  */
594 EAPI void                  elm_map_canvas_to_region_convert(const Evas_Object *obj, const Evas_Coord x, const Evas_Coord y, double *lon, double *lat);
595
596 /**
597  * Convert geographic coordinates (longitude, latitude)
598  * into canvas coordinates.
599  *
600  * @param obj The map object.
601  * @param lon The longitude to convert.
602  * @param lat The latitude to convert.
603  * @param x   A pointer to horizontal coordinate.
604  * @param y   A pointer to vertical coordinate.
605  *
606  * This gets canvas x, y coordinates from longitude and latitude. The canvas
607  * coordinates mean x, y coordinate from current viewport.
608  *
609  * see elm_map_canvas_to_region_convert()
610  *
611  * @ingroup Map
612  */
613 EAPI void                  elm_map_region_to_canvas_convert(const Evas_Object *obj, double lon, double lat, Evas_Coord *x, Evas_Coord *y);
614
615 /**
616  * Pause or unpause the map.
617  *
618  * @param obj The map object.
619  * @param paused Use @c EINA_TRUE to pause the map @p obj or @c EINA_FALSE
620  * to unpause it.
621 >>>>>>> remotes/origin/upstream
622  *
623  * This sets the paused state to on (@c EINA_TRUE) or off (@c EINA_FALSE)
624  * for map.
625  *
626  * The default is off.
627  *
628  * This will stop zooming using animation, changing zoom levels will
629  * change instantly. This will stop any existing animations that are running.
630  *
631 <<<<<<< HEAD
632  * This sets the paused state to on (@c EINA_TRUE) or off (@c EINA_FALSE)
633  * for the markers.
634  *
635  * The default  is off.
636  *
637  * Enabling it will force the map to stop displaying the markers during
638  * zoom level changes. Set to on if you have a large number of markers.
639  *
640  * @see elm_map_paused_markers_get()
641  *
642  * @ingroup Map
643  */
644 EAPI void                  elm_map_paused_markers_set(Evas_Object *obj, Eina_Bool paused);
645
646 /**
647  * Get a value whether markers will be displayed on zoom level changes or not
648  *
649  * @param obj The map object.
650  * @return @c EINA_TRUE means map @b won't display markers or @c EINA_FALSE
651  * indicates it will. If @p obj is @c NULL, @c EINA_FALSE is returned.
652  *
653  * This gets the current markers paused state for the map object.
654  *
655  * @see elm_map_paused_markers_set() for details.
656  *
657  * @ingroup Map
658  */
659 EAPI Eina_Bool             elm_map_paused_markers_get(const Evas_Object *obj);
660
661 /**
662  * Get the information of downloading status.
663  *
664  * @param obj The map object.
665  * @param try_num Pointer where to store number of tiles being downloaded.
666  * @param finish_num Pointer where to store number of tiles successfully
667  * downloaded.
668  *
669  * This gets the current downloading status for the map object, the number
670  * of tiles being downloaded and the number of tiles already downloaded.
671  *
672  * @ingroup Map
673  */
674 EAPI void                  elm_map_utils_downloading_status_get(const Evas_Object *obj, int *try_num, int *finish_num);
675
676 /**
677  * Convert a pixel coordinate (x,y) into a geographic coordinate
678  * (longitude, latitude).
679  *
680  * @param obj The map object.
681  * @param x the coordinate.
682  * @param y the coordinate.
683  * @param size the size in pixels of the map.
684  * The map is a square and generally his size is : pow(2.0, zoom)*256.
685  * @param lon Pointer where to store the longitude that correspond to x.
686  * @param lat Pointer where to store the latitude that correspond to y.
687  *
688  * @note Origin pixel point is the top left corner of the viewport.
689  * Map zoom and size are taken on account.
690  *
691  * @see elm_map_utils_convert_geo_into_coord() if you need the inverse.
692  *
693  * @ingroup Map
694  */
695 EAPI void                  elm_map_utils_convert_coord_into_geo(const Evas_Object *obj, int x, int y, int size, double *lon, double *lat);
696
697 /**
698  * Convert a geographic coordinate (longitude, latitude) into a pixel
699  * coordinate (x, y).
700  *
701  * @param obj The map object.
702  * @param lon the longitude.
703  * @param lat the latitude.
704  * @param size the size in pixels of the map. The map is a square
705  * and generally his size is : pow(2.0, zoom)*256.
706  * @param x Pointer where to store the horizontal pixel coordinate that
707  * correspond to the longitude.
708  * @param y Pointer where to store the vertical pixel coordinate that
709  * correspond to the latitude.
710  *
711  * @note Origin pixel point is the top left corner of the viewport.
712  * Map zoom and size are taken on account.
713  *
714  * @see elm_map_utils_convert_coord_into_geo() if you need the inverse.
715  *
716  * @ingroup Map
717  */
718 EAPI void                  elm_map_utils_convert_geo_into_coord(const Evas_Object *obj, double lon, double lat, int size, int *x, int *y);
719
720 /**
721  * Convert a geographic coordinate (longitude, latitude) into a name
722  * (address).
723  *
724  * @param obj The map object.
725  * @param lon the longitude.
726  * @param lat the latitude.
727  * @return name A #Elm_Map_Name handle for this coordinate.
728  *
729  * To get the string for this address, elm_map_name_address_get()
730  * should be used.
731  *
732  * @see elm_map_utils_convert_name_into_coord() if you need the inverse.
733  *
734  * @ingroup Map
735  */
736 EAPI Elm_Map_Name         *elm_map_utils_convert_coord_into_name(const Evas_Object *obj, double lon, double lat);
737
738 /**
739  * Convert a name (address) into a geographic coordinate
740  * (longitude, latitude).
741  *
742  * @param obj The map object.
743  * @param name The address.
744  * @return name A #Elm_Map_Name handle for this address.
745  *
746  * To get the longitude and latitude, elm_map_name_region_get()
747  * should be used.
748  *
749  * @see elm_map_utils_convert_coord_into_name() if you need the inverse.
750  *
751  * @ingroup Map
752  */
753 EAPI Elm_Map_Name         *elm_map_utils_convert_name_into_coord(const Evas_Object *obj, char *address);
754
755 /**
756  * Convert canvas coordinates into a geographic coordinate
757  * (longitude, latitude).
758  *
759  * @param obj The map object.
760  * @param x   horizontal coordinate of the point to convert.
761  * @param y   vertical coordinate of the point to convert.
762  * @param lon A poniter to the longitude.
763  * @param lat A pointer to the latitude.
764  *
765  * This gets longitude and latitude from canvas x, y coordinates. The canvas
766  * coordinates mean x, y coordinate from current viewport.
767  * elm_map_utils_convert_coord_into_geo() internally to get the geographic
768  * location.
769  *
770  * see elm_map_rotate_get()
771  * see elm_map_utils_convert_coord_into_geo()
772  *
773  * @ingroup Map
774  */
775 EAPI void                  elm_map_canvas_to_geo_convert(const Evas_Object *obj, const Evas_Coord x, const Evas_Coord y, double *lon, double *lat);
776
777 /**
778  * Add a new marker to the map object.
779  *
780  * @param obj The map object.
781  * @param lon The longitude of the marker.
782  * @param lat The latitude of the marker.
783  * @param clas The class, to use when marker @b isn't grouped to others.
784  * @param clas_group The class group, to use when marker is grouped to others
785  * @param data The data passed to the callbacks.
786  *
787  * @return The created marker or @c NULL upon failure.
788  *
789  * A marker will be created and shown in a specific point of the map, defined
790  * by @p lon and @p lat.
791  *
792  * It will be displayed using style defined by @p class when this marker
793  * is displayed alone (not grouped). A new class can be created with
794  * elm_map_marker_class_new().
795  *
796  * If the marker is grouped to other markers, it will be displayed with
797  * style defined by @p class_group. Markers with the same group are grouped
798  * if they are close. A new group class can be created with
799  * elm_map_marker_group_class_new().
800  *
801  * Markers created with this method can be deleted with
802  * elm_map_marker_remove().
803  *
804  * A marker can have associated content to be displayed by a bubble,
805  * when a user click over it, as well as an icon. These objects will
806  * be fetch using class' callback functions.
807  *
808  * @see elm_map_marker_class_new()
809  * @see elm_map_marker_group_class_new()
810  * @see elm_map_marker_remove()
811  *
812  * @ingroup Map
813  */
814 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);
815
816 /**
817  * Set the maximum numbers of markers' content to be displayed in a group.
818  *
819  * @param obj The map object.
820  * @param max The maximum numbers of items displayed in a bubble.
821  *
822  * A bubble will be displayed when the user clicks over the group,
823  * and will place the content of markers that belong to this group
824  * inside it.
825  *
826  * A group can have a long list of markers, consequently the creation
827  * of the content of the bubble can be very slow.
828  *
829  * In order to avoid this, a maximum number of items is displayed
830  * in a bubble.
831  *
832  * By default this number is 30.
833  *
834  * Marker with the same group class are grouped if they are close.
835  *
836  * @see elm_map_marker_add()
837  *
838  * @ingroup Map
839  */
840 EAPI void                  elm_map_max_marker_per_group_set(Evas_Object *obj, int max);
841
842 /**
843  * Remove a marker from the map.
844  *
845  * @param marker The marker to remove.
846  *
847  * @see elm_map_marker_add()
848  *
849  * @ingroup Map
850  */
851 EAPI void                  elm_map_marker_remove(Elm_Map_Marker *marker);
852
853 /**
854  * Get the current coordinates of the marker.
855  *
856  * @param marker marker.
857  * @param lat Pointer where to store the marker's latitude.
858  * @param lon Pointer where to store the marker's longitude.
859  *
860  * These values are set when adding markers, with function
861  * elm_map_marker_add().
862  *
863  * @see elm_map_marker_add()
864  *
865  * @ingroup Map
866  */
867 EAPI void                  elm_map_marker_region_get(const Elm_Map_Marker *marker, double *lon, double *lat);
868
869 /**
870  * Animatedly bring in given marker to the center of the map.
871  *
872  * @param marker The marker to center at.
873  *
874  * This causes map to jump to the given @p marker's coordinates
875  * and show it (by scrolling) in the center of the viewport, if it is not
876  * already centered. This will use animation to do so and take a period
877  * of time to complete.
878  *
879  * @see elm_map_marker_show() for a function to avoid animation.
880  * @see elm_map_marker_region_get()
881  *
882  * @ingroup Map
883  */
884 EAPI void                  elm_map_marker_bring_in(Elm_Map_Marker *marker);
885
886 /**
887  * Show the given marker at the center of the map, @b immediately.
888  *
889  * @param marker The marker to center at.
890  *
891  * This causes map to @b redraw its viewport's contents to the
892  * region contining the given @p marker's coordinates, that will be
893  * moved to the center of the map.
894  *
895  * @see elm_map_marker_bring_in() for a function to move with animation.
896  * @see elm_map_markers_list_show() if more than one marker need to be
897  * displayed.
898  * @see elm_map_marker_region_get()
899  *
900  * @ingroup Map
901  */
902 EAPI void                  elm_map_marker_show(Elm_Map_Marker *marker);
903
904 /**
905  * Move and zoom the map to display a list of markers.
906  *
907  * @param markers A list of #Elm_Map_Marker handles.
908  *
909  * The map will be centered on the center point of the markers in the list.
910  * Then the map will be zoomed in order to fit the markers using the maximum
911  * zoom which allows display of all the markers.
912  *
913  * @warning All the markers should belong to the same map object.
914  *
915  * @see elm_map_marker_show() to show a single marker.
916  * @see elm_map_marker_bring_in()
917  *
918  * @ingroup Map
919  */
920 EAPI void                  elm_map_markers_list_show(Eina_List *markers);
921
922 /**
923  * Get the Evas object returned by the ElmMapMarkerGetFunc callback
924  *
925  * @param marker The marker wich content should be returned.
926  * @return Return the evas object if it exists, else @c NULL.
927  *
928  * To set callback function #ElmMapMarkerGetFunc for the marker class,
929  * elm_map_marker_class_get_cb_set() should be used.
930  *
931  * This content is what will be inside the bubble that will be displayed
932  * when an user clicks over the marker.
933  *
934  * This returns the actual Evas object used to be placed inside
935  * the bubble. This may be @c NULL, as it may
936  * not have been created or may have been deleted, at any time, by
937  * the map. <b>Do not modify this object</b> (move, resize,
938  * show, hide, etc.), as the map is controlling it. This
939  * function is for querying, emitting custom signals or hooking
940  * lower level callbacks for events on that object. Do not delete
941  * this object under any circumstances.
942  *
943  * @ingroup Map
944  */
945 EAPI Evas_Object          *elm_map_marker_object_get(const Elm_Map_Marker *marker);
946
947 /**
948  * Update the marker
949  *
950  * @param marker The marker to be updated.
951  *
952  * If a content is set to this marker, it will call function to delete it,
953  * #ElmMapMarkerDelFunc, and then will fetch the content again with
954  * #ElmMapMarkerGetFunc.
955  *
956  * These functions are set for the marker class with
957  * elm_map_marker_class_get_cb_set() and elm_map_marker_class_del_cb_set().
958  *
959  * @ingroup Map
960  */
961 EAPI void                  elm_map_marker_update(Elm_Map_Marker *marker);
962
963 /**
964  * Close all the bubbles opened by the user.
965  *
966  * @param obj The map object.
967  *
968  * A bubble is displayed with a content fetched with #ElmMapMarkerGetFunc
969  * when the user clicks on a marker.
970  *
971  * This functions is set for the marker class with
972  * elm_map_marker_class_get_cb_set().
973  *
974  * @ingroup Map
975  */
976 EAPI void                  elm_map_bubbles_close(Evas_Object *obj);
977
978 /**
979  * Create a new group class.
980  *
981  * @param obj The map object.
982  * @return Returns the new group class.
983  *
984  * Each marker must be associated to a group class. Markers in the same
985  * group are grouped if they are close.
986  *
987  * The group class defines the style of the marker when a marker is grouped
988  * to others markers. When it is alone, another class will be used.
989  *
990  * A group class will need to be provided when creating a marker with
991  * elm_map_marker_add().
992  *
993  * Some properties and functions can be set by class, as:
994  * - style, with elm_map_group_class_style_set()
995  * - data - to be associated to the group class. It can be set using
996  *   elm_map_group_class_data_set().
997  * - min zoom to display markers, set with
998  *   elm_map_group_class_zoom_displayed_set().
999  * - max zoom to group markers, set using
1000  *   elm_map_group_class_zoom_grouped_set().
1001  * - visibility - set if markers will be visible or not, set with
1002  *   elm_map_group_class_hide_set().
1003  * - #ElmMapGroupIconGetFunc - used to fetch icon for markers group classes.
1004  *   It can be set using elm_map_group_class_icon_cb_set().
1005  *
1006  * @see elm_map_marker_add()
1007  * @see elm_map_group_class_style_set()
1008  * @see elm_map_group_class_data_set()
1009  * @see elm_map_group_class_zoom_displayed_set()
1010  * @see elm_map_group_class_zoom_grouped_set()
1011  * @see elm_map_group_class_hide_set()
1012  * @see elm_map_group_class_icon_cb_set()
1013  *
1014  * @ingroup Map
1015  */
1016 EAPI Elm_Map_Group_Class  *elm_map_group_class_new(Evas_Object *obj);
1017
1018 /**
1019  * Set the marker's style of a group class.
1020  *
1021  * @param clas The group class.
1022  * @param style The style to be used by markers.
1023  *
1024  * Each marker must be associated to a group class, and will use the style
1025  * defined by such class when grouped to other markers.
1026  *
1027  * The following styles are provided by default theme:
1028  * @li @c radio - blue circle
1029  * @li @c radio2 - green circle
1030  * @li @c empty
1031  *
1032  * @see elm_map_group_class_new() for more details.
1033  * @see elm_map_marker_add()
1034  *
1035  * @ingroup Map
1036  */
1037 EAPI void                  elm_map_group_class_style_set(Elm_Map_Group_Class *clas, const char *style);
1038
1039 /**
1040  * Set the icon callback function of a group class.
1041  *
1042  * @param clas The group class.
1043  * @param icon_get The callback function that will return the icon.
1044  *
1045  * Each marker must be associated to a group class, and it can display a
1046  * custom icon. The function @p icon_get must return this icon.
1047  *
1048  * @see elm_map_group_class_new() for more details.
1049  * @see elm_map_marker_add()
1050  *
1051  * @ingroup Map
1052  */
1053 EAPI void                  elm_map_group_class_icon_cb_set(Elm_Map_Group_Class *clas, ElmMapGroupIconGetFunc icon_get);
1054
1055 /**
1056  * Set the data associated to the group class.
1057  *
1058  * @param clas The group class.
1059  * @param data The new user data.
1060  *
1061  * This data will be passed for callback functions, like icon get callback,
1062  * that can be set with elm_map_group_class_icon_cb_set().
1063  *
1064  * If a data was previously set, the object will lose the pointer for it,
1065  * so if needs to be freed, you must do it yourself.
1066  *
1067  * @see elm_map_group_class_new() for more details.
1068  * @see elm_map_group_class_icon_cb_set()
1069  * @see elm_map_marker_add()
1070  *
1071  * @ingroup Map
1072  */
1073 EAPI void                  elm_map_group_class_data_set(Elm_Map_Group_Class *clas, void *data);
1074
1075 /**
1076  * Set the minimum zoom from where the markers are displayed.
1077  *
1078  * @param clas The group class.
1079  * @param zoom The minimum zoom.
1080  *
1081  * Markers only will be displayed when the map is displayed at @p zoom
1082  * or bigger.
1083  *
1084  * @see elm_map_group_class_new() for more details.
1085  * @see elm_map_marker_add()
1086  *
1087  * @ingroup Map
1088  */
1089 EAPI void                  elm_map_group_class_zoom_displayed_set(Elm_Map_Group_Class *clas, int zoom);
1090
1091 /**
1092  * Set the zoom from where the markers are no more grouped.
1093  *
1094  * @param clas The group class.
1095  * @param zoom The maximum zoom.
1096  *
1097  * Markers only will be grouped when the map is displayed at
1098  * less than @p zoom.
1099  *
1100  * @see elm_map_group_class_new() for more details.
1101  * @see elm_map_marker_add()
1102  *
1103  * @ingroup Map
1104  */
1105 EAPI void                  elm_map_group_class_zoom_grouped_set(Elm_Map_Group_Class *clas, int zoom);
1106
1107 /**
1108  * Set if the markers associated to the group class @p clas are hidden or not.
1109  *
1110  * @param clas The group class.
1111  * @param hide Use @c EINA_TRUE to hide markers or @c EINA_FALSE
1112  * to show them.
1113  *
1114  * If @p hide is @c EINA_TRUE the markers will be hidden, but default
1115  * is to show them.
1116  *
1117  * @ingroup Map
1118  */
1119 EAPI void                  elm_map_group_class_hide_set(Evas_Object *obj, Elm_Map_Group_Class *clas, Eina_Bool hide);
1120
1121 /**
1122  * Create a new marker class.
1123  *
1124  * @param obj The map object.
1125  * @return Returns the new group class.
1126  *
1127  * Each marker must be associated to a class.
1128  *
1129  * The marker class defines the style of the marker when a marker is
1130  * displayed alone, i.e., not grouped to to others markers. When grouped
1131  * it will use group class style.
1132  *
1133  * A marker class will need to be provided when creating a marker with
1134  * elm_map_marker_add().
1135  *
1136  * Some properties and functions can be set by class, as:
1137  * - style, with elm_map_marker_class_style_set()
1138  * - #ElmMapMarkerIconGetFunc - used to fetch icon for markers classes.
1139  *   It can be set using elm_map_marker_class_icon_cb_set().
1140  * - #ElmMapMarkerGetFunc - used to fetch bubble content for marker classes.
1141  *   Set using elm_map_marker_class_get_cb_set().
1142  * - #ElmMapMarkerDelFunc - used to delete bubble content for marker classes.
1143  *   Set using elm_map_marker_class_del_cb_set().
1144  *
1145  * @see elm_map_marker_add()
1146  * @see elm_map_marker_class_style_set()
1147  * @see elm_map_marker_class_icon_cb_set()
1148  * @see elm_map_marker_class_get_cb_set()
1149  * @see elm_map_marker_class_del_cb_set()
1150  *
1151  * @ingroup Map
1152  */
1153 EAPI Elm_Map_Marker_Class *elm_map_marker_class_new(Evas_Object *obj);
1154
1155 /**
1156  * Set the marker's style of a marker class.
1157  *
1158  * @param clas The marker class.
1159  * @param style The style to be used by markers.
1160  *
1161  * Each marker must be associated to a marker class, and will use the style
1162  * defined by such class when alone, i.e., @b not grouped to other markers.
1163  *
1164  * The following styles are provided by default theme:
1165  * @li @c radio
1166  * @li @c radio2
1167  * @li @c empty
1168  *
1169  * @see elm_map_marker_class_new() for more details.
1170  * @see elm_map_marker_add()
1171  *
1172  * @ingroup Map
1173  */
1174 EAPI void                  elm_map_marker_class_style_set(Elm_Map_Marker_Class *clas, const char *style);
1175
1176 /**
1177  * Set the icon callback function of a marker class.
1178  *
1179  * @param clas The marker class.
1180  * @param icon_get The callback function that will return the icon.
1181  *
1182  * Each marker must be associated to a marker class, and it can display a
1183  * custom icon. The function @p icon_get must return this icon.
1184  *
1185  * @see elm_map_marker_class_new() for more details.
1186  * @see elm_map_marker_add()
1187  *
1188  * @ingroup Map
1189  */
1190 EAPI void                  elm_map_marker_class_icon_cb_set(Elm_Map_Marker_Class *clas, ElmMapMarkerIconGetFunc icon_get);
1191
1192 /**
1193  * Set the bubble content callback function of a marker class.
1194  *
1195  * @param clas The marker class.
1196  * @param get The callback function that will return the content.
1197  *
1198  * Each marker must be associated to a marker class, and it can display a
1199  * a content on a bubble that opens when the user click over the marker.
1200  * The function @p get must return this content object.
1201  *
1202  * If this content will need to be deleted, elm_map_marker_class_del_cb_set()
1203  * can be used.
1204  *
1205  * @see elm_map_marker_class_new() for more details.
1206  * @see elm_map_marker_class_del_cb_set()
1207  * @see elm_map_marker_add()
1208  *
1209  * @ingroup Map
1210  */
1211 EAPI void                  elm_map_marker_class_get_cb_set(Elm_Map_Marker_Class *clas, ElmMapMarkerGetFunc get);
1212
1213 /**
1214  * Set the callback function used to delete bubble content of a marker class.
1215  *
1216  * @param clas The marker class.
1217  * @param del The callback function that will delete the content.
1218  *
1219  * Each marker must be associated to a marker class, and it can display a
1220  * a content on a bubble that opens when the user click over the marker.
1221  * The function to return such content can be set with
1222  * elm_map_marker_class_get_cb_set().
1223  *
1224  * If this content must be freed, a callback function need to be
1225  * set for that task with this function.
1226  *
1227  * If this callback is defined it will have to delete (or not) the
1228  * object inside, but if the callback is not defined the object will be
1229  * destroyed with evas_object_del().
1230  *
1231  * @see elm_map_marker_class_new() for more details.
1232  * @see elm_map_marker_class_get_cb_set()
1233  * @see elm_map_marker_add()
1234  *
1235  * @ingroup Map
1236  */
1237 EAPI void                  elm_map_marker_class_del_cb_set(Elm_Map_Marker_Class *clas, ElmMapMarkerDelFunc del);
1238
1239 /**
1240  * Get the list of available sources.
1241  *
1242  * @param obj The map object.
1243  * @return The source names list.
1244  *
1245  * It will provide a list with all available sources, that can be set as
1246  * current source with elm_map_source_name_set(), or get with
1247  * elm_map_source_name_get().
1248  *
1249  * Available sources:
1250  * @li "Mapnik"
1251  * @li "Osmarender"
1252  * @li "CycleMap"
1253  * @li "Maplint"
1254  *
1255  * @see elm_map_source_name_set() for more details.
1256  * @see elm_map_source_name_get()
1257  *
1258  * @ingroup Map
1259  */
1260 EAPI const char          **elm_map_source_names_get(const Evas_Object *obj);
1261
1262 /**
1263  * Set the source of the map.
1264  *
1265  * @param obj The map object.
1266  * @param source The source to be used.
1267  *
1268  * Map widget retrieves images that composes the map from a web service.
1269  * This web service can be set with this method.
1270  *
1271  * A different service can return a different maps with different
1272  * information and it can use different zoom values.
1273  *
1274  * The @p source_name need to match one of the names provided by
1275  * elm_map_source_names_get().
1276  *
1277  * The current source can be get using elm_map_source_name_get().
1278  *
1279  * @see elm_map_source_names_get()
1280  * @see elm_map_source_name_get()
1281  *
1282  *
1283  * @ingroup Map
1284  */
1285 EAPI void                  elm_map_source_name_set(Evas_Object *obj, const char *source_name);
1286
1287 /**
1288  * Get the name of currently used source.
1289  *
1290  * @param obj The map object.
1291  * @return Returns the name of the source in use.
1292  *
1293  * @see elm_map_source_name_set() for more details.
1294  *
1295  * @ingroup Map
1296  */
1297 EAPI const char           *elm_map_source_name_get(const Evas_Object *obj);
1298
1299 /**
1300  * Set the source of the route service to be used by the map.
1301  *
1302  * @param obj The map object.
1303  * @param source The route service to be used, being it one of
1304  * #ELM_MAP_ROUTE_SOURCE_YOURS (default), #ELM_MAP_ROUTE_SOURCE_MONAV,
1305  * and #ELM_MAP_ROUTE_SOURCE_ORS.
1306  *
1307  * Each one has its own algorithm, so the route retrieved may
1308  * differ depending on the source route. Now, only the default is working.
1309  *
1310  * #ELM_MAP_ROUTE_SOURCE_YOURS is the routing service provided at
1311  * http://www.yournavigation.org/.
1312  *
1313  * #ELM_MAP_ROUTE_SOURCE_MONAV, offers exact routing without heuristic
1314  * assumptions. Its routing core is based on Contraction Hierarchies.
1315  *
1316  * #ELM_MAP_ROUTE_SOURCE_ORS, is provided at http://www.openrouteservice.org/
1317  *
1318  * @see elm_map_route_source_get().
1319  *
1320  * @ingroup Map
1321  */
1322 EAPI void                  elm_map_route_source_set(Evas_Object *obj, Elm_Map_Route_Sources source);
1323
1324 /**
1325  * Get the current route source.
1326  *
1327  * @param obj The map object.
1328  * @return The source of the route service used by the map.
1329  *
1330  * @see elm_map_route_source_set() for details.
1331  *
1332  * @ingroup Map
1333  */
1334 EAPI Elm_Map_Route_Sources elm_map_route_source_get(const Evas_Object *obj);
1335
1336 /**
1337  * Set the minimum zoom of the source.
1338  *
1339  * @param obj The map object.
1340  * @param zoom New minimum zoom value to be used.
1341  *
1342  * By default, it's 0.
1343  *
1344  * @ingroup Map
1345  */
1346 EAPI void                  elm_map_source_zoom_min_set(Evas_Object *obj, int zoom);
1347
1348 /**
1349  * Get the minimum zoom of the source.
1350  *
1351  * @param obj The map object.
1352  * @return Returns the minimum zoom of the source.
1353  *
1354  * @see elm_map_source_zoom_min_set() for details.
1355  *
1356  * @ingroup Map
1357  */
1358 EAPI int                   elm_map_source_zoom_min_get(const Evas_Object *obj);
1359
1360 /**
1361  * Set the maximum zoom of the source.
1362  *
1363  * @param obj The map object.
1364  * @param zoom New maximum zoom value to be used.
1365  *
1366  * By default, it's 18.
1367  *
1368  * @ingroup Map
1369  */
1370 EAPI void                  elm_map_source_zoom_max_set(Evas_Object *obj, int zoom);
1371
1372 /**
1373  * Get the maximum zoom of the source.
1374  *
1375  * @param obj The map object.
1376  * @return Returns the maximum zoom of the source.
1377  *
1378  * @see elm_map_source_zoom_min_set() for details.
1379  *
1380  * @ingroup Map
1381  */
1382 EAPI int                   elm_map_source_zoom_max_get(const Evas_Object *obj);
1383
1384 /**
1385  * Set the user agent used by the map object to access routing services.
1386  *
1387  * @param obj The map object.
1388  * @param user_agent The user agent to be used by the map.
1389  *
1390  * User agent is a client application implementing a network protocol used
1391  * in communications within a client–server distributed computing system
1392  *
1393  * The @p user_agent identification string will transmitted in a header
1394  * field @c User-Agent.
1395  *
1396  * @see elm_map_user_agent_get()
1397  *
1398  * @ingroup Map
1399  */
1400 EAPI void                  elm_map_user_agent_set(Evas_Object *obj, const char *user_agent);
1401
1402 /**
1403  * Get the user agent used by the map object.
1404  *
1405  * @param obj The map object.
1406  * @return The user agent identification string used by the map.
1407  *
1408  * @see elm_map_user_agent_set() for details.
1409  *
1410  * @ingroup Map
1411  */
1412 EAPI const char           *elm_map_user_agent_get(const Evas_Object *obj);
1413 =======
1414  * @see elm_map_paused_get()
1415  *
1416  * @ingroup Map
1417  */
1418 EAPI void                  elm_map_paused_set(Evas_Object *obj, Eina_Bool paused);
1419
1420 /**
1421  * Get a value whether map is paused or not.
1422  *
1423  * @param obj The map object.
1424  * @return @c EINA_TRUE means map is pause. @c EINA_FALSE indicates
1425  * it is not.
1426  *
1427  * This gets the current paused state for the map object.
1428  *
1429  * @see elm_map_paused_set() for details.
1430  *
1431  * @ingroup Map
1432  */
1433 EAPI Eina_Bool             elm_map_paused_get(const Evas_Object *obj);
1434
1435 /**
1436  * Rotate the map.
1437  *
1438  * @param obj The map object.
1439  * @param degree Angle from 0.0 to 360.0 to rotate around Z axis.
1440  * @param cx Rotation's center horizontal position.
1441  * @param cy Rotation's center vertical position.
1442  *
1443  * @see elm_map_rotate_get()
1444  *
1445  * @ingroup Map
1446  */
1447 EAPI void                  elm_map_rotate_set(Evas_Object *obj, double degree, Evas_Coord cx, Evas_Coord cy);
1448
1449 /**
1450  * Get the rotate degree of the map
1451  *
1452  * @param obj The map object
1453  * @param degree Pointer to store degrees from 0.0 to 360.0
1454  * to rotate around Z axis.
1455  * @param cx Pointer to store rotation's center horizontal position.
1456  * @param cy Pointer to store rotation's center vertical position.
1457  *
1458  * @see elm_map_rotate_set() to set map rotation.
1459  *
1460  * @ingroup Map
1461  */
1462 EAPI void                  elm_map_rotate_get(const Evas_Object *obj, double *degree, Evas_Coord *cx, Evas_Coord *cy);
1463
1464 /**
1465  * Enable or disable mouse wheel to be used to zoom in / out the map.
1466  *
1467  * @param obj The map object.
1468  * @param disabled Use @c EINA_TRUE to disable mouse wheel or @c EINA_FALSE
1469  * to enable it.
1470  *
1471  * Mouse wheel can be used for the user to zoom in or zoom out the map.
1472  *
1473  * It's disabled by default.
1474  *
1475  * @see elm_map_wheel_disabled_get()
1476  *
1477  * @ingroup Map
1478  */
1479 EAPI void                  elm_map_wheel_disabled_set(Evas_Object *obj, Eina_Bool disabled);
1480
1481 /**
1482  * Get a value whether mouse wheel is enabled or not.
1483  *
1484  * @param obj The map object.
1485  * @return @c EINA_TRUE means map is disabled. @c EINA_FALSE indicates
1486  * it is enabled.
1487  *
1488  * Mouse wheel can be used for the user to zoom in or zoom out the map.
1489  *
1490  * @see elm_map_wheel_disabled_set() for details.
1491  *
1492  * @ingroup Map
1493  */
1494 EAPI Eina_Bool             elm_map_wheel_disabled_get(const Evas_Object *obj);
1495
1496 /**
1497  * Set the user agent used by the map object to access routing services.
1498  *
1499  * @param obj The map object.
1500  * @param user_agent The user agent to be used by the map.
1501  *
1502  * User agent is a client application implementing a network protocol used
1503  * in communications within a client–server distributed computing system
1504  *
1505  * The @p user_agent identification string will transmitted in a header
1506  * field @c User-Agent.
1507  *
1508  * @see elm_map_user_agent_get()
1509  *
1510  * @ingroup Map
1511  */
1512 EAPI void                  elm_map_user_agent_set(Evas_Object *obj, const char *user_agent);
1513
1514 /**
1515  * Get the user agent used by the map object.
1516  *
1517  * @param obj The map object.
1518  * @return The user agent identification string used by the map.
1519  *
1520  * @see elm_map_user_agent_set() for details.
1521  *
1522  * @ingroup Map
1523  */
1524 EAPI const char           *elm_map_user_agent_get(const Evas_Object *obj);
1525
1526
1527 /**
1528  * Add a new overlay to the map object. This overlay has a default type.
1529  *
1530  * @param obj The map object to add a new overlay.
1531  * @param lon The longitude of the overlay.
1532  * @param lat The latitude of the overlay.
1533  * @return The created overlay or @c NULL upon failure.
1534  *
1535  * A overlay will be created and shown in a specific point of the map, defined
1536  * by @p lon and @p lat.
1537  *
1538  * The created overlay has a default style layout before content or
1539  * icon is set.
1540  * If content or icon is set, those are displayed instead of default style
1541  * layout.
1542  * You can set by using elm_map_overlay_content_set() or
1543  * elm_map_overlay_icon_set(). If NULL is set, default style
1544  * is shown again.
1545  *
1546  * Overlay created with this method can be deleted by elm_map_overlay_del().
1547  *
1548  * @see elm_map_overlay_del()
1549  * @see elm_map_overlay_class_add()
1550  * @see elm_map_overlay_bubble_add()
1551  * @see elm_map_overlay_content_set()
1552  * @see elm_map_overlay_icon_set()
1553  *
1554  * @ingroup Map
1555  */
1556 EAPI Elm_Map_Overlay *     elm_map_overlay_add(Evas_Object *obj, double lon, double lat);
1557
1558 /**
1559  * Delete a overlay from the map. This function can delete all types
1560  * of overlays.
1561  *
1562  * @param overlay The overlay to be deleted.
1563  *
1564  * @see elm_map_overlay_add()
1565  * @see elm_map_overlay_class_add()
1566  * @see elm_map_overlay_bubble_add()
1567  *
1568  * @ingroup Map
1569  */
1570 EAPI void                  elm_map_overlay_del(Elm_Map_Overlay *overlay);
1571
1572 /**
1573  * Get the overlay type.
1574  *
1575  * @param overlay The overlay to return type.
1576  * @return Return the overlay type.
1577  *
1578  * This type is resolved when the overlay is created.
1579  *
1580  * @see elm_map_overlay_add()
1581  * @see elm_map_overlay_class_add()
1582  * @see elm_map_overlay_bubble_add()
1583  *
1584  * @ingroup Map
1585  */
1586 EAPI Elm_Map_Overlay_Type  elm_map_overlay_type_get(const Elm_Map_Overlay *overlay);
1587
1588  /**
1589  * Set a pointer of user data for a overlay.
1590  *
1591  * @param overlay The overlay to own the user data.
1592  * @param data A pointer of user data
1593  *
1594  * @see elm_map_overlay_data_get()
1595  *
1596  * @ingroup Map
1597  */
1598 EAPI void                  elm_map_overlay_data_set(Elm_Map_Overlay *overlay, void *data);
1599
1600 /**
1601  * Get the user data stored on a overlay.
1602  *
1603  * @param overlay The overlay to return the user data.
1604  * @return A pointer to data stored using elm_map_overlay_data_set(),
1605  *         or @c NULL, if none has been set.
1606  *
1607  * @see elm_map_overlay_data_set()
1608  *
1609  * @ingroup Map
1610  */
1611 EAPI void *                elm_map_overlay_data_get(const Elm_Map_Overlay *overlay);
1612
1613 /**
1614  * Set if the overlay is hidden or not.
1615  *
1616  * @param overlay The overlay to be hidden.
1617  * @param hide Use @c EINA_TRUE to hide the overlay or @c EINA_FALSE to show.
1618  *
1619  * @see elm_map_overlay_hide_get()
1620  *
1621  * @ingroup Map
1622  */
1623 EAPI void                  elm_map_overlay_hide_set(Elm_Map_Overlay *overlay, Eina_Bool hide);
1624
1625 /**
1626  * Get a value whether the overlay is hidden or not.
1627  *
1628  * @param overlay The overlay to return the hidden state.
1629  * @return @c EINA_TRUE means the overlay is hidden. @c EINA_FALSE indicates
1630  * it is not.
1631  *
1632  * This gets the current hidden state for the overlay.
1633  *
1634  * @see elm_map_overlay_hide_set()
1635  *
1636  * @ingroup Map
1637  */
1638 EAPI Eina_Bool             elm_map_overlay_hide_get(const Elm_Map_Overlay *overlay);
1639
1640 /**
1641  * Set the minimum zoom from where the overlay is displayed.
1642  *
1643  * @param overlay The overlay to be set the minimum zoom.
1644  * @param zoom The minimum zoom.
1645  *
1646  * The overlay only will be displayed when the map is displayed at @p zoom
1647  * or bigger.
1648  *
1649  * @see elm_map_overlay_displayed_zoom_min_get()
1650  *
1651  * @ingroup Map
1652  */
1653 EAPI void                  elm_map_overlay_displayed_zoom_min_set(Elm_Map_Overlay *overlay, int zoom);
1654
1655 /**
1656  * Get the minimum zoom from where the overlay is displayed.
1657  *
1658  * @param overlay The overlay to return the minimum zoom.
1659  * @return zoom The minimum zoom.
1660  *
1661  * @see elm_map_overlay_displayed_zoom_min_set()
1662  *
1663  * @ingroup Map
1664  */
1665 EAPI int                   elm_map_overlay_displayed_zoom_min_get(const Elm_Map_Overlay *overlay);
1666
1667 /**
1668  * Pause or unpause the overlay.
1669  *
1670  * @param overlay The overlay to be paused.
1671  * @param paused Use @c EINA_TRUE to pause the @p overlay or @c EINA_FALSE
1672  * to unpause it.
1673  *
1674  * This sets the paused state to on (@c EINA_TRUE) or off (@c EINA_FALSE)
1675  * for the overlay.
1676  *
1677  * The default is off.
1678  *
1679  * This will stop moving the overlay coordinates instantly.
1680  * even if map being scrolled or zoomed.
1681  *
1682  * @see elm_map_overlay_paused_get()
1683  *
1684  * @ingroup Map
1685  */
1686 EAPI void                  elm_map_overlay_paused_set(Elm_Map_Overlay *overlay, Eina_Bool paused);
1687
1688 /**
1689  * Get a value whether the overlay is paused or not.
1690  *
1691  * @param overlay The overlay to return paused state.
1692  * @return @c EINA_TRUE means overlay is paused. @c EINA_FALSE indicates
1693  * it is not.
1694  *
1695  * This gets the current paused state for the overlay.
1696  *
1697  * @see elm_map_overlay_paused_set()
1698  *
1699  * @ingroup Map
1700  */
1701 EAPI Eina_Bool             elm_map_overlay_paused_get(const Elm_Map_Overlay *overlay);
1702
1703 /**
1704  * Set the content object of the overlay.
1705  *
1706  * @param overlay The overlay to be set the content.
1707  * @param obj The evas object will be used to display the overlay.
1708  *
1709  * Only default and class type overlay support this function.
1710  *
1711  * The content should be resized or set size hints before set to the overlay.
1712  * <b> Do not modify this object</b> (move, show, hide, del, etc.),
1713  * after set.
1714  * You can only resize this.
1715  *
1716  * This content is what will be inside the overlay that will be displayed.
1717  * If a content is set, icon and default style layout are no more used before
1718  * the content is deleted.
1719  *
1720  * If @p obj is @c NULL, content inside the overlay is deleted.
1721  *
1722  * @see elm_map_overlay_content_get()
1723  *
1724  * @ingroup Map
1725  */
1726 EAPI void                  elm_map_overlay_content_set(Elm_Map_Overlay *overlay, Evas_Object *obj);
1727
1728 /**
1729  * Get the content object.
1730  *
1731  * @param overlay The overlay to return the content.
1732  * @return Return the evas object if it exists, else @c NULL.
1733  *
1734  * Only default and class type overlay support this function.
1735  *
1736  * Returned content is what being inside the overlay that being displayed.
1737  *
1738  * <b> Do not modify this object</b> (move, show, hide, del, etc.).
1739  * You can only resize this.
1740  *
1741  * The content can be set by elm_map_overlay_content_set().
1742  *
1743  * @see elm_map_overlay_content_set()
1744  *
1745  * @ingroup Map
1746  */
1747 EAPI const Evas_Object *   elm_map_overlay_content_get(const Elm_Map_Overlay *overlay);
1748
1749 /**
1750  * Set a icon of the overlay.
1751  *
1752  * @param overlay The overlay to be set the icon.
1753  * @param icon The icon will be used to display the overlay.
1754  *
1755  * Only default and class type overlay support this function.
1756  *
1757  * <b> Do not modify this object</b> (move, show, hide, resize, del, etc.),
1758  * after set.
1759  *
1760  * If icon is set, default style layout will not be used.
1761  *
1762  * If @p icon is @c NULL, icon inside the overlay will be deleted.
1763  *
1764  * @see elm_map_overlay_icon_get()
1765  *
1766  * @ingroup Map
1767  */
1768 EAPI void                  elm_map_overlay_icon_set(Elm_Map_Overlay *overlay, Evas_Object *icon);
1769
1770 /**
1771  * Get the icon object.
1772  *
1773  * @param overlay The overlay to return the icon.
1774  * @return Return the icon object if it exists, else @c NULL.
1775  *
1776  * Only default and class type overlay support this function.
1777  *
1778  * Returned icon is what being inside the overlay that being displayed.
1779  *
1780  * <b> Do not modify this icon </b> (move, show, hide, resize, del, etc.).
1781  *
1782  * The icon can be set by elm_map_overlay_icon_set().
1783  *
1784  * @see elm_map_overlay_icon_set()
1785  *
1786  * @ingroup Map
1787  */
1788 EAPI const Evas_Object *   elm_map_overlay_icon_get(const Elm_Map_Overlay *overlay);
1789
1790 /**
1791  * Set the geographic coordinates of the overlay.
1792  *
1793  * @param overlay The overlay to be set geographic coordinates.
1794  * @param lon Longitude to be set.
1795  * @param lat Latitude to be set.
1796  *
1797  * Only default and bubble type overlay support this function.
1798  *
1799  * This sets the center coordinates of the overlay. It can be
1800  * get by elm_map_overlay_region_get().
1801  *
1802  * @see elm_map_overlay_region_get()
1803  *
1804  * @ingroup Map
1805  */
1806 EAPI void                  elm_map_overlay_region_set(Elm_Map_Overlay *overlay, double lon, double lat);
1807
1808 /**
1809  * Get the geographic coordinates of the overlay.
1810  *
1811  * @param overlay The overlay to return geographic coordinates.
1812  * @param lon Pointer to store longitude.
1813  * @param lat Pointer to store latitude.
1814  *
1815  * Only default and bubble type overlay support this function.
1816  *
1817  * This returns the center coordinates of the overlay. It can be
1818  * set by elm_map_overlay_region_set().
1819  *
1820  * @see elm_map_overlay_region_set()
1821  *
1822  * @ingroup Map
1823  */
1824 EAPI void                  elm_map_overlay_region_get(const Elm_Map_Overlay *overlay, double *lon, double *lat);
1825
1826
1827 /**
1828  * Set the object color of the overlay.
1829  *
1830  * @param overlay The overlay to be set color.
1831  * @param r Red channel value, from 0 to 255.
1832  * @param g Green channel value, from 0 to 255.
1833  * @param b Blue channel value, from 0 to 255.
1834  * @param a Alpha channel value, from 0 to 255.
1835  *
1836  * It uses an additive color model, so each color channel represents
1837  * how much of each primary colors must to be used. 0 represents
1838  * absence of this color, so if all of the three are set to 0,
1839  * the color will be black.
1840  *
1841  * These component values should be integers in the range 0 to 255,
1842  * (single 8-bit byte).
1843  *
1844  * This sets the color used for the overlay. By default, it is set to
1845  * solid red (r = 255, g = 0, b = 0, a = 255).
1846  *
1847  * For alpha channel, 0 represents completely transparent, and 255, opaque.
1848  *
1849  * @see elm_map_overlay_color_get()
1850  *
1851  * @ingroup Map
1852  */
1853 EAPI void                  elm_map_overlay_color_set(Elm_Map_Overlay *overlay, int r, int g, int b, int a);
1854
1855 /**
1856  * Get the object color of the overlay.
1857  *
1858  * @param overlay The overlay to return color.
1859  * @param r Pointer to store the red channel value.
1860  * @param g Pointer to store the green channel value.
1861  * @param b Pointer to store the blue channel value.
1862  * @param a Pointer to store the alpha channel value.
1863  *
1864  * @see elm_map_overlay_color_set()
1865  *
1866  * @ingroup Map
1867  */
1868 EAPI void                  elm_map_overlay_color_get(const Elm_Map_Overlay *overlay, int *r, int *g, int *b, int *a);
1869
1870 /**
1871  * Show the given overlay at the center of the map, immediately.
1872  *
1873  * @param overlay The overlay to be center at.
1874  *
1875  * This causes map to @b redraw its viewport's contents to the
1876  * region containing the given @p overlay's coordinates, that will be
1877  * moved to the center of the map.
1878  *
1879  * @see elm_map_overlays_show() if more than one overlay need to be displayed.
1880  *
1881  * @ingroup Map
1882  */
1883 EAPI void                  elm_map_overlay_show(Elm_Map_Overlay *overlay);
1884
1885 /**
1886  * Move and zoom the map to display a list of overlays.
1887  *
1888  * @param overlays A list of #Elm_Map_Overlay handles.
1889  *
1890  * The map will be centered on the center point of the overlays in the list.
1891  * Then the map will be zoomed in order to fit the overlays using the maximum
1892  * zoom which allows display of all the overlays.
1893  *
1894  * @warning All the overlays should belong to the same map object.
1895  *
1896  * @see elm_map_overlay_show() to show a single overlay.
1897  *
1898  * @ingroup Map
1899  */
1900 EAPI void                  elm_map_overlays_show(Eina_List *overlays);
1901
1902 /**
1903  * Set the get callback function of the overlay.
1904  *
1905  * @param overlay The overlay to own the get callback function.
1906  * @param get_cb The callback function.
1907  * @param data The user callback data.
1908  *
1909  * You can delete this callback function by setting @c NULL.
1910  *
1911  * @ingroup Map
1912  */
1913 EAPI void elm_map_overlay_get_cb_set(Elm_Map_Overlay *overlay, Elm_Map_Overlay_Get_Cb get_cb, void *data);
1914
1915
1916 /**
1917  * Add a new class overlay to the map object.
1918  * This overlay has a class type.
1919  *
1920  * @param obj The map object to add a new overlay.
1921  * @return The created overlay or @c NULL upon failure.
1922  *
1923  * This overlay is not shown before overlay members are appended.
1924  * if overlay members in the same class are close, group overlays
1925  * are created. If they are far away, group overlays are hidden.
1926  * When group overlays are shown, they have default style layouts at first.
1927  *
1928  * You can changed the state (hidden, paused, etc.) or set the content
1929  * or icon of the group overlays.
1930  * Also these changes have a influence on the overlays in the same class
1931  * even if each overlay is alone and is not grouped.
1932  *
1933  * @see elm_map_overlay_del()
1934  * @see elm_map_overlay_add()
1935  * @see elm_map_overlay_bubble_add()
1936  *
1937  * @ingroup Map
1938  */
1939 EAPI Elm_Map_Overlay *     elm_map_overlay_class_add(Evas_Object *obj);
1940
1941 /**
1942  * Add a new overlay member to the class overlay.
1943  *
1944  * @param clas The class overlay to add a new overlay.
1945  * @param overlay The overlay to be added to the class overlay.
1946  *
1947  * @see elm_map_overlay_class_remove()
1948  *
1949  * @ingroup Map
1950  */
1951 EAPI void                  elm_map_overlay_class_append(Elm_Map_Overlay *clas, Elm_Map_Overlay *overlay);
1952
1953 /**
1954  * Remove a overlay from the class.
1955  *
1956  * @param clas The class overlay to delete the overlay.
1957  * @param overlay The overlay to be deleted from the class overlay.
1958  *
1959  * @see elm_map_overlay_class_append()
1960  *
1961  * @ingroup Map
1962  */
1963 EAPI void                  elm_map_overlay_class_remove(Elm_Map_Overlay *clas, Elm_Map_Overlay *overlay);
1964
1965 /**
1966  * Set the maximum zoom from where the overlay members in the class can be
1967  * grouped.
1968  *
1969  * @param clas The overlay class has overlay members.
1970  * @param zoom The maximum zoom.
1971  *
1972  * Overlay members in the class only will be grouped when the map
1973  * is displayed at less than @p zoom.
1974  *
1975  * @see elm_map_overlay_class_zoom_max_get()
1976  *
1977  * @ingroup Map
1978  */
1979 EAPI
1980 EAPI void                  elm_map_overlay_class_zoom_max_set(Elm_Map_Overlay *clas, int zoom);
1981
1982 /**
1983  * Get the zoom from where the overlay members in the class are no more grouped.
1984  *
1985  * @param clas The overlay class has overlay members.
1986  *
1987  * @return The maximum zoom.
1988  *
1989  * @see elm_map_overlay_class_zoom_max_set()
1990  *
1991  * @ingroup Map
1992  */
1993 EAPI int                   elm_map_overlay_class_zoom_max_get(const Elm_Map_Overlay *clas);
1994
1995 /**
1996  * Add a new bubble overlay to the map object.
1997  * This overlay has a bubble type.
1998  *
1999  * @param obj The map object to add a new overlay.
2000  * @return The created overlay or @c NULL upon failure.
2001  *
2002  * A bubble will not be displayed before geographic coordinates are set or
2003  * any other overlays are followed.
2004  *
2005  * This overlay has a bubble style layout and icon or content can not
2006  * be set.
2007  *
2008  * Overlay created with this method can be deleted with elm_map_overlay_del().
2009  *
2010  * @see elm_map_overlay_del()
2011  * @see elm_map_overlay_add()
2012  * @see elm_map_overlay_class_add()
2013  * @see elm_map_overlay_region_set()
2014  * @see elm_map_overlay_bubble_follow()
2015  *
2016  * @ingroup Map
2017  */
2018 EAPI Elm_Map_Overlay *     elm_map_overlay_bubble_add(Evas_Object *obj);
2019
2020 /**
2021  * Follow a other overlay.
2022  *
2023  * @param bubble The bubble overlay to follow a parent overlay.
2024  * @param parent The parent overlay to be followed by the bubble overlay.
2025  *
2026  * Bubble overlay will follow the parent overlay's movement (hide, show, move).
2027  *
2028  * @see elm_map_overlay_bubble_add()
2029  *
2030  * @ingroup Map
2031  */
2032 EAPI void                  elm_map_overlay_bubble_follow(Elm_Map_Overlay *bubble, Elm_Map_Overlay *parent);
2033
2034 /**
2035  * Add a content object to the bubble overlay.
2036  *
2037  * @param bubble The bubble overlay to add a content.
2038  * @param content The content to be added to the bubble overlay.
2039  *
2040  * Added contents will be displayed inside the bubble overlay.
2041  *
2042  * @see elm_map_overlay_bubble_content_clear()
2043  *
2044  * @ingroup Map
2045  */
2046 EAPI void                  elm_map_overlay_bubble_content_append(Elm_Map_Overlay *bubble, Evas_Object *content);
2047
2048 /**
2049  * Clear all contents inside the bubble overlay.
2050  *
2051  * @param bubble The bubble overlay to clear the contents.
2052  *
2053  * This will delete all contents inside the bubble overlay.
2054  *
2055  * @see elm_map_overlay_bubble_content_append()
2056  *
2057  * @ingroup Map
2058  */
2059
2060 EAPI void                  elm_map_overlay_bubble_content_clear(Elm_Map_Overlay *bubble);
2061
2062 /**
2063  * Add a new route overlay to the map object.
2064  * This overlay has a route type.
2065  *
2066  * @param obj The map object to add a new overlay.
2067  * @param route The route object to make a overlay.
2068  * @return The created overlay or @c NULL upon failure.
2069  *
2070  * This overlay has a route style layout and icon or content can not
2071  * be set.
2072  *
2073  * The color scheme can be changed by elm_map_overlay_content_set().
2074  *
2075  * Overlay created with this method can be deleted with elm_map_overlay_del().
2076  *
2077  * @see elm_map_overlay_del()
2078  * @see elm_map_overlay_class_add()
2079  * @see elm_map_overlay_content_set()
2080  * @see elm_map_overlay_content_get()
2081  *
2082  * @ingroup Map
2083  */
2084 EAPI Elm_Map_Overlay *     elm_map_overlay_route_add(Evas_Object *obj, const Elm_Map_Route *route);
2085
2086 /**
2087  * Get the information of tile load status.
2088  *
2089  * @param obj The map object.
2090  * @param try_num Pointer to store number of tiles download requested.
2091  * @param finish_num Pointer to store number of tiles successfully downloaded.
2092  *
2093  * This gets the current tile loaded status for the map object.
2094  *
2095  * @ingroup Map
2096  */
2097 EAPI void                  elm_map_tile_load_status_get(const Evas_Object *obj, int *try_num, int *finish_num);
2098
2099 /**
2100  * Get the names of available sources for a specific type.
2101  *
2102  * @param obj The map object.
2103  * @param type source type.
2104  * @return The char pointer array of source names.
2105  *
2106  * It will provide a list with all available sources.
2107  * Current source can be set by elm_map_source_set(), or get with
2108  * elm_map_source_get().
2109  *
2110  * At least available sources of tile type:
2111  * @li "Mapnik"
2112  * @li "Osmarender"
2113  * @li "CycleMap"
2114  * @li "Maplint"
2115  *
2116  * At least available sources of route type:
2117  * @li "Yours"
2118  *
2119  * At least available sources of name type:
2120  * @li "Nominatim"
2121  *
2122  * @see elm_map_source_set()
2123  * @see elm_map_source_get()
2124  *
2125  * @ingroup Map
2126  */
2127 EAPI const char          **elm_map_sources_get(const Evas_Object *obj, Elm_Map_Source_Type type);
2128
2129 /**
2130  * Set the current source of the map for a specific type.
2131  *
2132  * @param obj The map object.
2133  * @param type source type.
2134  * @param source_name The source to be used.
2135  *
2136  * Map widget retrieves tile images that composes the map from a web service.
2137  * This web service can be set with this method
2138  * for ELM_MAP_SOURCE_TYPE_TILE type.
2139  * A different service can return a different maps with different
2140  * information and it can use different zoom values.
2141  *
2142  * Map widget provides route data based on a external web service.
2143  * This web service can be set with this method
2144  * for ELM_MAP_SOURCE_TYPE_ROUTE type.
2145  *
2146  * Map widget also provide geoname data based on a external web service.
2147  * This web service can be set with this method
2148  * for ELM_MAP_SOURCE_TYPE_NAME type.
2149  *
2150  * The @p source_name need to match one of the names provided by
2151  * elm_map_sources_get().
2152  *
2153  * The current source can be get using elm_map_source_get().
2154  *
2155  * @see elm_map_sources_get()
2156  * @see elm_map_source_get()
2157  *
2158  * @ingroup Map
2159  */
2160 EAPI void                  elm_map_source_set(Evas_Object *obj, Elm_Map_Source_Type type, const char *source_name);
2161
2162 /**
2163  * Get the name of currently used source for a specific type.
2164  *
2165  * @param obj The map object.
2166  * @param type source type.
2167  * @return Returns the name of the source in use.
2168  *
2169  * @see elm_map_sources_get()
2170  * @see elm_map_source_set()
2171  *
2172  * @ingroup Map
2173  */
2174 EAPI const char           *elm_map_source_get(const Evas_Object *obj, Elm_Map_Source_Type type);
2175 >>>>>>> remotes/origin/upstream
2176
2177 /**
2178  * Add a new route to the map object.
2179  *
2180  * @param obj The map object.
2181  * @param type The type of transport to be considered when tracing a route.
2182 <<<<<<< HEAD
2183  * @param method The routing method, what should be priorized.
2184 =======
2185  * @param method The routing method, what should be prioritized.
2186 >>>>>>> remotes/origin/upstream
2187  * @param flon The start longitude.
2188  * @param flat The start latitude.
2189  * @param tlon The destination longitude.
2190  * @param tlat The destination latitude.
2191  *
2192  * @return The created route or @c NULL upon failure.
2193  *
2194  * A route will be traced by point on coordinates (@p flat, @p flon)
2195  * to point on coordinates (@p tlat, @p tlon), using the route service
2196  * set with elm_map_route_source_set().
2197  *
2198  * It will take @p type on consideration to define the route,
2199  * depending if the user will be walking or driving, the route may vary.
2200  * One of #ELM_MAP_ROUTE_TYPE_MOTOCAR, #ELM_MAP_ROUTE_TYPE_BICYCLE, or
2201  * #ELM_MAP_ROUTE_TYPE_FOOT need to be used.
2202  *
2203 <<<<<<< HEAD
2204  * Another parameter is what the route should priorize, the minor distance
2205 =======
2206  * Another parameter is what the route should prioritize, the minor distance
2207 >>>>>>> remotes/origin/upstream
2208  * or the less time to be spend on the route. So @p method should be one
2209  * of #ELM_MAP_ROUTE_METHOD_SHORTEST or #ELM_MAP_ROUTE_METHOD_FASTEST.
2210  *
2211  * Routes created with this method can be deleted with
2212  * elm_map_route_remove(), colored with elm_map_route_color_set(),
2213  * and distance can be get with elm_map_route_distance_get().
2214  *
2215  * @see elm_map_route_remove()
2216  * @see elm_map_route_color_set()
2217  * @see elm_map_route_distance_get()
2218  * @see elm_map_route_source_set()
2219  *
2220  * @ingroup Map
2221  */
2222 <<<<<<< HEAD
2223 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);
2224 =======
2225 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);
2226 >>>>>>> remotes/origin/upstream
2227
2228 /**
2229  * Remove a route from the map.
2230  *
2231  * @param route The route to remove.
2232  *
2233  * @see elm_map_route_add()
2234  *
2235  * @ingroup Map
2236  */
2237 <<<<<<< HEAD
2238 EAPI void                  elm_map_route_remove(Elm_Map_Route *route);
2239
2240 /**
2241  * Set the route color.
2242  *
2243  * @param route The route object.
2244  * @param r Red channel value, from 0 to 255.
2245  * @param g Green channel value, from 0 to 255.
2246  * @param b Blue channel value, from 0 to 255.
2247  * @param a Alpha channel value, from 0 to 255.
2248  *
2249  * It uses an additive color model, so each color channel represents
2250  * how much of each primary colors must to be used. 0 represents
2251  * ausence of this color, so if all of the three are set to 0,
2252  * the color will be black.
2253  *
2254  * These component values should be integers in the range 0 to 255,
2255  * (single 8-bit byte).
2256  *
2257  * This sets the color used for the route. By default, it is set to
2258  * solid red (r = 255, g = 0, b = 0, a = 255).
2259  *
2260  * For alpha channel, 0 represents completely transparent, and 255, opaque.
2261  *
2262  * @see elm_map_route_color_get()
2263  *
2264  * @ingroup Map
2265  */
2266 EAPI void                  elm_map_route_color_set(Elm_Map_Route *route, int r, int g, int b, int a);
2267
2268 /**
2269  * Get the route color.
2270  *
2271  * @param route The route object.
2272  * @param r Pointer where to store the red channel value.
2273  * @param g Pointer where to store the green channel value.
2274  * @param b Pointer where to store the blue channel value.
2275  * @param a Pointer where to store the alpha channel value.
2276  *
2277  * @see elm_map_route_color_set() for details.
2278  *
2279  * @ingroup Map
2280  */
2281 EAPI void                  elm_map_route_color_get(const Elm_Map_Route *route, int *r, int *g, int *b, int *a);
2282 =======
2283 EAPI void                  elm_map_route_del(Elm_Map_Route *route);
2284 >>>>>>> remotes/origin/upstream
2285
2286 /**
2287  * Get the route distance in kilometers.
2288  *
2289  * @param route The route object.
2290  * @return The distance of route (unit : km).
2291  *
2292  * @ingroup Map
2293  */
2294 EAPI double                elm_map_route_distance_get(const Elm_Map_Route *route);
2295
2296 /**
2297  * Get the information of route nodes.
2298  *
2299  * @param route The route object.
2300  * @return Returns a string with the nodes of route.
2301  *
2302  * @ingroup Map
2303  */
2304 EAPI const char           *elm_map_route_node_get(const Elm_Map_Route *route);
2305
2306 /**
2307  * Get the information of route waypoint.
2308  *
2309  * @param route the route object.
2310  * @return Returns a string with information about waypoint of route.
2311  *
2312  * @ingroup Map
2313  */
2314 EAPI const char           *elm_map_route_waypoint_get(const Elm_Map_Route *route);
2315
2316 /**
2317 <<<<<<< HEAD
2318 =======
2319  * Request a address or geographic coordinates(longitude, latitude)
2320  * from a given address or geographic coordinate(longitude, latitude).
2321  *
2322  * @param obj The map object.
2323  * @param address The address.
2324  * @param lon The longitude.
2325  * @param lat The latitude.
2326  * @param name_cb The callback function.
2327  * @param data The user callback data.
2328  * @return name A #Elm_Map_Name handle for this coordinate.
2329  *
2330  * If you want to get address from geographic coordinates, set input @p address
2331  * as NULL and set @p lon, @p lat as you want to convert.
2332  * If address is set except NULL, @p lon and @p lat are checked.
2333  *
2334  * To get the string for this address, elm_map_name_address_get()
2335  * should be used after callback or "name,loaded" signal is called.
2336  *
2337  * To get the longitude and latitude, elm_map_name_region_get()
2338  * should be used.
2339  *
2340  * @ingroup Map
2341  */
2342 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);
2343
2344 /**
2345 >>>>>>> remotes/origin/upstream
2346  * Get the address of the name.
2347  *
2348  * @param name The name handle.
2349  * @return Returns the address string of @p name.
2350  *
2351  * This gets the coordinates of the @p name, created with one of the
2352  * conversion functions.
2353  *
2354  * @see elm_map_utils_convert_name_into_coord()
2355  * @see elm_map_utils_convert_coord_into_name()
2356  *
2357  * @ingroup Map
2358  */
2359 EAPI const char           *elm_map_name_address_get(const Elm_Map_Name *name);
2360
2361 /**
2362  * Get the current coordinates of the name.
2363  *
2364  * @param name The name handle.
2365 <<<<<<< HEAD
2366  * @param lat Pointer where to store the latitude.
2367  * @param lon Pointer where to store The longitude.
2368 =======
2369  * @param lat Pointer to store the latitude.
2370  * @param lon Pointer to store The longitude.
2371 >>>>>>> remotes/origin/upstream
2372  *
2373  * This gets the coordinates of the @p name, created with one of the
2374  * conversion functions.
2375  *
2376  * @see elm_map_utils_convert_name_into_coord()
2377  * @see elm_map_utils_convert_coord_into_name()
2378  *
2379  * @ingroup Map
2380  */
2381 EAPI void                  elm_map_name_region_get(const Elm_Map_Name *name, double *lon, double *lat);
2382
2383 /**
2384  * Remove a name from the map.
2385  *
2386  * @param name The name to remove.
2387  *
2388 <<<<<<< HEAD
2389  * Basically the struct handled by @p name will be freed, so convertions
2390 =======
2391  * Basically the struct handled by @p name will be freed, so conversions
2392 >>>>>>> remotes/origin/upstream
2393  * between address and coordinates will be lost.
2394  *
2395  * @see elm_map_utils_convert_name_into_coord()
2396  * @see elm_map_utils_convert_coord_into_name()
2397  *
2398  * @ingroup Map
2399  */
2400 <<<<<<< HEAD
2401 EAPI void                  elm_map_name_remove(Elm_Map_Name *name);
2402
2403 /**
2404  * Rotate the map.
2405  *
2406  * @param obj The map object.
2407  * @param degree Angle from 0.0 to 360.0 to rotate arount Z axis.
2408  * @param cx Rotation's center horizontal position.
2409  * @param cy Rotation's center vertical position.
2410  *
2411  * @see elm_map_rotate_get()
2412  *
2413  * @ingroup Map
2414  */
2415 EAPI void                  elm_map_rotate_set(Evas_Object *obj, double degree, Evas_Coord cx, Evas_Coord cy);
2416
2417 /**
2418  * Get the rotate degree of the map
2419  *
2420  * @param obj The map object
2421  * @param degree Pointer where to store degrees from 0.0 to 360.0
2422  * to rotate arount Z axis.
2423  * @param cx Pointer where to store rotation's center horizontal position.
2424  * @param cy Pointer where to store rotation's center vertical position.
2425  *
2426  * @see elm_map_rotate_set() to set map rotation.
2427  *
2428  * @ingroup Map
2429  */
2430 EAPI void                  elm_map_rotate_get(const Evas_Object *obj, double *degree, Evas_Coord *cx, Evas_Coord *cy);
2431
2432 /**
2433  * Enable or disable mouse wheel to be used to zoom in / out the map.
2434  *
2435  * @param obj The map object.
2436  * @param disabled Use @c EINA_TRUE to disable mouse wheel or @c EINA_FALSE
2437  * to enable it.
2438  *
2439  * Mouse wheel can be used for the user to zoom in or zoom out the map.
2440  *
2441  * It's disabled by default.
2442  *
2443  * @see elm_map_wheel_disabled_get()
2444  *
2445  * @ingroup Map
2446  */
2447 EAPI void                  elm_map_wheel_disabled_set(Evas_Object *obj, Eina_Bool disabled);
2448
2449 /**
2450  * Get a value whether mouse wheel is enabled or not.
2451  *
2452  * @param obj The map object.
2453  * @return @c EINA_TRUE means map is disabled. @c EINA_FALSE indicates
2454  * it is enabled. If @p obj is @c NULL, @c EINA_FALSE is returned.
2455  *
2456  * Mouse wheel can be used for the user to zoom in or zoom out the map.
2457  *
2458  * @see elm_map_wheel_disabled_set() for details.
2459  *
2460  * @ingroup Map
2461  */
2462 EAPI Eina_Bool             elm_map_wheel_disabled_get(const Evas_Object *obj);
2463
2464 #ifdef ELM_EMAP
2465 /**
2466 =======
2467 EAPI void                  elm_map_name_del(Elm_Map_Name *name);
2468
2469 /**
2470 >>>>>>> remotes/origin/upstream
2471  * Add a track on the map
2472  *
2473  * @param obj The map object.
2474  * @param emap The emap route object.
2475  * @return The route object. This is an elm object of type Route.
2476  *
2477  * @see elm_route_add() for details.
2478  *
2479  * @ingroup Map
2480  */
2481 <<<<<<< HEAD
2482 EAPI Evas_Object          *elm_map_track_add(Evas_Object *obj, EMap_Route *emap);
2483 #endif
2484 =======
2485 EAPI Evas_Object          *elm_map_track_add(Evas_Object *obj, void *emap);
2486 >>>>>>> remotes/origin/upstream
2487
2488 /**
2489  * Remove a track from the map
2490  *
2491  * @param obj The map object.
2492  * @param route The track to remove.
2493  *
2494  * @ingroup Map
2495  */
2496 EAPI void                  elm_map_track_remove(Evas_Object *obj, Evas_Object *route);
2497
2498 <<<<<<< HEAD
2499 /**
2500  * @}
2501  */
2502 =======
2503 >>>>>>> remotes/origin/upstream