主窗口框架 QMainWindow
用 QMainWindow 搭建菜单栏工具栏状态栏与停靠窗口
#为什么用 QMainWindow
第 2 章提到过:QMainWindow 是为"正经应用程序"准备的窗口骨架。它内部预置了一套标准结构,你往里填内容即可:
┌─────────────────────────────────────┐
│ 菜单栏 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 避免"菜单和工具栏状态不同步"的办法。
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
// 在 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(),否则用户下次打开程序时布局会复位。
#状态栏与停靠窗口
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:
<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):
add_executable(MainDemo
main.cpp
mainwindow.cpp
mainwindow.h
resources.qrc
)代码里用 :/ 前缀引用,规则是 :/prefix/path——prefix 取自 <qresource prefix="...">,path 是 <file> 里写的相对路径(相对于 .qrc 文件所在目录):
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) 这样的内置图标,不想找素材时可以直接用系统风格图标,保证与平台观感一致。
#完整示例
// 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。
#练习
- 在本章示例基础上添加"编辑"菜单:撤销/重做/剪切/复制/粘贴五个标准 Action,复用
QTextEdit自带的槽(提示:connect(m_undoAct, &QAction::triggered, m_editor, &QTextEdit::undo);),并给它们设置QKeySequence::Undo等标准快捷键。 - 增加第二个
QDockWidget(放在右侧),内容为"属性面板";用tabifyDockWidget把它与"大纲"合并成标签页,再用splitDockWidget改成上下拆分,体会两者的差别。 - 用
QSettings在关闭时保存窗口的geometry()与saveState(),启动时恢复;验证工具栏位置与停靠窗口布局是否被记住。 - 制作一个
resources.qrc,放入 3 个图标(或用QStyle::standardIcon代替),让菜单项与工具栏按钮都显示图标;再实现"视图"菜单下的工具栏显隐开关,观察 Action 的 enabled 状态如何在菜单与工具栏间同步。