桌面应用 / 系统课时

重写鼠标和键盘事件

重写鼠标和键盘事件

当窗口需要响应鼠标点击、键盘按键或修饰键组合时,可以重写 QWidget 的事件处理函数,并从事件对象中读取位置、按键和修饰键等信息。本节通过一个可运行窗口完成输入捕获,同时说明焦点、事件参数和默认处理之间的关系。

学习目标

  • 能重写 mousePressEvent() 和 keyPressEvent() 处理用户输入
  • 能从 QMouseEvent、QKeyEvent 中读取常用事件参数
  • 能正确区分自行处理事件与交给基类继续处理的场景

输入事件如何进入处理函数

Qt 接收到系统输入后,会把事件发送给目标控件。对 QWidget 而言,通用事件入口最终会根据事件类型调用对应的虚函数,例如鼠标按下进入 mousePressEvent(),键盘按下进入 keyPressEvent()。因此,自定义控件通常不需要自己轮询鼠标或键盘状态。

Qt 输入事件分发到控件处理函数的流程

事件处理函数必须使用 Qt 定义的准确签名。给成员函数加上 override 很重要:如果参数类型或函数名写错,编译器会直接报错,而不是悄悄创建一个永远不会被 Qt 调用的新函数。

重写鼠标和键盘事件

下面的程序创建一个没有子控件的窗口。鼠标左键按下时读取窗口内坐标和 Ctrl 状态;键盘按下时读取文本和自动重复状态。事件内容同时显示在窗口标题和调试输出中,按 Esc 可以关闭窗口。

cpp
#include <QApplication>
#include <QDebug>
#include <QKeyEvent>
#include <QMouseEvent>
#include <QString>
#include <QWidget>

class InputWidget final : public QWidget
{
public:
    InputWidget()
    {
        resize(520, 300);
        setWindowTitle("点击窗口或按键");

        // 键盘事件只会发送给具有键盘焦点的控件。
        setFocusPolicy(Qt::StrongFocus);
    }

protected:
    void mousePressEvent(QMouseEvent *event) override
    {
        if (event->button() == Qt::LeftButton) {
            const QPointF pos = event->position();
            const bool ctrl = event->modifiers().testFlag(Qt::ControlModifier);

            const QString message =
                QString("mouse left x=%1 y=%2 ctrl=%3")
                    .arg(pos.x(), 0, 'f', 0)
                    .arg(pos.y(), 0, 'f', 0)
                    .arg(ctrl ? "yes" : "no");

            setWindowTitle(message);
            qDebug().noquote() << message;
            event->accept();
            return;
        }

        // 当前类不处理其他鼠标按键,保留 QWidget 的默认行为。
        QWidget::mousePressEvent(event);
    }

    void keyPressEvent(QKeyEvent *event) override
    {
        const QString text = event->text().isEmpty()
                                 ? "<none>"
                                 : event->text();

        const QString message =
            QString("key text=%1 autoRepeat=%2")
                .arg(text)
                .arg(event->isAutoRepeat() ? "yes" : "no");

        setWindowTitle(message);
        qDebug().noquote() << message;

        if (event->key() == Qt::Key_Escape) {
            close();
        }

        event->accept();
    }
};

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);

    InputWidget window;
    window.show();
    window.setFocus();

    return app.exec();
}

预期输出:按住 Ctrl 在窗口中单击鼠标左键,再按一次 A,调试输出会出现类似内容;<X>、<Y> 代表实际点击位置,因此每次运行可能不同。

text
mouse left x=<X> y=<Y> ctrl=yes
key text=a autoRepeat=no

窗口标题也会同步显示最近一次事件。按下 Esc 时,keyPressEvent() 会收到该按键并关闭窗口。

读取事件参数

QMouseEvent::position() 返回事件相对于接收控件的浮点坐标,这是 Qt 6 中处理控件局部位置时最常用的接口。如果需要屏幕坐标,可以读取 globalPosition()。处理按下事件时,button() 表示触发这次事件的那个鼠标按键,而 buttons() 表示事件发生时仍处于按下状态的鼠标按键集合,两者不要混用。

键盘事件中,key() 适合判断 Esc、Enter、方向键等逻辑按键,text() 更适合取得用户实际输入的文本。modifiers() 可以检测 Ctrl、Shift、Alt 等组合键,isAutoRepeat() 则可以判断当前事件是否由长按按键后的自动重复产生。

焦点与事件处理边界

鼠标事件通常由鼠标所在的目标控件接收,而键盘事件依赖键盘焦点。示例通过 setFocusPolicy(Qt::StrongFocus) 允许窗口通过鼠标点击、Tab 等方式获得焦点,并在启动后调用 setFocus(),避免程序刚打开时按键没有进入该窗口。

已经完全处理的事件可以调用 accept()。如果当前类只关心部分情况,例如示例只处理鼠标左键,那么其余情况调用基类实现通常更安全,因为这样可以保留控件原本的行为。不同事件类型的传播规则并不完全相同,不要把 accept() 和 ignore() 简化成适用于所有事件的统一冒泡规则。

重写专用事件函数适合实现控件级自定义交互;当需求只是按钮点击、文本变化等控件已经提供的高层行为时,应优先使用 Qt 的信号与槽,而不是退回到底层鼠标和键盘事件。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

重写鼠标和键盘事件

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通