path: root/src/lib/elementary/elm_map.eo

/* 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.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, Efl.Ui.Zoom)
{
   [[Elementary map class]]
   legacy_prefix: elm_map;
   eo_prefix: elm_obj_map;
   event_prefix: elm_map;
   methods {
      @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 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 map_rotate {
         set {
            [[Rotate the map.]]
            legacy: elm_map_rotate_set;
         }
         get {
            [[Get the rotate degree of the map.]]
            legacy: elm_map_rotate_get;
         }
         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 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 @.map_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 @.map_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.]]
         }
      }
      map_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.
         ]]
         legacy: elm_map_region_bring_in;
         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 @.map_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.Entity.position { set; }
      Efl.Gfx.Entity.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; }
      Efl.Ui.Zoom.zoom_level { set; }
      Efl.Ui.Zoom.zoom_mode { set; }
      Elm.Interface_Scrollable.wheel_disabled { set; }
   }
   events {
      press; [[Called when map was pressed]]
      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]]
   }
}