Qt for OpenHarmony/user development guide

English 中文

Prerequisite Knowledge

OpenHarmony application lifecycle-related documentation:

Application Lifecycle (Stage Model)

UIAbility Component Lifecycle

UIAbilityContext API Reference

Qt for OHOS Application Lifecycle Overview

In the OpenHarmony system, application lifecycle management follows the Stage model, primarily involving the lifecycle management of UIAbility components. Qt for OHOS applications, as part of the OpenHarmony 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 OpenHarmony 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)

#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);
}

Implicit Matching (Matching through Action and URI)

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);
}

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.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
      }
    ]
  }
]

Handling Received Want

#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);
    }
}

Multiple Instance Management

In the OpenHarmony 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:

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
}

Multi-instance Single-process Mode

Creates a new UIAbility instance each time it is launched, but shares the same process:

void MainWindow::onNewWantReceived(QtOhosExtras::QOhosWant want)
{
    // Create new window instance
    MainWindow *newWindow = new MainWindow();
    newWindow->processRequest(want);
    newWindow->show();
}

Multi-instance Multi-process Mode

Starts a new application process to create a new UIAbility instance to handle requests:

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);
}

Note: Multi-instance multi-process mode requires adding configuration in module.json5:

"abilities": [
  {
    "name": "QAbility",
    // Other configurations...
    "isolationProcess": true
  }
]