Qt for HarmonyOS/user development guide/mainwindow and subwindow guide

English 中文 == Main Window and Subwindow Development Guide for Qt on HarmonyOS ==

1. Concepts of Main Window and Subwindow

==== 1.1 Main Window and Subwindow in HarmonyOS ==== Main Window: Represents a "task" window, has a Dock icon and a task icon (visible in Alt+Tab task switcher), generally has an independent lifecycle, and can be maximized, minimized, or windowed.

Subwindow: An independent window created for a sub-feature of a task, displayed outside the main window but without a Dock icon or task icon. It must belong to a main window. When the main window closes, the subwindow closes automatically; when the main window is minimized, the subwindow hides; when the main window is restored, the subwindow is shown again. On HarmonyOS, subwindows typically correspond to popups and dialogs.

==== 1.2 Creating Qt Widgets or Windows ==== Qt does not natively distinguish between main and subwindows when creating widgets or windows (some widgets like QDialog have a Transient Parent concept, which is similar to the main/subwindow relationship in HarmonyOS).

Example:

 // Independent window QWidget w; w.show();

// Window with parent-child relationship (assuming wp is associated with a native window) QWidget wp; wp.show(); QWidget w(&wp);

// Dialog QDialog dlg; dlg.exec();

// Dialog with a parent window (Transient Parent) QWidget w; w.show(); QDialog dlg(&w); dlg.exec();

2. HarmonyOS Adaptation Rules

2.1 Core Rules

Tagging function: Use QOhosFunctions::tagWindowOrWidgetAsSubWindowOf(QObject *windowOrWidgetToTag, QWindow *mainWindow) to instruct Qt to create a HarmonyOS subwindow for the specified top-level window, and specify its parent window. This function must be called after the main window is created and before the subwindow is created.

First window rule: The first QWindow (or a QWidget without a parent) created in the process will automatically be bound to the system's first main window for the application.

Subsequent windows rule: Any non-first QWindow (or QWidget without a parent) that is created without the AsSubWindowOf tag will be created as a HarmonyOS main window.

Transient Parent handling: For Qt widgets that natively support the Transient Parent concept (such as QDialog), if a Transient Parent is provided, the main window will be the one associated with the Transient Parent; if not, the main window is determined as with ordinary widgets.

Automatic Fallback mechanism: If the tagged parent window is invalid, the system will automatically find a suitable parent window for certain types (such as Qt::Popup, Qt::ToolTip, Qt::Dialog, Qt::Tool):

  Prefer the currently focused window
  Otherwise, use the first available top-level window
  Ensure every window finds a suitable parent

==== 2.2 Development Recommendations ==== Developers should understand the main/subwindow concept in HarmonyOS. When creating a new top-level Widget (without a parent) in Qt, if it should be a HarmonyOS subwindow, call QOhosFunctions::tagWindowOrWidgetAsSubWindowOf() and specify its parent window.

Typical scenarios:

Single-instance application: If your app has a single main window, call the AsSubWindowOf tag when creating subwindows. Multi-instance application: If your app supports multiple main windows in a single process, and all subwindows are triggered by user actions, call the AsSubWindowOf tag for subwindows. Creating a new main window requires no special handling. Transient Parent windows: For QDialogs or similar widgets that support Transient Parent and are constructed with a parent, you do not need to call the AsSubWindowOf tag—default behavior is sufficient.

3. API Reference

==== 3.1 Main Function ====

 static void QOhosFunctions::tagWindowOrWidgetAsSubWindowOf(QObject *windowOrWidgetToTag, QWindow *mainWindow)

This function sets a hint for the window system so that the given QWindow or QWidget is instantiated as a subwindow of the specified main window, not as a main window.

Parameter Description:

windowOrWidgetToTag: The QObject (must be a QWindow or QWidget) to be tagged as a subwindow mainWindow: The designated parent main window

==== 3.2 Auxiliary Functions ====

 // Tag a window as a main window

static void QOhosFunctions::tagWindowOrWidgetAsMainWindow(QObject *windowOrWidgetToTag, bool forceMainWindow = true)

// Get the parent window pointer tagged by tagWindowOrWidgetAsSubWindowOf

static QWindow *QOhosFunctions::getWindowOrWidgetAsSubWindowOfTagValue(QObject *targetWindowOrWidget)

4. Important Notes

⚠️ Warning:

Calling winId() or show() before tagging will invalidate the tag. mainWindow must be a valid QWindow pointer. If mainWindow points to a valid QWindow but it is not a main window, Qt will use the automatic fallback mechanism to find a suitable main window. If none is found, a main window will be created instead of a subwindow.

5. Code Examples

==== 5.1 Basic Usage ====

 #include <QtPlatformHeaders/QOhosFunctions>

// Create a subwindow and specify its parent main window

m_subwindow = new QWidget();

QOhosFunctions::tagWindowOrWidgetAsSubWindowOf(m_subwindow, this->windowHandle());

m_subwindow->resize(800, 600);

m_subwindow->show();

==== 5.2 Dialog Example ====

 // Method 1: Use Transient Parent (recommended)

QDialog *dialog = new QDialog(this); // 'this' is the main window widget

dialog->exec(); // No extra tagging needed

// Method 2: Manual tagging

QDialog *dialog = new QDialog();

QOhosFunctions::tagWindowOrWidgetAsSubWindowOf(dialog, this->windowHandle());

dialog->exec();

==== 5.3 Multi-window Application Example ====

 class MainWindow : public QMainWindow

{

public:

    void createSubWindow() {

        // Create a subwindow

        QWidget *subWindow = new QWidget();

        // Tag as a subwindow of the current main window

        QOhosFunctions::tagWindowOrWidgetAsSubWindowOf(subWindow, this->windowHandle());

        subWindow->setWindowTitle("Subwindow");

        subWindow->resize(400, 300);

        subWindow->show();

    }

    void createNewMainWindow() {

        // Create a new main window (no special tagging needed)

        MainWindow *newMainWindow = new MainWindow();

        newMainWindow->show();

    }

};

6. Best Practices

Tag in time: Always tag the window before calling show() or winId()

Classify properly: Clearly distinguish which windows should be main windows and which should be subwindows

Use Transient Parent: For dialogs and temporary windows, prefer Qt’s native parent mechanism

Test and verify: Check window hierarchy and lifecycle on HarmonyOS devices

Error handling: Consider fallback behavior when the parent window is invalid

7. FAQ

Q: Why does my subwindow appear as a main window?

A: Possible reasons:

• Tagging function was called after show().

• The mainWindow parameter is invalid.
• Forgot to call the tagging function.

Q: Can a subwindow exist independently of the main window?

A: No. On HarmonyOS, subwindows must be attached to a main window. When the main window closes, the subwindow closes automatically.

Q: How can I check if the window parent-child relationship is correct?

A: Use QOhosFunctions::getWindowOrWidgetAsSubWindowOfTagValue() to query the tag status of a window.