本章重要 API 函数#

💡 Tips：Qt6 把 globalPos() 改成了 globalPosition()（返回 QPointF，更精确），Qt5 用 globalPos()（返回 QPoint）。本项目是 Qt6，用的是 globalPosition()。button() 与 buttons() 极易混：前者是”触发本次事件的那个键”，后者是”当前所有被按住的键的位或掩码”；拖动判定必须用 buttons() & Qt::LeftButton（按住期间多次移动都含左键），而按下/松开判定用 button()。

本章目录#

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

学习前后依赖#

💡 Tips：本篇是 15 篇的”具体展开”——第 15 篇讲 event() 总入口如何把 MouseButtonPress 分流到 mousePressEvent；本篇直接重写这些具体函数。先读 15 理解分发链，再看本篇就不会觉得这些函数是”凭空被调用”的。

1. 概述#

鼠标是人类与 GUI 交互最频繁的输入设备。Qt 把鼠标行为拆成一组清晰的事件虚函数：按下、移动、释放、双击、滚轮、进入/离开。本工程 qt16_tst_mouse 把它们集成进一个 400×400 窗口，演示了四个实用能力：

1. 拖动窗口：左键按下记录偏移，移动时按全局坐标差移动窗口。
2. 光标反馈：左键按下变”握拳”光标、松开恢复”张开手”；右键按下临时换成一张图片光标（Doraemon.png）。
3. 双击全屏：左键双击在普通/全屏间切换。
4. 滚轮缩放：在 QTextEdit 上滚轮回滚缩放文字；关闭窗口弹确认框，可取消退出。

💡 Tips：记住一句话——鼠标事件的核心难点不是”怎么响应”，而是”坐标用哪种、按键用哪个函数取”。本工程的拖动算法 offset = globalPos - pos() 是 GUI 拖拽的教科书写法，务必吃透 globalPosition()（屏幕坐标）与 pos()（窗口左上角相对父的坐标）的区别。

2. 核心概念 / 原理#

鼠标事件对象 QMouseEvent 携带三类关键信息：(1) 按键——button()（本次事件的键）与 buttons()（当前按住的所有键掩码）；(2) 坐标——pos()（相对接收控件）、globalPosition()（相对屏幕，Qt6）；(3) 修饰键——modifiers()（Shift/Ctrl/Alt）。

拖动窗口的经典算法依赖”全局坐标”而非”相对坐标”：按下时记录 offset = 鼠标全局坐标 - 窗口左上角全局坐标；之后每次移动，新窗口位置 = 鼠标全局坐标 - offset。这样无论鼠标在窗口哪个位置按下，拖动都不会”跳变”。

1
// 拖动核心（在 mousePressEvent 记录，在 mouseMoveEvent 应用）
2
offset = event->globalPosition() - pos();   // pos() 即窗口左上角
3
// 移动时：
4
move(event->globalPosition() - offset);

光标管理用 栈式覆盖：setOverrideCursor 把光标压入 Qt 的全局光标栈，restoreOverrideCursor 弹出一层。这意味着可以嵌套多层（按下 A 压一种、再按下 B 压另一种），释放时逐层恢复，不会乱。

💡 Tips：原理上最易误解的是 mouseMoveEvent 默认只在按键按住时才触发（因为 setMouseTracking 默认 false）。本工程正是利用这点做”按住左键才拖动”——没按住时移动鼠标 mouseMoveEvent 根本不被调用，既省 CPU 又天然实现了”拖拽而非悬停跟随”。若要”悬停即跟随”，需 setMouseTracking(true)，但那样拖动逻辑要加 buttons() 判断否则会乱飞。

3. 鼠标事件的分发与拖动链路#

下面用流程图展示从鼠标移动到窗口拖动的完整链路，并标示各事件函数的介入点：

💡 Tips：流程里最关键的节点是 J（记录 offset）→ K（move） 这一对——它们必须配合 globalPosition()（屏幕坐标系）才能正确。若误用 pos()（相对控件）做偏移，拖动会从鼠标按下点”瞬移”到窗口左上角。另外注意 F 分支只在”左键按住”时抵达 K（因 buttons()&LeftButton 判定），这正是默认 setMouseTracking(false) 的效果。

4. 核心代码解析#

1
Widget::Widget(QWidget *parent) : QWidget(parent) {
2
    setGeometry(100,100,400,400);
3
    QCursor cursor;
4
    cursor.setShape(Qt::OpenHandCursor);   // 张开手光标
5
    setCursor(cursor);
6
    edit = new QTextEdit(this);
7
    edit->resize(200,200); edit->move(100,100);
8
}

1
void Widget::mousePressEvent(QMouseEvent *event) {
2
    if(event->button()==Qt::LeftButton) {
3
        QCursor cursor; cursor.setShape(Qt::ClosedHandCursor);
4
        QApplication::setOverrideCursor(cursor);   // 全局压栈：握拳
5
        offset = event->globalPosition() - pos();
6
    } else if(event->button()==Qt::RightButton) {
7
        QPixmap pixmap("./Doraemon.png");
8
        qreal dpr = qApp->primaryScreen()->devicePixelRatio();
9
        QSize realSize = QSize(64,64)*dpr;
10
        pixmap = pixmap.scaled(realSize, Qt::KeepAspectRatio, Qt::SmoothTransformation);
11
        pixmap.setDevicePixelRatio(dpr);
12
        QCursor cursor(pixmap, 64, 64);
13
        QApplication::setOverrideCursor(cursor);    // 临时图片光标
14
    }
15
    QWidget::mousePressEvent(event);
16
}
17
void Widget::mouseReleaseEvent(QMouseEvent *event) {
18
    Q_UNUSED(event);
19
    QApplication::restoreOverrideCursor();          // 弹出一层光标
20
    QWidget::mouseReleaseEvent(event);
21
}

1
void Widget::mouseMoveEvent(QMouseEvent *event) {
2
    if(event->buttons() & Qt::LeftButton) {         // 注意用 buttons()
3
        QPointF temp = event->globalPosition() - offset;
4
        move(temp.x(), temp.y());
5
    }
6
}
7
void Widget::mouseDoubleClickEvent(QMouseEvent *event) {
8
    if(event->button()==Qt::LeftButton) {
9
        if(windowState()!=Qt::WindowFullScreen)
10
            setWindowState(Qt::WindowFullScreen);
11
        else
12
            setWindowState(Qt::WindowNoState);
13
    }
14
    QWidget::mouseDoubleClickEvent(event);
15
}

1
void Widget::wheelEvent(QWheelEvent *event) {
2
    if(event->angleDelta().y()>0) edit->zoomIn();
3
    else                           edit->zoomOut();
4
}
5
void Widget::closeEvent(QCloseEvent *event) {
6
    QMessageBox::StandardButton result = QMessageBox::question(
7
        this,"鼠标事件框","确定退出吗？",
8
        QMessageBox::Yes|QMessageBox::No|QMessageBox::Cancel);
9
    if(result==QMessageBox::Yes) event->accept();
10
    else                         event->ignore();
11
}

5. 运行效果 / 验证#

运行 400×400 窗口，中央有文本框。验证：

1. 鼠标移到窗口上 → 光标是”张开手”。
2. 左键按住并拖动 → 窗口跟随鼠标平滑移动，光标变”握拳”；松开恢复张开手。
3. 右键按下 → 光标临时变成 Doraemon 图片（若有图）；松开恢复。
4. 左键双击 → 窗口在全屏/普通间切换。
5. 在文本框上滚动滚轮 → 文字放大/缩小。
6. 点关闭按钮 → 弹”确定退出吗？“，选 Yes 退出、No/Cancel 取消。

💡 Tips：验证时容易误判”成功”的假象——若拖动时窗口”瞬移”，基本是 offset 用了 pos() 而非 globalPosition()（坐标系统不一致）。若右键光标无变化，先确认 exe 同目录有 Doraemon.png。若双击不切全屏，检查双击的是窗口空白区（控件 Widget 自身）而非文本框（文本框可能会吞事件）。

容易踩坑（注意点）#

• 坑 1：拖动用 pos() 算 offset 导致瞬移 → 混合了相对坐标与全局坐标。规避：按下与移动都用 globalPosition()（或 Qt5 的 globalPos()）保持一致。
• 坑 2：拖动判定用 button() 而非 buttons() → button() 在移动事件里返回 NoButton（移动不是”按下”动作），导致永远不拖动。规避：移动中用 buttons() & Qt::LeftButton。
• 坑 3：setOverrideCursor 与 restoreOverrideCursor 不配对 → 光标栈失衡，光标错乱。规避：按下压一次、释放弹一次，严格对称。
• 坑 4：setMouseTracking(true) 后没加 buttons() 判定 → 鼠标悬停就拖动，窗口乱飞。规避：要么保持默认 false（仅按住触发），要么在 move 里加 buttons() 判断。
• 坑 5：Qt5/Qt6 坐标 API 混用 → globalPos()（Qt5 返回 QPoint）与 globalPosition()（Qt6 返回 QPointF）不兼容。规避：项目是 Qt6，统一用 globalPosition()；跨版本注意返回类型差异。
• 坑 6：重写事件函数后忘调基类 → 焦点、默认绘制等丢失。规避：本工程每个函数末尾都 QWidget::xxxEvent(event)，保留默认行为。
• 坑 7：Doraemon.png 缺失 → 图片光标无效。规避：把图片放到构建产物（exe）同目录，或用资源文件 qrc 内嵌。

学习要点总结#

Q&A（常见问题）#

Q1：button() 和 buttons() 到底怎么区分？ A1：button() 返回触发本次事件的那个键——在 mousePressEvent 里它就是刚被按下的键，在 mouseReleaseEvent 里是刚被松开的键；在 mouseMoveEvent 里它通常是 NoButton（因为移动动作本身没有”按下某个键”）。buttons() 返回当前所有被按住的键的位或掩码，在按住期间的移动事件里持续包含左键。所以”按下瞬间判断用哪个键”用 button()，“按住期间是否含某键”用 buttons()。

Q2：为什么我的窗口拖不动 / 拖动会跳？ A2：两个最常见原因：(1) 在 mouseMoveEvent 里用了 button()==LeftButton 判断——移动事件 button() 是 NoButton，永远不成立；(2) offset 用了 pos()（相对控件）而 move 用的是 globalPosition()（相对屏幕），坐标系统错配导致跳变。修正为 buttons()&LeftButton 且全程用 globalPosition() 即可。

Q3：Qt5 和 Qt6 在鼠标事件上有差异吗？ A3：事件函数签名基本一致，最大差异在坐标 API：Qt5 用 event->globalPos() 返回 QPoint，Qt6 用 event->globalPosition() 返回 QPointF（更高精度，支持高分屏）。本项目用 Qt6，务必用 globalPosition()。其余 button()/buttons()/wheelEvent 逻辑一致。

Q4：右键图片光标显示不出来怎么办？ A4：先确认 Doraemon.png 在可执行文件运行目录下（Qt 的资源路径 ./ 是进程工作目录）。若缺失，QPixmap 加载为空，QCursor 构造无效但不报错。更稳妥的做法是把图片放进 .qrc 资源文件用 ":/Doraemon.png" 引用，避免路径依赖。

Tips（全局速记）#