Revision control
++ // Copyright (C) 2020 The Qt Company Ltd
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++
++ /*!
++ \page platform-integration.html
++ \title Platform Integration
++ \brief Integrating Qt with the native platform.
++ \ingroup explanations-platforms
++
++ 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
++
++ \include platformintegration.qdocinc type-conversions
++
++ For example, to get the current user's username on Apple platforms:
++
++ \code
++ NSProcessInfo *processInfo = NSProcessInfo.processInfo;
++ QString userName = QString::fromNSString(processInfo.userName)
++ \endcode
++
++ For a complete list of all type conversions, see the \l{Type Conversions} overview.
++
++ \section1 Integrating with other UI toolkits
++
++ \include platformintegration.qdocinc mixing-qt-with-other-ui-toolkits-intro
++
++ See \l{Mixing Qt with other UI toolkits} for a deep-dive into how Qt supports
++ these two use-cases.
++
++ \section1 Event Handling
++
++ Most event handling use-cases in Qt are sufficiently covered by the cross
++ platform event delivery, via QWindow::event() and friends, or through
++ QObject::installEventFilter().
++
++ In cases where this is not enough, Qt provides access to the delivery of the
++ native events. A global event filter that receives all native events can be
++ installed by using QCoreApplication::installNativeEventFilter(), while
++ per-window native events can be handled in QWindow::nativeEvent().
++
++ \note Interfering with the native event flow may put Qt in an inconsistent
++ state. These APIs should primarily be used to augment Qt's existing
++ event handling, for example for events Qt doesn't handle yet.
++
++ \section1 Native Interfaces
++
++ Platform specific functionality not covered by the APIs mentioned above
++ are handled by the more generic \l{Native Interfaces}{native interface}
++ mechanism in Qt. The interfaces provide access to native or platform
++ specific APIs of the classes they extend.
++
++ \include platformintegration.qdocinc native-interface-blurb
++
++ \include platformintegration.qdocinc native-interface-handle-access-example
++
++ For a complete list of all native interfaces, see the \l{Native Interfaces} overview.
++
++ \warning \include platformintegration.qdocinc native-interface-compat-warning
++
++ \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} and the rendering
++ hardware abstractions in RHI.
++
++ 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.
++ */
++
++ /*!
++ \group platform-type-conversions
++ \title Type Conversions
++
++ \include platformintegration.qdocinc type-conversions
++
++ The following list enumerates all of the available type conversions:
++ */
++
++ /*!
++ \group native-interfaces
++ \title Native Interfaces
++
++ The native interfaces provide access to native or platform specific APIs of
++ the classes they extend.
++
++ \include platformintegration.qdocinc native-interface-blurb
++
++ \section1 Example Usage
++
++ \section2 Accessing underlying native handles
++
++ In situations where a feature of the native platform is not exposed in Qt,
++ it can be helpful to access the native handles maintained by Qt, and use
++ those to call the native APIs instead.
++
++ \include platformintegration.qdocinc native-interface-handle-access-example
++
++ The native interface is accessed through the QOpenGLContext::nativeInterface()
++ accessor, which ensures that the requested interface is available, and otherwise
++ returns \nullptr. The underlying NSOpenGLContext is then accessed through the
++ \l{QNativeInterface::QCocoaGLContext::nativeContext()}{nativeContext()} accessor.
++
++ \section2 Adopting existing native handles
++
++ In some situations the native platform, or another toolkit, has created a native
++ handle that you would like to pass on to Qt \mdash wrapping the existing handle
++ instead of creating a new one.
++
++ For example, to adopt an existing NSOpenGLContext, and use that to share
++ resources with a context created by Qt:
++
++ \code
++ using namespace QNativeInterface;
++ QOpenGLContext *adoptedContext = QCocoaGLContext::fromNativeContext(nsOpenGLContext);
++ anotherContext->setShareContext(adoptedContext);
++ \endcode
++
++ The adopted context is created by a platform specific factory function
++ in the QNativeInterface::QCocoaGLContext native interface.
++
++ \section2 Accessing platform specific APIs
++
++ In some cases an API is too platform specific to be included in the cross platform
++ Qt classes, but is still useful to include. These APIs are available either in the
++ same way as when accessing the underlying native handles, through the
++ \l{QOpenGLContext::nativeInterface()}{nativeInterface()} accessor, or directly
++ as static function in the native interface.
++
++ For example, to pull out the OpenGL module handle on Windows:
++
++ \code
++ using namespace QNativeInterface;
++ HMODULE moduleHandle = QWGLContext::openGLModuleHandle();
++ \endcode
++
++ \section1 Source and Binary Compatibility
++
++ \include platformintegration.qdocinc native-interface-compat-warning
++
++ \section1 Available Interfaces
++
++ For a list of all available interfaces, see the QNativeInterface namespace.
++
++ \section2 QOpenGLContext
++
++ Accessed through QOpenGLContext::nativeInterface().
++
++ \annotatedlist native-interfaces-qopenglcontext
++
++ \section2 QOffscreenSurface
++
++ Accessed through QOffscreenSurface::nativeInterface().
++
++ \annotatedlist native-interfaces-qoffscreensurface
++
++ \section2 QSGTexture
++
++ Accessed through QSGTexture::nativeInterface().
++
++ \annotatedlist native-interfaces-qsgtexture
++
++ \noautolist
++ */
++
++ /*!
++ \namespace QNativeInterface
++ \inmodule QtPlatformIntegration
++ \since 6.0
++
++ \brief Contains the available native interfaces.
++
++ For documentation on how to use these interfaces, see the \l{Native Interfaces} overview.
++
++ \warning \include platformintegration.qdocinc native-interface-compat-warning
++ */
++
++ /*!
++ \namespace QNativeInterface::Private
++ \inmodule QtPlatformIntegration
++ \internal
++ \since 6.0
++
++ \brief Contains the available private native interfaces.
++ */