对话框与交互
掌握模态/非模态对话框与标准对话框,写出可校验的自定义对话框
#对话框的本质:一次"阻塞的问答"
普通窗口(QMainWindow/QWidget)是并行的:你打开它,主窗口还能照常点。对话框(QDialog)通常是串行的:弹出后你必须先回答它,程序流程才继续。这个"回答"就是对话框的结果码(Accepted 或 Rejected),而"必须等待"这个约束就是模态。
把对话框理解成函数调用会更准确:它有输入(初始数据)、有返回值(结果码)、调用期间调用方暂停。想通这一点,你就不会纠结"为什么 exec() 之后代码才往下走",也不会试图在非模态对话框上强行同步取结果。
理解这一点,exec() 的很多行为就顺理成章了。很多初学者以为 exec() 会卡死主线程——它确实会阻塞调用它的那段代码,但不会冻结界面,因为 exec() 内部开启了一个嵌套的局部事件循环,鼠标、键盘、重绘事件照常被处理。所以对话框能动、能输入、能拖拽,只是主窗口被"禁用"了。
| 维度 | 模态(Modal) | 非模态(Modeless) |
|---|---|---|
| 显示方式 | exec() 或 open() | show() |
| 是否阻塞代码 | 是 | 否 |
| 事件循环 | 新建嵌套循环 | 复用主循环 |
| 生命周期 | 常在栈上,if (dlg.exec() == QDialog::Accepted) | 常在堆上,需自行管理释放 |
| 典型用途 | 打开文件、确认删除、登录框 | 查找替换、工具面板、日志窗口 |
#三种模态级别
QDialog 的 modal 属性配合 windowModality 决定"禁用到什么程度":
Qt::NonModal—— 非模态,不阻塞任何窗口。Qt::WindowModal—— 只阻塞父窗口及其子窗口,同一应用的其他独立窗口仍可操作。Qt::ApplicationModal—— 阻塞整个应用的所有窗口。这是exec()的默认值。
推荐在非 exec() 场景使用 open():它是异步模态——窗口显示为模态,但代码不阻塞,结果通过 finished(int) 信号返回。这避免了嵌套事件循环带来的重入问题(例如在 exec() 期间又收到一个网络回调,弹出了第二个对话框)。
#include <QApplication>
#include <QMainWindow>
#include <QPushButton>
#include <QDialog>
#include <QVBoxLayout>
#include <QDebug>
// 方式一:栈上模态,最经典
static void modalDemo(QWidget *parent)
{
QDialog dlg(parent);
dlg.setWindowTitle("设置");
auto *lay = new QVBoxLayout(&dlg);
lay->addWidget(new QPushButton("确定", &dlg));
int ret = dlg.exec(); // 阻塞,直到用户关闭
qDebug() << "结果码:" << ret; // QDialog::Accepted(1) / Rejected(0)
}
// 方式二:异步模态,不阻塞调用方
static void openDemo(QWidget *parent)
{
auto *dlg = new QDialog(parent);
dlg->setAttribute(Qt::WA_DeleteOnClose); // 关闭时自动释放
dlg->setWindowModality(Qt::WindowModal);
QObject::connect(dlg, &QDialog::finished,
dlg, [](int result) { qDebug() << "异步结果:" << result; });
dlg->open(); // 立即返回
}
// 方式三:非模态
static void modelessDemo(QWidget *parent)
{
auto *dlg = new QDialog(parent);
dlg->setAttribute(Qt::WA_DeleteOnClose);
dlg->show(); // 立即返回,主窗口仍可用
}非模态对话框最大的坑是内存与重复弹出。务必设置 Qt::WA_DeleteOnClose,否则关闭只是隐藏,内存泄漏;如果只允许一个实例,用 findChild 或保存指针判断后 raise() + activateWindow()。
#快速问答:QMessageBox
QMessageBox 提供了一组静态函数,覆盖 95% 的场景,一行代码搞定。它们的返回值是 QMessageBox::StandardButton,可与 QMessageBox::Ok、Yes、Save 等比较。
| 静态方法 | 用途 | 默认按钮 |
|---|---|---|
information() | 操作成功的提示 | Ok |
warning() | 警告但可继续 | Ok |
critical() | 严重错误 | Ok |
question() | 需要用户决策 | Yes / No |
about() | 关于对话框,无图标按钮 | 无返回值 |
#include <QMessageBox>
#include <QPushButton>
void messageDemo(QWidget *parent)
{
// 提问:默认是 No,按 Esc 也是 No —— 危险操作必须用这个默认
auto ret = QMessageBox::question(
parent,
"确认删除",
"确定要删除这 3 个文件吗?此操作不可撤销。",
QMessageBox::Yes | QMessageBox::No,
QMessageBox::No);
if (ret == QMessageBox::Yes) {
// ...执行删除
}
// 三选一保存提示
auto r2 = QMessageBox::warning(
parent, "未保存的更改",
"文档已修改,是否保存?",
QMessageBox::Save | QMessageBox::Discard | QMessageBox::Cancel,
QMessageBox::Save);
if (r2 == QMessageBox::Cancel) {
return; // 用户放弃,什么都不做
}
// 详细错误:用 setDetailedText 折叠技术细节
QMessageBox box(QMessageBox::Critical, "连接失败",
"无法连接到服务器。", QMessageBox::Ok, parent);
box.setDetailedText("SocketError #3\nhost=192.168.1.10:8080\ntimeout=3000ms");
box.exec();
}设计要点:危险操作的默认按钮必须是"取消"。用户习惯性按 Enter 或 Esc,question() 的最后一个参数就是默认按钮,把它设成安全选项可以救命。
#输入与文件:QInputDialog / QFileDialog
QInputDialog 同样以静态函数为主,适合"要一个值"的场景。它比自己搭一个对话框快得多,但可定制性差——需要复杂校验时就应该自定义对话框。
#include <QInputDialog>
#include <QFileDialog>
#include <QLineEdit>
#include <QColorDialog>
#include <QFontDialog>
#include <QDebug>
void inputDemo(QWidget *parent)
{
bool ok = false;
// 文本:第四个参数是回显模式,密码用 QLineEdit::Password
QString name = QInputDialog::getText(parent, "重命名", "新名称:",
QLineEdit::Normal, "未命名", &ok);
if (ok && !name.isEmpty()) {
qDebug() << "重命名为" << name;
}
// 整数:min, max, step
int port = QInputDialog::getInt(parent, "端口", "监听端口:",
8080, 1, 65535, 1, &ok);
if (ok) {
qDebug() << "端口" << port;
}
// 下拉选择
QStringList langs{"C++", "Python", "Rust"};
QString pick = QInputDialog::getItem(parent, "语言", "首选语言:",
langs, 0, false, &ok);
if (ok) {
qDebug() << "选中" << pick;
}
}
void fileDemo(QWidget *parent)
{
// 打开单个文件
QString path = QFileDialog::getOpenFileName(
parent,
"打开项目",
QDir::homePath(), // 起始目录
"文本文件 (*.txt *.md);;C++ 源码 (*.cpp *.h);;所有文件 (*)");
if (path.isEmpty()) {
return; // 用户取消
}
// 保存文件:注意返回的是"用户想存到哪",不会真的写盘
QString save = QFileDialog::getSaveFileName(parent, "导出", "", "JSON (*.json)");
if (!save.isEmpty() && !save.endsWith(".json", Qt::CaseInsensitive)) {
save += ".json"; // 补扩展名,QFileDialog 不负责
}
// 选择目录
QString dir = QFileDialog::getExistingDirectory(parent, "选择工作目录");
}getOpenFileName() 的过滤器语法是 描述 (*.ext1 *.ext2);;描述2 (*.ext3),多个模式用空格分隔,多个过滤器用两个分号分隔——少写一个分号是最常见的 bug。getSaveFileName() 不创建文件,它只返回路径;写入与否由你的 QFile 决定。覆盖提示由对话框负责,但"扩展名补全"需要你自己判断。
颜色与字体对话框同理,Qt 提供了 QColorDialog::getColor() 和 QFontDialog::getFont()。前者有一个实用参数:传 QColorDialog::ShowAlphaChannel 可以启用透明度选择。
#长任务:QProgressDialog
后台处理超过 1 秒就应该给反馈。QProgressDialog 会自动判断任务时长——默认 4 秒内不显示,避免"闪一下"的尴尬。它自带"取消"按钮,连接 canceled() 信号即可中断。
#include <QProgressDialog>
#include <QThread>
bool batchProcess(const QVector<QString> &items, QWidget *parent)
{
QProgressDialog dlg("正在处理文件…", "取消", 0, items.size(), parent);
dlg.setWindowModality(Qt::WindowModal);
dlg.setMinimumDuration(1000); // 1 秒后才显示
dlg.setValue(0);
for (int i = 0; i < items.size(); ++i) {
if (dlg.wasCanceled()) {
return false; // 用户取消
}
// doHeavyWork(items[i]); // 实际工作
QThread::msleep(50); // 演示用,替代耗时操作
dlg.setValue(i + 1);
dlg.setLabelText(QString("正在处理 %1 / %2").arg(i + 1).arg(items.size()));
QCoreApplication::processEvents(); // 手动让界面刷新(仅同步循环时需要)
}
return true;
}注意最后的 processEvents():如果耗时代码跑在主线程(不推荐,但现实很常见),进度条不会更新,因为没有事件循环在跑。更正确的做法是把耗时工作放到 QThread 或 QtConcurrent,通过信号驱动进度条,这样就完全不需要 processEvents()。
#自定义对话框:数据校验与结果码
标准对话框解决不了"要三个字段且互相约束"的场景。自定义对话框的模式非常固定:内部控件 → 校验 → accept() 或保持打开。
// logindialog.h
#include <QDialog>
#include <QLineEdit>
class LoginDialog : public QDialog
{
Q_OBJECT
public:
explicit LoginDialog(QWidget *parent = nullptr);
QString user() const;
QString password() const;
private slots:
void validateAndAccept();
private:
QLineEdit *m_userEdit;
QLineEdit *m_passEdit;
};// logindialog.cpp
#include "logindialog.h"
#include <QFormLayout>
#include <QDialogButtonBox>
#include <QPushButton>
#include <QMessageBox>
#include <QRegularExpression>
LoginDialog::LoginDialog(QWidget *parent) : QDialog(parent)
{
m_userEdit = new QLineEdit(this);
m_passEdit = new QLineEdit(this);
m_passEdit->setEchoMode(QLineEdit::Password);
auto *buttons = new QDialogButtonBox(
QDialogButtonBox::Ok | QDialogButtonBox::Cancel, this);
auto *form = new QFormLayout(this);
form->addRow("用户名:", m_userEdit);
form->addRow("密码:", m_passEdit);
form->addRow(buttons);
setWindowTitle("登录");
setModal(true);
connect(buttons, &QDialogButtonBox::accepted, this, &LoginDialog::validateAndAccept);
connect(buttons, &QDialogButtonBox::rejected, this, &QDialog::reject);
}
QString LoginDialog::user() const { return m_userEdit->text().trimmed(); }
QString LoginDialog::password() const { return m_passEdit->text(); }
void LoginDialog::validateAndAccept()
{
// 校验失败:提示后保持对话框打开
if (user().length() < 3) {
QMessageBox::warning(this, "输入有误", "用户名至少 3 个字符。");
m_userEdit->setFocus();
m_userEdit->selectAll();
return;
}
if (password().length() < 6) {
QMessageBox::warning(this, "输入有误", "密码至少 6 位。");
m_passEdit->setFocus();
return;
}
accept(); // 等价于 done(QDialog::Accepted)
}// 调用方
void MainWindow::onLogin()
{
LoginDialog dlg(this);
if (dlg.exec() == QDialog::Accepted) {
qDebug() << "登录:" << dlg.user();
}
// dlg 析构后仍能通过 getter 取数据?可以——但必须在对象存活时取。
// 上面的写法是对的:exec() 返回后 dlg 还没析构。
}#accept / reject / done 的关系
三个函数不是并列关系,而是层层封装:
| 函数 | 行为 |
|---|---|
done(int r) | 最底层:设置结果码 r,发 finished(r),关闭窗口 |
accept() | done(Accepted),额外发 accepted() 信号 |
reject() | done(Rejected),额外发 rejected() 信号 |
setResult(int) | 只设结果码,不关闭窗口 |
因此若你需要区分"保存"和"另存为",可以直接 done(2) 或用 setResult(),然后在调用方判断自定义结果码。惯例是正数表示成功路径,0/负数表示取消或失败,且避开 Qt 内置的 0 和 1。
Qt 5 提示:Qt 6 中
QDialog::exec()的返回值仍是int,但更推荐与QDialog::DialogCode枚举比较。Qt 5 里QFileDialog::getOpenFileName()的过滤器行为一致;差异主要在 Qt 6 需要显式链接Qt6::Widgets,且QRegExp已被QRegularExpression全面取代。
#常见陷阱
- 在非模态对话框上调用
exec()—— 会造成事件循环重入,轻则界面错乱,重则崩溃。 - 忘记
WA_DeleteOnClose—— 非模态对话框关闭后只是 hide,对象还在。 - 在
exec()之后才取数据但对象已析构 —— 用栈对象没问题,堆对象要小心。 - 把
QDialogButtonBox的accepted直接连到QDialog::accept—— 跳过了校验,数据可能非法。
#小结
exec()是嵌套事件循环,阻塞代码但不冻结界面;show()非模态需自己管内存。- 模态级别用
windowModality控制:ApplicationModal阻塞全局,WindowModal只阻塞父窗口。 QMessageBox/QInputDialog/QFileDialog的静态函数覆盖绝大多数场景,危险操作默认按钮要设成"取消"。accept()/reject()都是done(int)的语法糖,自定义结果码可区分多条成功路径。- 自定义对话框的标准范式是:先校验,失败则保持打开并聚焦问题控件,成功才
accept()。
#练习
- 写一个"查找/替换"非模态对话框,要求主窗口可同时操作,且重复点击菜单时不会弹出第二个实例(提示:
raise()+activateWindow())。 - 实现一个自定义"导出设置"对话框,包含文件路径、格式下拉框、质量滑块,其中"质量"仅在格式为 JPEG 时可用,校验通过后
accept()。 - 用
QProgressDialog配合QtConcurrent::run重写批量处理,让进度条由信号驱动,不允许出现processEvents()。 - 给登录对话框加一个"记住密码"复选框,用
QSettings保存上次用户名,下次启动时自动填充。