Platform Integration 6.8.3
Description: Integrating Qt with the native platform.

- Qt 6.8
- Platform Integration
- Qt 6.8.3 Reference Documentation

# Platform Integration

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.

## Type Conversions

Many of Qt's basic data types, such as QString, QPoint, or QImage, provide conversions to and from the native equivalent types.

For example, to get the current user's username on Apple platforms:

     NSProcessInfo *processInfo = NSProcessInfo.processInfo;
     QString userName = QString::fromNSString(processInfo.userName)

For a complete list of all type conversions, see the Type Conversions overview.

## Window Embedding

Windows created by the underlying platform APIs may be used as both parent containers for Qt windows, or embedded into Qt windows as child windows.

The former is useful if the application is mainly written using the native platform APIs, but where parts of the application uses Qt, for example to draw a specialized UI. To embed Qt into the window hierarchy of the native application, use QWindow::winId() to get the native handle for the Qt window, and then use the native APIs to re-parent the window into the native UI.

The latter is useful if the native platform, or another toolkit, exposes a specialized control as a native window. By using QWindow::fromWinId() to wrap the native window handle in a QWindow, the window can then be re-parented into the Qt window hierarchy as any other QWindow. To re-parent this QWindow into a Qt Widget based UI, use the widgets-specific QWidget::createWindowContainer() function.

## 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.

## Native Interfaces

Platform specific functionality not covered by the APIs mentioned above are handled by the more generic native interface mechanism in Qt. The interfaces provide access to native or platform specific APIs of the classes they extend.

The interfaces live in the QNativeInterface namespace, and cover use-cases such as accessing underlying native handles, adopting existing native handles, or providing platform specific APIs.

For example, to access the underlying NSOpenGLContext of an QOpenGLContext on macOS, via the QNativeInterface::QCocoaGLContext native interface:

     using namespace QNativeInterface;
     if (auto *cocoaGLContext = glContext->nativeInterface<QCocoaGLContext>())
         [cocoaGLContext->nativeContext() makeCurrentContext];

For a complete list of all native interfaces, see the Native Interfaces overview.

Warning: There are no source or binary compatibility guarantees for the native interface APIs, meaning that an application using these interfaces is only guaranteed to work with the Qt version it was developed against.

## 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 Qt Core and the rendering hardware abstractions in RHI.

The main abstraction layer here is the Qt Platform Abstraction, or QPA for short, which deals with window system integration and related use-cases.