Revision control
Copy as Markdown
// Copyright (C) 2026 The Qt Company Ltd
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\page mixing-qt-with-other-ui-toolkits.html
\title Mixing Qt with other UI toolkits
\ingroup explanations-platforms
\include platformintegration.qdocinc mixing-qt-with-other-ui-toolkits-intro
We now look at different aspects of solving these two use-cases.
\section1 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 \c{WId} type, an opaque handle, with each platform having its own definition
of what native type it maps to.
\include platformintegration.qdocinc winid-types
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.
\code
QWindow *foreignWindow = QWindow::fromWinId(WId(nativeHandle));
\endcode
A window created in this manner is known as a \e{foreign window} in Qt, since it
represents a control created by a foreign (to Qt) UI toolkit.
\include platformintegration.qdocinc winid-ownership-note
We can now embed our Qt UI into this foreign window, or host the foreign window
in our Qt UI.
\section1 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.
\section2 Embedding Qt Widgets
To embed a Qt Widget UI we ask the widget for its
\l{QWidget::windowHandle}{window handle}, and then
reparent that into the foreign window.
\code
QMainWindow *mainWindow = new QMainWindow;
mainWindow->windowHandle()->setParent(foreignWindow);
\endcode
\section2 Embedding Qt Quick
To embed a Qt Quick UI we can directly reparent the quick view.
\code
QQuickView *quickView = new QQuickView;
quickView->setParent(foreignWindow);
\endcode
\section2 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.
\code
quickView->setFlags(quickView->flags() | Qt::SubWindow);
\endcode
We then ask the QWidget or QQuickView for its \c{WId}, via
QWindow::winId(), and then return this native handle
to be reparented.
\code
return reinterpret_cast<NSView*>(quickView->winId());
\endcode
\section2 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.
\section1 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.
\section2 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.
\code
QWidget *hostedWidget = QWidget::createWindowContainer(foreignWindow);
layout->addWidget(hostedWidget);
\endcode
\section2 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.
\code
engine.setInitialProperties({{ "foreignWindow", QVariant::fromValue(foreignWindow) }});
\endcode
\badcode
ApplicationWindow {
required property QtObject foreignWindow;
WindowContainer {
window: foreignWindow
anchors.centerIn: parent
}
}
\endcode
See the \l{Window Hosting Example} for a detailed look at this use-case.
\section1 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.
\section2 Active Qt module
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 \l{Active Qt} for more information.
*/