diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a9b1ae552e..b5fc2aacfc 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -208,7 +208,7 @@ jobs: pre-command: | sudo apt update -y sudo apt install -y --no-install-recommends \ - blackbox pkg-config python3-dev libgirepository1.0-dev libcairo2-dev gir1.2-webkit2-4.0 + blackbox pkg-config python3-dev libgirepository1.0-dev libcairo2-dev gir1.2-webkit2-4.1 # Start Virtual X server echo "Start X server..." diff --git a/changes/2544.doc.rst b/changes/2544.doc.rst new file mode 100644 index 0000000000..9bbce9768b --- /dev/null +++ b/changes/2544.doc.rst @@ -0,0 +1 @@ +An explicit system requirements section was added to the documentation for widgets that require the installation of additional system components. diff --git a/docs/reference/api/containers/optioncontainer.rst b/docs/reference/api/containers/optioncontainer.rst index f832efd013..284d584c69 100644 --- a/docs/reference/api/containers/optioncontainer.rst +++ b/docs/reference/api/containers/optioncontainer.rst @@ -132,6 +132,13 @@ item, you can specify an item using: # Delete the pasta tab del container.content[pasta_tab] +System requirements +------------------- + +* Using OptionContainer on Android requires the Material package in your project's + Gradle dependencies. Ensure your app declares a dependency on + ``com.google.android.material:material:1.11.0`` or later. + Notes ----- diff --git a/docs/reference/api/widgets/mapview.rst b/docs/reference/api/widgets/mapview.rst index 50b7625162..d519f97b8c 100644 --- a/docs/reference/api/widgets/mapview.rst +++ b/docs/reference/api/widgets/mapview.rst @@ -95,6 +95,30 @@ updated and removed at runtime: 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. +.. _mapview-system-requires: + +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 18.04, 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`` + - FreeBSD: ``webkit2-gtk3`` + +* 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.0`` or later. + Notes ----- @@ -107,18 +131,6 @@ Notes `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. diff --git a/docs/reference/api/widgets/webview.rst b/docs/reference/api/widgets/webview.rst index 1e172ece86..f1e7472377 100644 --- a/docs/reference/api/widgets/webview.rst +++ b/docs/reference/api/widgets/webview.rst @@ -61,12 +61,11 @@ Usage # Load static HTML content into the wevbiew. webview.set_content("https://example.com", "...") -Notes ------ -* Due to app security restrictions, WebView can only display ``http://`` and - ``https://`` URLs, not ``file://`` URLs. To serve local file content, run a - web server on ``localhost`` using a background thread. +.. _webview-system-requires: + +System requirements +------------------- * Using WebView on Windows 10 requires that your users have installed the `Edge WebView2 Evergreen Runtime @@ -74,7 +73,21 @@ Notes This is installed by default on Windows 11. * Using WebView on Linux requires that the user has installed the system packages - for WebKit2, plus the GObject Introspection bindings for WebKit2. + for WebKit2, plus the GObject Introspection bindings for WebKit2. The name of + the system package required is distribution dependent: + + - Ubuntu 18.04, 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`` + - FreeBSD: ``webkit2-gtk3`` + +Notes +----- + +* Due to app security restrictions, WebView can only display ``http://`` and + ``https://`` URLs, not ``file://`` URLs. To serve local file content, run a + web server on ``localhost`` using a background thread. * On macOS 13.3 (Ventura) and later, the content inspector for your app can be opened by running Safari, `enabling the developer tools diff --git a/docs/reference/platforms/unix-prerequisites.rst b/docs/reference/platforms/unix-prerequisites.rst index 5c94b4a3f2..b47fd1bdf5 100644 --- a/docs/reference/platforms/unix-prerequisites.rst +++ b/docs/reference/platforms/unix-prerequisites.rst @@ -2,34 +2,39 @@ These instructions are different on almost every version of Linux and Unix; here some of the common alternatives: .. - The package list should be the same as in ci.yml, and the BeeWare tutorial. + The package list should be the same as in ci.yml, and the BeeWare tutorial + (CI will also have WebView requirements) -**Ubuntu 18.04+ / Debian 10+** +**Ubuntu 18.04+ / Debian 11+** .. code-block:: console (venv) $ sudo apt update - (venv) $ sudo apt install pkg-config python3-dev libgirepository1.0-dev libcairo2-dev gir1.2-webkit2-4.0 libcanberra-gtk3-module + (venv) $ sudo apt install pkg-config python3-dev libgirepository1.0-dev libcairo2-dev libcanberra-gtk3-module **Fedora** .. code-block:: console - (venv) $ sudo dnf install pkg-config python3-devel gobject-introspection-devel cairo-gobject-devel webkit2gtk3 libcanberra-gtk3 + (venv) $ sudo dnf install pkg-config python3-devel gobject-introspection-devel cairo-gobject-devel libcanberra-gtk3 **Arch / Manjaro** .. code-block:: console - (venv) $ sudo pacman -Syu git pkgconf gobject-introspection cairo webkit2gtk libcanberra + (venv) $ sudo pacman -Syu git pkgconf gobject-introspection cairo libcanberra **FreeBSD** .. code-block:: console (venv) $ sudo pkg update - (venv) $ sudo pkg install gobject-introspection cairo webkit2-gtk3 libcanberra-gtk3 + (venv) $ sudo pkg install gobject-introspection cairo libcanberra-gtk3 If you're not using one of these, you'll need to work out how to install the developer libraries for ``python3``, ``cairo``, and ``gobject-introspection`` (and please let us know so we can improve this documentation!) + +Some widgets (most notably, the :ref:`WebView ` and +:ref:`MapView ` widgets) have additional system requirements. +See the documentation of those widgets for details. diff --git a/gtk/src/toga_gtk/libs/gtk.py b/gtk/src/toga_gtk/libs/gtk.py index 21c74800e6..40fd0034d5 100644 --- a/gtk/src/toga_gtk/libs/gtk.py +++ b/gtk/src/toga_gtk/libs/gtk.py @@ -16,7 +16,7 @@ try: try: gi.require_version("WebKit2", "4.1") - except ValueError: + except ValueError: # pragma: no cover gi.require_version("WebKit2", "4.0") from gi.repository import WebKit2 # noqa: F401 except (ImportError, ValueError): # pragma: no cover diff --git a/gtk/src/toga_gtk/widgets/mapview.py b/gtk/src/toga_gtk/widgets/mapview.py index c701d1166a..60fb0ff1fc 100644 --- a/gtk/src/toga_gtk/widgets/mapview.py +++ b/gtk/src/toga_gtk/widgets/mapview.py @@ -71,7 +71,9 @@ def create(self): if WebKit2 is None: # pragma: no cover raise RuntimeError( "Unable to import WebKit2. Ensure that the system package " - "providing Webkit2 and its GTK bindings have been installed." + "providing WebKit2 and its GTK bindings have been installed. " + "See https://toga.readthedocs.io/en/stable/reference/api/widgets/mapview.html#system-requirements " + "for details." ) self.native = WebKit2.WebView() diff --git a/gtk/src/toga_gtk/widgets/webview.py b/gtk/src/toga_gtk/widgets/webview.py index 103df304ea..15ff96bd3a 100644 --- a/gtk/src/toga_gtk/widgets/webview.py +++ b/gtk/src/toga_gtk/widgets/webview.py @@ -13,7 +13,9 @@ def create(self): if WebKit2 is None: # pragma: no cover raise RuntimeError( "Unable to import WebKit2. Ensure that the system package " - "providing Webkit2 and its GTK bindings have been installed." + "providing WebKit2 and its GTK bindings have been installed. " + "See https://toga.readthedocs.io/en/stable/reference/api/widgets/webview.html#system-requirements " + "for details." ) self.native = WebKit2.WebView()