Doc: Revise Qt GUI module landing page

Move some of the sections into an overview page and reorganize the
contents structure. In addition, provide links to the different sections
that are covered in the overview.

Task-number: QTBUG-100369
Pick-to: 6.3
Change-Id: I46eb3df4a09e57f5778002ce694decf134b65e83
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>

2 files changed, 176 insertions, 125 deletions

diff --git a/src/gui/doc/src/qtgui-overview.qdoc b/src/gui/doc/src/qtgui-overview.qdoc
new file mode 100644
index 0000000000..d9888ce62d
--- /dev/null
+++ b/src/gui/doc/src/qtgui-overview.qdoc
@@ -0,0 +1,150 @@
+/****************************************************************************
+**
+** Copyright (C) 2022 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \page qtgui-overview.html
+    \title Qt GUI Overview
+    \brief An overview of the Qt GUI module.
+
+    The Qt GUI module provides classes for windowing system integration, event
+    handling, OpenGL and OpenGL ES integration, 2D graphics, basic imaging,
+    fonts, and text. These classes are used internally by Qt's user interface
+    technologies but can also be used directly, for example to write
+    applications using low-level OpenGL ES graphics APIs.
+
+    For application developers writing user interfaces, Qt provides higher level
+    APIs, like Qt Quick, that are much more suitable than the enablers found in
+    the Qt GUI module.
+
+    \section1 Application Windows
+
+    The most important classes in the Qt GUI module are QGuiApplication and
+    QWindow. A Qt application that wants to show content on screen has to use
+    these. QGuiApplication contains the main event loop, where all events from
+    the window system and other sources are processed and dispatched. It also
+    handles the application's initialization and finalization.
+
+    The \l QWindow class represents a window in the underlying windowing system.
+    It provides a number of virtual functions to handle events (\l {QEvent})
+    from the windowing system, such as touch-input, exposure, focus, key
+    strokes, and geometry changes.
+
+    \section1 2D Graphics
+
+    The Qt GUI module contains classes for 2D graphics, imaging, fonts,
+    and advanced typography.
+
+    A \l QWindow created with the surface type \l {QSurface::RasterSurface} can
+    be used in combination with \l {QBackingStore} and \l {QPainter}, Qt's
+    highly optimized 2D vector graphics API. QPainter supports drawing lines,
+    polygons, vector paths, images, and text. For more information, see \l{Paint
+    System} and \l {Raster Window Example}.
+
+    Qt can load and save images using the \l QImage and \l QPixmap classes. By
+    default, Qt supports the most common image formats including JPEG and PNG
+    among others. Users can add support for additional formats via the \l
+    QImageIOPlugin class. For more information, see \l {Reading and Writing
+    Image Files}.
+
+    Typography in Qt is done with \l QTextDocument, which uses the \l QPainter
+    API in combination with Qt's font classes, primarily QFont. Applications
+    that prefer more low-level APIs to text and font handling can use classes
+    like QRawFont and QGlyphRun.
+
+    \section1 OpenGL and OpenGL ES Integration
+
+    QWindow supports rendering using OpenGL and OpenGL ES, depending on what the
+    platform supports. OpenGL rendering is enabled by setting the QWindow's
+    surface type to QSurface::OpenGLSurface, choosing the format attributes with
+    QSurfaceFormat, and then creating a QOpenGLContext to manage the native
+    OpenGL context. In addition, Qt has QOpenGLPaintDevice, which enables the
+    use of OpenGL accelerated QPainter rendering, as well as convenience classes
+    that simplify the writing of OpenGL code and hides the complexities of
+    extension handling and the differences between OpenGL ES 2 and desktop
+    OpenGL. The convenience classes include QOpenGLFunctions that lets an
+    application use all the OpenGL ES 2 functions on desktop OpenGL without
+    having to manually resolve the OpenGL function pointers. This enables
+    cross-platform development of applications targeting mobile or embedded
+    devices, and provides classes that wrap native OpenGL functionality in a
+    simpler Qt API:
+
+    \list
+        \li QOpenGLBuffer
+        \li QOpenGLFramebufferObject
+        \li QOpenGLShaderProgram
+        \li QOpenGLTexture
+        \li QOpenGLDebugLogger
+        \li QOpenGLTimerQuery
+        \li QOpenGLVertexArrayObject
+    \endlist
+
+    Finally, to provide better support for the newer versions (3.0 and
+    higher) of OpenGL, a versioned function wrapper mechanism is also available:
+    The QOpenGLFunction_N_N family of classes expose all the functions in a
+    given OpenGL version and profile, allowing easy development of desktop
+    applications that rely on modern, desktop-only OpenGL features.
+
+    For more information, see the \l {OpenGL Window Example}.
+
+    The Qt GUI module also contains a few math classes to aid with the most
+    common mathematical operations related to 3D graphics. These classes include
+    \l {QMatrix4x4}, \l {QVector4D}, and \l {QQuaternion}.
+
+    A \l {QWindow} created with the \l {QSurface::OpenGLSurface} can be used in
+    combination with \l QPainter and \l QOpenGLPaintDevice to have OpenGL
+    hardware-accelerated 2D graphics by sacrificing some of the visual quality.
+
+    \section1 Vulkan Integration
+
+    Qt GUI has support for the \l {Vulkan} API. Qt applications require the
+    presence of the \l{LunarG Vulkan SDK}.
+
+    On Windows, the SDK sets the environment variable \c {VULKAN_SDK},
+    which will be detected by the \c {configure} script.
+
+    On Android, Vulkan headers were added in API level 24 of the NDK.
+
+    Relevant classes:
+
+    \list
+        \li QVulkanDeviceFunctions
+        \li QVulkanExtension
+        \li QVulkanFunctions
+        \li QVulkanInfoVector
+        \li QVulkanInstance
+        \li QVulkanWindow
+        \li QVulkanWindowRenderer
+    \endlist
+
+    For more information, see the \l{Hello Vulkan Widget Example}
+    and the \l {Hello Vulkan Window Example}.
+
+    \section1 Drag and Drop
+
+    Qt GUI includes support for drag and drop. The \l{Drag and Drop} overview
+    has more information.
+*/
diff --git a/src/gui/doc/src/qtgui.qdoc b/src/gui/doc/src/qtgui.qdoc
index d7d91eeb19..75fde3db27 100644
--- a/src/gui/doc/src/qtgui.qdoc
+++ b/src/gui/doc/src/qtgui.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2016 The Qt Company Ltd.
+** Copyright (C) 2022 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -45,8 +45,8 @@
     The Qt GUI module provides classes for windowing system
     integration, event handling, OpenGL and OpenGL ES integration, 2D
     graphics, basic imaging, fonts, and text. These classes are used
-    internally by Qt's user interface technologies and can also be
-    used directly, for instance to write applications using low-level
+    internally by Qt's user interface technologies but can also be
+    used directly, for example to write applications using low-level
     OpenGL ES graphics APIs.
 
     For application developers writing user interfaces, Qt provides
@@ -55,10 +55,13 @@
 
     \if !defined(qtforpython)
 
-    \include module-use.qdocinc using qt module
-    \quotefile overview/using-qt-gui.cmake
+    \section1 Using the Module
 
-    See also the \l {Build with CMake} overview.
+    \include {module-use.qdocinc} {using the c++ api}
+
+    \section2 Building with CMake
+
+    \include {module-use.qdocinc} {building with cmake} {Gui}
 
     \section2 Building with qmake
 
@@ -68,124 +71,32 @@
     \snippet code/doc_src_qtgui.pro 1
     \endif
 
-    \section1 Application Windows
-
-    The most important classes in the Qt GUI module are
-    QGuiApplication and QWindow. A Qt application that wants to show
-    content on screen will need to make use of these. QGuiApplication
-    contains the main event loop, where all events from the window
-    system and other sources are processed and dispatched. It also
-    handles the application's initialization and finalization.
-
-    The \l QWindow class represents a window in the underlying
-    windowing system. It provides a number of virtual functions to
-    handle events (\l {QEvent}) from the windowing system, such as
-    touch-input, exposure, focus, key strokes, and geometry changes.
-
-
-
-    \section1 2D Graphics
-
-    The Qt GUI module contains classes for 2D graphics, imaging, fonts,
-    and advanced typography.
-
-    A \l QWindow created with the surface type \l
-    {QSurface::RasterSurface} can be used in combination with \l
-    {QBackingStore} and \l {QPainter}, Qt's highly optimized 2D vector
-    graphics API. QPainter supports drawing lines, polygons, vector
-    paths, images, and text. For more information, see \l{Paint
-    System} and \l {Raster Window Example}.
-
-    Qt can load and save images using the \l QImage and \l QPixmap
-    classes. By default, Qt supports the most common image formats
-    including JPEG and PNG among others. Users can add support for
-    additional formats via the \l QImageIOPlugin class. For more
-    information, see \l {Reading and Writing Image Files}.
-
-    Typography in Qt is done with \l QTextDocument, which uses the \l
-    QPainter API in combination with Qt's font classes, primarily
-    QFont. Applications that prefer more low-level APIs to text
-    and font handling can use classes like QRawFont and QGlyphRun.
-
-    \section1 OpenGL and OpenGL ES Integration
-
-    QWindow supports rendering using OpenGL and OpenGL ES, depending
-    on what the platform supports. OpenGL rendering is enabled by
-    setting the QWindow's surface type to QSurface::OpenGLSurface,
-    choosing the format attributes with QSurfaceFormat, and then
-    creating a QOpenGLContext to manage the native OpenGL context. In
-    addition, Qt has QOpenGLPaintDevice, which enables the use of
-    OpenGL accelerated QPainter rendering, as well as convenience
-    classes that simplify the writing of OpenGL code and hides the
-    complexities of extension handling and the differences between
-    OpenGL ES 2 and desktop OpenGL. The convenience classes include
-    QOpenGLFunctions that lets an application use all the OpenGL ES 2
-    functions on desktop OpenGL without having to manually resolve the
-    OpenGL function pointers. This enables cross-platform development
-    of applications targeting mobile or embedded devices, and provides
-    classes that wrap native OpenGL functionality in a simpler Qt API:
+    \section1 Articles and Guides
 
     \list
-    \li QOpenGLBuffer
-    \li QOpenGLFramebufferObject
-    \li QOpenGLShaderProgram
-    \li QOpenGLTexture
-    \li QOpenGLDebugLogger
-    \li QOpenGLTimerQuery
-    \li QOpenGLVertexArrayObject
+        \li \l {Qt GUI Overview}
+        \list
+            \li \l {Application Windows} {Qt GUI Application Windows}
+            \li \l {2D Graphics} {Qt GUI 2D Graphics}
+            \li \l {OpenGL and OpenGL ES Integration}
+                   {Qt GUI OpenGL and OpenGL ES Integration}
+            \li \l {Vulkan Integration} {Qt GUI Vulkan Integration}
+        \endlist
     \endlist
 
-    Finally, in order to provide better support for the newer versions
-    (3.0 and higher) of OpenGL, a versioned function wrapper mechanism
-    is also available: The QOpenGLFunction_N_N family of classes
-    expose all the functions in a given OpenGL version and profile,
-    allowing easy development of desktop applications that rely on
-    modern, desktop-only OpenGL features.
-
-    For more information, see the \l {OpenGL Window Example}.
-
-    The Qt GUI module also contains a few math classes to aid with the
-    most common mathematical operations related to 3D graphics. These
-    classes include \l {QMatrix4x4}, \l {QVector4D}, and \l {QQuaternion}.
-
-    A \l {QWindow} created with the \l {QSurface::OpenGLSurface} can
-    be used in combination with \l QPainter and \l QOpenGLPaintDevice
-    to have OpenGL hardware-accelerated 2D graphics by sacrificing
-    some of the visual quality.
-
-
-
-    \section1 Vulkan Integration
-
-    Qt GUI has support for the \l {Vulkan} API. Qt applications require the
-    presence of the \l{LunarG Vulkan SDK}.
-
-    On Windows, the SDK sets the environment variable \c {VULKAN_SDK},
-    which will be detected by the \c {configure} script.
-
-    On Android, Vulkan headers were added in API level 24 of the NDK.
-
-    Relevant classes:
+    \section1 Reference
 
     \list
-    \li QVulkanDeviceFunctions
-    \li QVulkanExtension
-    \li QVulkanFunctions
-    \li QVulkanInfoVector
-    \li QVulkanInstance
-    \li QVulkanWindow
-    \li QVulkanWindowRenderer
+        \li \l{Qt GUI C++ Classes}
+            \list
+                \li \l{Event Classes}
+                \li \l{Painting Classes}
+                \li \l{Rendering in 3D}
+            \endlist
     \endlist
 
-    For more information, see the \l{Hello Vulkan Widget Example}
-    and the \l {Hello Vulkan Window Example}.
-
-    \section1 Drag and Drop
-
-    Qt GUI includes support for drag and drop. The \l{Drag and Drop} overview
-    has more information.
-
     \section1 Module Evolution
+
     \l{Changes to Qt GUI} lists important changes in the module API
     and functionality that were done for the Qt 6 series of Qt.
 
@@ -201,14 +112,4 @@
     modules under following permissive licenses:
 
     \generatelist{groupsbymodule attributions-qtgui}
-
-    \section1 Reference
-    \list
-    \li \l{Qt GUI C++ Classes}
-        \list
-        \li \l{Event Classes}
-        \li \l{Painting Classes}
-        \li \l{Rendering in 3D}
-        \endlist
-    \endlist
  */