Qt for HarmonyOS Native Window ID Example

Shows the platform IDs of the windows of a Qt application on HarmonyOS.

Each window of the example shows the ID of its platform window, the window.Window that the window is shown in, and the ID of the display that the platform window is on. Platform APIs and other applications identify windows and displays by these IDs.

A window gets its window.Window from QNativeInterface::QHarmonyWindow on the Qt thread, as a QHarmonyJsObjectRef handle. getWindowProperties() returns the IDs synchronously, so the example reads them with QNativeInterface::QHarmonyApplication::runOnJsThreadAndWait(), which returns the result of the task to the Qt thread:

void WindowIdWindow::showWindowIds()
{
    auto *harmonyWindow = windowHandle()->nativeInterface<QHarmonyWindow>();
    const auto jsWindowRef = harmonyWindow ? harmonyWindow->jsWindow() : QHarmonyJsObjectRef();
    const WindowIds windowIds = QHarmonyApplication::runOnJsThreadAndWait(
        [&](QHarmonyJsContext &jsContext) {
            return readWindowIds(jsContext, jsWindowRef);
        });

    if (!windowIds.errorText.isEmpty()) {
        m_idsLabel->setText(QStringLiteral("Reading the IDs failed: %1").arg(windowIds.errorText));
        return;
    }
    m_idsLabel->setText(
        QStringLiteral("Window ID: %1\nDisplay ID: %2")
            .arg(QString::number(windowIds.windowId), formatDisplayId(windowIds.optDisplayId)));
}

On the JS thread, the task dereferences the handle and reads the IDs from the window properties. The display ID is an optional property. An error that the call throws is returned as text:

struct WindowIds
{
    std::int64_t windowId = 0;
    std::optional<std::int64_t> optDisplayId;
    QString errorText;
};

WindowIds readWindowIds(QHarmonyJsContext &jsContext, const QHarmonyJsObjectRef &jsWindowRef)
{
    Napi::Env env(jsContext.env());
    Napi::Object jsWindow(env, jsWindowRef.value(jsContext));
    if (jsWindow.IsEmpty()) {
        return WindowIds{
            .errorText = QStringLiteral("the window is not shown in a window.Window"),
        };
    }

    try {
        auto getWindowPropertiesFunc = jsWindow.Get("getWindowProperties").As<Napi::Function>();
        auto windowProperties = getWindowPropertiesFunc.Call(jsWindow, {}).As<Napi::Object>();
        auto displayIdValue = windowProperties.Get("displayId");
        return WindowIds{
            .windowId = windowProperties.Get("id").As<Napi::Number>().Int64Value(),
            .optDisplayId = displayIdValue.IsNumber() ? std::optional(displayIdValue.As<Napi::Number>().Int64Value()) : std::nullopt,
        };
    } catch (const Napi::Error &error) {
        return WindowIds{
            .errorText = QString::fromUtf8(error.what()),
        };
    }
}

The constructor creates the window's QWindow and connects to QWindow::screenChanged(), so the IDs are read again whenever the window moves to another display:

create();
connect(windowHandle(), &QWindow::screenChanged, this, &WindowIdWindow::showWindowIds);

A window reads its IDs right after show() has returned, when its platform window exists:

void WindowIdWindow::openWindow(const QString &title, QWidget *parentWindow)
{
    auto *newWindow = new WindowIdWindow(title, parentWindow);
    newWindow->setAttribute(Qt::WA_DeleteOnClose);
    newWindow->show();
    newWindow->showWindowIds();
}

Running the Example

Press New sub window and New top-level window. Each window shows a window ID of its own. A sub window is shown in a platform window of its own too.

Move a window to another display. The display ID follows the window, while the window ID stays the same.

Example project @ code.qt.io

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.