To enable window embedding higher in the stack (Qt Widgets, Qt Quick), we rely on primitives provided by QtGui and in turn the QPA layer. This task is a survey of these enablers, and the current state on the various platforms.

• QWindow support
  • All platforms (hopefully) have this  
• Multiple top level QWindows
  • Not a requirement for window embedding, but a related topic
• Child QWindow support
  • A QWindow be both top level (with or without a transient parent), or a child window
  • Child window support requires that the platform handles QPlatformWindow::setParent()
  • Child windows handle all input transformation, ie content is agnostic to the window being a child.

• QWindow::setMask()
  • Useful for masking away part of the window (punching a hole)
  • Is documented to apply to input events (mouse, touch)
  • Is not guaranteed to visually clip the window
    • Client should clip drawing to mask

• QWindow::fromWinId()
  • Allows adopting windows created via the native APIs
  • Results in a QWindow that represents the native window
  • Supports two distinct use-cases
    • Embedding of a Qt window into a native window
      • Useful for using Qt as part of a larger application writing with a native toolkit
      • The foreign window acts only as a parent for the Qt window
      • No other modifications of the native window through the wrapper QWindow
    • Embedding of a native window into a Qt window
      • Useful for adding UI elements to a Qt app that Qt doesn’t support (yet)
      • Or where the platform has native UI controls that we can’t easily replicate
      • The foreign window must support parenting into another QWindow
      • Once parented, it should support all normal operations on a QWindow, since the rest of the app shouldn’t care that the window is foreign. E.g setGeometry, setMask, setOpacity
        • Our various platforms differ in how far they go here. At a minimum we need setParent and setGeometry
• QSurfaceFormat::setAlphaBufferSize()
  • Allows windows with transparency
  • Useful for overlays that are not perfectly square

A test case for these areas is added in qtbase tests/manual/embeddedwindows/

Shown here on macOS:

• The top row tests child windows, with a circular setMask, and with alpha channel
• The second row tests foreign windows, with a mask
• The third row is a foreign window with an embedded Qt window