Qt for HarmonyOS/api inconsistencies on harmonyos

English 中文

Qt for HarmonyOS: API Compatibility and Porting Notes

This document outlines the key differences and limitations when using Qt public APIs on the HarmonyOS platform compared to other common platforms such as Windows, Linux, macOS, and Android.

The focus of this guide is on behavioral differences that affect application development and cross-platform porting, rather than internal implementation details.

Application Startup and Argument Passing

main(int argc, char *argv[])

On traditional platforms, argv[0] typically represents the executable path, and business arguments start from argv[1].

On HarmonyOS, the source and splicing of startup arguments differ:

• argv[0] represents the application library path, not a traditional executable file path.
• When passing arguments via a Want, the want.uri may occupy argv[1] by default.
• Consequently, the index of business arguments in argv may vary compared to other platforms.

Recommendations:

• Do not assume business arguments fixedly start at argv[1].
• Parse arguments based on the actual content of argc/argv.

Reference: Passing Arguments to main

Launching Application Instances or Processes

On desktop platforms, applications usually start another process via an executable path. On HarmonyOS, this depends on the system's Ability/Want/Process management mechanism. Qt for HarmonyOS capabilities are centered around "Starting an Ability" or "Starting an App Instance" rather than "Running an arbitrary external program."

Key public interfaces include:

• QtOhosExtras::startAbility()
• QtOhosExtras::startNewAbilityInstance()
• QtOhosExtras::startAppProcess()

Recommendations:

• Avoid the desktop mindset of "providing a path to launch a process."
• Use Ability/Want interfaces for cross-instance or cross-process activation.

Reference: Application Lifecycle Guide

UI-less Child Processes

Qt provides a dedicated "UI-less child process" capability via: QtOhosExtras::QOhosAppContext::startNoUiChildProcess(). This uses the HarmonyOS Child Process Manager. Arguments are forwarded to the child's main().

Once started, the process enters a specialized NoUiChildProcess mode. In this mode, certain Qt platform capabilities are restricted (e.g., UI rendering pipelines are not initialized).

Recommendations:

• UI-less processes should be used strictly for computation, background tasks, or auxiliary processing.
• Use QtOhosExtras::QOhosAppContext::isNoUiChildMode() to detect this state.
• Do not attempt to create or manipulate windows/UI elements in this mode.

QProcess

On desktop, QProcess is a universal interface for external programs. On HarmonyOS, the process model is different. The explicitly supported path for Qt child processes is startNoUiChildProcess(), not QProcess.

Do not assume QProcess behaves identically to desktop platforms regarding:

• Launching arbitrary external executables.
• Launching independent GUI child processes.
• Standard start(), startDetached(), or execute() semantics.

Recommendations:

• Do not treat QProcess as the recommended solution for launching child processes on HarmonyOS.
• Use startNoUiChildProcess() for background tasks and startAbility() for independent UI instances.

Window Types and Relationships

QDialog, Qt::Popup, Qt::ToolTip, Qt::Tool

On desktop, these are often treated as independent top-level windows. On HarmonyOS, they behave more like sub-windows attached to a main window:

• Parent-child relationships are strictly enforced.
• Activation behavior depends on the main window.
• Closing behavior is tied to the main window's lifecycle.

Recommendations:

• Explicitly set a parent or transientParent.
• Do not design these as completely independent top-level windows.

setParent() / Reparenting

HarmonyOS imposes additional restrictions on adjusting parent-child relationships, especially regarding embedded or external windows.

Recommendations:

• Do not treat external embedded windows as standard parent windows.
• Verify the window path before re-parenting.

Modality and Window States

Qt::WindowModality

• Modality is primarily effective in sub-window scenarios.
• Qt::ApplicationModal does not have the same global application-level scope as on desktop. Currently, it is only meaningful for sub-windows and is typically supported only on 2-in-1 or multi-window devices.

showFullScreen() / Qt::WindowFullScreen

showFullScreen() is supported. For the initial main window, "fullscreen-on-startup" (via flags) is not supported because it often utilizes a platform-pre-created window path. Subsequent windows created by the app do support startup-fullscreen via flags.

Recommendations:

• For the first main window, call showFullScreen() after the window is created/shown to ensure stability.

showMinimized() / Qt::WindowMinimized

• Main Windows: Support minimization semantics.
• Sub-windows: Do not support minimization behavior consistent with desktop platforms.

hide()

On HarmonyOS, hide() is not a universal window capability.

• For Main Windows: It attempts system-level hiding (only supported if a tray exists), otherwise falls back to minimization.
• For Sub-windows/Floating Windows: It hides the window but lacks system-level "hide" semantics.

Recommendations:

• Do not use hide() as a universal "close replacement" in closeEvent().
• Use showMinimized() for main window persistence scenarios.

Window Hints and Decorations

Minimize, Maximize, and Close Buttons

Hints like Qt::WindowMinimizeButtonHint are:

• Primarily targeted at Main Windows.
• Usually only meaningful in PC mode.
• Not guaranteed to work on all device types.

Qt::FramelessWindowHint

On HarmonyOS, this flag hides system decorations. Note that for main windows, this also makes standard title bar buttons (Min/Max/Close) unavailable.

Qt::WindowStaysOnTopHint

This capability is strictly limited:

• Primarily for Main Windows.
• Usually only effective in PC mode.

Window Shapes and Persistence

setMask()

setMask() is only supported for sub-windows. It does not work on Main Windows. For main window shaped-looks, use content-level clipping or custom painting.

Window Geometry Persistence

Unlike QSettings on desktop, HarmonyOS window persistence relies on system capabilities. Use QtOhosExtras::setMainWindowGeometryPersistenceHint().

• Must be called before the first main window is shown.
• Currently only supported on 2-in-1 devices.

Close Semantics and Drag & Drop

closeEvent(QCloseEvent *)

A closeEvent may originate from a user action or the system's Ability lifecycle termination.

• Recommendation: Distinguish between UI window closing and lifecycle-driven termination in your design.

Drag and Drop Data Access

• dragEnterEvent / dragMoveEvent: Usually only MIME type information is available. Actual data content cannot be accessed at this stage.
• dropEvent: This is the only stage where the actual QMimeData content is provided to the application.

Recommendations:

• Do not rely on actual data content for validation during "Enter" or "Move" phases.
• Use MIME types to decide acceptance and read the data only in dropEvent.

Summary of Known Principles

Avoid applying desktop experiences directly to the following on HarmonyOS:

• Minimizing sub-windows.
• Desktop-style global application modality.
• Uniform title bar button support across all window types.
• Universal "Stay on Top" support.
• Main window masking/clipping via setMask().
• Treating external embedded windows as standard Qt top-level windows.