summaryrefslogtreecommitdiff
path: root/src/lib/elementary/elm_map.eo
blob: 9c4d68d162dac3a2d7743d947d89d0840b98c4fe (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
/* FIXME: Handle properly. */
type Elm_Map_Route: __undefined_type; [[Elementary map route type]]
type Elm_Map_Route_Cb: __undefined_type; [[Elementary map route callback type]]
type Elm_Map_Overlay: __undefined_type; [[Elementary map overlay type]]
type Elm_Map_Name: __undefined_type; [[Elementary map name type]]
type Elm_Map_Name_Cb: __undefined_type; [[Elementary map name callback type]]
type Elm_Map_Name_List_Cb: __undefined_type; [[Elementary map name list callback type]]

enum Elm.Map.Zoom_Mode
{
   [[
     Set map's zoom behavior. It can be set to manual or automatic.

     Default value is #ELM_MAP_ZOOM_MODE_MANUAL.

     Values <b> don't </b> work as bitmask, only one can be chosen.

     Valid sizes are 2^zoom, consequently the map may be smaller
     than the scroller view.

     See @Elm.Map.zoom_mode.set()
     See @Elm.Map.zoom_mode.get()
   ]]
   manual,    [[Zoom controlled manually by elm_map_zoom_set(). It's set by default.]]
   auto_fit,  [[Zoom until map fits inside the scroll frame with no pixels outside this area.]]
   auto_fill, [[Zoom until map fills scroll, ensuring no pixels are left unfilled.]]
   last       [[Sentinel value to indicate last enum field during iteration]]
}

enum Elm.Map.Source_Type
{
   [[
     Set type of a external source (provider).

     See @Elm.Map.sources_get()
     See @Elm.Map.source_get()
     See @Elm.Map.source_set()
   ]]
   tile,  [[Map tile provider.]]
   route, [[Route service provider.]]
   name,  [[Name service provider.]]
   last   [[Sentinel value to indicate last enum field during iteration]]
}

enum Elm.Map.Route_Type
{
   [[
     Set type of transport used on route.

     See @Elm.Map.route_add()
   ]]
   motocar, [[Route should consider an automobile will be used.]]
   bicycle, [[Route should consider a bicycle will be used by the user.]]
   foot,    [[Route should consider user will be walking.]]
   last     [[Sentinel value to indicate last enum field during iteration]]
}


enum Elm.Map.Route_Method
{
   [[
     Set the routing method, what should be prioritized, time or distance.

     See @Elm.Map.route_add()
   ]]
   fastest,  [[Route should prioritize time.]]
   shortest, [[Route should prioritize distance.]]
   last      [[Sentinel value to indicate last enum field during iteration]]
}


class Elm.Map (Efl.Ui.Widget, Elm.Interface_Scrollable,
               Efl.Access.Widget.Action,
               Efl.Ui.Clickable, Efl.Ui.Legacy)
{
   [[Elementary map class]]
   legacy_prefix: elm_map;
   eo_prefix: elm_obj_map;
   event_prefix: elm_map;
   methods {
      @property zoom {
         set {
            [[Set the zoom level of the map.

              This sets the zoom level.

              It will respect limits defined by @.zoom_min.set and
              @.zoom_max.set.

              By default these values are 0 (world map) and 18 (maximum zoom).

              This function should be used when zoom mode is set to
              #ELM_MAP_ZOOM_MODE_MANUAL. This is the default mode, and
              can be set with @.zoom_mode.set.
            ]]
         }
         get {
            [[Get the zoom level of the map.

              This returns the current zoom level of the map object.

              Note that if you set the fill mode to other than
              #ELM_MAP_ZOOM_MODE_MANUAL (which is the default), the zoom
              level may be changed at any time by the map object itself
              to account for map size and map viewport size.
            ]]
         }
         values {
            zoom: int; [[The zoom level.]]
         }
      }
      @property paused {
         set {
            [[Pause or unpause the map.

              This sets the paused state to on ($true) or off ($false)
              for map.

              The default is off.

              This will stop zooming using animation, changing zoom levels
              will change instantly. This will stop any existing animations
              that are running.
            ]]
         }
         get {
            [[Get a value whether map is paused or not.

              This gets the current paused state for the map object.
            ]]
         }
         values {
            paused: bool; [[Use $true to pause the map $obj or $false
                            to unpause it.]]
         }
      }
      @property wheel_disabled {
         set {
            [[Enable or disable mouse wheel to be used to zoom in / out the
              map.

              Wheel is enabled by default.
            ]]
         }
         get {
            [[Get a value whether mouse wheel is enabled or not.

              Mouse wheel can be used for the user to zoom in or zoom out
              the map.
            ]]
         }
         values {
            disabled: bool; [[Use $true to disable mouse wheel or $false
                              to enable it.]]
         }
      }
      @property zoom_min {
         set {
            [[Set the minimum zoom of the source.]]
         }
         get {
            [[Get the minimum zoom of the source.]]
         }
         values {
            zoom: int(-1); [[Minimum zoom value to be used.]]
         }
      }
      @property rotate {
         set {
            [[Rotate the map.]]
         }
         get {
            [[Get the rotate degree of the map.]]
         }
         values {
            degree: double; [[Angle from 0.0 to 360.0 to rotate around Z axis.]]
            cx: int; [[Rotation's center horizontal position.]]
            cy: int; [[Rotation's center vertical position.]]
         }
      }
      @property user_agent {
         set {
            [[Set the user agent used by the map object to access routing
              services.

              User agent is a client application implementing a network
              protocol used in communications within a clientserver
              distributed computing system

              The $user_agent identification string will transmitted in
              a header field $User-Agent.
            ]]
         }
         get {
            [[Get the user agent used by the map object.]]
         }
         values {
            user_agent: string; [[The user agent to be used by the map.]]
         }
      }
      @property zoom_max {
         set {
            [[Set the maximum zoom of the source.]]
         }
         get {
            [[Get the maximum zoom of the source.]]
         }
         values {
            zoom: int(-1); [[Maximum zoom value to be used.]]
         }
      }
      @property zoom_mode {
         set {
            [[Set the zoom mode used by the map object.

              This sets the zoom mode to manual or one of the automatic
              levels. Manual (#ELM_MAP_ZOOM_MODE_MANUAL) means that zoom
              is set manually by @.zoom_mode.set and will stay at that
              level until changed by code or until zoom mode is changed.
              This is the default mode.

              The Automatic modes will allow the map object to
              automatically adjust zoom mode based on properties.
              #ELM_MAP_ZOOM_MODE_AUTO_FIT will adjust zoom so the map
              fits inside the scroll frame with no pixels outside this
              area. #ELM_MAP_ZOOM_MODE_AUTO_FILL will be similar but
              ensure no pixels within the frame are left unfilled. Do not
              forget that the valid sizes are 2^zoom, consequently the map
              may be smaller than the scroller view.
            ]]
         }
         get {
            [[Get the zoom mode used by the map object.

              This function returns the current zoom mode used by the ma
              object.
            ]]
         }
         values {
            mode: Elm.Map.Zoom_Mode; [[The zoom mode of the map, being it
                                       one of #ELM_MAP_ZOOM_MODE_MANUAL
                                       (default), #ELM_MAP_ZOOM_MODE_AUTO_FIT,
                                       or #ELM_MAP_ZOOM_MODE_AUTO_FILL.]]
         }
      }
      @property region {
         get {
            [[Get the current geographic coordinates of the map.

              This gets the current center coordinates of the map object.
              It can be set by @.region_bring_in and @.region_show.
            ]]
         }
         values {
            lon: double; [[Pointer to store longitude.]]
            lat: double; [[Pointer to store latitude.]]
         }
      }
      @property overlays {
         get {
            [[Return all overlays in the map object.

              This list includes group overlays also.
              So this can be changed dynamically while zooming and panning.

              @since 1.7
            ]]
            return: list<ptr(Elm_Map_Overlay)>; [[The list of all overlays or $null upon failure.]]
         }
      }
      @property tile_load_status {
         get {
            [[Get the information of tile load status.

              This gets the current tile loaded status for the map object.
            ]]
         }
         values {
            try_num: int; [[Pointer to store number of tiles download requested.]]
            finish_num: int; [[Pointer to store number of tiles successfully downloaded.]]
         }
      }
      source_set {
         [[Set the current source of the map for a specific type.

           Map widget retrieves tile images that composes the map from a
           web service. This web service can be set with this method
           for #ELM_MAP_SOURCE_TYPE_TILE type. A different service can
           return a different maps with different information and it can
           use different zoom values.

           Map widget provides route data based on a external web service.
           This web service can be set with this method
           for #ELM_MAP_SOURCE_TYPE_ROUTE type.

           Map widget also provide geoname data based on a external web
           service. This web service can be set with this method
           for #ELM_MAP_SOURCE_TYPE_NAME type.

           The $source_name need to match one of the names provided by
           @.sources_get.

           The current source can be get using @.source_get.
         ]]
         params {
            @in type: Elm.Map.Source_Type; [[Source type.]]
            @in source_name: string; [[The source to be used.]]
         }
      }
      source_get @const {
         [[Get the name of currently used source for a specific type.]]
         return: string; [[The name of the source in use.]]
         params {
            @in type: Elm.Map.Source_Type; [[Source type.]]
         }
      }
      route_add {
         [[Add a new route to the map object.

           A route will be traced by point on coordinates ($flat, $flon)
           to point on coordinates ($tlat, $tlon), using the route service
           set with @.source_set.

           It will take $type on consideration to define the route,
           depending if the user will be walking or driving, the route may
           vary. One of #ELM_MAP_ROUTE_TYPE_MOTOCAR, #ELM_MAP_ROUTE_TYPE_BICYCLE,
           or #ELM_MAP_ROUTE_TYPE_FOOT need to be used.

           Another parameter is what the route should prioritize, the minor
           distance or the less time to be spend on the route. So $method
           should be one of #ELM_MAP_ROUTE_METHOD_SHORTEST or
           #ELM_MAP_ROUTE_METHOD_FASTEST.

           Routes created with this method can be deleted with
           \@ref elm_map_route_del and distance can be get with
           \@ref elm_map_route_distance_get.
         ]]
         return: ptr(Elm_Map_Route); [[The created route or $null upon failure.]]
         params {
            @in type: Elm.Map.Route_Type; [[The type of transport to be considered when tracing a route.]]
            @in method: Elm.Map.Route_Method; [[The routing method, what should be prioritized.]]
            @in flon: double; [[The start longitude.]]
            @in flat: double; [[The start latitude.]]
            @in tlon: double; [[The destination longitude.]]
            @in tlat: double; [[The destination latitude.]]
            @in route_cb: Elm_Map_Route_Cb @optional; [[The route to be traced.]]
            @in data: void_ptr @optional; [[A pointer of user data.]]
         }
      }
      track_add {
         [[Add a track on the map.]]
         return: Efl.Canvas.Object; [[The route object. This is an elm object of type Route.]]
         params {
            @in emap: void_ptr; [[The emap route object.]]
         }
      }
      region_to_canvas_convert @const {
         [[Convert geographic coordinates (longitude, latitude)
           into canvas coordinates.

           This gets canvas x, y coordinates from longitude and latitude.
           The canvas coordinates mean x, y coordinate from current viewport.
         ]]
         params {
            @in lon: double; [[The longitude to convert.]]
            @in lat: double; [[The latitude to convert.]]
            @out x: int; [[A pointer to horizontal coordinate.]]
            @out y: int; [[A pointer to vertical coordinate.]]
         }
      }
      overlay_circle_add {
         [[Add a new circle overlay to the map object.
           This overlay has a circle type.

           Overlay created with this method can be deleted with
           \@ref elm_map_overlay_del.
         ]]

         return: ptr(Elm_Map_Overlay); [[The created overlay or $null upon failure.]]
         params {
            @in lon: double; [[The center longitude.]]
            @in lat: double; [[The center latitude.]]
            @in radius: double; [[The pixel length of radius.]]
         }
      }
      overlay_class_add {
         [[Add a new class overlay to the map object.
           This overlay has a class type.

           This overlay is not shown before overlay members are appended.
           if overlay members in the same class are close, group overlays
           are created. If they are far away, group overlays are hidden.
           When group overlays are shown, they have default style layouts
           at first.

           You can change the state (hidden, paused, etc.) or set the
           content or icon of the group overlays by chaning the state of
           the class overlay. Do not modify the group overlay itself.

           Also these changes have a influence on the overlays in the
           same class even if each overlay is alone and is not grouped.
         ]]
         return: ptr(Elm_Map_Overlay); [[The created overlay or $null upon failure.]]
      }
      overlay_bubble_add {
         [[Add a new bubble overlay to the map object.
           This overlay has a bubble type.

           A bubble will not be displayed before geographic coordinates
           are set or any other overlays are followed.

           This overlay has a bubble style layout and icon or content can
           not be set.

           Overlay created with this method can be deleted with
           \@ref elm_map_overlay_del.
         ]]
         return: ptr(Elm_Map_Overlay); [[The created overlay or $null upon failure.]]
      }
      sources_get @const {
         [[Get the names of available sources for a specific type.

           It will provide a list with all available sources.
           Current source can be set by @.source_set, or get with
           @.source_get.

           At least available sources of tile type are "Mapnik", "Osmarender",
           "CycleMap" and "Maplint".

           At least available sources of route type are "Yours".

           At least available sources of name type are "Nominatim".
         ]]
         return: legacy(ptr(string)); [[The char pointer array of source names.]]
         params {
            @in type: Elm.Map.Source_Type; [[Source type.]]
         }
      }
      overlay_polygon_add {
         [[Add a new polygon overlay to the map object.
           This overlay has a polygon type.

           At least 3 regions should be added to show the polygon overlay.

           Overlay created with this method can be deleted with
           \@ref elm_map_overlay_del.
         ]]
         return: ptr(Elm_Map_Overlay); [[The created overlay or $null upon failure.]]
      }
      overlay_line_add {
         [[Add a new line overlay to the map object.
           This overlay has a line type.

           Overlay created with this method can be deleted with 
           \@ref elm_map_overlay_del.
         ]]
         return: ptr(Elm_Map_Overlay); [[The created overlay or $null upon failure.]]
         params {
            @in flon: double; [[The start longitude.]]
            @in flat: double; [[The start latitude.]]
            @in tlon: double; [[The destination longitude.]]
            @in tlat: double; [[The destination latitude.]]
         }
      }
      region_show {
         [[Show the given coordinates at the center of the map, immediately.

           This causes map to redraw its viewport's contents to the region
           containing the given $lat and $lon, that will be moved to the
           center of the map.

           See @.region_bring_in for a function to move with animation.
         ]]
         params {
            @in lon: double; [[Longitude to center at.]]
            @in lat: double; [[Latitude to center at.]]
         }
      }
      name_add @const {
         [[Request a address or geographic coordinates(longitude, latitude)
           from a given address or geographic coordinate(longitude, latitude).

           If you want to get address from geographic coordinates, set input
           $address as $null and set $lon, $lat as you want to convert. If
           address is set except NULL, $lon and $lat are checked.

           To get the string for this address, \@ref elm_map_name_address_get
           should be used after callback or "name,loaded" signal is called.

           To get the longitude and latitude, \@ref elm_map_region_get
           should be used.
         ]]
         return: ptr(Elm_Map_Name); [[A #Elm_Map_Name handle for this coordinate.]]
         params {
            @in address: string @optional; [[The address.]]
            @in lon: double; [[The longitude.]]
            @in lat: double; [[The latitude.]]
            @in name_cb: Elm_Map_Name_Cb @optional; [[The callback function.]]
            @in data: void_ptr @optional; [[The user callback data.]]
         }
      }
      name_search @const {
         [[Requests a list of addresses corresponding to a given name.

           \@internal

           @since 1.8
         ]]
         params {
            @in address: string; [[The address.]]
            @in name_cb: Elm_Map_Name_List_Cb @optional; [[The callback function.]]
            @in data: void_ptr @optional; [[The user callback data.]]
         }
      }
      region_bring_in {
         [[Animatedly bring in given coordinates to the center of the map.

           This causes map to jump to the given $lat and $lon coordinates
           and show it (by scrolling) in the center of the viewport, if it
           is not already centered. This will use animation to do so and
           take a period of time to complete.

           See @.region_show for a function to avoid animation.
         ]]
         params {
            @in lon: double; [[Longitude to center at.]]
            @in lat: double; [[Latitude to center at.]]
         }
      }
      region_zoom_bring_in {
         [[Animatedly set the zoom level of the map and bring in given
           coordinates to the center of the map.

           This causes map to zoom into specific zoom level and also move
           to the given $lat and $lon coordinates and show it (by scrolling)
           in the center of the viewport concurrently.

           See also @.region_bring_in.

           @since 1.11
         ]]
         params {
            @in zoom: int;   [[The zoom level to set.]]
            @in lon: double; [[Longitude to center at.]]
            @in lat: double; [[Latitude to center at.]]
         }
      }
      track_remove {
         [[Remove a track from the map.]]
         params {
            @in route: Efl.Canvas.Object; [[The track to remove.]]
         }
      }
      overlay_route_add {
         [[Add a new route overlay to the map object.
           This overlay has a route type.

           This overlay has a route style layout and icon or content can
           not be set.

           The color scheme can be changed by
           \@ref elm_map_overlay_content_set.

           Overlay created with this method can be deleted with
           \@ref elm_map_overlay_del.
         ]]
         return: ptr(Elm_Map_Overlay); [[The created overlay or $null upon failure.]]
         params {
            @cref route: Elm_Map_Route; [[The route object to make a overlay.]]
         }
      }
      overlay_scale_add {
         [[Add a new scale overlay to the map object. This overlay has a
           scale type.

           The scale overlay shows the ratio of a distance on the map to
           the corresponding distance.

           Overlay created with this method can be deleted with
           \@ref elm_map_overlay_del.
         ]]
         return: ptr(Elm_Map_Overlay); [[The created overlay or $null upon failure.]]
         params {
            @in x: int; [[horizontal pixel coordinate.]]
            @in y: int; [[vertical pixel coordinate.]]
         }
      }
      overlay_add {
         [[Add a new overlay to the map object. This overlay has a default
           type.

           A overlay will be created and shown in a specific point of the
           map, defined by $lon and $lat.

           The created overlay has a default style layout before content or
           icon is set. If content or icon is set, those are displayed
           instead of default style layout.
   
           You can set by using \@ref elm_map_overlay_content_set or
           \@ref elm_map_overlay_icon_set. If $null is set, default style
           is shown again.

           Overlay created with this method can be deleted by
           \@ref elm_map_overlay_del.
         ]]
         return: ptr(Elm_Map_Overlay); [[The created overlay or $null upon failure.]]
         params {
            @in lon: double; [[The longitude of the overlay.]]
            @in lat: double; [[The latitude of the overlay.]]
         }
      }
      canvas_to_region_convert @const {
         [[Convert canvas coordinates into geographic coordinates
           (longitude, latitude).

           This gets longitude and latitude from canvas x, y coordinates.
           The canvas coordinates mean x, y coordinate from current viewport.
         ]]
         params {
            @in x: int; [[Horizontal coordinate of the point to convert.]]
            @in y: int; [[Vertical coordinate of the point to convert.]]
            @out lon: double; [[A pointer to the longitude.]]
            @out lat: double; [[A pointer to the latitude.]]
         }
      }
   }
   implements {
      class.constructor;
      Efl.Object.constructor;
      Efl.Gfx.position { set; }
      Efl.Gfx.size { set; }
      Efl.Canvas.Group.group_member_add;
      Efl.Ui.Widget.theme_apply;
      Efl.Ui.Focus.Object.on_focus_update;
      Efl.Ui.Widget.widget_event;
      Efl.Access.Widget.Action.elm_actions { get; }
   }
   events {
      press; [[Called when map was pressed]]
      zoom,change; [[Called when map zoom changed]]
      loaded; [[Called when map loaded]]
      tile,load; [[Called when title load started]]
      tile,loaded; [[Called when title load finished]]
      tile,loaded,fail; [[Called when title load failed]]
      route,load; [[Called when route load started]]
      route,loaded; [[Called when route load finished]]
      route,loaded,fail; [[Called when route load failed]]
      name,load; [[Called when name load started]]
      name,loaded; [[Called when name load finished]]
      name,loaded,fail; [[Called when name load failed]]
      overlay,clicked; [[Called when overlay was clicked]]
      overlay,del; [[Called when overlay was deleted]]
   }
}