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

/* FIXME: Handle properly. */
type Elm_Map_Route: __undefined_type;
type Elm_Map_Route_Cb: __undefined_type;
type Elm_Map_Overlay: __undefined_type;
type Elm_Map_Name: __undefined_type;
type Elm_Map_Name_Cb: __undefined_type;
type Elm_Map_Name_List_Cb: __undefined_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
}

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
}

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
}


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
}


class Elm.Map (Elm.Widget, Elm.Interface_Scrollable,
               Elm.Interface.Atspi_Widget_Action,
               Evas.Clickable_Interface)
{
   legacy_prefix: elm_map;
   eo_prefix: elm_obj_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: Evas.Coord; [[Rotation's center horizontal position.]]
            cy: Evas.Coord; [[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: const(char)*; [[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<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: const(char)*; [[The source to be used.]]
         }
      }
      source_get @const {
         [[Get the name of currently used source for a specific type.]]
         return: const(char)*; [[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: 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 * @optional; [[A pointer of user data.]]
         }
      }
      track_add {
         [[Add a track on the map.]]
         return: Evas.Object *; [[The route object. This is an elm object of type Route.]]
         params {
            @in emap: void *; [[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: Evas.Coord; [[A pointer to horizontal coordinate.]]
            @out y: Evas.Coord; [[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: 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: 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: 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: const(char)**; [[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: 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: 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: Elm_Map_Name *; [[A #Elm_Map_Name handle for this coordinate.]]
         params {
            @in address: const(char)* @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 * @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: const(char)*; [[The address.]]
            @in name_cb: Elm_Map_Name_List_Cb @optional; [[The callback function.]]
            @in data: void * @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: Evas.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: Elm_Map_Overlay *; [[The created overlay or $null upon failure.]]
         params {
            @in route: const(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: Elm_Map_Overlay *; [[The created overlay or $null upon failure.]]
         params {
            @in x: Evas.Coord; [[horizontal pixel coordinate.]]
            @in y: Evas.Coord; [[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: 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: Evas.Coord; [[Horizontal coordinate of the point to convert.]]
            @in y: Evas.Coord; [[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;
      Eo.Base.constructor;
      Evas.Object.Smart.move;
      Evas.Object.Smart.add;
      Evas.Object.Smart.del;
      Evas.Object.Smart.member_add;
      Evas.Object.Smart.resize;
      Elm.Widget.theme_apply;
      Elm.Widget.on_focus;
      Elm.Widget.event;
      Elm.Interface.Atspi_Widget_Action.elm_actions.get;
   }
   events {
      press;
      zoom,change;
      loaded;
      tile,load;
      tile,loaded;
      tile,loaded,fail;
      route,load;
      route,loaded;
      route,loaded,fail;
      name,load;
      name,loaded;
      name,loaded,fail;
      overlay,clicked;
      overlay,del;
   }

}