English 中文

Qt for HarmonyOS: Development Guide for Full-Screen Main Window Launch

Introduction

This document details how to implement the full-screen / maximized launch functionality for the main window in Qt for HarmonyOS applications.

The HarmonyOS platform has specific support strategies for window display modes. Qt provides developers with the ability to create full-screen main windows through standard window state APIs.

This guide elaborates on the usage, implementation mechanism of this feature, and provides complete code examples.

Functional Architecture Overview

When using Qt's full-screen main window functionality on the HarmonyOS platform, it is necessary to understand the following architectural principles.

Application Startup Process

Window creation for Qt for HarmonyOS applications follows a specific startup flow:

Main Application Launch (First Window)
- Displayed in standard window mode
- Cannot be directly full-screen due to HarmonyOS system startup mechanism restrictions
Subsequent Window Creation
- Full support for full-screen / maximized mode launch
- Complete window state control capabilities

Qt API Details

showFullScreen() Function

void QWidget::showFullScreen();

This function is a standard Qt full-screen display API and is fully supported on the HarmonyOS platform.

Functional Mechanism

On the HarmonyOS platform, the behavior characteristics of showFullScreen() are as follows:

Instant Full-Screen: The window is displayed in full-screen mode immediately after creation
State Persistence: The window state is correctly set to full-screen
System Integration: Compatible with HarmonyOS native full-screen mechanisms
Reversible Operation: Supports switching back to other window states

Related Window State APIs

API Function	Function Description	Usage Scenarios
showFullScreen()	Display window in full-screen mode	Immersive experiences, games, media playback
showMaximized()	Display window in maximized mode	Maximized display with title bar retained
showNormal()	Normal window mode	Standard application windows
showMinimized()	Minimize window	Window hidden to background

Development Implementation

Core Implementation Principle

The key to implementing the full-screen main window functionality lies in:

Dynamic window creation
Calling showFullScreen() immediately after creation

Key Code Examples

1. Dynamically Create Full-Screen Main Window

// mainwindow.cpp
void MainWindow::on_pushButton_clicked()
{
    // Create a new window instance
    CustomWidget *widget = new CustomWidget();

    // Key: Call showFullScreen() to achieve full-screen launch
    widget->showFullScreen();
}

Notes:

Create a new window through user interaction (button click)
The newly created window can be displayed in full-screen directly
showFullScreen() is the core API for implementing full-screen

2. Basic Structure of Full-Screen Window

// customwidget.cpp
CustomWidget::CustomWidget(QWidget *parent)
    : QWidget(parent)
{
    QLabel *label = new QLabel("2nd Main Window", this);

    QVBoxLayout *layout = new QVBoxLayout(this);
    layout->addWidget(label);
    setLayout(layout);

    // Automatically release memory when the window is closed
    setAttribute(Qt::WA_DeleteOnClose);
}

Notes:

Inherits from QWidget and can serve as an independent main window
Layout and content can be customized according to actual requirements
Use Qt::WA_DeleteOnClose to ensure resource release

3. Application Entry (First Window in Standard Mode)

// main.cpp
int main(int argc, char *argv[])
{
    QApplication app(argc, argv);

    // First window: Can only launch in standard mode
    MainWindow mainWindow;
    mainWindow.show();

    return app.exec();
}

Notes:

The first window of the application is restricted by the HarmonyOS system
The first window cannot be full-screen directly
Subsequent windows can be created through user interaction and displayed in full-screen

Application Scenarios

Applicable Scenarios

Media playback: Immersive experiences for video players, image browsers
Game applications: Full-screen game interfaces
Presentation tools: Slides, demonstration-type applications
Professional software: Design, editing applications requiring maximum display area

Basic Usage Pattern

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

    // 2. Initialize window content
    window->setupContent();

    // 3. Display in full-screen mode
    window->showFullScreen();
}

Compilation and Testing

Compilation Steps

qmake testMainWindowFullScreen.pro && make

Testing and Verification

Launch the application: The first window is displayed in standard mode
Click the "Open Main Window" button
Verify if the new window is displayed in full-screen mode
Test if window state switching works properly

Development Notes

Window Display Mode Restrictions

Window Type	Full-Screen Launch Supported	Description
Application startup first window	No	Restricted by HarmonyOS startup mechanism
Dynamically created window	Yes	Qt window state APIs work normally

Recommended Solution:

Use standard mode for the first window
Create subsequent windows through user operations and call showFullScreen()

Related Resources

[1] - HarmonyOS Native Window Management Related Documentation
[2] - Qt QWidget Class Reference Documentation (Window State APIs)