桌面应用 / 系统课时
重写鼠标和键盘事件
重写鼠标和键盘事件
当窗口需要响应鼠标点击、键盘按键或修饰键组合时,可以重写 QWidget 的事件处理函数,并从事件对象中读取位置、按键和修饰键等信息。本节通过一个可运行窗口完成输入捕获,同时说明焦点、事件参数和默认处理之间的关系。
学习目标
- 能重写
mousePressEvent()和keyPressEvent()处理用户输入 - 能从
QMouseEvent、QKeyEvent中读取常用事件参数 - 能正确区分自行处理事件与交给基类继续处理的场景
输入事件如何进入处理函数
Qt 接收到系统输入后,会把事件发送给目标控件。对 QWidget 而言,通用事件入口最终会根据事件类型调用对应的虚函数,例如鼠标按下进入 mousePressEvent(),键盘按下进入 keyPressEvent()。因此,自定义控件通常不需要自己轮询鼠标或键盘状态。

事件处理函数必须使用 Qt 定义的准确签名。给成员函数加上 override 很重要:如果参数类型或函数名写错,编译器会直接报错,而不是悄悄创建一个永远不会被 Qt 调用的新函数。
重写鼠标和键盘事件
下面的程序创建一个没有子控件的窗口。鼠标左键按下时读取窗口内坐标和 Ctrl 状态;键盘按下时读取文本和自动重复状态。事件内容同时显示在窗口标题和调试输出中,按 Esc 可以关闭窗口。
#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> 代表实际点击位置,因此每次运行可能不同。
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 的信号与槽,而不是退回到底层鼠标和键盘事件。