doc: Update and flesh out native interface docs

The namespace and overviews are in the qtdoc repository.

Docs for individual interfaces should live with their platform.

Change-Id: Iba5fd7e9ebc4f1f634ec9dc3ec125ce88a1312ba
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

4 files changed, 418 insertions, 6 deletions

diff --git a/src/gui/platform/android/qandroidnativeinterface.cpp b/src/gui/platform/android/qandroidnativeinterface.cpp
index bdb322add0..b1063034a0 100644
--- a/src/gui/platform/android/qandroidnativeinterface.cpp
+++ b/src/gui/platform/android/qandroidnativeinterface.cpp
@@ -47,7 +47,19 @@ QT_BEGIN_NAMESPACE
 
 using namespace QNativeInterface::Private;
 
-#if defined(Q_OS_ANDROID)
+/*!
+    \class QNativeInterface::QAndroidOffscreenSurface
+    \since 6.0
+    \brief Native interface to a offscreen surface on Android.
+
+    Accessed through QOffscreenSurface::nativeInterface().
+
+    \inmodule QtGui
+    \inheaderfile QOffscreenSurface
+    \ingroup native-interfaces
+    \ingroup native-interfaces-qoffscreensurface
+*/
+
 QT_DEFINE_NATIVE_INTERFACE(QAndroidOffscreenSurface, QOffscreenSurface);
 QT_DEFINE_PRIVATE_NATIVE_INTERFACE(QAndroidOffScreenIntegration);
 
@@ -56,6 +68,5 @@ QOffscreenSurface  *QNativeInterface::QAndroidOffscreenSurface::fromNative(ANati
     return QGuiApplicationPrivate::platformIntegration()->call<
             &QAndroidOffScreenIntegration::createOffscreenSurface>(nativeSurface);
 }
-#endif
 
 QT_END_NAMESPACE
diff --git a/src/gui/platform/macos/qcocoanativeinterface.mm b/src/gui/platform/macos/qcocoanativeinterface.mm
index f9d5f5dbe5..5d199f8a0f 100644
--- a/src/gui/platform/macos/qcocoanativeinterface.mm
+++ b/src/gui/platform/macos/qcocoanativeinterface.mm
@@ -50,12 +50,66 @@ QT_BEGIN_NAMESPACE
 
 using namespace QNativeInterface::Private;
 
+/*!
+    \class QNativeInterface::Private::QCocoaWindow
+    \since 6.0
+    \internal
+    \brief Native interface for QPlatformWindow on \macos.
+    \inmodule QtGui
+    \ingroup native-interfaces
+*/
+
 QT_DEFINE_PRIVATE_NATIVE_INTERFACE(QCocoaWindow);
+
+
+/*!
+    \class QNativeInterface::Private::QCocoaMenu
+    \since 6.0
+    \internal
+    \brief Native interface for QPlatformMenu on \macos.
+    \inmodule QtGui
+    \ingroup native-interfaces
+*/
+
 QT_DEFINE_PRIVATE_NATIVE_INTERFACE(QCocoaMenu);
 QT_DEFINE_PRIVATE_NATIVE_INTERFACE(QCocoaMenuBar);
 
 #ifndef QT_NO_OPENGL
 
+/*!
+    \class QNativeInterface::QCocoaGLContext
+    \since 6.0
+    \brief Native interface to an NSOpenGLContext on \macos.
+
+    Accessed through QOpenGLContext::nativeInterface().
+
+    \inmodule QtGui
+    \inheaderfile QOpenGLContext
+    \ingroup native-interfaces
+    \ingroup native-interfaces-qopenglcontext
+*/
+
+/*!
+    \fn QOpenGLContext *QNativeInterface::QCocoaGLContext::fromNative(NSOpenGLContext *context, QOpenGLContext *shareContext = nullptr)
+
+    \brief Adopts an NSOpenGLContext.
+
+    The adopted NSOpenGLContext is retained. Ownership of the created QOpenGLContext is transferred to the caller.
+*/
+
+/*!
+    \fn NSOpenGLContext *QNativeInterface::QCocoaGLContext::nativeContext() const
+
+    \return the underlying NSOpenGLContext.
+*/
+
+struct Q_GUI_EXPORT QCocoaGLContext
+{
+    QT_DECLARE_NATIVE_INTERFACE(QCocoaGLContext)
+    static QOpenGLContext *fromNative(QT_IGNORE_DEPRECATIONS(NSOpenGLContext) *, QOpenGLContext *shareContext = nullptr);
+    virtual QT_IGNORE_DEPRECATIONS(NSOpenGLContext) *nativeContext() const = 0;
+};
+
 QT_DEFINE_NATIVE_INTERFACE(QCocoaGLContext, QOpenGLContext);
 QT_DEFINE_PRIVATE_NATIVE_INTERFACE(QCocoaGLIntegration);
 
diff --git a/src/gui/platform/unix/qunixnativeinterface.cpp b/src/gui/platform/unix/qunixnativeinterface.cpp
index 378282936e..43184daa12 100644
--- a/src/gui/platform/unix/qunixnativeinterface.cpp
+++ b/src/gui/platform/unix/qunixnativeinterface.cpp
@@ -56,6 +56,46 @@ using namespace QNativeInterface::Private;
 #ifndef QT_NO_OPENGL
 
 #if defined(Q_OS_LINUX)
+
+/*!
+    \class QNativeInterface::QGLXContext
+    \since 6.0
+    \brief Native interface to a GLX context.
+
+    Accessed through QOpenGLContext::nativeInterface().
+
+    \inmodule QtGui
+    \ingroup native-interfaces
+    \ingroup native-interfaces-qopenglcontext
+*/
+
+/*!
+    \fn QOpenGLContext *QNativeInterface::QGLXContext::fromNative(GLXContext configBasedContext, QOpenGLContext *shareContext = nullptr)
+
+    \brief Adopts a GLXContext created from an FBConfig.
+
+    The context must be created from a framebuffer configuration, using the \c glXCreateNewContext function.
+
+    Ownership of the created QOpenGLContext is transferred to the caller.
+*/
+
+/*!
+    \fn QOpenGLContext *QNativeInterface::QGLXContext::fromNative(GLXContext visualBasedContext, void *visualInfo, QOpenGLContext *shareContext = nullptr)
+
+    \brief Adopts a GLXContext created from an X visual.
+
+    The context must be created from a visual, using the \c glXCreateContext function.
+    The same visual must be passed as a pointer to an \c XVisualInfo struct, in the \a visualInfo argument.
+
+    Ownership of the created QOpenGLContext is transferred to the caller.
+*/
+
+/*!
+    \fn GLXContext QNativeInterface::QGLXContext::nativeContext() const
+
+    \return the underlying GLXContext.
+*/
+
 QT_DEFINE_NATIVE_INTERFACE(QGLXContext, QOpenGLContext);
 QT_DEFINE_PRIVATE_NATIVE_INTERFACE(QGLXIntegration);
 
@@ -70,9 +110,38 @@ QOpenGLContext *QNativeInterface::QGLXContext::fromNative(GLXContext visualBased
     return QGuiApplicationPrivate::platformIntegration()->call<
         &QGLXIntegration::createOpenGLContext>(visualBasedContext, visualInfo, shareContext);
 }
-#endif
+#endif // defined(Q_OS_LINUX)
 
 #if QT_CONFIG(egl)
+
+/*!
+    \class QNativeInterface::QEGLContext
+    \since 6.0
+    \brief Native interface to an EGL context.
+
+    Accessed through QOpenGLContext::nativeInterface().
+
+    \inmodule QtGui
+    \ingroup native-interfaces
+    \ingroup native-interfaces-qopenglcontext
+*/
+
+/*!
+    \fn QOpenGLContext *QNativeInterface::QEGLContext::fromNative(EGLContext context, EGLDisplay display, QOpenGLContext *shareContext = nullptr)
+
+    \brief Adopts an EGLContext.
+
+    The same \c EGLDisplay passed to \c eglCreateContext must be passed as the \a display argument.
+
+    Ownership of the created QOpenGLContext is transferred to the caller.
+*/
+
+/*!
+    \fn EGLContext QNativeInterface::QEGLContext::nativeContext() const
+
+    \return the underlying EGLContext.
+*/
+
 QT_DEFINE_NATIVE_INTERFACE(QEGLContext, QOpenGLContext);
 QT_DEFINE_PRIVATE_NATIVE_INTERFACE(QEGLIntegration);
 
@@ -81,20 +150,51 @@ QOpenGLContext *QNativeInterface::QEGLContext::fromNative(EGLContext context, EG
     return QGuiApplicationPrivate::platformIntegration()->call<
         &QEGLIntegration::createOpenGLContext>(context, display, shareContext);
 }
-#endif
+#endif // QT_CONFIG(egl)
 
 #endif // QT_NO_OPENGL
 
 #if QT_CONFIG(xcb)
+
+/*!
+    \class QNativeInterface::Private::QXcbScreen
+    \since 6.0
+    \internal
+    \brief Native interface to QPlatformScreen.
+    \inmodule QtGui
+    \ingroup native-interfaces
+*/
+
 QT_DEFINE_PRIVATE_NATIVE_INTERFACE(QXcbScreen);
+
+/*!
+    \class QNativeInterface::Private::QXcbWindow
+    \since 6.0
+    \internal
+    \brief Native interface to QPlatformWindow.
+    \inmodule QtGui
+    \ingroup native-interfaces
+*/
+
 QT_DEFINE_PRIVATE_NATIVE_INTERFACE(QXcbWindow);
-#endif
+
+#endif // QT_CONFIG(xcb)
 
 #if QT_CONFIG(vsp2)
 QT_DEFINE_PRIVATE_NATIVE_INTERFACE(QVsp2Screen);
 #endif
 
 #if QT_CONFIG(evdev)
+
+/*!
+    \class QNativeInterface::Private::QEvdevKeyMapper
+    \since 6.0
+    \internal
+    \brief Native interface to QKeyMapper.
+    \inmodule QtGui
+    \ingroup native-interfaces
+*/
+
 QT_DEFINE_PRIVATE_NATIVE_INTERFACE(QEvdevKeyMapper);
 
 template <>
@@ -102,6 +202,6 @@ QEvdevKeyMapper *QKeyMapper::nativeInterface<QEvdevKeyMapper>() const
 {
     return dynamic_cast<QEvdevKeyMapper*>(QGuiApplicationPrivate::platformIntegration());
 }
-#endif
+#endif // QT_CONFIG(evdev)
 
 QT_END_NAMESPACE
diff --git a/src/gui/platform/windows/qwindowsnativeinterface.cpp b/src/gui/platform/windows/qwindowsnativeinterface.cpp
index 950c86d7fb..700a3b34bf 100644
--- a/src/gui/platform/windows/qwindowsnativeinterface.cpp
+++ b/src/gui/platform/windows/qwindowsnativeinterface.cpp
@@ -51,6 +51,48 @@ using namespace QNativeInterface::Private;
 
 #ifndef QT_NO_OPENGL
 
+/*!
+    \class QNativeInterface::QWGLContext
+    \since 6.0
+    \brief Native interface to a WGL context on Windows.
+
+    Accessed through QOpenGLContext::nativeInterface().
+
+    \inmodule QtGui
+    \ingroup native-interfaces
+    \ingroup native-interfaces-qopenglcontext
+*/
+
+/*!
+    \fn QOpenGLContext *QNativeInterface::QWGLContext::fromNative(HGLRC context, HWND window, QOpenGLContext *shareContext = nullptr)
+
+    \brief Adopts an WGL context handle.
+
+    The \a window is needed because the its pixel format will be queried. When the
+    adoption is successful, QOpenGLContext::format() will return a QSurfaceFormat
+    describing this pixel format.
+
+    \note The window specified by \a window must have its pixel format set to a
+    format compatible with the context's. If no SetPixelFormat() call was made on
+    any device context belonging to the window, adopting the context will fail.
+
+    Ownership of the created QOpenGLContext is transferred to the caller.
+*/
+
+/*!
+    \fn HGLRC QNativeInterface::QWGLContext::nativeContext() const
+
+    \return the underlying context handle.
+*/
+
+/*!
+    \fn HMODULE QNativeInterface::QWGLContext::openGLModuleHandle()
+
+    \return the handle for the OpenGL implementation that is currently in use.
+
+    \note This function requires that the QGuiApplication instance is already created.
+*/
+
 QT_DEFINE_NATIVE_INTERFACE(QWGLContext, QOpenGLContext);
 QT_DEFINE_PRIVATE_NATIVE_INTERFACE(QWindowsGLIntegration);
 
@@ -68,7 +110,212 @@ QOpenGLContext *QNativeInterface::QWGLContext::fromNative(HGLRC context, HWND wi
 
 #endif // QT_NO_OPENGL
 
+/*!
+    \class QNativeInterface::Private::QWindowsApplication
+    \since 6.0
+    \internal
+    \brief Native interface to QGuiApplication, to be retrieved from QPlatformIntegration.
+    \inmodule QtGui
+    \ingroup native-interfaces
+*/
+
 QT_DEFINE_PRIVATE_NATIVE_INTERFACE(QWindowsApplication);
+
+/*!
+    \enum QNativeInterface::Private::QWindowsApplication::TouchWindowTouchType
+
+    This enum represents the supported TouchWindow touch flags for registerTouchWindow().
+
+    \value NormalTouch
+    \value FineTouch
+    \value WantPalmTouch
+*/
+
+/*!
+    \fn void QNativeInterface::Private::QWindowsApplication::setTouchWindowTouchType(QNativeInterface::Private::QWindowsApplication::TouchWindowTouchTypes type)
+
+    Sets the touch window type for all windows to \a type.
+*/
+
+/*!
+    \fn QNativeInterface::Private::QWindowsApplication::TouchWindowTouchTypes QNativeInterface::Private::QWindowsApplication::touchWindowTouchType() const
+
+    Returns the currently set the touch window type.
+*/
+
+/*!
+    \enum QNativeInterface::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 QNativeInterface::Private::QWindowsApplication::setWindowActivationBehavior(QNativeInterface::Private::QWindowsApplication::WindowActivationBehavior behavior)
+
+    Sets the window activation behavior to \a behavior.
+
+    \sa QWidget::activateWindow(), QWindow::requestActivate()
+*/
+
+/*!
+    \fn QNativeInterface::Private::QWindowsApplication::WindowActivationBehavior QNativeInterface::Private::QWindowsApplication::windowActivationBehavior() const
+
+    Returns the currently set the window activation behavior.
+*/
+
+/*!
+    \fn bool QNativeInterface::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 QNativeInterface::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 QNativeInterface::Private::QWindowsApplication::isDarkMode() const = 0
+
+    Returns \c true if Windows 10 is configured to use dark mode for
+    applications.
+*/
+
+/*!
+    \fn void QNativeInterface::Private::QWindowsApplication::setDarkModeHandling(DarkModeHandling handling) = 0
+
+    Sets the dark mode handling to \a handling.
+*/
+
+/*!
+    \fn QNativeInterface::Private::QWindowsApplication::DarkModeHandling QNativeInterface::Private::QWindowsApplication::darkModeHandling() const
+
+    Returns the currently set dark mode handling.
+*/
+
+/*!
+    \fn bool QNativeInterface::Private::QWindowsApplication::isWinTabEnabled() const = 0
+
+    Returns whether the \e{Tablet WinTab Driver} (\c Wintab32.dll) is used.
+*/
+
+/*!
+    \fn bool QNativeInterface::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 QNativeInterface::Private::QWindowsApplication::registerMime(QWindowsMime *mime)
+
+    Registers the converter \a mime to the system.
+
+    \sa QNativeInterface::Private::QWindowsMime, unregisterMime()
+*/
+
+/*!
+    \fn void QNativeInterface::Private::QWindowsApplication::unregisterMime(QWindowsMime *mime)
+
+    Unregisters the converter \a mime from the system.
+
+    \sa QNativeInterface::Private::QWindowsMime, registerMime()
+*/
+
+/*!
+    \fn int QNativeInterface::Private::QWindowsApplication::registerMimeType(const QString &mime)
+
+    Registers the MIME type \a mime, and returns an ID number
+    identifying the format on Windows.
+*/
+
+/*!
+    \fn HWND QNativeInterface::Private::QWindowsApplication::createMessageWindow(const QString &, const QString &, QFunctionPointer) const
+    \internal
+*/
+
+/*!
+    \fn bool QNativeInterface::Private::QWindowsApplication::asyncExpose() const
+    \internal
+*/
+
+/*!
+    \fn void QNativeInterface::Private::QWindowsApplication::setAsyncExpose(bool)
+    \internal
+*/
+
+/*!
+    \fn QVariant QNativeInterface::Private::QWindowsApplication::gpu()
+    \internal
+*/
+
+/*!
+    \fn QVariant QNativeInterface::Private::QWindowsApplication::gpuList()
+    \internal
+*/
+
+/*!
+    \class QNativeInterface::Private::QWindowsWindow
+    \since 6.0
+    \internal
+    \brief Native interface to QPlatformWindow.
+    \inmodule QtGui
+    \ingroup native-interfaces
+*/
+
 QT_DEFINE_PRIVATE_NATIVE_INTERFACE(QWindowsWindow);
 
+/*!
+    \fn void QNativeInterface::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 QNativeInterface::Private::QWindowsWindow::hasBorderInFullScreen() const
+
+    Returns whether the WS_BORDER flag will be set for the window in full screen
+    mode.
+*/
+
+/*!
+    \fn QMargins QNativeInterface::Private::QWindowsWindow::customMargins() const
+
+    Returns the margin to be used when handling the \c WM_NCCALCSIZE message.
+*/
+
+/*!
+    \fn void QNativeInterface::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.
+*/
+
 QT_END_NAMESPACE