Revision control
Copy as Markdown
// 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.
*/