事件系统
理解事件循环与事件分发,掌握事件重写与过滤
#事件循环再深入
第 2 章我们说过 app.exec() 会进入事件循环。现在把它看清楚:
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() |
| 窗口 | QResizeEvent | oldSize() / size() |
| 窗口 | QCloseEvent | 可 accept() / ignore() 决定是否关闭 |
| 绘制 | QPaintEvent | 需重绘的区域 rect() |
| 焦点 | QFocusEvent | gotFocus() / lostFocus() |
| 拖放 | QDragEnterEvent / QDropEvent | MIME 数据 |
| 定时器 | QTimerEvent | timerId() |
| 自定义 | QEvent 子类 | 你自己定义 |
判断类型用 event->type(),向下转型用 static_cast(因为类型已经确认,不需要 dynamic_cast 的开销):
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()。迁移时留意这些浮点化改动。
#重写事件处理函数
这是处理事件最常见的方式:在你的控件子类里重写对应的虚函数。
// 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;
};// 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();
}三个极易踩的坑:
- 键盘事件收不到? 默认
QWidget的focusPolicy是Qt::NoFocus,必须先setFocusPolicy(Qt::StrongFocus)(或ClickFocus/TabFocus)。 - 不按鼠标就收不到
mouseMoveEvent? 需要setMouseTracking(true)。 - 重写了事件却"吃掉"了它? 对于你不关心的事件,一定要调用父类的同名实现(
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()——所有事件都会先经过它:
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():
// 在构造函数里
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 异步:
// 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() 或 eventFilter | connect 到槽/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()。
// 正确:数据变化后请求重绘,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()。
#练习
- 写一个自定义控件:鼠标按下画点、拖动画线、松开结束,支持 Ctrl+Z 撤销上一条线。要求用
mousePressEvent/MoveEvent/ReleaseEvent+paintEvent,并用update()触发重绘。 - 给窗口加"未保存时关闭需确认":重写
closeEvent(),根据内部 dirty 标志决定accept()还是ignore();再试着用QApplication::quit()触发退出,观察closeEvent是否被调用。 - 用事件过滤器实现:界面上所有
QLineEdit获得焦点时全选文本、按下回车跳到下一个输入框。要求只写一个eventFilter处理所有输入框,体会它比重写子类的优势。 - 用
QThread起一个工作线程,它用QApplication::postEvent把自定义ProgressEvent发到主线程更新进度条;再改用信号槽实现同样的功能,对比两种写法的代码量与可读性。