From 40e6fe780150161bb608f5df356bfe4f00861be5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tor=20Arne=20Vestb=C3=B8?= Date: Wed, 14 Oct 2020 12:20:38 +0200 Subject: 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 --- .../platform/android/qandroidnativeinterface.cpp | 15 +- src/gui/platform/macos/qcocoanativeinterface.mm | 54 +++++ src/gui/platform/unix/qunixnativeinterface.cpp | 108 ++++++++- .../platform/windows/qwindowsnativeinterface.cpp | 247 +++++++++++++++++++++ 4 files changed, 418 insertions(+), 6 deletions(-) (limited to 'src/gui/platform') 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() const { return dynamic_cast(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 -- cgit v1.2.3