QC++ / Qt 学习之路

主窗口框架 QMainWindow

用 QMainWindow 搭建菜单栏工具栏状态栏与停靠窗口

入门第 23 / 48 章第三篇 · Qt 入门

#为什么用 QMainWindow

第 2 章提到过:QMainWindow 是为"正经应用程序"准备的窗口骨架。它内部预置了一套标准结构,你往里填内容即可:

QMainWindow 主窗口分区自带菜单栏、工具栏、停靠区、中央部件与状态栏的标准窗口骨架窗口标题栏(由窗口系统绘制)文件 编辑 视图 帮助工具栏按钮(可拖动停靠)可停靠面板QDockWidget可拖出浮动centralWidget中央部件(唯一,必须设置)业务界面就放在这里QStatusBar 就绪QMenuBar菜单栏(顶部)QToolBar工具栏(可拖动)QWidget中央部件(唯一)QStatusBar状态栏(底部)QDockWidget可停靠 · 可浮动用法:setCentralWidget(w) / addDockWidget(Qt::LeftDockWidgetArea, dock) / menuBar()->addMenu(...)
QMainWindow 的标准分区
Text
┌─────────────────────────────────────┐
│ 菜单栏 QMenuBar                     │
├─────────────────────────────────────┤
│ 工具栏 QToolBar(可拖动,可多条)   │
├────────┬───────────────────┬────────┤
│ 停靠   │     中央部件       │ 停靠   │
│ Dock   │  Central Widget   │ Dock   │
├────────┴───────────────────┴────────┤
│ 状态栏 QStatusBar                   │
└─────────────────────────────────────┘

每一部分都是可选的。关键规则是:中央部件必须设置(setCentralWidget()),否则窗口中央会出现一块空白并可能打印警告;它是唯一不能省略的区域。

与之相比,第 2 章用的 QWidget 是"裸窗口",什么都得自己摆。选择标准很简单:需要菜单/工具栏/状态栏/多面板 → QMainWindow;只是个小工具窗口或自定义控件 → QWidget。

对比:Java Swing 里 JFrame 需要你手动 setJMenuBar()、add(toolbar, BorderLayout.NORTH),各部件的布局要自己用 BorderLayout 拼装;Qt 的 QMainWindow 把这些区域固定下来了,你不用操心它们怎么排布,只需填充。这与 Electron/VS Code 那种"菜单栏 + 侧边栏 + 编辑区 + 状态栏"的应用骨架是同一个模型——事实上 Qt 的 QMainWindow 就是这类经典桌面应用布局的标准化。

#QAction:把"一个命令"抽象成对象

在讲菜单之前必须先讲 QAction,因为它是菜单、工具栏、快捷键三者的共同载体。

一个 QAction 代表"用户可以执行的一个命令",它打包了:显示文本、图标、快捷键、提示(tooltip/statusTip)、是否可用(enabled)、是否可选中(checkable)。同一个 QAction 可以同时放进菜单和工具栏,它们共享同一份状态——禁用它,菜单项和工具栏按钮同时变灰。这就是 Qt 避免"菜单和工具栏状态不同步"的办法。

C++
auto *openAct = new QAction(QIcon(":/icons/open.png"), tr("打开(&O)..."), this);
openAct->setShortcut(QKeySequence::Open);          // 标准快捷键(Ctrl+O / Cmd+O)
openAct->setStatusTip(tr("打开一个已有的文件"));
openAct->setToolTip(tr("打开文件"));

connect(openAct, &QAction::triggered, this, &MainWindow::openFile);
// 注意信号是 triggered(bool checked = false),一般用无参 Lambda:
connect(openAct, &QAction::triggered, this, [this]() { openFile(); });

要点:

  • 文本中的 & 定义助记符:tr("打开(&O)") 表示 Alt+O;显示时 & 不出现。写 && 才显示字面 &。
  • 用 QKeySequence::Open 等标准枚举,Qt 会自动映射到各平台的正确组合键(macOS 用 Cmd+O,Windows/Linux 用 Ctrl+O)。也可以写 QKeySequence("Ctrl+Shift+S")。
  • setShortcut() 之外还有 setShortcutContext(Qt::WindowShortcut / ApplicationShortcut / WidgetShortcut),控制快捷键在什么范围内生效。默认是 WindowShortcut(当前窗口激活时)。
  • 可勾选的 Action:setCheckable(true) 后它会变成带对勾的菜单项 / 可按下保持的工具按钮,信号用 toggled(bool) 或 triggered(bool)。适合"显示行号""自动换行"这类开关。
  • QActionGroup 用于让一组 Action 互斥(如"左对齐/居中/右对齐")。

#菜单栏:QMenuBar / QMenu

C++
// 在 QMainWindow 的构造函数中
QMenu *fileMenu = menuBar()->addMenu(tr("文件(&F)"));
fileMenu->addAction(m_newAct);
fileMenu->addAction(m_openAct);
fileMenu->addSeparator();                 // 分隔线
fileMenu->addAction(m_saveAct);
fileMenu->addAction(m_saveAsAct);
fileMenu->addSeparator();

QMenu *recentMenu = fileMenu->addMenu(tr("最近打开"));   // 子菜单
recentMenu->addAction(tr("无"));

fileMenu->addSeparator();
fileMenu->addAction(m_exitAct);

QMenu *editMenu = menuBar()->addMenu(tr("编辑(&E)"));
QMenu *helpMenu = menuBar()->addMenu(tr("帮助(&H)"));
helpMenu->addAction(m_aboutAct);

// ---- QToolBar:复用同一批 Action ----
QToolBar *fileToolBar = addToolBar(tr("文件"));
fileToolBar->addAction(m_newAct);      // 复用同一个 Action!
fileToolBar->addAction(m_openAct);
fileToolBar->addSeparator();

QToolBar *editToolBar = addToolBar(tr("编辑"));
editToolBar->addAction(m_cutAct);
editToolBar->addWidget(m_zoomSpin);    // 工具栏里可以放任意控件

// 常用设置
fileToolBar->setMovable(true);                        // 允许拖动(默认 true)
fileToolBar->setAllowedAreas(Qt::TopToolBarArea | Qt::BottomToolBarArea);
fileToolBar->setToolButtonStyle(Qt::ToolButtonTextUnderIcon);  // 图标+文字
fileToolBar->setIconSize(QSize(24, 24));

menuBar() 返回窗口自带的菜单栏(Qt 会自动创建)。注意 macOS 的特殊性:Qt 会把菜单栏移到屏幕顶部(系统菜单栏),这是平台原生行为,Qt 6 中可以用 menuBar()->setNativeMenuBar(false) 强制留在窗口内。菜单还可以做右键上下文菜单:重写 contextMenuEvent(),或者更简单地 widget->setContextMenuPolicy(Qt::ActionsContextMenu) 后把 Action 加到该 widget 上。

工具栏默认可拖动、可浮动,还能被用户隐藏——这一点与很多框架"工具栏只能放按钮且位置固定"的做法不同,Qt 的工具栏完全可以放下搜索框、缩放比例、字体选择器等任意控件。但要注意:Qt 不会自动保存工具栏与停靠窗口的布局状态,需要你配合 QSettings 手动调用 saveState() / restoreState(),否则用户下次打开程序时布局会复位。

#状态栏与停靠窗口

C++
statusBar()->showMessage(tr("就绪"), 3000);      // 显示 3 秒后自动清空

// 常驻部件(不会被临时消息覆盖)
m_posLabel = new QLabel(tr("行 1, 列 1"));
statusBar()->addWidget(m_posLabel);              // 左侧
statusBar()->addPermanentWidget(new QLabel("UTF-8"));  // 右侧永久区
// statusBar()->removeWidget(m_posLabel);        // 移除

// ---- QDockWidget:可停靠、可浮动的面板 ----
QDockWidget *dock = new QDockWidget(tr("项目结构"), this);
dock->setAllowedAreas(Qt::LeftDockWidgetArea | Qt::RightDockWidgetArea);
dock->setWidget(m_treeWidget);                  // 内部放任意控件
addDockWidget(Qt::LeftDockWidgetArea, dock);

m_viewMenu->addAction(dock->toggleViewAction());  // 用 Action 控制显示/隐藏

// 两个 dock 的排布
addDockWidget(Qt::LeftDockWidgetArea, dock2);
splitDockWidget(dock, dock2, Qt::Vertical);      // 上下拆分
tabifyDockWidget(dock, dock2);                   // 合并成标签页
setDockNestingEnabled(true);                     // 允许更复杂的嵌套

状态栏要区分两类内容:showMessage() 显示的是临时消息(第二参数为毫秒,0 表示一直显示到被下一条消息或 clearMessage() 替换);addWidget() / addPermanentWidget() 放的部件是常驻的,后者位于右端且不会被临时消息挤走,适合放编码、缩放比例、行列号这类长期信息。

QDockWidget 用户可以拖动、浮动、关闭。dock->toggleViewAction() 返回一个现成的"显示/隐藏"Action,直接加到"视图"菜单即可,非常省事。

#资源系统:qrc 与图标

Qt 提供资源编译机制:把图片、翻译文件等打包进可执行文件,避免"程序找不到图标"的部署问题。

resources.qrc:

Text
<RCC>
    <qresource prefix="/icons">
        <file>icons/open.png</file>
        <file>icons/save.png</file>
        <file>icons/exit.png</file>
    </qresource>
    <qresource prefix="/translations">
        <file>app_zh_CN.qm</file>
    </qresource>
</RCC>

CMake 中把 qrc 加入源文件(并开启 CMAKE_AUTORCC):

CMake
add_executable(MainDemo
    main.cpp
    mainwindow.cpp
    mainwindow.h
    resources.qrc
)

代码里用 :/ 前缀引用,规则是 :/prefix/path——prefix 取自 <qresource prefix="...">,path 是 <file> 里写的相对路径(相对于 .qrc 文件所在目录):

C++
QAction *openAct = new QAction(QIcon(":/icons/open.png"), tr("打开"), this);
QPixmap logo(":/icons/logo.png");
QFile cfg(":/data/default.json");       // 读资源里的文本文件

Qt 6 提供了更现代的 qt_add_resources 与 QT_RESOURCE 机制,但 .qrc + AUTORCC 依然是最通用、最简单的做法。

对比:Web 前端的图片要么放 CDN 要么被打包器(webpack/Vite)内联成 base64;Java 用 getResourceAsStream() 从 jar 里读。Qt 的 qrc 与 Java 的做法最像——资源编进二进制,路径用虚拟前缀访问,部署时零依赖。

把上面这些区域想象成"五个插槽",你的工作就是往每个插槽里填东西,唯一必须填的是中央部件。若某个区域暂时没有内容,不要创建它——例如没有菜单就不要调 menuBar() 添加空菜单,Qt 会按需惰性创建。

关于图标:Qt 6 建议使用 SVG 图标(缩放不失真),需要链接 Qt6::Svg。另外 Qt 提供了 QStyle::standardIcon(QStyle::SP_DialogOpenButton) 这样的内置图标,不想找素材时可以直接用系统风格图标,保证与平台观感一致。

#完整示例

C++
// mainwindow.h
#pragma once
#include <QMainWindow>
class QLabel;
class QTextEdit;
class QTreeWidget;

class MainWindow : public QMainWindow
{
    Q_OBJECT
public:
    explicit MainWindow(QWidget *parent = nullptr);
private slots:
    void openFile();
    void about();
    void updateStatusBar();
private:
    void createActions();
    void createMenus();
    void createToolBars();
    void createStatusBar();
    void createDockWindows();

    QTextEdit   *m_editor;
    QTreeWidget *m_tree;
    QLabel      *m_posLabel;

    QAction *m_openAct;
    QAction *m_saveAct;
    QAction *m_exitAct;
    QAction *m_aboutAct;
    QAction *m_wrapAct;
};

// ---- mainwindow.cpp ----
#include "mainwindow.h"
#include <QAction>
#include <QMenuBar>
#include <QToolBar>
#include <QStatusBar>
#include <QTextEdit>
#include <QTreeWidget>
#include <QDockWidget>
#include <QLabel>
#include <QFileDialog>
#include <QMessageBox>
#include <QFile>
#include <QTextStream>
#include <QIcon>
#include <QDebug>

MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent)
{
    m_editor = new QTextEdit(this);
    m_editor->setMinimumWidth(400);
    setCentralWidget(m_editor);            // 中央部件:必须设置

    createActions();
    createMenus();
    createToolBars();
    createStatusBar();
    createDockWindows();

    setWindowTitle(tr("简易文本编辑器"));
    resize(800, 600);
    connect(m_editor, &QTextEdit::textChanged, this, &MainWindow::updateStatusBar);
}

void MainWindow::createActions()
{
    m_openAct = new QAction(QIcon(":/icons/open.png"), tr("打开(&O)..."), this);
    m_openAct->setShortcut(QKeySequence::Open);
    m_openAct->setStatusTip(tr("打开一个已有的文件"));
    connect(m_openAct, &QAction::triggered, this, &MainWindow::openFile);

    m_saveAct = new QAction(QIcon(":/icons/save.png"), tr("保存(&S)"), this);
    m_saveAct->setShortcut(QKeySequence::Save);

    m_exitAct = new QAction(tr("退出(&Q)"), this);
    m_exitAct->setShortcut(QKeySequence::Quit);
    connect(m_exitAct, &QAction::triggered, this, &QWidget::close);

    m_aboutAct = new QAction(tr("关于"), this);
    connect(m_aboutAct, &QAction::triggered, this, &MainWindow::about);

    m_wrapAct = new QAction(tr("自动换行"), this);
    m_wrapAct->setCheckable(true);
    m_wrapAct->setChecked(true);
    connect(m_wrapAct, &QAction::toggled, this, [this](bool on) {
        m_editor->setLineWrapMode(on ? QTextEdit::WidgetWidth : QTextEdit::NoWrap);
    });
}

void MainWindow::createMenus()
{
    QMenu *file = menuBar()->addMenu(tr("文件(&F)"));
    file->addAction(m_openAct);
    file->addAction(m_saveAct);
    file->addSeparator();
    file->addAction(m_exitAct);

    QMenu *view = menuBar()->addMenu(tr("视图(&V)"));
    view->addAction(m_wrapAct);

    QMenu *help = menuBar()->addMenu(tr("帮助(&H)"));
    help->addAction(m_aboutAct);
}

void MainWindow::createToolBars()
{
    QToolBar *fileTb = addToolBar(tr("文件"));
    fileTb->addAction(m_openAct);
    fileTb->addAction(m_saveAct);
    fileTb->setToolButtonStyle(Qt::ToolButtonTextBesideIcon);

    QToolBar *viewTb = addToolBar(tr("视图"));
    viewTb->addAction(m_wrapAct);
}

void MainWindow::createStatusBar()
{
    statusBar()->showMessage(tr("就绪"));
    m_posLabel = new QLabel(tr("字符数:0"));
    statusBar()->addPermanentWidget(m_posLabel);
}

void MainWindow::createDockWindows()
{
    QDockWidget *dock = new QDockWidget(tr("大纲"), this);
    dock->setAllowedAreas(Qt::LeftDockWidgetArea | Qt::RightDockWidgetArea);

    m_tree = new QTreeWidget(dock);
    m_tree->setHeaderLabel(tr("结构"));
    m_tree->addTopLevelItem(new QTreeWidgetItem(m_tree, {tr("第一章")}));
    m_tree->addTopLevelItem(new QTreeWidgetItem(m_tree, {tr("第二章")}));
    dock->setWidget(m_tree);

    addDockWidget(Qt::LeftDockWidgetArea, dock);
    menuBar()->addMenu(tr("视图(&V)"))->addAction(dock->toggleViewAction());
}

void MainWindow::openFile()
{
    const QString path = QFileDialog::getOpenFileName(this, tr("打开文件"), "",
                                                      tr("文本文件 (*.txt *.md);;所有文件 (*)"));
    if (path.isEmpty())
        return;
    QFile f(path);
    if (!f.open(QIODevice::ReadOnly | QIODevice::Text)) {
        QMessageBox::warning(this, tr("错误"), f.errorString());
        return;
    }
    QTextStream in(&f);
    in.setEncoding(QStringConverter::Utf8);
    m_editor->setPlainText(in.readAll());
    statusBar()->showMessage(tr("已打开 %1").arg(path), 5000);
}

void MainWindow::about()
{
    QMessageBox::about(this, tr("关于"),
                       tr("简易文本编辑器\nQt 6 示例程序"));
}

void MainWindow::updateStatusBar()
{
    m_posLabel->setText(tr("字符数:%1").arg(m_editor->toPlainText().size()));
}

// ---- main.cpp ----
#include <QApplication>
#include "mainwindow.h"

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);
    MainWindow w;
    w.show();
    return app.exec();
}

把 resources.qrc 与上述文件一起加入 CMake 即可构建。注意 QFileDialog::getOpenFileName 也是同步阻塞的(内部嵌套事件循环),返回值即用户选择,未选择时为空串——Qt 不用异常,靠返回值判断。

#小结

  • QMainWindow 提供菜单栏、工具栏、停靠区、中央部件、状态栏的标准骨架;中央部件必须设置。
  • QAction 是命令的抽象,同一个 Action 可同时用于菜单与工具栏,状态自动同步;& 定义助记符,QKeySequence::Open 自动适配平台。
  • menuBar() / addToolBar() / statusBar() / addDockWidget() 是四个主要入口;状态栏的 showMessage 是临时的,addPermanentWidget 是常驻的。
  • QDockWidget 可停靠浮动,toggleViewAction() 直接给出显隐开关。
  • .qrc 资源编译进可执行文件,用 :/prefix/path 访问;配合 CMAKE_AUTORCC。

#练习

  1. 在本章示例基础上添加"编辑"菜单:撤销/重做/剪切/复制/粘贴五个标准 Action,复用 QTextEdit 自带的槽(提示:connect(m_undoAct, &QAction::triggered, m_editor, &QTextEdit::undo);),并给它们设置 QKeySequence::Undo 等标准快捷键。
  2. 增加第二个 QDockWidget(放在右侧),内容为"属性面板";用 tabifyDockWidget 把它与"大纲"合并成标签页,再用 splitDockWidget 改成上下拆分,体会两者的差别。
  3. 用 QSettings 在关闭时保存窗口的 geometry() 与 saveState(),启动时恢复;验证工具栏位置与停靠窗口布局是否被记住。
  4. 制作一个 resources.qrc,放入 3 个图标(或用 QStyle::standardIcon 代替),让菜单项与工具栏按钮都显示图标;再实现"视图"菜单下的工具栏显隐开关,观察 Action 的 enabled 状态如何在菜单与工具栏间同步。
我的学习笔记笔记总览
笔记保存在本机浏览器(localStorage),换设备或清理缓存会丢失;重要内容请点「导出全部笔记」存成 .md 文件。