// 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

    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{ActiveQt}{Active Qt} for more information.
*/
