Revision control
++ // Copyright (C) 2024 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++
++ /*!
++ \title Window Hosting Example
++ \ingroup examples-widgets
++ \example demos/windowhosting
++ \examplecategory {User Interface Components}
++ \meta {tag} {demo,gui,quick,widgets}
++ \brief A demonstration of how to host non-Qt UI elements in Qt applications.
++
++ Qt offers a wide range of UI controls for both Qt Widget and Qt Quick-based
++ applications, but sometimes it may be desirable to use controls from other
++ UI toolkits, such as the platform's native UI toolkit.
++
++ To integrate these controls, we build upon the QWindow abstraction in Qt, by creating a
++ QWindow representation of the native UI control, that can then be hosted within the Qt UI.
++ A window created in this manner is known in Qt as a \e{foreign window}, as it represents a
++ control created by a foreign (to Qt) UI toolkit.
++
++ \section1 Creating a foreign window
++
++ To create the QWindow representation we use QWindow::fromWinId(), passing a reference to a
++ native window handle, represented by the opaque WId type.
++
++ Each platform defines what native type the WId opaque type maps to.
++
++ \include platformintegration.qdocinc winid-types
++
++ The result is a QWindow that represents the native window handle.
++
++ \include platformintegration.qdocinc winid-ownership-note
++
++ Now, before we can create a QWindow using QWindow::fromWinId() we need a native window handle.
++ In this example, we will host a month calendar control, as most platforms have it in their
++ native UI toolkits, or otherwise readily available. The specifics of how to create the
++ calendar on each platform are shown in the code snippets below.
++
++ To ensure that the native handle stays alive, but is also cleaned up properly on
++ application exit, we maintain a list of cleanup functions that we execute before
++ returning from \c main().
++
++ In addition to creating the native window handle and turning that into a QWindow,
++ we also set a minimum size on the resulting QWindow, based on what the native toolkit
++ reports as the preferred minimum size of the calendar control. This allows
++
++ Qt to lay out the hosted foreign window properly.
++
++ \if defined(onlinedocs)
++ \tab {from-win-id}{macos}{macOS}{checked}
++ \tab {from-win-id}{windows}{Windows}{}
++ \tab {from-win-id}{x11}{X11}{}
++ \tab {from-win-id}{ios}{iOS}{}
++ \tab {from-win-id}{android}{Android}{}
++ \tab {from-win-id}{webassembly}{WebAssembly}{}
++ \endif
++
++ \if defined(onlinedocs)
++ \tabcontent {macos}
++ \else
++ \section2 macOS
++ \endif
++ \inlineimage macos.webp {Qt GUI, Qt Widgets, and Qt Quick windows hosting a macOS calendar}
++ \snippet demos/windowhosting/main.cpp macos
++ \if defined(onlinedocs)
++ \endtabcontent
++ \endif
++
++ \if defined(onlinedocs)
++ \tabcontent {windows}
++ \else
++ \section2 Windows
++ \endif
++ \inlineimage windows.webp
++ {Qt GUI, Qt Widgets, and Qt Quick windows hosting a Windows calendar}
++ \snippet demos/windowhosting/main.cpp windows
++ \if defined(onlinedocs)
++ \endtabcontent
++ \endif
++
++ \if defined(onlinedocs)
++ \tabcontent {x11}
++ \else
++ \section2 X11
++ \endif
++ \inlineimage x11.webp {Qt GUI, Qt Widgets, and Qt Quick windows hosting a GTK calendar}
++ \snippet demos/windowhosting/main.cpp x11
++ \if defined(onlinedocs)
++ \endtabcontent
++ \endif
++
++ \if defined(onlinedocs)
++ \tabcontent {ios}
++ \else
++ \section2 iOS
++ \endif
++ \inlineimage ios.webp {Qt GUI, Qt Widgets, and Qt Quick containers hosting an iOS calendar}
++
++ \snippet demos/windowhosting/main.cpp ios
++ \if defined(onlinedocs)
++ \endtabcontent
++ \endif
++
++ \if defined(onlinedocs)
++ \tabcontent {android}
++ \else
++ \section2 Android
++ \endif
++ \inlineimage android.webp {Qt GUI, Qt Widgets, and Qt Quick containers hosting an Android calendar}
++
++ \snippet demos/windowhosting/main.cpp android
++ \if defined(onlinedocs)
++ \endtabcontent
++ \endif
++
++ \if defined(onlinedocs)
++ \tabcontent {webassembly}
++ \else
++ \section2 WebAssembly
++ \endif
++ \inlineimage webassembly.webp {Qt GUI, Qt Widgets, and Qt Quick windows hosting a calendar on a WebAssembly calendar}
++ \snippet demos/windowhosting/main.cpp webassembly
++ \if defined(onlinedocs)
++ \endtabcontent
++ \endif
++
++ \section1 Hosting a foreign window
++
++ Now that we have a foreign QWindow, we can host it in a Qt UI.
++ We have several options here, as described below.
++
++ \section2 Hosting in Qt GUI
++
++ At the lowest level, we can host the foreign window by reparenting it into
++ another QWindow, via QWindow::setParent(). This approach leaves it up to
++ the application developer to handle positioning, resizing, and other aspects
++ of managing the hosted child window, so we generally advise against
++
++ integrating on this level, if at all possible.
++
++ In this example we first create a minimal container window implementation.
++
++ \snippet demos/windowhosting/main.cpp qt-gui-container-window
++
++ Which we can then reparent our foreign window into.
++
++ \snippet demos/windowhosting/main.cpp qt-gui
++
++ \section2 Hosting in Qt Widgets
++
++ For applications built on the Qt Widgets UI stack we follow the same approach
++ as for QWindow::fromWinId(), by creating a QWidget representation of the
++ QWindow, via QWidget::createWindowContainer().
++
++ We could then reparent the widget into another widget, via QWidget::setParent(),
++ with the same caveats as the Qt GUI example above of having to manage positioning,
++ resizing, etc. manually. In this example we prefer to add the window container
++ widget to a QVBoxLayout, which allows us to automatically center the foreign
++ window inside the top level widget.
++
++ \snippet demos/windowhosting/main.cpp qt-widgets
++
++ \section2 Hosting in Qt Quick
++
++ Finally, for applications built on the Qt Quick UI stack, we use the WindowContainer
++ item to manage the foreign window.
++
++ \snippet demos/windowhosting/Main.qml qt-quick
++
++ In this example the foreign window is exposed to the QML engine as an initial property,
++ but this could be solved in different ways depending on the needs of the application.
++
++ \snippet demos/windowhosting/main.cpp qt-quick
++ */