MapView

A zoomable map that can be annotated with location pins.

../../../_images/mapview-cocoa.png

Usage

A MapView is a scrollable area that can show a map at varying levels of detail, from nation-level to street level. The map can be centered at a given coordinate, and zoomed to the required level of detail using an integer from 0 (for global detail) to 20 (for building level detail):

import toga

# Create a map centered in London, UK.
mapview = toga.MapView(location=(51.507222, -0.1275))

# Center the map in Perth, Australia
mapview.location = (-31.9559, 115.8606)

# Zoom to show the map to show street level detail
mapview.zoom = 15

A map can also display pins. A map pin must have a title, and can optionally have a subtitle. Pins can be added at time of map construction, or can be dynamically added, updated and removed at runtime:

import toga

mapview = toga.MapView(
    pins=[
        toga.MapPin(toga.MapPin((-31.95064, 115.85889), title="Yagan Square"))
    ]
)

# Create a new pin, and add it to the map
brutus = toga.MapPin(toga.MapPin((41.50375, -81.69475), title="Brutus was here"))
mapview.pins.add(brutus)

# Update the pin label and position
brutus.location = (40.440831, -79.991162)
brutus.title = "Brutus will be here"

# Remove the Brutus pin
mapview.pins.remove(brutus)

# Remove all pins
mapview.pins.clear()

Pins can respond to being pressed. When a pin is pressed, the map generates an on_select event, which receives the pin as an argument.

Notes

  • The Android, GTK and Winforms implementations of MapView use OpenStreetMap as a source of map tiles. OpenStreetMap is an open data project with its own copyright, license terms, and acceptable use policies. If you make use of MapView in your application, it is your responsibility to ensure that your app complies with these terms. In addition, we strongly encourage you to financially support the OpenStreetMap Foundation, as their work is what allows Toga to provide map content on these platforms.

  • Using MapView on Android requires the OSMDroid package to be added your project’s Gradle dependencies. Ensure your app declares a dependency on org.osmdroid:osmdroid-android:6.1.0 or later.

  • Using MapView on Windows 10 requires that your users have installed the Edge WebView2 Evergreen Runtime. This is installed by default on Windows 11.

  • Using MapView on Linux requires that the user has installed the system packages for WebKit2, plus the GObject Introspection bindings for WebKit2.

  • On macOS and iOS, MapView will not repeat map tiles if the viewable area at the given zoom level is bigger than the entire world. A zoom to a very low level will be clipped to the lowest level that allows displaying the map without repeating tiles.

Reference

class toga.MapView(id=None, style=None, location=None, zoom=11, pins=None, on_select=None)

Bases: Widget

Create a new MapView widget.

Parameters:

  • id – The ID for the widget.

  • style – A style object. If no style is provided, a default style will be applied to the widget.

  • location (toga.LatLng | tuple[float, float] | None) – The initial latitude/longitude where the map should be centered. If not provided, the initial location for the map is Perth, Australia.

  • zoom (int) – The initial zoom level for the map.

  • pins (list[MapPin] | None) – The initial pins to display on the map.

  • on_select (toga.widgets.mapview.OnSelectHandler | None) – A handler that will be invoked when the user selects a map pin.

property location: LatLng

The latitude/longitude where the map is centered.

A tuple of (latitude, longitude) can be provided as input; this will be converted into a toga.LatLng object.

property on_select: OnSelectHandler

The handler to invoke when the user selects a pin on a map.

Note: This is not currently supported on GTK or Windows.

property pins: MapPinSet

The set of pins currently being displayed on the map

property zoom: int

Set the zoom level for the map.

The zoom level is an integer in the range 0-20 (inclusive). It can be used to set the number of degrees of longitude that will span a 256 CSS pixel region in the horizontal axis of the map, following the relationship:

longitude_per_256_pixels = 360 / (2**zoom)

In practical terms, this means a 256px square will cover:

  • 0-2: Whole world

  • 3-6: Large countries

  • 7-8: Small countries, or a state in a large country

  • 9-11: The extent of a city

  • 12-14: Suburbs of a city, or small towns

  • 15-17: Roads at the level useful for navigation

  • 18-19: Individual buildings

  • 20: A single building

These zoom levels use the same mathematical basis as the OpenStreetMap API. See OpenStreetMap’s documentation on zoom levels for more details.

If the provided zoom value is outside the supported range, it will be clipped.

At very low zoom levels, some backends may constrain the viewable range to avoid repeating map tiles in the visible area. This effectively sets a minimum bound on the zoom level that can be requested. The value of this minimum varies depending on the size and aspect ratio of the map view.

class toga.MapPin(location, *, title, subtitle=None)

Create a new map pin.

Parameters:

  • location (toga.LatLng | tuple[float, float]) – A tuple describing the (latitude, longitude) for the pin.

  • title (str) – The title to apply to the pin.

  • subtitle (str | None) – A subtitle label to apply to the pin.

property location: LatLng

The (latitude, longitude) where the pin is located.

property subtitle: str | None

The subtitle of the pin.

property title: str

The title of the pin.

class toga.widgets.mapview.MapPinSet(interface, pins)
add(pin)

Add a new pin to the map.

Parameters:

pin – The toga.MapPin instance to add.

clear()

Remove all pins from the map.

remove(pin)

Remove a pin from the map.

Parameters:

pin – The toga.MapPin instance to remove.

protocol toga.widgets.mapview.OnSelectHandler

typing.Protocol.

Classes that implement this protocol must have the following methods / attributes:

__call__(widget, *, pin, **kwargs)

A handler that will be invoked when the user selects a map pin.

Parameters:

  • widget (MapView) – The button that was pressed.

  • pin (MapPin) – The pin that was selected.

  • kwargs (Any) – Ensures compatibility with arguments added in future versions.

Return type:

None