QHarmonyAppJsContext Class
The QHarmonyAppJsContext class gives code on the JS thread of a HarmonyOS application access to the application's state. More...
| Header: | #include <QHarmonyAppJsContext> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Core)target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake: | QT += core |
| Inherits: | QHarmonyJsContext |
Public Functions
| std::shared_ptr<void> | addUiAbilityDelegate(int delegateValue) |
| int | defaultAbility() |
Static Public Members
| QHarmonyAppJsContext & | fromEnv(int env) |
| QHarmonyAppJsContext & | fromJsContext(QHarmonyJsContext &jsContext) |
Detailed Description
QHarmonyJsContext describes the JS runtime. QHarmonyAppJsContext holds the state of the application in that runtime, such as its default UIAbility instance. Keeping the two apart makes function signatures meaningful. A function that takes a QHarmonyAppJsContext depends on the application's state. A function that takes a QHarmonyJsContext needs only the runtime. A task gets the application context once, with fromJsContext(), and passes it on.
The class derives from QHarmonyJsContext, and there is only one object. QHarmonyJsContext::fromEnv() returns it as the base class. All member functions must be called on the JS thread. References to it and its napi_value results follow the lifetime rules of QHarmonyJsContext.
See also Qt for HarmonyOS Platform API.
Member Function Documentation
std::shared_ptr<void> QHarmonyAppJsContext::addUiAbilityDelegate(int delegateValue)
Registers delegateValue as a delegate for the methods of the application's UIAbility class and returns a handle that keeps the registration. delegateValue must be a JS object.
Qt forwards a UIAbility method by calling the delegate method of the same name with the UIAbility instance as the first argument, followed by the arguments the UIAbility method received. It looks the method up at each call and calls it as a method of the delegate. A delegate defines a method when the property of that name is a function. It may define any subset of the forwarded methods. Delegates are called in registration order. A method with a result has a default, which Qt returns when no delegate defines the method or when the delegate method throws. If a delegate method throws, the exception is logged and cleared. The throw does not change which other delegates are called.
The forwarded methods are:
onNewWant(): called on every delegate. The return value is ignored. The delegate must not modify the arguments. Qt does not forward the Wants that it sends to its own abilities.onContinue(): called on the first delegate that defines it. Its result is returned to the system. The default isAbilityConstant.OnContinueResult.REJECT.
Methods not listed are not forwarded. Later versions may forward more methods.
Qt holds a strong reference to the delegate until the handle is released. Releasing it unregisters the delegate, and no delegate method is called afterwards. A delegate method may release the handle.
The handle can be released on any thread. Releasing it on another thread blocks that thread until the JS thread has unregistered the delegate.
See also Qt for HarmonyOS Platform API.
int QHarmonyAppJsContext::defaultAbility()
Returns the default ArkTS UIAbility instance of the application. This is the first instance created for the application or, once that instance is destroyed, another live instance. The result can therefore change over the lifetime of the process. Returns nullptr when no ability is left, which happens at some stages of application shutdown. Also returns nullptr in a child process started without a UI, where no ability exists.
The ability is the entry point to the ability-bound platform APIs. Its context property is the UIAbilityContext. APIs such as notificationManager.requestEnableNotification(), systemShare.ShareController.show(), and iap.createPurchase() take this context. context.getApplicationContext() returns the ApplicationContext, which provides restartApp() and the application directories.
[static] QHarmonyAppJsContext &QHarmonyAppJsContext::fromEnv(int env)
Returns the application context of env. env must be the environment of the JS thread. The returned context is valid as long as env.
Use this function in a JS callback created with napi_create_function(), which receives only the napi_env.
[static] QHarmonyAppJsContext &QHarmonyAppJsContext::fromJsContext(QHarmonyJsContext &jsContext)
Returns the application context of jsContext. The returned context is valid as long as jsContext.
© 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.