fix: force xcb on Linux and warn on handle=0 in Wayland sessions

qt.py: override QT_QPA_PLATFORM=xcb unconditionally on Linux for all Qt
bindings (PyQt5/PyQt6/PySide6).  Wayland desktops such as KDE Plasma on
Kubuntu often pre-set QT_QPA_PLATFORM=wayland in the session environment;
setdefault was insufficient to override it, causing CEF to open a detached
top-level window instead of embedding into the Qt widget.

window_info.pyx: add a warnings.warn() in SetAsChild when
parentWindowHandle is 0 and WAYLAND_DISPLAY is set.  This catches the
same misconfiguration for any toolkit (Qt, GTK, SDL2) and points the
developer to the correct per-toolkit env var fix.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: linesight

examples/qt.py

@@ -62,12 +62,14 @@
 LINUX = (platform.system() == "Linux")
 MAC = (platform.system() == "Darwin")
 
-# Qt6 (PyQt6/PySide6) defaults to the Wayland backend when the session is
-# Wayland.  CEF always uses X11 (ozone-platform=x11), so embedding requires
-# both sides to use X11.  Force Qt6 onto the xcb (X11) platform.
-# This must be set before creating QApplication.
-if LINUX and (PYQT6 or PYSIDE6):
-    os.environ.setdefault("QT_QPA_PLATFORM", "xcb")
+# CEF only supports X11 on Linux.  Force Qt onto the xcb (X11/XWayland)
+# backend for all bindings so that winId() returns a real X11 window ID
+# that CEF can embed into.  Wayland desktops (e.g. KDE Plasma on Kubuntu)
+# often pre-set QT_QPA_PLATFORM=wayland in the session environment, so a
+# hard override is needed — setdefault would not override a pre-set value.
+# Must be set before creating QApplication.
+if LINUX:
+    os.environ["QT_QPA_PLATFORM"] = "xcb"
 
 # On Linux, query the X11 pointer button mask directly to detect outside-clicks
 # on the context menu.  XQueryPointer returns real button state even while CEF

src/window_info.pyx

@@ -113,6 +113,25 @@ cdef class WindowInfo:
                     % parentWindowHandle)
         self.windowType = "child"
         IF UNAME_SYSNAME == "Linux":
+            if parentWindowHandle == 0:
+                import os as _os
+                import warnings
+                if "WAYLAND_DISPLAY" in _os.environ:
+                    warnings.warn(
+                        "WindowInfo.SetAsChild: parentWindowHandle is 0 on Linux "
+                        "in a Wayland session. The GUI toolkit is likely using the "
+                        "native Wayland backend where winId()/GetHandle() returns 0 "
+                        "instead of an X11 window ID — CEF will open a detached "
+                        "window instead of embedding. Force X11 (XWayland) before "
+                        "initialising the toolkit:\n"
+                        "  Qt (PyQt5/PyQt6/PySide2/PySide6): "
+                        "os.environ[\"QT_QPA_PLATFORM\"] = \"xcb\"\n"
+                        "  GTK (wxPython/PyGTK): "
+                        "os.environ[\"GDK_BACKEND\"] = \"x11\"\n"
+                        "  SDL2 (pysdl2): "
+                        "os.environ[\"SDL_VIDEODRIVER\"] = \"x11\"",
+                        stacklevel=2,
+                    )
             if parentWindowHandle != 0:
                 # Xwayland cross-client restriction: Chrome's internal XCB
                 # connection cannot create a child window under a window owned