Add a setting to force the platform and improve Wayland handling

Closes #3078
See #2932

doc/help/settings.asciidoc

@@ -211,6 +211,7 @@
 |<<prompt.filebrowser,prompt.filebrowser>>|Show a filebrowser in upload/download prompts.
 |<<prompt.radius,prompt.radius>>|The rounding radius for the edges of prompts.
 |<<qt.args,qt.args>>|Additional arguments to pass to Qt, without leading `--`.
+|<<qt.force_platform,qt.force_platform>>|Force a Qt platform to use.
 |<<qt.force_software_rendering,qt.force_software_rendering>>|Force software rendering for QtWebEngine.
 |<<scrolling.bar,scrolling.bar>>|Show a scrollbar.
 |<<scrolling.smooth,scrolling.smooth>>|Enable smooth scrolling for web pages.
@@ -2443,6 +2444,15 @@ Type: <<types,List of String>>
 
 Default: empty
 
+[[qt.force_platform]]
+=== qt.force_platform
+Force a Qt platform to use.
+This sets the `QT_QPA_PLATFORM` environment variable and is useful to force using the XCB plugin when running QtWebEngine on Wayland.
+
+Type: <<types,String>>
+
+Default: empty
+
 [[qt.force_software_rendering]]
 === qt.force_software_rendering
 Force software rendering for QtWebEngine.

qutebrowser/config/configdata.yml

@@ -145,6 +145,17 @@ qt.force_software_rendering:
     This is needed for QtWebEngine to work with Nouveau drivers.
     This setting requires a restart.
 
+qt.force_platform:
+  type:
+    name: String
+    none_ok: true
+  default: null
+  desc: >-
+    Force a Qt platform to use.
+
+    This sets the `QT_QPA_PLATFORM` environment variable and is useful to force
+    using the XCB plugin when running QtWebEngine on Wayland.
+
 
 ## auto_save
 

qutebrowser/config/configinit.py

@@ -85,6 +85,9 @@ def _init_envvars():
             config.val.qt.force_software_rendering):
         os.environ['QT_XCB_FORCE_SOFTWARE_OPENGL'] = '1'
 
+    if config.val.qt.force_platform is not None:
+        os.environ['QT_QPA_PLATFORM'] = config.val.qt.force_platform
+
     if config.val.window.hide_wayland_decoration:
         os.environ['QT_WAYLAND_DISABLE_WINDOWDECORATION'] = '1'
     else:

qutebrowser/misc/backendproblem.py

@@ -197,14 +197,31 @@ def _handle_wayland():
     if platform not in ['wayland', 'wayland-egl']:
         return
 
-    _show_dialog(
-        backend=usertypes.Backend.QtWebEngine,
-        because="you're using Wayland",
-        text="<p>There are two ways to fix this:</p>"
-             "<p><b>Set up XWayland</b></p>"
-             "<p>This allows you to use the newer QtWebEngine backend (based "
-             "on Chromium). "
-    )
+    if 'DISPLAY' in os.environ:
+        # XWayland is available, but QT_QPA_PLATFORM=wayland is set
+        button = _Button("Force XWayland", 'qt.force_platform', 'xcb')
+        _show_dialog(
+            backend=usertypes.Backend.QtWebEngine,
+            because="you're using Wayland",
+            text="<p>There are two ways to fix this:</p>"
+                 "<p><b>Force Qt to use XWayland</b></p>"
+                 "<p>This allows you to use the newer QtWebEngine backend "
+                 "(based on Chromium). "
+                 "This sets the <i>qt.force_platform = 'xcb'</i> option "
+                 "(if you have a <i>config.py</i> file, you'll need to set "
+                 "this manually).</p>",
+            buttons=[button],
+        )
+    else:
+        # XWayland is unavailable
+        _show_dialog(
+            backend=usertypes.Backend.QtWebEngine,
+            because="you're using Wayland without XWayland",
+            text="<p>There are two ways to fix this:</p>"
+                 "<p><b>Set up XWayland</b></p>"
+                 "<p>This allows you to use the newer QtWebEngine backend "
+                 "(based on Chromium). "
+        )
 
     # Should never be reached
     assert False

tests/unit/config/test_configinit.py

@@ -213,6 +213,15 @@ class TestEarlyInit:
 
         assert os.environ[envvar] == '1'
 
+    def test_force_platform(self, monkeypatch, config_stub):
+        envvar = 'QT_QPA_PLATFORM'
+        monkeypatch.delenv(envvar, raising=False)
+
+        config_stub.val.qt.force_platform = 'toaster'
+
+        configinit._init_envvars()
+        assert os.environ[envvar] == 'toaster'
+
     @pytest.mark.parametrize('old', ['1', '0', None])
     @pytest.mark.parametrize('configval', [True, False])
     def test_hide_wayland_decoration(self, monkeypatch, config_stub,