Mixing Qt with other UI toolkits

Qt provides a comprehensive set of cross-platform UI components and controls that cover the vast majority of application development needs. However, there are situations where integrating Qt with other UI toolkits becomes necessary or beneficial.

One scenario is embedding Qt UIs into applications built with other toolkits, for example when implementing plugins for an existing application, or when gradually introducing Qt into an existing codebase.

Another scenario is hosting native or third-party UI elements in a Qt application, for example to access specialized controls that Qt doesn't provide.

We now look at different aspects of solving these two use-cases.

Foreign windows

To integrate Qt with other UI toolkits, we first need a shared representation of the primitive UI building blocks for that platform. In Qt, this is represented by the WId type, an opaque handle, with each platform having its own definition of what native type it maps to.

The next step is to wrap that native handle in something Qt can interact with. We build upon the QWindow abstraction in Qt by creating a QWindow representation of the native handle.

QWindow *foreignWindow = QWindow::fromWinId(WId(nativeHandle));

A window created in this manner is known as a foreign window in Qt, since it represents a control created by a foreign (to Qt) UI toolkit.

We can now embed our Qt UI into this foreign window, or host the foreign window in our Qt UI.

Embedding Qt into other UI toolkits

To embed Qt UIs in other UI toolkits we use the foreign window as our UI's parent window.

Embedding Qt Widgets

To embed a Qt Widget UI we ask the widget for its window handle, and then reparent that into the foreign window.

QMainWindow *mainWindow = new QMainWindow;
mainWindow->windowHandle()->setParent(foreignWindow);

Embedding Qt Quick

To embed a Qt Quick UI we can directly reparent the quick view.

QQuickView *quickView = new QQuickView;
quickView->setParent(foreignWindow);

When there is no parent handle

In some cases we might not have access to the native parent handle, and are instead asked to produce a native handle that will be reparented outside of our control.

As a QWindow without a parent is normally a top level window, we first need to explicitly tell Qt that the window is going to be a child window, by adding the Qt::SubWindow flag.

quickView->setFlags(quickView->flags() | Qt::SubWindow);

We then ask the QWidget or QQuickView for its WId, via

QWindow::winId(), and then return this native handle to be reparented.

return reinterpret_cast<NSView*>(quickView->winId());

Event dispatching

Qt relies on being able to regularly process events and timers, so when integrating Qt UIs into another UI toolkit we still need a QGuiApplication. A typical pattern is to create the application instance when first building the Qt UI, and then deleting it when we know the Qt UI has been torn down, for example during plugin unloading.

Hosting other UI toolkits in Qt

To host other UI toolkits in Qt we wrap the foreign window in a Qt Widget or Qt Quick specific window container.

Hosting in Qt Widgets

For applications built on the Qt Widgets UI stack, we create a QWidget representation of the QWindow, via QWidget::createWindowContainer(), which can then be managed like any other widget, for example, in a layout.

QWidget *hostedWidget = QWidget::createWindowContainer(foreignWindow);
layout->addWidget(hostedWidget);

Hosting in Qt Quick

For applications built on the Qt Quick UI stack, we expose the foreign window to the QQmlApplicationEngine, and then use the WindowContainer item to manage the foreign window.

engine.setInitialProperties({{ "foreignWindow", QVariant::fromValue(foreignWindow) }});

ApplicationWindow {
    required property QtObject foreignWindow;
    WindowContainer {
        window: foreignWindow
        anchors.centerIn: parent
    }
}

See the Window Hosting Example for a detailed look at this use-case.

Platform specific solutions

The basic primitives for window embedding and hosting described above should cover most cases, but Qt also provides platform specific solutions where an even deeper integration is needed.

Active Qt

Qt's ActiveX and COM support enables Qt for Windows developers to access and use ActiveX controls and COM objects provided by any ActiveX server in their Qt applications, and to make their Qt applications available as COM servers, with any number of Qt objects and widgets as COM objects and ActiveX controls.

See Active Qt for more information.