First steps towards documenting our platform APIs

Adds a new top level topic for platform integration, moving
the QPA docs under that, and cleans up and rewrites the QPA docs
for Qt 6.

Task-number: QTBUG-80233
Change-Id: I658e5e2c402a25ce391102675cee6ada0563e71f
Reviewed-by: Friedemann Kleint <Friedemann.Kleint@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

4 files changed, 286 insertions, 0 deletions

diff --git a/doc/src/platformintegration/platformintegration.pro b/doc/src/platformintegration/platformintegration.pro
new file mode 100644
index 000000000..470e66591
--- /dev/null
+++ b/doc/src/platformintegration/platformintegration.pro
@@ -0,0 +1,9 @@
+TEMPLATE = aux
+
+QMAKE_DOCS = $$PWD/platformintegration.qdocconf
+
+QTDIR = $$[QT_HOST_PREFIX]
+exists($$QTDIR/.qmake.cache): \
+    QMAKE_DOCS_OUTPUTDIR = $$QTDIR/doc/cmake
+else: \
+    QMAKE_DOCS_OUTPUTDIR = $$OUT_PWD/cmake
diff --git a/doc/src/platformintegration/platformintegration.qdoc b/doc/src/platformintegration/platformintegration.qdoc
new file mode 100644
index 000000000..0957fe8de
--- /dev/null
+++ b/doc/src/platformintegration/platformintegration.qdoc
@@ -0,0 +1,63 @@
+/****************************************************************************
+**
+** Copyright (C) 2020 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 platform-integration.html
+    \title Platform Integration
+    \brief Integrating Qt with the native platform.
+
+    Qt's main strength as a cross-platform toolkit for application development
+    is removing the need for duplicating the application code for each target
+    platform.
+
+    While Qt solves many of the typical tasks of writing an application,
+    there are always corner cases that Qt can not cover, or where it makes more
+    sense to build a feature on top of the platform specific APIs, or another
+    toolkit.
+
+    To support these use-cases, while still allowing Qt to handle the bulk of
+    the application logic, Qt provides a wide range of platform integration
+    APIs, from simple type conversions to platform specific native interfaces.
+
+    \section1 Type Conversions
+
+    \section1 Window Embedding
+
+    \section1 Native Interfaces
+
+    \section1 Platform Support
+
+    In addition to the application developer APIs, Qt also interfaces with the
+    platform when providing the underlying implementations of the cross-platform
+    building blocks in Qt.
+
+    Examples are the event dispatcher abstractions in \l{Qt Core}, the rendering
+    hardware abstractions in RHI, and the multimedia backends in \l{Qt Multimedia}.
+
+    The main abstraction layer here is the \l{Qt Platform Abstraction},
+    or QPA for short, which deals with window system integration and related use-cases.
+*/
diff --git a/doc/src/platformintegration/platformintegration.qdocconf b/doc/src/platformintegration/platformintegration.qdocconf
new file mode 100644
index 000000000..b02294589
--- /dev/null
+++ b/doc/src/platformintegration/platformintegration.qdocconf
@@ -0,0 +1,21 @@
+include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf)
+include($QT_INSTALL_DOCS/global/externalsites.qdocconf)
+
+project = QtPlatformIntegration
+navigation.landingpage = "Platform Integration"
+description = "Integrating Qt with the native platform"
+version = $QT_VERSION
+
+depends += qtcore qtgui qtdoc
+sourcedirs = .
+headerdirs = .
+
+moduleheader =
+
+qhp.projects = QtPlatformIntegration
+
+qhp.QtPlatformIntegration.file                = qtplatformintegration.qhp
+qhp.QtPlatformIntegration.namespace           = org.qt-project.qtplatformintegration.$QT_VERSION_TAG
+qhp.QtPlatformIntegration.virtualFolder       = qtplatformintegration
+qhp.QtPlatformIntegration.indexTitle          = "Platform Integration"
+qhp.QtPlatformIntegration.filterAttributes    = qt $QT_VERSION
diff --git a/doc/src/platformintegration/qpa.qdoc b/doc/src/platformintegration/qpa.qdoc
new file mode 100644
index 000000000..b980b63be
--- /dev/null
+++ b/doc/src/platformintegration/qpa.qdoc
@@ -0,0 +1,193 @@
+/****************************************************************************
+**
+** Copyright (C) 2019 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 qpa.html
+\title Qt Platform Abstraction
+
+The Qt Platform Abstraction (QPA) is the main platform abstraction layer in Qt.
+
+The API can be identified by the \c QPlatform* class prefix, and is used
+for implementing higher level classes typically found in \l{Qt GUI}, e.g.
+\c QPlatformWindow for window system integration exposed through QWindow,
+or \c QPlatformTheme for deeper platform theming and integration, exposed
+through QStyleHint and QStyle.
+
+There are no source or binary compatibility guarantees for the QPA classes,
+meaning that the API is only guaranteed to work with the Qt version
+it was developed against. API changes will however only be made in minor
+releases. (5.1, 5.2, and so on.)
+
+\section1 API Overview
+
+\list
+\li Window system integration
+    \list
+    \li QPlatformIntegration
+    \li QPlatformAccessibility
+    \li QPlatformBackingStore
+    \li QPlatformClipboard
+    \li QPlatformCursor
+    \li QPlatformDrag
+    \li QPlatformFontDatabase
+    \li QPlatformGraphicsBuffer
+    \li QPlatformInputContext
+    \li QPlatformOffscreenSurface
+    \li QPlatformOpenGLContext
+    \li QPlatformScreen
+    \li QPlatformServices
+    \li QPlatformSharedGraphicsCache
+    \li QPlatformSurface
+    \li QPlatformWindow
+    \endlist
+
+\li Style/theming
+    \list
+    \li QPlatformTheme
+    \li platform palettes
+    \li platform fonts
+    \li theme hints
+    \endlist
+
+\li Native dialogs and menus
+    \list
+    \li QPlatformDialogHelper
+    \li QPlatformMenu
+    \li QPlatformMenuBar
+    \li QPlatformMenuItem
+    \endlist
+\endlist
+
+\note In addition to the QPA APIs, there are many other platform abstractions
+in Qt, for example the event dispatcher abstractions in \l{Qt Core}, the
+rendering hardware abstractions in RHI, and the multimedia backends in \l{Qt Multimedia}.
+The QPA APIs are mostly focused on window system integration and related support.
+
+\section1 QPA Plugins
+
+Concrete implementations of the interfaces listed above live in QPA plugins,
+or platform plugins, adding support for the various platforms Qt runs on.
+QPA plugins are implemented by subclassing the \c QPlatform* classes.
+
+The following table summarizes the platform plugins available:
+
+\table
+\header
+    \li Plugin Name
+    \li Plugin Class Name
+    \li Description
+\row
+    \li \c qandroid
+    \li QAndroidPlatformIntegration
+    \li \l{Qt for Android}{Android support}
+\row
+    \li \c qbsdfb
+    \li QBsdFbIntegration
+    \li BsdFb support
+\row
+    \li \c qcocoa
+    \li QCocoaIntegrationPlugin
+    \li \l{Qt for macOS}{macOS support}
+\row
+    \li \c qdirect2d
+    \li QWindowsDirect2DIntegrationPlugin
+    \li Similar to the \c qwindows plugin, but replaces the raster paint engine
+        with a Direct2D-based paint engine for QPixmap and QBackingStore.
+\row
+    \li \c qdirectfb
+    \li QDirectFbIntegrationPlugin
+    \li DirectFB is centered around \e surfaces, which are the equivalent of a
+        QPaintDevice.
+\row
+    \li \c qeglfs
+    \li QEglFSIntegrationPlugin
+    \li \l{embedded eglfs}{EGLFS} support for embedded Linux devices.
+\row
+    \li \c qhaiku
+    \li QHaikuIntegration
+    \li Haiku support
+\row
+    \li \c qios
+    \li QIOSIntegrationPlugin
+    \li \l{Qt for iOS}{iOS support}
+\row
+    \li \c qlinuxfb
+    \li QLinuxFbIntegrationPlugin
+    \li \l LinuxFB support for embedded Linux devices.
+\row
+    \li \c qmirclient
+    \li QMirClientIntegration
+    \li Mir client support
+\row
+    \li \c qopenwf
+    \li QOpenWFDIntegrationPlugin
+    \li OpenWF Display support for managing display control hardware.
+\row
+    \li \c qvnc
+    \li QVncIntegration
+    \li VNC support
+\row
+    \li \c qwayland
+    \li \list
+            \li QWaylandIntegrationPlugin
+            \li QWaylandBrcmEglPlatformIntegrationPlugin
+            \li QWaylandEglPlatformIntegrationPlugin
+            \li QWaylandXCompositeEglPlatformIntegrationPlugin
+            \li QWaylandXCompositeGlxPlatformIntegrationPlugin
+        \endlist
+    \li \l{Qt Wayland Compositor}{Wayland support}
+\row
+    \li \c qwindows
+    \li QWindowsIntegrationPlugin
+    \li \l{Qt for Windows}{Windows support}
+\row
+    \li \c qxcb
+    \li QXcbIntegrationPlugin
+    \li \l{Qt for Linux/X11}{X Window System (X11) support}
+\row
+    \li \c webgl
+    \li QWebGLIntegrationPlugin
+    \li \l{Qt Quick WebGL}{WebGL} support for Qt Quick applications
+\endtable
+
+\section2 Writing a QPA plugin
+
+There is no detailed tutorial documentation for writing QPA plugins at this
+time. However, there are two minimal plugins shipped with Qt for testing and
+other special purposes that you can use as examples:
+
+\list
+\li \c{qtbase/src/plugins/platforms/minimal/}
+\li \c{qtbase/src/plugins/platforms/minimalegl/}
+\endlist
+
+The \c qminimal plugin is used for tools that link against \l{Qt GUI}, but do
+not require window system integration (for example, \c qmlplugindump).
+It also has diagnostic support for dumping window contents to image files
+as determined by environment variables.
+
+*/