QC++ / Qt 学习之路

事件系统

理解事件循环与事件分发,掌握事件重写与过滤

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

#事件循环再深入

第 2 章我们说过 app.exec() 会进入事件循环。现在把它看清楚:

Qt 事件循环 QApplication::exec()外部输入进入事件队列,循环取事件 → 分发 → 调用事件处理器鼠标 / 键盘定时器 QTimer网络 QTcpSocket系统窗口消息自定义事件事件队列FIFO 队列postEventQApplication::exec()事件循环 Event Loop① 取事件 nextEvent()② 分发 notify(recv, e)③ 调用事件处理器 event()队列非空 → 继续取下一个事件(循环)新事件重要约束槽函数在此线程串行执行不能阻塞耗时操作放子线程quit() / exit()退出循环,exec() 返回
Qt 事件循环:事件入队、分发、处理
Text
QApplication::exec()
  └─ while (!退出) {
       1. 从事件队列中取出一个 QEvent(可能来自:操作系统窗口消息、
          定时器、网络、其他线程 postEvent、程序自己 post 的事件)
       2. QApplication::notify(receiver, event)   ← 分发总入口
             └─ receiver->event(event)            ← 过滤 → 分发
                  └─ 具体的 xxxEvent() 处理函数
       3. 若无事件可取,等待(不占用 CPU)
     }

关键事实:事件是"投递给某个对象的",每个事件都有一个明确的接收者(一个 QObject)。这与信号"广播给所有连接者"不同,后面会对比。

另一个关键事实:事件循环是可以嵌套的。当你弹出 QMessageBox::question() 或 QFileDialog::getOpenFileName() 时,它们内部会启动一个新的事件循环,因此能同步返回用户的选择,而主窗口依然能响应绘制事件。理解这一点,你就能明白为什么这些"同步对话框"不会让界面卡死。

事件队列里的事件有优先级:Qt 会优先处理某些事件(如 QEvent::DeferredDelete),但普通事件的顺序基本是"先来先服务"。

对比:浏览器的事件循环(宏任务/微任务队列)与 Qt 的模型几乎同构;Java Swing 的 EventQueue + dispatchEvent 也是同一套。区别在细节:JS 的事件循环只有一个且跑在主线程,而 Qt 允许每个线程有自己的事件循环(QThread::exec()),因此 QObject 需要知道自己"属于"哪个线程(QObject::thread()),投递时才能送到正确的队列。

#QEvent 类层次

所有事件继承自 QEvent,它携带一个类型枚举 QEvent::Type:

类别事件类主要数据
输入QMouseEvent位置 pos()、按钮 button()、修饰键 modifiers()
输入QKeyEvent键码 key()、文本 text()、modifiers()
输入QWheelEvent滚动量 angleDelta()
窗口QResizeEventoldSize() / size()
窗口QCloseEvent可 accept() / ignore() 决定是否关闭
绘制QPaintEvent需重绘的区域 rect()
焦点QFocusEventgotFocus() / lostFocus()
拖放QDragEnterEvent / QDropEventMIME 数据
定时器QTimerEventtimerId()
自定义QEvent 子类你自己定义

判断类型用 event->type(),向下转型用 static_cast(因为类型已经确认,不需要 dynamic_cast 的开销):

C++
void MyWidget::mousePressEvent(QMouseEvent *e)
{
    qDebug() << "按下位置:" << e->pos()               // 相对于本控件
             << "全局位置:" << e->globalPosition()    // Qt 6 返回 QPointF
             << "按钮:" << e->button();               // Qt::LeftButton 等
}

Qt 5 提示:Qt 5 中 QMouseEvent::globalPos() 返回 QPoint,Qt 6 改为 globalPosition() 返回 QPointF(为高 DPI 与非整数缩放准备),pos() 依然返回 QPoint 但 Qt 6 也有 position()。同理 QWheelEvent::delta() 在 Qt 6 中改为 angleDelta()。迁移时留意这些浮点化改动。

#重写事件处理函数

这是处理事件最常见的方式:在你的控件子类里重写对应的虚函数。

C++
// mywidget.h
#pragma once
#include <QWidget>

class MyWidget : public QWidget
{
    Q_OBJECT
public:
    explicit MyWidget(QWidget *parent = nullptr);
protected:
    void mousePressEvent(QMouseEvent *event) override;
    void mouseMoveEvent(QMouseEvent *event) override;
    void mouseReleaseEvent(QMouseEvent *event) override;
    void keyPressEvent(QKeyEvent *event) override;
    void wheelEvent(QWheelEvent *event) override;
    void closeEvent(QCloseEvent *event) override;
    void paintEvent(QPaintEvent *event) override;
    void resizeEvent(QResizeEvent *event) override;
private:
    bool m_dragging = false;
    QPoint m_dragStart;
};
C++
// mywidget.cpp
#include "mywidget.h"
#include <QMouseEvent>
#include <QKeyEvent>
#include <QWheelEvent>
#include <QCloseEvent>
#include <QPainter>
#include <QMessageBox>
#include <QDebug>

MyWidget::MyWidget(QWidget *parent) : QWidget(parent)
{
    setFocusPolicy(Qt::StrongFocus);    // 关键:默认不接受键盘焦点!
    setMouseTracking(true);             // 不按下鼠标也能收到 mouseMoveEvent
}

void MyWidget::mousePressEvent(QMouseEvent *event)
{
    if (event->button() == Qt::LeftButton) {
        m_dragging = true;
        m_dragStart = event->pos();
        qDebug() << "按下:" << event->pos();
    }
    // event->accept();   // 默认已 accept
}

void MyWidget::mouseMoveEvent(QMouseEvent *event)
{
    if (m_dragging)
        qDebug() << "拖动中:" << event->pos() - m_dragStart;
}

void MyWidget::mouseReleaseEvent(QMouseEvent *event)
{
    m_dragging = false;
    Q_UNUSED(event);
}

void MyWidget::keyPressEvent(QKeyEvent *event)
{
    // 先处理自己关心的键,其余交给父类(比如 Tab 键切换焦点)
    if (event->key() == Qt::Key_Escape) {
        qDebug() << "按下 Esc";
        event->accept();
    } else if (event->modifiers() & Qt::ControlModifier &&
               event->key() == Qt::Key_S) {
        qDebug() << "Ctrl+S";
        event->accept();
    } else {
        QWidget::keyPressEvent(event);   // 重要:别吞掉其他键
    }
}

void MyWidget::wheelEvent(QWheelEvent *event)
{
    qDebug() << "滚轮:" << event->angleDelta().y();
    event->accept();
}

void MyWidget::closeEvent(QCloseEvent *event)
{
    auto ret = QMessageBox::question(this, tr("确认"),
                                     tr("确定要关闭吗?"));
    if (ret == QMessageBox::Yes)
        event->accept();      // 允许关闭
    else
        event->ignore();      // 拦截关闭!
}

void MyWidget::paintEvent(QPaintEvent *event)
{
    QPainter p(this);
    p.setRenderHint(QPainter::Antialiasing);
    p.fillRect(event->rect(), Qt::white);
    p.setPen(QPen(Qt::darkBlue, 2));
    p.drawEllipse(rect().adjusted(10, 10, -10, -10));
    p.drawText(rect(), Qt::AlignCenter, tr("在这里画图"));
}

void MyWidget::resizeEvent(QResizeEvent *event)
{
    qDebug() << "尺寸从" << event->oldSize() << "变为" << event->size();
}

三个极易踩的坑:

  1. 键盘事件收不到? 默认 QWidget 的 focusPolicy 是 Qt::NoFocus,必须先 setFocusPolicy(Qt::StrongFocus)(或 ClickFocus / TabFocus)。
  2. 不按鼠标就收不到 mouseMoveEvent? 需要 setMouseTracking(true)。
  3. 重写了事件却"吃掉"了它? 对于你不关心的事件,一定要调用父类的同名实现(QWidget::keyPressEvent(event)),否则 Tab 切换焦点、快捷键、输入法等会全部失效。这是新手最常制造的隐性 bug。

Q_UNUSED(event) 宏用于消除"未使用参数"的编译警告,等价于 (void)event;。

#accept() 与 ignore()

每个 QEvent 都有 accept() / ignore(),表达"我处理了吗"。

  • accept():我消费了这个事件,不再向父控件传递。
  • ignore():我没处理,请交给父控件(对于键盘事件等,Qt 会沿 parent 链向上冒泡)。

重要理解:大多数虚函数默认已经调用 accept()(比如 QWidget::mousePressEvent)。如果你重写后希望事件继续向上传播(例如让父窗口也能收到点击),必须显式 event->ignore()。

QCloseEvent 是个特例:它默认 accept()(允许关闭),你调用 ignore() 就能阻止窗口关闭——这正是"关闭前确认"的实现方式,见上例。

#event() 函数:事件的总入口

如果你不想为每个事件重写一个函数,可以重写 event()——所有事件都会先经过它:

C++
bool MyWidget::event(QEvent *event)
{
    if (event->type() == QEvent::KeyPress) {
        auto *ke = static_cast<QKeyEvent *>(event);
        if (ke->key() == Qt::Key_Tab) {
            // 自定义 Tab 行为
            return true;      // 返回 true = 已处理(等价于 accept)
        }
    } else if (event->type() == QEvent::ToolTip) {
        // 拦截 tooltip
        return true;
    }
    return QWidget::event(event);   // 其余交给父类分发到具体 xxxEvent()
}

返回值:true 表示已处理(事件停止传播),false 表示继续分发。

什么时候用 event() 而不是具体的 xxxEvent()?两种情况:一、你想拦截某类事件阻止它到达默认处理(比如禁用 tooltip、禁用右键菜单);二、你要处理没有专用虚函数的事件(比如 QEvent::ApplicationActivate、QEvent::PaletteChange)。

对比:event() 相当于浏览器 DOM 的"捕获阶段"或 jQuery 里 $(document).on('click', ...) 的统一入口;具体的 mousePressEvent 相当于 onclick 的具体处理器。设计意图完全一样——先给一个统一入口让你拦截,再分发到具体处理器。

#事件过滤器:监视别人的事件

有时候你想处理另一个对象的事件,但不想(或不能)继承它。用 installEventFilter():

C++
// 在构造函数里
m_lineEdit->installEventFilter(this);

// 重写 eventFilter
bool MainWindow::eventFilter(QObject *watched, QEvent *event)
{
    if (watched == m_lineEdit && event->type() == QEvent::KeyPress) {
        auto *ke = static_cast<QKeyEvent *>(event);
        if (ke->key() == Qt::Key_Return || ke->key() == Qt::Key_Enter) {
            submitText();
            return true;         // 吃掉回车,输入框不再处理
        }
    } else if (watched == m_textEdit && event->type() == QEvent::Wheel) {
        return true;             // 屏蔽 textEdit 的滚轮,让外层滚动
    }
    return QMainWindow::eventFilter(watched, event);   // 必须调用父类!
}

要点:

  • 过滤器安装在监视者(this)上,监视被监视者(m_lineEdit)。
  • 过滤器的 eventFilter() 在被监视者的 event() 之前执行,因此你可以抢先拦截。
  • 多个过滤器按安装的"逆序"执行(后安装的先执行)。
  • removeEventFilter() 可以移除;对象销毁时自动移除。
  • 返回 true = 事件到此为止;返回 false = 放行。
  • 常见用途:给输入框加"回车提交"、"点击清空"、给窗口加"拖动标题栏移动"、给多个控件统一加悬停高亮。

还有一个全局过滤器:qApp->installEventFilter(this) 可以监视整个应用的所有事件。威力巨大但代价也大(每个事件都会走一遍你的函数),谨慎使用。

#发送自定义事件

QApplication 提供两个函数,区别在同步 vs 异步:

C++
// 1. 同步发送:立即调用目标的处理函数,函数返回后才继续往下走
QMouseEvent press(QEvent::MouseButtonPress, QPointF(10, 10),
                  Qt::LeftButton, Qt::LeftButton, Qt::NoModifier);
QApplication::sendEvent(targetWidget, &press);
// 注意:sendEvent 的事件必须在栈上(它不接管所有权)

// 2. 异步投递:放进目标线程的事件队列,等事件循环取到才处理
auto *ev = new QMyCustomEvent(data);
QApplication::postEvent(targetWidget, ev);
// postEvent 的事件必须在堆上(Qt 会在处理后自动 delete)

// ---- 自定义事件类型:继承 QEvent,类型值从 QEvent::User(=1000) 开始 ----
class ProgressEvent : public QEvent
{
public:
    explicit ProgressEvent(int percent)
        : QEvent(QEvent::User),
          m_percent(percent) {}

    int percent() const { return m_percent; }

private:
    int m_percent;
};

// 接收方重写 customEvent()
void Receiver::customEvent(QEvent *event)
{
    if (event->type() == QEvent::User) {
        auto *pe = static_cast<ProgressEvent *>(event);
        m_bar->setValue(pe->percent());
    }
}

// 自定义类型建议用 registerEventType() 取全局唯一值,避免与第三方库冲突
static const QEvent::Type ProgressEventType =
    static_cast<QEvent::Type>(QEvent::registerEventType());

postEvent 是跨线程通信的底层机制——事实上第 3 章讲的 QueuedConnection 信号槽,内部就是用 postEvent 实现的。直接发事件比信号槽更底层、更灵活,但可读性差,日常开发优先用信号槽。

#事件 vs 信号:该用哪个

维度事件(QEvent)信号(signal)
接收者明确的单个对象所有连接者(多播)
来源通常是操作系统或系统内部通常是你的代码语义
处理位置重写 xxxEvent() 或 eventFilterconnect 到槽/Lambda
能否拦截可以 ignore() / accept() / 返回 true 拦截不能,发出去就发出去了
典型场景鼠标按下、键盘输入、重绘、关闭窗口"用户提交了表单"、"下载完成"

判断口诀:"这件事发生在我的控件本身(鼠标、键盘、绘制)" → 用事件;"这件事是我这个对象的业务状态变化" → 用信号。

典型模式是两者结合:重写 mousePressEvent 处理原始输入,然后在里面 emit clicked() 之类的信号,把底层事件翻译成高层的语义信号。Qt 的 QPushButton 就是这么做的——它重写鼠标事件,然后发出 clicked() 信号。你在自己的自定义控件里也应遵循这个模式:底层处理事件,对外暴露信号。

对比:Web 里 onclick 是事件,但 React 的状态变化驱动重渲染则是"信号/状态"层;Java Swing 里 MouseListener 监听底层事件,ActionListener 监听语义动作——Qt 的信号槽正好统一在这两者之间:底层用事件(对应 MouseListener),上层用信号(对应 ActionListener),且转换非常自然。

#update() 与 repaint()

最后一个重要话题:什么时候画面会重绘?

  • update():异步重绘。它只是向事件队列投递一个 QPaintEvent(并且会合并多次 update() 调用,避免重复绘制),等到事件循环空闲时才真正绘制。这是你应该用的方式。
  • repaint():同步立即重绘,直接调用 paintEvent()。它会打断当前流程,若在事件处理函数中调用可能造成递归、闪烁或性能问题。除非你明确知道为什么需要它(例如在某个阻塞循环中必须立刻看到反馈),否则一律用 update()。
C++
// 正确:数据变化后请求重绘,Qt 会在合适时机合并处理
void MyWidget::setData(const QList<int> &d)
{
    m_data = d;
    update();          // 可能被调用 100 次,最终只画一次
}

// 不推荐:每次都立刻重画,浪费且可能闪烁
void MyWidget::setDataImmediately(const QList<int> &d)
{
    m_data = d;
    repaint();
}

另外 QWidget::setAttribute(Qt::WA_OpaquePaintEvent) 可以告诉 Qt"我会画满整个区域",避免它先擦背景再画,能消除闪烁。做自定义绘图(图表、仪表盘、波形)时这两点都要注意。

对比:这与浏览器的渲染机制非常像——你修改 DOM 后浏览器不会立刻重绘,而是在下一帧统一批量处理(requestAnimationFrame 的批量合并)。update() 就是"标记 dirty,等下一帧",repaint() 则是"强制同步布局并重绘"(相当于 JS 里读取 offsetHeight 触发的强制 reflow)。Qt 早在二十多年前就用上了同样的批处理思路。

#小结

  • 事件循环不断从队列取事件 → notify() → event() → 具体的 xxxEvent();事件有明确接收者,可嵌套循环。
  • 重写事件处理函数是最常用方式;三个高频坑:键盘需 setFocusPolicy、拖动需 setMouseTracking、无关事件必须调父类实现。
  • accept() 表示消费,ignore() 表示向上传递;QCloseEvent::ignore() 可拦截窗口关闭。
  • event() 是总入口(可拦截无专用虚函数的事件),eventFilter() 用于监视别人的事件,qApp->installEventFilter 可全局监视。
  • sendEvent 同步(栈上事件)、postEvent 异步(堆上事件,跨线程通信的底层);自定义事件用 QEvent::User 或 registerEventType()。
  • 底层输入用事件、业务语义用信号;重绘一律用 update() 而非 repaint()。

#练习

  1. 写一个自定义控件:鼠标按下画点、拖动画线、松开结束,支持 Ctrl+Z 撤销上一条线。要求用 mousePressEvent/MoveEvent/ReleaseEvent + paintEvent,并用 update() 触发重绘。
  2. 给窗口加"未保存时关闭需确认":重写 closeEvent(),根据内部 dirty 标志决定 accept() 还是 ignore();再试着用 QApplication::quit() 触发退出,观察 closeEvent 是否被调用。
  3. 用事件过滤器实现:界面上所有 QLineEdit 获得焦点时全选文本、按下回车跳到下一个输入框。要求只写一个 eventFilter 处理所有输入框,体会它比重写子类的优势。
  4. 用 QThread 起一个工作线程,它用 QApplication::postEvent 把自定义 ProgressEvent 发到主线程更新进度条;再改用信号槽实现同样的功能,对比两种写法的代码量与可读性。
我的学习笔记笔记总览
笔记保存在本机浏览器(localStorage),换设备或清理缓存会丢失;重要内容请点「导出全部笔记」存成 .md 文件。