第18章 Qt事件系统

课程目录第18章 Qt事件系统

18、Qt事件系统：事件处理机制、重写事件处理器、事件过滤器

各位同学，今天我们来聊聊Qt里一个非常核心的机制——事件系统。

说实话，我刚学Qt那会儿，对事件的理解就是“鼠标点一下，程序响应一下”。后来做项目多了才发现，事件系统其实是整个Qt框架的“神经中枢”。你想想看，无论是按钮点击、键盘输入，还是窗口重绘，底层都是通过事件来驱动的。

这一章，我会带着大家把事件系统的三个核心知识点捋清楚：事件是怎么流转的、如何重写事件处理器、以及事件过滤器这个“黑科技”。

18.1 事件处理机制：从产生到消费

先说说事件是怎么来的。

用户在界面上点一下鼠标，操作系统会收到一个硬件中断。Qt把这个底层消息包装成一个 QEvent 对象，然后丢进事件队列里。事件循环（QEventLoop）会不断从队列里取出事件，分发给对应的 QObject。

分发的过程，说白了就是调用 QObject::event() 这个虚函数。它会根据事件类型，再调用具体的处理器，比如 mousePressEvent()、keyPressEvent() 等等。

核心流程：

操作系统产生消息
Qt 包装成 QEvent
进入事件队列
事件循环分发
QObject::event() 派发
具体的事件处理器被调用

这里有个关键点：事件可以被“消费”，也可以被“忽略”。如果你在事件处理器里调用了 event->accept()，事件就停止传播；如果调用了 event->ignore()，事件会继续向上传递给父组件。

嗯，这里要注意：accept() 和 ignore() 的默认行为取决于事件类型。比如鼠标事件默认是 accept()，而键盘事件默认是 ignore()。我刚开始做项目时就被这个坑过——明明重写了 keyPressEvent，但按键就是没反应，后来才发现是忘了调用 event->accept()。

18.2 重写事件处理器：实战 mousePressEvent 和 keyPressEvent

重写事件处理器，是Qt里最常用的自定义交互方式。说白了，就是继承一个QWidget，然后重新实现它的虚函数。

我给大家写个例子，一个自定义的标签控件，点击时改变颜色，按空格键重置。

// MyLabel.h
class MyLabel : public QLabel {
    Q_OBJECT
public:
    explicit MyLabel(QWidget *parent = nullptr);

protected:
    void mousePressEvent(QMouseEvent *event) override;
    void keyPressEvent(QKeyEvent *event) override;
};

// MyLabel.cpp
MyLabel::MyLabel(QWidget *parent) : QLabel(parent) {
    setText("点击我或按空格键");
    setAlignment(Qt::AlignCenter);
    setStyleSheet("background-color: lightgray; padding: 20px;");
    // 让控件能接收焦点，否则键盘事件不会触发
    setFocusPolicy(Qt::StrongFocus);
}

void MyLabel::mousePressEvent(QMouseEvent *event) {
    if (event->button() == Qt::LeftButton) {
        // 随机生成一个颜色
        int r = QRandomGenerator::global()->bounded(256);
        int g = QRandomGenerator::global()->bounded(256);
        int b = QRandomGenerator::global()->bounded(256);
        setStyleSheet(QString("background-color: rgb(%1, %2, %3); padding: 20px;")
                      .arg(r).arg(g).arg(b));
        setText(QString("RGB(%1, %2, %3)").arg(r).arg(g).arg(b));
    }
    // 调用基类实现，确保事件正常传播
    QLabel::mousePressEvent(event);
}

void MyLabel::keyPressEvent(QKeyEvent *event) {
    if (event->key() == Qt::Key_Space) {
        setStyleSheet("background-color: lightgray; padding: 20px;");
        setText("已重置，点击我或按空格键");
    }
    // 其他按键交给基类处理
    QLabel::keyPressEvent(event);
}

个人经验： 重写事件处理器时，一定要记得调用基类的同名函数。我曾经在做一个绘图板项目时，重写了 paintEvent 但忘了调用 QWidget::paintEvent，结果整个窗口的背景都画不出来了。排查了半天才发现是这个问题。

另外，QMouseEvent 里有很多有用的信息：

button()：哪个鼠标键被按下（左键、右键、中键）
buttons()：当前按下的所有鼠标键（支持多键同时按下）
pos()：事件发生时的相对坐标（相对于当前控件）
globalPos()：全局屏幕坐标

键盘事件里，QKeyEvent 的 key() 返回的是Qt定义的键值常量，比如 Qt::Key_A、Qt::Key_Return。如果你需要获取输入的字符，用 text() 方法。

18.3 事件过滤器：拦截与监控的利器

事件过滤器，是我个人非常喜欢的一个特性。它让你不用继承控件，就能拦截和处理某个对象的事件。

原理其实很简单：你给目标对象安装一个事件过滤器，目标对象的所有事件在到达它自己的事件处理器之前，会先经过过滤器的 eventFilter() 函数。你可以在这里决定是拦截事件，还是放行。

我给大家画个流程图，帮助理解：

看明白了吗？事件过滤器就像是一个“门卫”，所有事件都要先经过它。如果它返回 true，事件就被拦截了，目标对象根本收不到。如果返回 false，事件继续往下传。

来，看个实际例子。假设我们有一个 QLineEdit，想限制它只能输入数字：

// 在 MainWindow 构造函数中
QLineEdit *lineEdit = new QLineEdit(this);
lineEdit->installEventFilter(this);  // 安装事件过滤器

// 重写 eventFilter
bool MainWindow::eventFilter(QObject *watched, QEvent *event) {
    if (watched == lineEdit && event->type() == QEvent::KeyPress) {
        QKeyEvent *keyEvent = static_cast(event);
        int key = keyEvent->key();

        // 允许数字键、退格键、删除键、方向键
        if ((key >= Qt::Key_0 && key <= Qt::Key_9) ||
            key == Qt::Key_Backspace ||
            key == Qt::Key_Delete ||
            key == Qt::Key_Left ||
            key == Qt::Key_Right) {
            return false;  // 放行
        }

        // 其他按键全部拦截
        return true;
    }
    // 其他事件交给基类处理
    return QMainWindow::eventFilter(watched, event);
}

避坑指南： 我曾经在一个项目中，给一个复杂的对话框安装了多个事件过滤器，结果事件处理顺序乱套了。后来我总结了一个原则：事件过滤器尽量少用，一个对象最多装一个过滤器。如果确实需要多层过滤，用 installEventFilter 的顺序决定了调用顺序——后安装的先被调用。

18.4 事件传播与优先级

最后，咱们聊聊事件的传播路径。当一个事件发生后，Qt会按照以下顺序寻找处理者：

步骤	处理者	说明
1	事件过滤器	如果有安装，先经过 eventFilter()
2	目标对象的 event()	虚函数，可以在这里拦截或修改事件
3	具体的事件处理器	如 mousePressEvent()、keyPressEvent()
4	父对象的事件处理器	如果子对象调用了 ignore()

这里有个细节：event() 函数是事件分发的“总开关”。如果你重写了 event()，可以在事件到达具体处理器之前做全局处理。比如，你可以拦截所有鼠标事件：

bool MyWidget::event(QEvent *e) {
    if (e->type() == QEvent::MouseButtonPress ||
        e->type() == QEvent::MouseMove ||
        e->type() == QEvent::MouseButtonRelease) {
        // 记录鼠标活动日志
        qDebug() << "鼠标事件被捕获";
        return true;  // 拦截所有鼠标事件
    }
    return QWidget::event(e);  // 其他事件正常处理
}

我的建议： 在实际项目中，能用事件过滤器解决的问题，尽量不要重写 event()。因为 event() 的优先级太高，容易破坏原有的事件处理逻辑。我一般只在需要全局拦截（比如禁用所有鼠标操作）时才用 event()。

好了，这一章的内容就到这里。事件系统是Qt里比较底层的东西，理解透了，后面学自定义控件、动画系统都会轻松很多。大家动手写写代码，试试看能不能用事件过滤器实现一个“只允许点击三次的按钮”？

📚 课程目录

18、Qt事件系统：事件处理机制、重写事件处理器、事件过滤器

18.1 事件处理机制：从产生到消费

18.2 重写事件处理器：实战 mousePressEvent 和 keyPressEvent

18.3 事件过滤器：拦截与监控的利器

18.4 事件传播与优先级