Add note about fullscreen windows limitation with solution

Change-Id: I38178d2b2f61c7ba2aca60aa62146f9f5c2af58c
Reviewed-by: Topi Reiniö <topi.reinio@theqtcompany.com>

1 files changed, 27 insertions, 0 deletions

diff --git a/doc/src/platforms/windows.qdoc b/doc/src/platforms/windows.qdoc
index d814765c..2a18547d 100644
--- a/doc/src/platforms/windows.qdoc
+++ b/doc/src/platforms/windows.qdoc
@@ -533,6 +533,33 @@
 
     Consult the \l{Qt for Windows - Requirements} page for specific versions
     of the Windows SDK.
+
+    \section1 Fullscreen OpenGL Based Windows
+
+    When a window is using an OpenGL based surface and is appearing in full screen mode,
+    problems can occur with other top-level windows which are part of the application.
+    When going into full screen mode, compositing is not handled correctly for OpenGL based
+    windows. As a result, other top-level windows are not placed on top of the full screen
+    window when they are made visible. For example, menus may not appear correctly, or
+    dialogs fail to show up.
+
+    A window can use an OpenGL based surface either explicitly when setSurfaceType() is
+    called or when something that requires OpenGL is used inside the window which causes
+    the whole window to be OpenGL based. For example, QOpenGLWidget or QQuickWidget can
+    trigger this. However, if it is contained in a QWindow which is hosted with
+    createWindowContainer() or the obsoleted QGLWidget is used and it does cover the
+    entire full screen window, then this problem does not occur.
+
+    To solve this problem, there is a QWindowsWindowFunction which can be used to enable
+    a native Windows flag which will set WS_BORDER when showing in fullscreen mode. This
+    can be utilized like:
+
+    \code
+    QWindowsWindowFunctions::setHasBorderInFullScreen(tlwWindow->windowHandle(), true);
+    \endcode
+
+    This will make the fullscreen window have a 1 pixel border thus enabling the other top
+    level windows to appear on top.
 */
 
 /*!