MapView

A zoomable map that can be annotated with location pins.

macOSLinuxWindowsAndroidiOSWeb ^❌Textual ^❌

Not supported

Not supported

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((-31.95064, 115.85889), title="Yagan Square"),
    ]
)

# Create a new pin, and add it to the map
brutus = 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.

System requirements

• 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. The name of the system package required is distribution dependent:

• Ubuntu 20.04; Debian 11: gir1.2-webkit2-4.0
• Ubuntu 22.04+; Debian 12+: gir1.2-webkit2-4.1
• Fedora: webkit2gtk4.1
• Arch/Manjaro: webkit2gtk-4.1
• OpenSUSE Tumbleweed: libwebkit2gtk3 typelib(WebKit2)
• FreeBSD: webkit2-gtk3

MapView is not fully supported on GTK4. If you want to contribute to the GTK4 MapView implementation, you will require v6.0 of the WebKit2 libraries. This is provided by gir1.2-webkit-6.0 on Ubuntu/Debian, and webkitgtk6.0 on Fedora; for other distributions, consult your distribution's platform documentation.

• Using MapView on Android requires the OSMDroid package in your project's Gradle dependencies. Ensure your app declares a dependency on org\.osmdroid:osmdroid-android:6.1.20 or later.

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.
• 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

toga.MapView

MapView(
    id=None,
    style=None,
    location=None,
    zoom=11,
    pins=None,
    on_select=None,
    **kwargs,
)

Bases: Widget

Create a new MapView widget.

PARAMETER	DESCRIPTION
id	The ID for the widget. TYPE: str | None DEFAULT: None
style	A style object. If no style is provided, a default style will be applied to the widget. TYPE: StyleT | None DEFAULT: None
location	The initial latitude/longitude where the map should be centered. If not provided, the initial location for the map is Perth, Australia. TYPE: LatLng | tuple[float, float] | None DEFAULT: None
zoom	The initial zoom level for the map. TYPE: int DEFAULT: 11
pins	The initial pins to display on the map. TYPE: Iterable[MapPin] | None DEFAULT: None
on_select	A handler that will be invoked when the user selects a map pin. TYPE: OnSelectHandler | None DEFAULT: None
kwargs	Initial style properties. DEFAULT: {}

location property writable

location

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.

on_select property writable

on_select

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

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

pins property

pins

The set of pins currently being displayed on the map

zoom property writable

zoom

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.

toga.MapPin

MapPin(location, *, title, subtitle=None)

Create a new map pin.

PARAMETER	DESCRIPTION
location	A tuple describing the (latitude, longitude) for the pin. TYPE: LatLng | tuple[float, float]
title	The title to apply to the pin. TYPE: str
subtitle	A subtitle label to apply to the pin. TYPE: str | None DEFAULT: None

location property writable

location

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

subtitle property writable

subtitle

The subtitle of the pin.

title property writable

title

The title of the pin.

toga.widgets.mapview.MapPinSet

MapPinSet(interface, pins)

__iter__

__iter__()

Return an iterator over the pins on the map.

__len__

__len__()

Return the number of pins being displayed.

add

add(pin)

Add a new pin to the map.

PARAMETER	DESCRIPTION
pin	The toga.MapPin instance to add. TYPE: MapPin

clear

clear()

Remove all pins from the map.

remove

remove(pin)

Remove a pin from the map.

PARAMETER	DESCRIPTION
pin	The toga.MapPin instance to remove. TYPE: MapPin

toga.widgets.mapview.OnSelectHandler

Bases: Protocol

__call__

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

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

PARAMETER	DESCRIPTION
widget	The MapView that was selected. TYPE: MapView
pin	The pin that was selected. TYPE: MapPin
kwargs	Ensures compatibility with arguments added in future versions. TYPE: Any DEFAULT: {}