View source for Qt for HarmonyOS/application lifecycle guide


'''English''' [[Qt_for_HarmonyOS/application_lifecycle_guide_zh|中文]]

= Prerequisite Knowledge =
HarmonyOS application lifecycle-related documentation:

[https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/application-models/stage-model-development-overview.md Application Lifecycle (Stage Model)]

[https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/application-models/uiability-lifecycle.md UIAbility Component Lifecycle]

[https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md UIAbilityContext API Reference]

= Qt for HarmonyOS Application Lifecycle Overview =
In the HarmonyOS system, application lifecycle management follows the Stage model, primarily involving the lifecycle management of UIAbility components. Qt for OHOS applications, as part of the HarmonyOS ecosystem, must adapt to this lifecycle model.

The lifecycle of Qt for OHOS applications mainly involves the following aspects:

1. Application startup and initialization

2. Inter-application interaction (launching other applications/being launched by other applications)

3. Multiple instance management

4. Application exit

= Application Startup and Initialization =
In Qt for OHOS, the application startup process is automatically managed by the system, and developers do not need to concern themselves with the underlying details. The actual process is as follows:

1. The system starts the UIAbility component under the HarmonyOS Stage model

2. The UIAbility component calls to start the Qt thread through NAPI

3. The system automatically loads the shared library of the Qt application and calls the main function of the Qt application

4. The main window of the Qt application is created and displayed in the OHOS WindowStage

For developers, the entry point of the application remains the main function, with no need to focus on additional details.

= Inter-application Interaction (Launching Other Applications/Being Launched by Other Applications) =
In Qt for OHOS, you can use the API (startAbility) provided by the QtOhosExtras module to launch other applications, replacing the traditional QProcess solution in Qt.

Note: The following methods can only launch applications with a user interface.

=== Launching Other Applications ===

==== Explicit Matching (Specifying Bundle Name and Ability Name) ====
<syntaxhighlight lang="c++">
#include <QtOhosExtras/qohoswant.h>
#include <QtOhosExtras/qohosuiabilitycontext.h>

void MainWindow::startSpecificApp()
{
    QtOhosExtras::QOhosWant want;
    want.bundleName = "com.example.targetapp";  // Target application bundle name
    want.abilityName = "MainAbility";           // Target application Ability name
    
    // Optional: Pass parameters
    QJsonObject parameters;
    parameters.insert("key", "value");
    want.parameters = parameters;
    
    // Launch the target application
    QtOhosExtras::startAbility(want);
}
</syntaxhighlight>

==== Implicit Matching (Matching through Action and URI) ====
<syntaxhighlight lang="c++">
void MainWindow::startAppByAction()
{
    QtOhosExtras::QOhosWant want;
    want.action = "ohos.want.action.viewData";  // Action type
    want.type = "text/plain";                   // Data type
    want.uri = "content://example/data";        // Data URI
    
    // Optional: Pass parameters
    QJsonObject parameters;
    parameters.insert("key", "value");
    want.parameters = parameters;
    
    // Launch the matching application
    QtOhosExtras::startAbility(want);
}
</syntaxhighlight>

=== Being Launched by Other Applications ===
When a Qt application is launched by other applications, it needs to handle the received Want parameters.

==== Configure the following in the module's module.json5: ====
<syntaxhighlight lang="json">
"abilities": [
  {
    "name": "QAbility",
    "srcEntry": "./ets/qability/QAbility.ets",
    "launchType": "specified",
    "description": "$string:QAbility_desc",
    "icon": "$media:icon",
    "label": "$string:QAbility_label",
    "startWindowIcon": "$media:icon",
    "startWindowBackground": "$color:start_window_background",
    "exported": true,
    "skills": [
      {
        "entities": [
          "entity.system.home"
        ],
        "actions": [
          "action.system.home",
          "ohos.want.action.viewData"  // Supported action types
        ],
        "uris": [{"type": "*/*"}]      // Supported data types
      }
    ]
  }
]
</syntaxhighlight>

==== Handling Received Want ====
<syntaxhighlight lang="c++">
#include <QtOhosExtras/QtOhosExtras>

void MainWindow::init()
{
    // Connect Want reception signal
    QObject::connect(
        QtOhosExtras::QOhosUiAbilityContext::instance(),
        &QtOhosExtras::QOhosUiAbilityContext::newWantReceived,
        this,
        &MainWindow::onNewWantReceived
    );
}

void MainWindow::onNewWantReceived(QtOhosExtras::QOhosWant want)
{
    // Handle received Want parameters
    qDebug() << "Received want with action:" << want.action;
    qDebug() << "URI:" << want.uri;
    qDebug() << "Type:" << want.type;
    
    // Process parameters
    if (want.parameters.contains("key")) {
        QString value = want.parameters.value("key").toString();
        processParameter(value);
    }
    
    // Execute corresponding operations based on Want content
    if (want.action == "ohos.want.action.viewData") {
        openDataForViewing(want.uri);
    }
}
</syntaxhighlight>

= Multiple Instance Management =
In the HarmonyOS system, applications can have multiple instance modes: singleton, multi-instance single-process, and multi-instance multi-process. Qt for OHOS applications need to choose the appropriate mode based on requirements.

Note: Instances here refer to UIAbility instances.

=== Singleton Mode ===
When the application is launched again, it uses the existing instance to handle new requests:
<syntaxhighlight lang="c++">
void MainWindow::onNewWantReceived(QtOhosExtras::QOhosWant want)
{
    // Use existing window to handle new requests
    processNewRequest(want);
    
    this->setText(want.uri); // Singleton single-process: original window handles
}
</syntaxhighlight>

=== Multi-instance Single-process Mode ===
Creates a new UIAbility instance each time it is launched, but shares the same process:
<syntaxhighlight lang="c++">
void MainWindow::onNewWantReceived(QtOhosExtras::QOhosWant want)
{
    // Create new window instance
    MainWindow *newWindow = new MainWindow();
    newWindow->processRequest(want);
    newWindow->show();
}
</syntaxhighlight>

=== Multi-instance Multi-process Mode ===
Starts a new application process to create a new UIAbility instance to handle requests:
<syntaxhighlight lang="c++">
void MainWindow::onNewWantReceived(QtOhosExtras::QOhosWant want)
{
    // Start new process
    static int processCounter = 0;
    QString processName = "Process" + QString::number(processCounter++);
    
    // Use QtOhosExtras to start new process
    QtOhosExtras::startAppProcess(processName, want);
}
</syntaxhighlight>

Note: Multi-instance multi-process mode requires adding configuration in module.json5:
<syntaxhighlight lang="json">
"abilities": [
  {
    "name": "QAbility",
    // Other configurations...
    "isolationProcess": true
  }
]
</syntaxhighlight>

= Application Exit =

=== Pre-close ===