Qt WindowState 枚举详细解析

最新推荐文章于 2025-12-07 18:35:29 发布

原创最新推荐文章于 2025-12-07 18:35:29 发布 · 244 阅读

8 ·

CC 4.0 BY-SA版权

版权所属：https://xuemingde.com

文章标签：

#qt #开发语言

Qt 专栏收录该内容

27 篇文章

订阅专栏

Qt `WindowState` 枚举详细解析

Qt::WindowState 是 Qt 中用于表示 顶级窗口当前显示状态 的核心枚举，定义了窗口的核心视觉状态（正常、最小化、最大化、全屏）及激活状态，支持通过位掩码组合（部分状态互斥），核心用于控制窗口显示行为（如最大化窗口、切换全屏）和判断窗口当前状态（如判断是否最小化）。

该枚举与 WindowType（窗口类型）的区别：WindowType 定义窗口“本质类型”（如窗口/对话框），WindowState 定义窗口“当前状态”（如是否最大化），二者可独立组合使用。

一、核心概念铺垫

状态特性：
- 基础状态（WindowMinimized/WindowMaximized/WindowFullScreen）互斥：窗口不能同时处于“最小化”和“最大化”状态，Qt 会自动处理冲突（如同时设置则以最后一个有效状态为准）。
- 辅助状态（WindowActive）可与基础状态组合：表示窗口在“最大化/全屏”等基础状态下，同时处于“激活状态”（前台、有焦点）。
核心操作接口：
- 获取当前状态：QWidget::windowState()（返回 Qt::WindowStates，支持位组合）。
- 设置窗口状态：QWidget::setWindowState(Qt::WindowStates state)（直接切换状态，无需调用 show()）。
- 状态变化信号：QWidget::windowStateChanged(Qt::WindowStates oldState, Qt::WindowStates newState)（Qt 5.15+ 支持，监听状态变化）。

二、枚举值逐一解析

枚举值	十六进制值	核心含义与行为	关键说明
`WindowNoState`	`0x00000000`	【默认状态】正常窗口状态：窗口保持自定义大小和位置，无最小化/最大化/全屏效果。	✅ 可自由拖动、缩放（依赖窗口边框）； ✅ 是窗口初始状态，也是退出其他状态后的恢复状态。
`WindowMinimized`	`0x00000001`	最小化状态：窗口缩小到系统任务栏（Windows）/程序坞（macOS），仅保留任务栏图标。	❌ 窗口界面不可见； ✅ 点击任务栏/程序坞图标可恢复为 `WindowNoState` 或之前的状态。
`WindowMaximized`	`0x00000002`	最大化状态：窗口扩大到占满整个屏幕（但保留系统任务栏、菜单栏）。	❌ 不可拖动、缩放（边框失效）； ✅ 点击标题栏“还原”按钮可恢复为 `WindowNoState`。
`WindowFullScreen`	`0x00000004`	全屏状态：窗口覆盖整个屏幕（隐藏系统任务栏、菜单栏、窗口标题栏）。	❌ 无标题栏、无边框； ✅ 常用于视频播放器、游戏等场景； ⚠️ 与 `WindowMaximized` 区别：是否覆盖系统任务栏。
`WindowActive`	`0x00000008`	激活状态：窗口处于前台（获得焦点），可接收键盘/鼠标事件。	✅ 辅助状态，可与其他基础状态组合（如 `WindowMaximized

三、关键使用场景与示例

1. 设置窗口状态（最大化、全屏、恢复正常）

// 1. 最大化窗口
this->setWindowState(Qt::WindowMaximized);

// 2. 切换全屏（隐藏标题栏，更纯粹的全屏）
this->setWindowState(Qt::WindowFullScreen);
this->setWindowFlags(this->windowFlags() | Qt::FramelessWindowHint); // 可选：隐藏标题栏

// 3. 最小化窗口
this->setWindowState(Qt::WindowMinimized);

// 4. 恢复正常状态（退出最大化/全屏/最小化）
this->setWindowState(Qt::WindowNoState);
this->setWindowFlags(this->windowFlags() & ~Qt::FramelessWindowHint); // 恢复标题栏

2. 判断窗口当前状态

// 示例：按钮点击时判断状态并切换
void MyWindow::on_toggleFullScreenBtn_clicked()
{
    Qt::WindowStates currentState = this->windowState();
    if (currentState & Qt::WindowFullScreen) {
        // 已全屏，恢复正常状态
        this->setWindowState(Qt::WindowNoState);
        this->setWindowFlags(this->windowFlags() & ~Qt::FramelessWindowHint);
    } else {
        // 未全屏，切换到全屏
        this->setWindowState(Qt::WindowFullScreen);
        this->setWindowFlags(this->windowFlags() | Qt::FramelessWindowHint);
    }
}

// 判断是否最小化
if (this->windowState() & Qt::WindowMinimized) {
    qDebug() << "窗口已最小化，执行唤醒逻辑";
    this->setWindowState(Qt::WindowNoState); // 恢复正常
}

3. 监听窗口状态变化

// Qt 5.15+ 支持 windowStateChanged 信号，低版本需重写 changeEvent
connect(this, &QWidget::windowStateChanged, [=](Qt::WindowStates oldState, Qt::WindowStates newState) {
    if (newState & Qt::WindowMaximized) {
        qDebug() << "窗口从" << oldState << "切换到最大化状态";
    } else if (newState & Qt::WindowFullScreen) {
        qDebug() << "窗口切换到全屏状态";
    } else if (newState & Qt::WindowMinimized) {
        qDebug() << "窗口最小化";
    }
});

// 低版本 Qt（<5.15）：重写 changeEvent 监听状态变化
void MyWindow::changeEvent(QEvent *event)
{
    if (event->type() == QEvent::WindowStateChange) {
        Qt::WindowStates newState = this->windowState();
        // 处理状态变化逻辑（同上）
    }
    QWidget::changeEvent(event);
}

4. 组合状态（激活+最大化）

// 设置窗口“最大化且激活”（前台显示）
this->setWindowState(Qt::WindowMaximized | Qt::WindowActive);

// 判断窗口是否“激活且全屏”
if ((this->windowState() & (Qt::WindowFullScreen | Qt::WindowActive)) == (Qt::WindowFullScreen | Qt::WindowActive)) {
    qDebug() << "全屏且处于激活状态";
}

四、注意事项

状态互斥性：
- 基础状态（WindowMinimized/WindowMaximized/WindowFullScreen）不能同时生效，Qt 会自动取“最后设置的有效状态”。
- 示例：setWindowState(Qt::WindowMinimized | Qt::WindowMaximized) 最终生效为 WindowMaximized（后设置的状态覆盖前一个）。

WindowMaximized 与 WindowFullScreen 区别（关键！）：

特性	`WindowMaximized`（最大化）	`WindowFullScreen`（全屏）
系统任务栏/菜单栏	保留（不覆盖）	隐藏（完全覆盖）
窗口标题栏/边框	保留	默认保留（需手动隐藏）
适用场景	普通软件窗口（如浏览器）	视频播放器、游戏、编辑器

激活状态（WindowActive）的独立性：
- WindowActive 仅表示窗口“是否有焦点”，不影响基础状态（如最大化的窗口可以是激活或非激活）。
- 窗口失去焦点时，WindowActive 状态会自动移除（无需手动设置）。
设置状态后无需 show()：
- 调用 setWindowState() 后，状态立即生效，无需再次调用 show() 或 hide()。
全屏时隐藏标题栏：
- 默认 WindowFullScreen 会保留标题栏，若需“纯全屏”（无任何系统控件），需配合 FramelessWindowHint 隐藏标题栏（如示例2）。