QC++ / Qt 学习之路

对话框与交互

掌握模态/非模态对话框与标准对话框,写出可校验的自定义对话框

进阶第 25 / 48 章第四篇 · Qt 进阶

#对话框的本质:一次"阻塞的问答"

普通窗口(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() 期间又收到一个网络回调,弹出了第二个对话框)。

C++
#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()关于对话框,无图标按钮无返回值
C++
#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 同样以静态函数为主,适合"要一个值"的场景。它比自己搭一个对话框快得多,但可定制性差——需要复杂校验时就应该自定义对话框。

C++
#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() 信号即可中断。

C++
#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() 或保持打开。

C++
// 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;
};
C++
// 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)
}
C++
// 调用方
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 全面取代。

#常见陷阱

  1. 在非模态对话框上调用 exec() —— 会造成事件循环重入,轻则界面错乱,重则崩溃。
  2. 忘记 WA_DeleteOnClose —— 非模态对话框关闭后只是 hide,对象还在。
  3. 在 exec() 之后才取数据但对象已析构 —— 用栈对象没问题,堆对象要小心。
  4. 把 QDialogButtonBox 的 accepted 直接连到 QDialog::accept —— 跳过了校验,数据可能非法。

#小结

  1. exec() 是嵌套事件循环,阻塞代码但不冻结界面;show() 非模态需自己管内存。
  2. 模态级别用 windowModality 控制:ApplicationModal 阻塞全局,WindowModal 只阻塞父窗口。
  3. QMessageBox/QInputDialog/QFileDialog 的静态函数覆盖绝大多数场景,危险操作默认按钮要设成"取消"。
  4. accept()/reject() 都是 done(int) 的语法糖,自定义结果码可区分多条成功路径。
  5. 自定义对话框的标准范式是:先校验,失败则保持打开并聚焦问题控件,成功才 accept()。

#练习

  1. 写一个"查找/替换"非模态对话框,要求主窗口可同时操作,且重复点击菜单时不会弹出第二个实例(提示:raise() + activateWindow())。
  2. 实现一个自定义"导出设置"对话框,包含文件路径、格式下拉框、质量滑块,其中"质量"仅在格式为 JPEG 时可用,校验通过后 accept()。
  3. 用 QProgressDialog 配合 QtConcurrent::run 重写批量处理,让进度条由信号驱动,不允许出现 processEvents()。
  4. 给登录对话框加一个"记住密码"复选框,用 QSettings 保存上次用户名,下次启动时自动填充。
我的学习笔记笔记总览
笔记保存在本机浏览器(localStorage),换设备或清理缓存会丢失;重要内容请点「导出全部笔记」存成 .md 文件。