QNativeInterface::QHarmonyApplication Struct
Native interface to a core application on HarmonyOS. More...
| Header: | #include <QCoreApplication> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Core)target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake: | QT += core |
- List of all members, including inherited members
- QHarmonyApplication is part of Native Interfaces.
Public Functions
| QHarmonyApplication() | |
| QHarmonyApplication(const QNativeInterface::QHarmonyApplication &) | |
| QHarmonyApplication(QNativeInterface::QHarmonyApplication &&) | |
| QNativeInterface::QHarmonyApplication & | operator=(QNativeInterface::QHarmonyApplication &&) |
| QNativeInterface::QHarmonyApplication & | operator=(const QNativeInterface::QHarmonyApplication &) |
Static Public Members
| void | runOnJsThread(std::function<void (QHarmonyJsContext &)> task) |
| Result | runOnJsThreadAndWait(Func &&task) |
| void | runOnJsThreadAndWait(const std::function<void (QHarmonyJsContext &)> &task) |
| void | runOnQtThread(std::function<void ()> task) |
Detailed Description
Accessed through QCoreApplication::nativeInterface().
On HarmonyOS, the ArkTS runtime and the platform APIs run on the main thread of the process, called the JS thread. The Qt application runs on a separate thread, called the Qt thread. This is the thread of the QCoreApplication object. This interface runs application code on the JS thread, where the code receives a QHarmonyJsContext. It also brings results back to the Qt thread.
Code that runs on the JS thread must follow these rules:
- It must not wait for the Qt thread, which may itself be waiting in runOnJsThreadAndWait(). Send results back asynchronously, with runOnQtThread() or through QPromise.
- It must not access Qt-thread objects directly, not even through a QPointer. A QPointer is created, checked, and dereferenced only on the thread of its object. The JS thread only passes copies of it along. The functor posted to the Qt thread checks the QPointer there.
- A JS callback may run after the Qt event loop has finished. Tasks that it queues with runOnQtThread() then never run.
- A
napi_valuethat it obtains is valid until the task returns, and must not leave the JS thread. To keep a JS object longer, use a QHarmonyJsObjectRef. - Resources bound to the JS engine, such as references and listeners, must be released on the JS thread.
- The JS thread also runs the platform UI, so tasks must be short.
Each task runs inside its own Node-API handle scope. A C++ exception that a task throws and a JS exception that it leaves pending are caught and logged on the JS thread. A task that needs to react to a failure must handle it itself.
See also Qt for HarmonyOS Platform API.
Member Function Documentation
[constexpr noexcept default] QHarmonyApplication::QHarmonyApplication()
Default-constructs an instance of QHarmonyApplication.
[delete] QHarmonyApplication::QHarmonyApplication(const QNativeInterface::QHarmonyApplication &)
Copy-constructs an instance of QHarmonyApplication. This function is deleted.
[delete] QHarmonyApplication::QHarmonyApplication(QNativeInterface::QHarmonyApplication &&)
Move-constructs an instance of QHarmonyApplication. This function is deleted.
[static] void QHarmonyApplication::runOnJsThread(std::function<void (QHarmonyJsContext &)> task)
Queues task for execution on the JS thread and returns immediately. You can call this function from any thread. This is the primary way to reach the platform APIs. The task, with everything it captures, is destroyed on the JS thread.
Tasks queued with runOnJsThread() and runOnJsThreadAndWait() run one at a time, in the order in which they were queued.
[static] template <typename Func, typename Result> Result QHarmonyApplication::runOnJsThreadAndWait(Func &&task)
Runs task on the JS thread, blocks the calling thread until task returns, and returns its result. task is ordered like in the overload without a result. If task throws an exception or leaves a JS exception pending, the exception is logged on the JS thread and a default-constructed value is returned. The result must not be a napi_value or a napi_ref. To bring JS data back, convert it with the QtHarmony functions or keep it in a QHarmonyJsObjectRef.
[static] void QHarmonyApplication::runOnJsThreadAndWait(const std::function<void (QHarmonyJsContext &)> &task)
Runs task on the JS thread and blocks the calling thread until task returns. You can call this function from any thread. task runs after the tasks queued before it with runOnJsThread() or runOnJsThreadAndWait(). When called on the JS thread, it runs task directly, before any task that is still queued. task must not wait for the calling thread.
[static] void QHarmonyApplication::runOnQtThread(std::function<void ()> task)
Queues task for execution on the Qt thread, the thread of the QCoreApplication object, and returns immediately. You can call this function from any thread at any time. Use it to bring results back from the JS thread. Tasks queued with runOnQtThread() run one at a time, in the order in which they were queued. A task queued after the Qt event loop has finished for good never runs.
[delete] QNativeInterface::QHarmonyApplication &QHarmonyApplication::operator=(QNativeInterface::QHarmonyApplication &&)
Move-assigns other to this QHarmonyApplication instance. This function is deleted.
[delete] QNativeInterface::QHarmonyApplication &QHarmonyApplication::operator=(const QNativeInterface::QHarmonyApplication &)
Copy-assigns other to this QHarmonyApplication instance. This function is deleted.
© 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.
