Document native interfaces

As the private headers are not included by default in the precompiled
header QDoc builds for QtGui, create a custom module header for
the documentation build and pull in the required headers.

Add dummy declarations for Windows-specific types for building docs
on non-Windows platforms.

Task-number: QTBUG-83252
Change-Id: I225ed08f68cf4f7c1f1d093424070b13ce36aa51
Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>
Reviewed-by: Tor Arne Vestbø <tor.arne.vestbo@qt.io>

5 files changed, 494 insertions, 0 deletions

diff --git a/src/gui/doc/includes/QtGuiDoc b/src/gui/doc/includes/QtGuiDoc
new file mode 100644
index 0000000000..77b598f006
--- /dev/null
+++ b/src/gui/doc/includes/QtGuiDoc
@@ -0,0 +1,9 @@
+#include <QtGui/QtGui>
+
+// native platform interfaces
+#include <QtGui/qpa/qplatformmenu_p.h>
+#include <QtGui/qpa/qplatformwindow_p.h>
+#include <QtGui/qpa/qplatformscreen_p.h>
+#include <QtGui/private/qguiapplication_p.h>
+#include <QtGui/private/qkeymapper_p.h>
+#include <QtGui/private/qwindowsmime_p.h>
diff --git a/src/gui/doc/includes/windows.h b/src/gui/doc/includes/windows.h
new file mode 100644
index 0000000000..aa42233e75
--- /dev/null
+++ b/src/gui/doc/includes/windows.h
@@ -0,0 +1,58 @@
+/****************************************************************************
+**
+** Copyright (C) 2020 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the QtGui module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** 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 Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 3 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL3 included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 3 requirements
+** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 2.0 or (at your option) the GNU General
+** Public license version 3 or any later version approved by the KDE Free
+** Qt Foundation. The licenses are as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
+** included in the packaging of this file. Please review the following
+** information to ensure the GNU General Public License requirements will
+** be met: https://www.gnu.org/licenses/gpl-2.0.html and
+** https://www.gnu.org/licenses/gpl-3.0.html.
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#pragma once
+
+//
+//  W A R N I N G
+//  -------------
+//
+// This file is not part of the Qt API. It exists purely as an
+// implementation detail. This header file may change from version to
+// version without notice, or even be removed.
+//
+// We mean it.
+//
+
+// Dummy declarations for generating docs on non-Windows platforms
+#if !defined(Q_OS_WIN) && defined(Q_CLANG_QDOC)
+typedef struct _FORMATETC {} FORMATETC;
+typedef struct _STGMEDIUM {} STGMEDIUM;
+typedef void *IDataObject;
+#endif
diff --git a/src/gui/doc/qtgui.qdocconf b/src/gui/doc/qtgui.qdocconf
index fa069f527c..478932ae04 100644
--- a/src/gui/doc/qtgui.qdocconf
+++ b/src/gui/doc/qtgui.qdocconf
@@ -8,6 +8,9 @@ project                 = QtGui
 description             = Qt GUI Reference Documentation
 version                 = $QT_VERSION
 
+includepaths           += ./includes
+moduleheader            = QtGuiDoc
+
 examplesinstallpath     = gui
 
 qhp.projects            = QtGui
diff --git a/src/gui/doc/src/nativeinterfaces.qdoc b/src/gui/doc/src/nativeinterfaces.qdoc
new file mode 100644
index 0000000000..9c0ab78ef4
--- /dev/null
+++ b/src/gui/doc/src/nativeinterfaces.qdoc
@@ -0,0 +1,422 @@
+/****************************************************************************
+**
+** 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$
+**
+****************************************************************************/
+
+
+/*!
+    \group native_interfaces
+    \title Native Interfaces
+
+    Native interfaces provide access to native APIs of the classes they extend.
+*/
+
+/*!
+    \namespace QPlatformInterface::Private
+    \inmodule QtGui
+    \since 6.0
+    \brief Contains the classes providing native interfaces.
+    \ingroup native_interfaces
+*/
+
+/*!
+    \class QPlatformInterface::QCocoaGLContext
+    \since 6.0
+    \brief Native interface to QPlatformOpenGLContext.
+    \inmodule QtGui
+    \ingroup native_interfaces
+*/
+
+/*!
+    \class QPlatformInterface::Private::QCocoaMenu
+    \since 6.0
+    \brief Native interface to QPlatformMenu.
+    \inmodule QtGui
+    \ingroup native_interfaces
+*/
+
+/*!
+    \class QPlatformInterface::Private::QCocoaWindow
+    \since 6.0
+    \brief Native interface to QPlatformWindow.
+    \inmodule QtGui
+    \ingroup native_interfaces
+*/
+
+/*!
+    \class QPlatformInterface::QEGLContext
+    \since 6.0
+    \brief Native interface to QPlatformOpenGLContext.
+    \inmodule QtGui
+    \ingroup native_interfaces
+*/
+
+/*!
+    \class QPlatformInterface::Private::QEvdevKeyMapper
+    \since 6.0
+    \brief Native interface to QKeyMapper.
+    \inmodule QtGui
+    \ingroup native_interfaces
+*/
+
+/*!
+    \class QPlatformInterface::QGLXContext
+    \since 6.0
+    \brief Native interface to QPlatformOpenGLContext.
+    \inmodule QtGui
+    \ingroup native_interfaces
+*/
+
+/*!
+    \class QPlatformInterface::QWGLContext
+    \since 6.0
+    \brief Native interface to QPlatformOpenGLContext.
+    \inmodule QtGui
+    \ingroup native_interfaces
+*/
+
+/*!
+    \class QPlatformInterface::Private::QWindowsApplication
+    \since 6.0
+    \brief Native interface to QGuiApplication, to be retrieved from QPlatformIntegration.
+    \inmodule QtGui
+    \ingroup native_interfaces
+*/
+
+/*!
+    \enum QPlatformInterface::Private::QWindowsApplication::TouchWindowTouchType
+
+    This enum represents the supported TouchWindow touch flags for registerTouchWindow().
+
+    \value NormalTouch
+    \value FineTouch
+    \value WantPalmTouch
+*/
+
+/*!
+    \fn void QPlatformInterface::Private::QWindowsApplication::setTouchWindowTouchType(QPlatformInterface::Private::QWindowsApplication::TouchWindowTouchTypes type)
+
+    Sets the touch window type for all windows to \a type.
+*/
+
+/*!
+    \fn QPlatformInterface::Private::QWindowsApplication::TouchWindowTouchTypes QPlatformInterface::Private::QWindowsApplication::touchWindowTouchType() const
+
+    Returns the currently set the touch window type.
+*/
+
+/*!
+    \enum QPlatformInterface::Private::QWindowsApplication::WindowActivationBehavior
+
+    This enum specifies the behavior of QWidget::activateWindow() and
+    QWindow::requestActivate().
+
+    \value DefaultActivateWindow The window is activated according to the default
+        behavior of the Windows operating system. This means the window will not
+        be activated in some circumstances (most notably when the calling process
+        is not the active process); only the taskbar entry will be flashed.
+    \value AlwaysActivateWindow  The window is always activated, even when the
+        calling process is not the active process.
+
+    \sa QWidget::activateWindow(), QWindow::requestActivate()
+*/
+
+/*!
+    \fn void QPlatformInterface::Private::QWindowsApplication::setWindowActivationBehavior(QPlatformInterface::Private::QWindowsApplication::WindowActivationBehavior behavior)
+
+    Sets the window activation behavior to \a behavior.
+
+    \sa QWidget::activateWindow(), QWindow::requestActivate()
+*/
+
+/*!
+    \fn QPlatformInterface::Private::QWindowsApplication::WindowActivationBehavior QPlatformInterface::Private::QWindowsApplication::windowActivationBehavior() const
+
+    Returns the currently set the window activation behavior.
+*/
+
+/*!
+    \fn bool QPlatformInterface::Private::QWindowsApplication::isTabletMode() const
+
+    Returns \c true if Windows 10 operates in \e{Tablet Mode}.
+    In this mode, Windows forces all application main windows to open in maximized
+    state. Applications should then avoid resizing windows or restoring geometries
+    to non-maximized states.
+
+    \sa QWidget::showMaximized(), QWidget::saveGeometry(), QWidget::restoreGeometry()
+*/
+
+/*!
+    \enum QPlatformInterface::Private::QWindowsApplication::DarkModeHandlingFlag
+
+    This enum specifies the behavior of the application when Windows
+    is configured to use dark mode for applications.
+
+    \value DarkModeWindowFrames The window frames will be switched to dark.
+    \value DarkModeStyle        The Windows Vista style will be turned off and
+                                a simple dark style will be used.
+
+    \sa isDarkMode(), setDarkModeHandling()
+*/
+
+/*!
+    \fn bool QPlatformInterface::Private::QWindowsApplication::isDarkMode() const
+
+    Returns \c true if Windows 10 is configured to use dark mode for
+    applications.
+*/
+
+/*!
+    \fn void QPlatformInterface::Private::QWindowsApplication::setDarkModeHandling(DarkModeHandling handling)
+
+    Sets the dark mode handling to \a handling.
+*/
+
+/*!
+    \fn QPlatformInterface::Private::QWindowsApplication::DarkModeHandling QPlatformInterface::Private::QWindowsApplication::darkModeHandling() const
+
+    Returns the currently set dark mode handling.
+*/
+
+/*!
+    \fn bool QPlatformInterface::Private::QWindowsApplication::isWinTabEnabled() const
+
+    Returns whether the \e{Tablet WinTab Driver} (\c Wintab32.dll) is used.
+*/
+
+/*!
+    \fn bool QPlatformInterface::Private::QWindowsApplication::setWinTabEnabled(bool enabled)
+
+    Sets whether the \e{Tablet WinTab Driver} (\c Wintab32.dll) should be used to \a enabled.
+
+    Returns \c true on success, \c false otherwise.
+*/
+
+/*!
+    \fn bool QPlatformInterface::Private::QWindowsApplication::registerMime(QWindowsMime *mime)
+
+    Registers the converter \a mime to the system.
+
+    \sa QPlatformInterface::Private::QWindowsMime, unregisterMime()
+*/
+
+/*!
+    \fn void QPlatformInterface::Private::QWindowsApplication::unregisterMime(QWindowsMime *mime)
+
+    Unregisters the converter \a mime from the system.
+
+    \sa QPlatformInterface::Private::QWindowsMime, registerMime()
+*/
+
+/*!
+    \fn int QPlatformInterface::Private::QWindowsApplication::registerMimeType(const QString &mime)
+
+    Registers the MIME type \a mime, and returns an ID number
+    identifying the format on Windows.
+*/
+
+/*!
+    \fn HWND QPlatformInterface::Private::QWindowsApplication::createMessageWindow(const QString &, const QString &, QFunctionPointer) const
+    \internal
+*/
+
+/*!
+    \fn bool QPlatformInterface::Private::QWindowsApplication::asyncExpose() const
+    \internal
+*/
+
+/*!
+    \fn void QPlatformInterface::Private::QWindowsApplication::setAsyncExpose(bool)
+    \internal
+*/
+
+/*!
+    \fn QVariant QPlatformInterface::Private::QWindowsApplication::gpu()
+    \internal
+*/
+
+/*!
+    \fn QVariant QPlatformInterface::Private::QWindowsApplication::gpuList()
+    \internal
+*/
+
+/*!
+    \class QPlatformInterface::Private::QWindowsMime
+    \since 6.0
+    \brief The QWindowsMime class maps open-standard MIME to Window Clipboard formats.
+    \inmodule QtGui
+    \ingroup native_interfaces
+
+    Qt's drag-and-drop and clipboard facilities use the MIME standard.
+    On X11, this maps trivially to the Xdnd protocol, but on Windows
+    although some applications use MIME types to describe clipboard
+    formats, others use arbitrary non-standardized naming conventions,
+    or unnamed built-in formats of Windows.
+
+    By instantiating subclasses of QWinMime that provide conversions
+    between Windows Clipboard and MIME formats, you can convert
+    proprietary clipboard formats to MIME formats.
+
+    Qt has predefined support for the following Windows Clipboard formats:
+
+    \table
+    \header \li Windows Format \li Equivalent MIME type
+    \row \li \c CF_UNICODETEXT \li \c text/plain
+    \row \li \c CF_TEXT        \li \c text/plain
+    \row \li \c CF_DIB         \li \c{image/xyz}, where \c xyz is
+                                 a \l{QImageWriter::supportedImageFormats()}{Qt image format}
+    \row \li \c CF_HDROP       \li \c text/uri-list
+    \row \li \c CF_INETURL     \li \c text/uri-list
+    \row \li \c CF_HTML        \li \c text/html
+    \endtable
+
+    An example use of this class would be to map the Windows Metafile
+    clipboard format (\c CF_METAFILEPICT) to and from the MIME type
+    \c{image/x-wmf}. This conversion might simply be adding or removing
+    a header, or even just passing on the data. See \l{Drag and Drop}
+    for more information on choosing and definition MIME types.
+
+    You can check if a MIME type is convertible using canConvertFromMime() and
+    can perform conversions with convertToMime() and convertFromMime().
+
+    \since 6.0
+*/
+
+/*!
+    \fn QPlatformInterface::Private::QWindowsMime::~QWindowsMime()
+
+    Destroys the conversion object.
+*/
+
+/*!
+    \fn bool QPlatformInterface::Private::QWindowsMime::canConvertFromMime(const FORMATETC &formatetc, const QMimeData *mimeData) const
+
+    Returns \c true if the converter can convert from the \a mimeData to
+    the format specified in \a formatetc.
+
+    All subclasses must reimplement this pure virtual function.
+*/
+
+/*!
+    \fn bool QPlatformInterface::Private::QWindowsMime::canConvertToMime(const QString &mimeType, IDataObject *pDataObj) const
+
+    Returns \c true if the converter can convert to the \a mimeType from
+    the available formats in \a pDataObj.
+
+    All subclasses must reimplement this pure virtual function.
+*/
+
+/*!
+    \fn QString QPlatformInterface::Private::QWindowsMime::mimeForFormat(const FORMATETC &formatetc) const
+
+    Returns the mime type that will be created form the format specified
+    in \a formatetc, or an empty string if this converter does not support
+    \a formatetc.
+
+    All subclasses must reimplement this pure virtual function.
+*/
+
+/*!
+    \fn QList<FORMATETC> QPlatformInterface::Private::QWindowsMime::formatsForMime(const QString &mimeType, const QMimeData *mimeData) const
+
+    Returns a QList of FORMATETC structures representing the different windows clipboard
+    formats that can be provided for the \a mimeType from the \a mimeData.
+
+    All subclasses must reimplement this pure virtual function.
+*/
+
+/*!
+    \fn QVariant QPlatformInterface::Private::QWindowsMime::convertToMime(const QString &mimeType, IDataObject *pDataObj,
+                                             QVariant::Type preferredType) const
+
+    Returns a QVariant containing the converted data for \a mimeType from \a pDataObj.
+    If possible the QVariant should be of the \a preferredType to avoid needless conversions.
+
+    All subclasses must reimplement this pure virtual function.
+*/
+
+/*!
+    \fn bool QPlatformInterface::Private::QWindowsMime::convertFromMime(const FORMATETC &formatetc, const QMimeData *mimeData, STGMEDIUM * pmedium) const
+
+    Convert the \a mimeData to the format specified in \a formatetc.
+    The converted data should then be placed in \a pmedium structure.
+
+    Return true if the conversion was successful.
+
+    All subclasses must reimplement this pure virtual function.
+*/
+
+/*!
+    \class QPlatformInterface::Private::QWindowsWindow
+    \since 6.0
+    \brief Native interface to QPlatformWindow.
+    \inmodule QtGui
+    \ingroup native_interfaces
+*/
+
+/*!
+    \fn void QPlatformInterface::Private::QWindowsWindow::setHasBorderInFullScreen(bool border)
+
+    Sets whether the WS_BORDER flag will be set for the window in full screen mode
+    to \a border.
+
+    See also \l [QtDoc] {Fullscreen OpenGL Based Windows}
+*/
+
+/*!
+    \fn bool QPlatformInterface::Private::QWindowsWindow::hasBorderInFullScreen() const
+
+    Returns whether the WS_BORDER flag will be set for the window in full screen
+    mode.
+*/
+
+/*!
+    \fn QMargins QPlatformInterface::Private::QWindowsWindow::customMargins() const
+
+    Returns the margin to be used when handling the \c WM_NCCALCSIZE message.
+*/
+
+/*!
+    \fn void QPlatformInterface::Private::QWindowsWindow::setCustomMargins(const QMargins &margins)
+
+    Sets the\a  margins to be used when handling the \c WM_NCCALCSIZE message. It is
+    possible to remove a frame border by specifying a negative value.
+*/
+
+/*!
+    \class QPlatformInterface::Private::QXcbScreen
+    \since 6.0
+    \brief Native interface to QPlatformScreen.
+    \inmodule QtGui
+    \ingroup native_interfaces
+*/
+
+/*!
+    \class QPlatformInterface::Private::QXcbWindow
+    \since 6.0
+    \brief Native interface to QPlatformWindow.
+    \inmodule QtGui
+    \ingroup native_interfaces
+*/
diff --git a/src/gui/doc/src/qtgui.qdoc b/src/gui/doc/src/qtgui.qdoc
index 4610b12e98..e3d636ef92 100644
--- a/src/gui/doc/src/qtgui.qdoc
+++ b/src/gui/doc/src/qtgui.qdoc
@@ -113,7 +113,9 @@
     and font handling, classes like QRawFont and QGlyphRun can be
     used.
 
+    \section1 Native Interfaces
 
+    See \l{Native Interfaces}.
 
     \section1 OpenGL and OpenGL ES Integration