本章重要 API 函数#

💡 Tips：event() 是”总开关”，具体事件函数（如 mousePressEvent）是”分插座”。永远不要忘记在自定义 event() 末尾 return QWidget::event(event);——否则没处理的事件被你吞掉，控件会”失灵”（点不动、画不出）。本工程 Widget::event 与 InnerLable::event 都正确地把事件交还基类。

本章目录#

点击条目可跳转到对应小节。

学习前后依赖#

💡 Tips：必须先懂第 13 篇的信号槽，因为本篇 InnerLable 是”在事件处理函数里 emit 信号”的典型——事件和信号在这里交汇。本篇是 16/17 的”总纲”：鼠标/键盘事件函数本质上就是 event() 根据类型转发到的那些具体虚函数。

1. 概述#

Qt 是事件驱动框架。用户的一次点击、一次按键、一次定时器到期、一次重绘请求，都会变成一个个 QEvent 对象，被 QApplication 从系统消息队列取出，然后逐层派发到目标控件。控件收到事件后，先经过总入口 event()，再被分流到 mousePressEvent、keyPressEvent 等具体处理函数。

本工程 qt15_tst_eventbase 用一个 Widget 承载一个自定义 InnerLable（继承自 QLabel）。它演示了三件事：(1) 在 Widget::event 中截获并打印鼠标按下事件；(2) InnerLable 重写 event()/mousePressEvent/mouseDoubleClickEvent，在双击时 emit double_clicked() 信号；(3) Widget 用 Lambda 连接该信号，把 show_label 文字设为”霜机完成”。

💡 Tips：记住一句话——信号槽是”对象间通信”，事件是”输入/系统的原始通知”；多数信号最终由事件触发。本篇双击 InnerLable 后 emit double_clicked，正是把”底层的鼠标双击事件”翻译成了”上层可连接的信号”，这就是 Qt 控件封装输入的典型模式。

2. 核心概念 / 原理#

事件分发是一条责任链。简化流程：

1. 操作系统产生鼠标/键盘消息 → QApplication 的 event loop 取出 → 调用 QApplication::notify(receiver, event)。
2. notify 先给 receiver 安装的事件过滤器（eventFilter）一次机会截获；过滤器 return true 则事件被吞掉，不再继续。
3. 若未被过滤，调用 receiver->event(event)——这是控件的总处理器。
4. event() 根据 event->type() 把事件转发给对应的具体虚函数（如 MouseButtonPress → mousePressEvent）。
5. 具体函数处理完后，事件结束（或继续向父控件传播，视事件类型而定）。

InnerLable 继承自 QLabel，说明任何 QObject 派生类都能重写 event() 与事件函数——自定义控件处理自定义事件，正是 Qt 可扩展性的来源。

1
// inner_lable.h 关键声明
2
class InnerLable : public QLabel {
3
    Q_OBJECT
4
protected:
5
    bool event(QEvent *event) override;
6
    void mousePressEvent(QMouseEvent *ev) override;
7
    void mouseDoubleClickEvent(QMouseEvent *event) override;
8
signals:
9
    void double_clicked();
10
};

💡 Tips：原理上最易误解的是”事件与信号槽的区别”——事件更底层、同步、由 notify 直接调用分发出去；信号槽是建立在 QObject 之上的高级抽象。一个事件可以 emit 出多个信号，一个信号也可以由多种事件触发。另外，event() 返回 true 表示”我已处理，停止传播”，返回 false 表示”我不管，交给基类”，这与 accept()/ignore() 是两套不同体系，别混。

3. 事件分发链与事件过滤器#

下面用流程图展示事件从系统到具体处理函数的完整责任链，并标注事件过滤器与 event() 的介入点：

💡 Tips：流程里最关键的箭头是 notify → eventFilter → event → 具体函数 这一串。事件过滤器位于 event() 之前，所以它能”抢在控件自己看到事件之前”拦截（常用于给别人的控件加行为而不改其源码）。而 event() 是控件”自己处理一切事件”的最后总闸——在 InnerLable::event 里加日志，就能看到所有流经它的事件。

4. 核心代码解析#

1
bool Widget::event(QEvent *ev) {
2
    if(ev->type()==QEvent::MouseButtonPress) {
3
        qDebug()<<__PRETTY_FUNCTION__;   // 打印 "Widget::event"
4
        qDebug()<<ev->type();            // 打印事件类型枚举
5
    }
6
    return QWidget::event(ev);           // 必须交还基类！
7
}
8
void Widget::mousePressEvent(QMouseEvent *ev) {
9
    qDebug()<<__PRETTY_FUNCTION__;
10
}

1
InnerLable::InnerLable(QWidget *parent) : QLabel(parent) {
2
    setFrameStyle(QFrame::Panel | QFrame::Plain);
3
    setLineWidth(3); setMidLineWidth(1);   // 画个边框，便于看到控件范围
4
}
5
bool InnerLable::event(QEvent *ev) {
6
    // 注释掉了一段"在 event 里直接调用 mousePressEvent 并返回 true"的写法
7
    return QLabel::event(ev);              // 交给 QLabel 默认分发
8
}
9
void InnerLable::mousePressEvent(QMouseEvent *ev) {
10
    qDebug()<<__PRETTY_FUNCTION__;
11
}
12
void InnerLable::mouseDoubleClickEvent(QMouseEvent *event) {
13
    emit double_clicked();                 // 双击 -> 发自定义信号
14
}

1
Widget::Widget(QWidget *parent) : QWidget(parent), ui(new Ui::Widget) {
2
    ui->setupUi(this);
3
    setGeometry(100,100,500,500);
4
    in_label = new InnerLable(this);
5
    in_label->resize(150,150);
6
    in_label->move(150,150);
7
    show_label = new QLabel(this);
8
    show_label->resize(100,50);
9
    show_label->move(10,20);
10
    QObject::connect(in_label, &InnerLable::double_clicked, this, [=](){
11
        show_label->setText("霜机完成");
12
    });
13
}

5. 运行效果 / 验证#

运行后窗口 500×500，左上角一个 show_label（初始空），中间一个带边框的 150×150 InnerLable。验证：

1. 在窗口空白处点击 → 控制台打印 Widget::event 及事件类型，并 Widget::mousePressEvent（证明总入口与具体函数都被调用）。
2. 在中间 InnerLable 上点击 → 打印 InnerLable::mousePressEvent。
3. 在 InnerLable 上双击 → show_label 文字变为”霜机完成”，证明 mouseDoubleClickEvent → emit double_clicked → Lambda 链路打通。

💡 Tips：验证时容易误判”成功”的假象——若双击 show_label 没变字，先确认双击发生在 InnerLable 区域内（它有边框可辨），而非窗口空白处；空白处只有 Widget 的事件，InnerLable 信号不会触发。另外 event() 里若误 return true 吞掉事件，双击信号也会发不出。

容易踩坑（注意点）#

• 坑 1：重写 event() 后忘记 return Base::event(event); → 所有事件被吞，控件点不动、画不出。规避：要么转发基类，要么对处理的事件显式 return true、其余转发。
• 坑 2：在 event() 里手动调用具体事件函数又 return true → 绕过默认分发，可能丢失双击/悬停等基类逻辑（本工程注释掉的写法就是反例）。规避：除非完全清楚后果，否则让 Base::event 正常转发。
• 坑 3：事件过滤器 eventFilter 返回 true 却没真处理 → 事件被悄悄吞掉。规避：只对你关心的事件返回 true；其余 return false（或 Base::eventFilter）。
• 坑 4：自定义控件忘记 Q_OBJECT 与继承 QObject 体系 → 信号 double_clicked 无法 emit/connect。规避：InnerLable 继承 QLabel（间接继承 QObject）且带 Q_OBJECT。
• 坑 5：误以为 event() 返回值和 accept()/ignore() 是一回事 → 前者控制”是否继续分发”，后者标记”事件是否被处理”用于父子传播。规避：理解两者作用域不同。
• 坑 6：双击依赖 mouseDoubleClickEvent 却没开启 → Qt 默认支持；但某些平台/自定义 event 吞掉 MouseButtonDblClick 会导致不触发。规避：保持事件正常转发到基类。

学习要点总结#

Q&A（常见问题）#

Q1：事件和信号槽到底先有谁？ A1：事件是更底层、先发生的一方。以本工程为例，用户在 InnerLable 上双击，操作系统产生鼠标事件 → notify 分发 → InnerLable::mouseDoubleClickEvent 被调用 → 其中 emit double_clicked() 才产生信号 → 连接的 Lambda 执行。所以”事件触发信号，信号再驱动槽”，事件是源头。

Q2：event() 返回 true 和调用 event->accept() 有什么区别？ A2：这是两套机制。event() 返回 true 告诉 Qt”这个事件我全权处理，不要再往基类/父控件转发”；accept()/ignore() 是 QEvent 上的标记，用于同一事件在控件层级间的传播语义（例如 closeEvent 里 ignore() 可阻止窗口关闭）。混用会出怪问题，记住 event() 的返回值控制”分发是否继续”，accept/ignore 控制”语义是否被消费”。

Q3：事件过滤器适合什么场景？和重写 event() 怎么选？ A3：想给别人写的、不想改源码的控件加预处理逻辑（如全局屏蔽某类按键、统一日志），用 installEventFilter 最干净——无侵入。若是自己的控件，直接重写 event() 或具体事件函数更直接。过滤器在 event() 之前执行，优先级更高。

Q4：为什么本工程 InnerLable::event 里把”手动调用 mousePressEvent 并返回 true”注释掉了？ A4：那种写法属于”在总入口自己处理按下事件并吞掉”，会跳过 QLabel::event 的默认分发链，导致双击识别、样式更新等基类行为可能失效，还可能重复触发。工程选择让 QLabel::event(ev) 正常转发，由具体事件函数各司其职，更安全、更符合 Qt 设计意图。

Tips（全局速记）#