Introduction¶
xleaflet
is the C++ backend for the leaflet maps visualization library. The
Python reference implementation is available in the ipyleaflet project.
xleaflet
depends on xwidgets, each object that you can create in xleaflet
is an xwidget instance which is synchronized with one or more views on the frontend.
See the xwidgets
documentation for the usage of widgets.
Basic usage¶
Default map¶
The default map can be displayed using Jupyter’s display framework.
xlf::map map;
map.display();
Changing widget attributes can be done from the model:
map.zoom = 15;
// latitude 52.204793, longitude 360.121558
map.center = std::array<double, 2>({52.204793, 360.121558});
Or by interacting directly with the view.
The map widget works with a list of layers. Layers are instances of tile_layer
, marker
, popup
, wms_layer
, image_overlay
,
video_overlay
, polygon
, rectangle
, circle_marker
, circle
, marker_cluster
, layer_group
or geo_json
.
#include "xleaflet/xmap.hpp"
xlf::map map;
map.add_layer(marker);
map.add_layer(circle);
map.add_layer(layer_group);
map.remove_layer(circle);
map.clear_layers();
It is also possible to have a list of controls on the map. Controls are instances of layers_control
, split_map_control
or draw_control
.
#include "xleaflet/xmap.hpp"
xlf::map map;
map.add_control(control1);
map.add_control(control2);
map.remove_control(control1);
map.clear_controls();
Generator classes¶
Widgets such as map
may have a large number of attributes that can be set by the user, such as center
, zoom
, min_zoom
, max_zoom
, scroll_wheel_zoom
, bounce_at_zoom_limits
, inertia
.
Providing a constructor for map
with a large number of such attributes would make the use of xleaflet
very cumbersome, because users would need to know all the positional arguments to modify only one value. Instead, we mimick a keyword argument initialization with a method-chaining mechanism.
#include "xleaflet/xmap.hpp"
auto map = xlf::map::initialize()
.center({52.204793, 360.121558})
.zoom(15)
.scroll_wheel_zoom(true)
.inertia(false)
.finalize();
Special Events¶
One could want to react on special map events like mousemove
, this can be achieved by using the on_interaction
method of map:
#include <iostream>
#include "xleaflet/xmap.hpp"
void print_mouse_position(xeus::xjson event)
{
if (event["type"] == "mousemove")
{
std::cout << "Mouse position: " << event["coordinates"].dump() << std::endl;
}
if (event["type"] == "mouseout")
{
std::cout << "Mouse out" << std::endl;;
}
}
xlf::map map;
map.on_interaction(print_mouse_position);
map.display();
XProperty Events¶
xleaflet
relies on the xproperty library, so that one could use the XOBSERVE
function to react on model changes:
#include <iostream>
#include "xleaflet/xmap.hpp"
void print_lat_lng(xlf::map& map)
{
std::string lat = std::to_string(map.center().front());
std::string lng = std::to_string(map.center().back());
std::cout << "latitude: " << lat << ", longitude: " << lng << std::endl;
}
xlf::map map;
XOBSERVE(map, center, print_lat_lng);
map.display();