Qt for HarmonyOS/user development guide/floating window guide

English 中文

Qt for HarmonyOS: Development Guide for Floating Window Functionality

Introduction

This document provides detailed instructions on implementing the floating window feature in Qt for HarmonyOS applications.

HarmonyOS offers native floating window capabilities. Through the QtOhosExtras module, Qt provides developers with interfaces for creating and managing Widget / QWindow instances based on HarmonyOS's floating window framework.

This guide explains the usage, implementation mechanism, and key code examples of the floating window feature in detail.

---

Functional Architecture Overview

When using Qt floating window functionality on HarmonyOS, you need to understand the following architectural principles.

Application Window Types

Qt for HarmonyOS supports the creation of multiple window types:

1. Standard Main Window
   • Built on HarmonyOS main window capabilities
   • Displayed within the application task stack
   • Follows the standard application lifecycle
2. Floating Window
   • Built on native HarmonyOS floating window capabilities
   • Can be displayed on top of other applications
   • Has an independent display layer

---

Window Hierarchy Relationships

Qt floating windows support complex hierarchy structures:

Window Type	Parent-Child Support	Usage Scenarios
Main Window	Supports child windows	Application main interface
Floating Window	Supports child windows	Floating tools, notification windows
Child Window	Nestable	Dialogs, pop-ups

---

Core Features

The floating window functionality in Qt for HarmonyOS has the following characteristics:

1. Underlying Integration: Implemented based on HarmonyOS native floating window capabilities.
2. Qt Object Interface: Supports creation, destruction, and property configuration via standard Qt interfaces.
3. Content Rendering: Uses the same content loading and painting mechanism as regular QWidgets.
4. Child Window Support: Supports modal and non-modal child windows within floating windows.

---

Qt API Details

setShowWindowAsFloatWindowHint()

void QtOhosExtras::setShowWindowAsFloatWindowHint(
    QWidget *widget,
    bool enable
);

This is the core floating window configuration API provided by Qt for HarmonyOS. It is used to set a specified Qt window to HarmonyOS floating window mode.

---

Parameter Description

Parameter	Type	Description
widget	QWidget*	The window object to be set as a floating window
enable	bool	true enables floating window mode; false sets it to normal window mode

---

Functional Mechanism

The function operates on the HarmonyOS platform as follows:

1. Window Hint Setting: Applies a floating window display hint to the specified QWidget.
2. Underlying Mapping: Maps the Qt window to a native HarmonyOS floating window.
3. Property Inheritance: Preserves all standard properties and behaviors of the Qt window.
4. Lifecycle Management: Floating windows follow the standard lifecycle of Qt objects.

---

Development Implementation

Core Implementation Principle

The key to implementing floating window functionality is:

• You must call setShowWindowAsFloatWindowHint() before calling show() on the window.

---

Key Code Examples

1. Creating a Floating Window

// Core implementation for creating a floating window
void MainWindow::openFloatingWindow()
{
    // Create window instance
    SecondWindow *win = new SecondWindow();

    // Critical: Set to floating window mode (must be called before show())
    QtOhosExtras::setShowWindowAsFloatWindowHint(win, true);

    // Configure window properties
    win->setAttribute(Qt::WA_DeleteOnClose);
    win->resize(300, 300);

    // Show the window
    win->show();
}

Notes:

• The floating window configuration API must be called before show().
• Floating windows can be sized and configured just like regular QWidgets.
• It is recommended to use Qt::WA_DeleteOnClose for automatic resource release.

---

2. Creating Child Windows Inside a Floating Window

// Create a modal dialog with the floating window as parent
void SecondWindow::modalWithParent()
{
    SimpleDialog dlg(this); // Parent is the floating window
    dlg.setWindowTitle("Modal with Parent");
    dlg.exec();
}

// Create a non-modal child window with the floating window as parent
void SecondWindow::nonModalWithParent()
{
    SimpleDialog *dlg = new SimpleDialog(this);
    dlg->setWindowTitle("Non-Modal with Parent");
    dlg->setAttribute(Qt::WA_DeleteOnClose);
    dlg->show();
}

Notes:

• A floating window can act as a parent for child windows.
• Both modal (exec()) and non-modal (show()) windows are supported.
• Child windows follow standard Qt parent-child relationships and lifecycle management.

---

Project Configuration

# FloatWindowChilds.pro
QT += core gui widgets ohosextras
SOURCES += main.cpp

Key Configuration Notes:

• The ohosextras module must be added to use floating window APIs.

---

Application Scenarios

Applicable Scenarios

• Floating tools: Calculators, notepads, and other small utilities
• System notifications: Message alerts, status display windows
• Auxiliary functions: Screen recording controls, volume adjustment panels
• Multi-task collaboration: Functional windows that need to be displayed alongside other apps

---

Basic Usage Pattern

void createFloatingWindow()
{
    // 1. Create window instance
    YourWindow *window = new YourWindow();

    // 2. Set as floating window
    QtOhosExtras::setShowWindowAsFloatWindowHint(window, true);

    // 3. Configure window properties
    window->setAttribute(Qt::WA_DeleteOnClose);
    window->resize(desiredWidth, desiredHeight);

    // 4. Show the window
    window->show();
}

---

Compilation and Testing

Compilation Steps

qmake FloatWindowChilds.pro && make

---

Testing and Verification

1. Launch the application: The main window displays normally.
2. Click the Open OHOS floating window button.
3. Verify that the floating window appears in floating mode and can overlay other applications.
4. Create child windows within the floating window and verify modal and non-modal behavior.
5. Verify that the floating window supports drag-and-drop movement.

---

Development Notes

Floating Window Permissions

When using the floating window feature, pay attention to HarmonyOS permission requirements:

• Floating Window Permission: The application must request the permission to display floating windows.
• System-level Permissions: Some scenarios may require system-level permissions.
• User Authorization: Manual user authorization is required on first use.

---

Related Resources

• [1] - Qt QWidget Class Reference Documentation