章节导航#

• 本章重要 API 函数
• 学习前后依赖
• 1. 概述
• 2. 核心概念与原理
  • 2.1 paintEvent 是”被动”的：你不能主动画
  • 2.2 QPainter 三件套：Pen、Brush、Font
  • 2.3 逻辑坐标与设备坐标
• 3. 关键机制：update 到 paintEvent 的重绘流程
  • 3.1 重绘流程图
  • 3.2 事件合并：连续 update 只重绘一次
• 4. 核心代码解析
  • 4.1 BasePainter：Pen、Brush、渐变与基本形状
  • 4.2 SeniorPainter：QPainterPath 布尔运算与坐标变换
  • 4.3 Ball：QTimer + update 驱动的弹球动画
  • 4.4 main.cpp 与 CMakeLists
• 5. 运行效果与验证
• 容易踩坑（注意点）
• 学习要点总结
  • 核心知识点
  • 关键 API
  • 下一步学习
• Q&A（常见问题）
• Tips（全局速记）

💡 Tips：建议先跑 BasePainter（静态图形）→ 再跑 SeniorPainter（路径与变换）→ 最后跑 Ball（动画）。本工程的 main.cpp 通过注释切换启动哪个类，这种”一个工程多个实验体”的组织方式很适合练手，但要记住：注释掉的类依然会被编译（CMakeLists 里都列着），所以它们的语法错误一样会拦住你。

2.1 paintEvent 是”被动”的：你不能主动画#

paintEvent(QPaintEvent*) 会在以下时机被 Qt 自动调用：

1. 窗口第一次显示（show()）；
2. 窗口被遮挡后又露出来（暴露事件）；
3. 窗口尺寸改变（resize）；
4. 你调用了 update() 或 repaint()；
5. 父窗口重绘波及到它。

关键推论：窗口上的图形不是”画上去就留在那里”的。每次重绘都是从零开始重画整幅内容。所以 paintEvent 必须是幂等的——只依赖成员变量的当前状态，不依赖”上次画了什么”。这也解释了 Ball::paintEvent 里为什么每帧都先 painter.drawRect(rect()) 铺一层黑底：不擦掉旧帧，小球就会拖出一条尾巴（虽然 Qt 默认会用背景色擦除，但显式铺底既是保险也是设计）。

1
// 正确：绘制代码在 paintEvent 里
2
void Ball::paintEvent(QPaintEvent *event) {
3
    QPainter painter(this);      // this 作为 paint device，仅此处合法
4
    painter.drawEllipse(...);
5
}
6

7
// 错误：在普通槽里构造 QPainter(this)
8
void Ball::onTimeOutV1() {
9
    QPainter painter(this);      // 运行期报错：Paint device returned engine == 0
10
    painter.drawEllipse(...);    // 什么也画不出来
11
}

2.2 QPainter 三件套：Pen、Brush、Font#

QPainter 是一个状态机。你先设置状态，再调 drawXxx，图形按当前状态渲染：

三个高频细节：

• setPen(Qt::NoPen) = 不画边框；setBrush(Qt::NoBrush) = 不填充（默认就是不填充）。
• drawText 的颜色由 Pen 决定，不是 Brush。这是最常见的”为什么我的字是黑的”来源。
• QBrush 可以直接用 QGradient 构造，所以渐变填充只需 painter.setBrush(gradient)，不用手写像素插值。

2.3 逻辑坐标与设备坐标#

QPainter 默认的坐标系原点在 widget 左上角，x 向右、y 向下，单位是像素。但一旦你调用 translate/rotate/scale，逻辑坐标就与设备坐标分离了：

1
painter.translate(W/2, H/2);        // 原点移到中心
2
painter.scale(side/200.0, side/200.0); // 逻辑坐标 200×200 映射到实际 side×side
3
// 从此你可以按"200×200 的画布"来思考，尺寸自适应由 scale 负责
4
painter.drawLine(81, 0, 99, 0);    // 这里的 81/99 是逻辑单位，不是像素

这套”先归一化再画”的手法是自绘控件的核心技巧：设计时按固定尺寸（如 200×200）画，运行时用 scale 适配任意窗口大小。SeniorPainter::base03/base04 和 qt21 的 SpeedWidget 都是这个套路。

💡 Tips：原理层面最容易误解的三点：

1. “paintEvent 由系统或 update() 触发”——你不能也不该直接调用 paintEvent(nullptr)。手动调用会绕过 Qt 的双缓冲和裁剪机制，QPainter(this) 在非绘制阶段构造会直接失败。
2. rotate() 旋转的是坐标系，不是图形。rotate(30) 之后你画的直线看起来转了 30°，但真实发生的是”整个纸张转了 30°，笔还是横着走”。想画一圈刻度就是”画一根 → 转 30° → 再画一根”，base03 正是这么干的。
3. 变换是累积的。连续两次 rotate(30) 等于 rotate(60)。所以循环里必须用 save()/restore() 把每次变换隔离开，否则第 n 根刻度会转到 30n 度而不是你算的角度。

3.1 重绘流程图#

下图完整展示了 Ball 的一帧是怎么产生的——从定时器超时到像素上屏。

3.2 事件合并：连续 update 只重绘一次#

注意 Ball 的构造里把同一个 timeout 信号连到了两个槽：

1
connect(m_timer, &QTimer::timeout, this, &Ball::onTimeOutV1);  // 改 X，调 update()
2
connect(m_timer, &QTimer::timeout, this, &Ball::onTimeOutV2);  // 改 Y，调 update()

一次 timeout 会调用两次 update()，但只会产生一次 paintEvent。因为 update() 的实现是”把脏区域并入待重绘区域 + 投递一个 UpdateRequest 事件（若已有待处理的就不再投）“。这是 Qt 的重要优化：你可以放心地在一个逻辑帧里调用 N 次 update()，代价近似于一次。

反过来，如果这里用的是 repaint()，就会真的同步绘制两次，帧率减半且可能撕裂。这正是”优先用 update()”的量化理由。

💡 Tips：流程图里最关键的两个节点是 C（update()）和 E（事件合并）。

• C 是”异步分界线”：它上面是你的业务逻辑（改数据），它下面是 Qt 的渲染流水线。把这条线看清楚，你就永远不会再想”在槽里直接画图”。
• E 是”性能保险丝”：它保证了即使你在一帧里调 100 次 update()，也只重绘一次。这个机制的代价是”update() 之后数据不会立刻上屏”——如果你在 update() 下一行就去读像素，读到的还是旧帧。需要”立刻可见”的极少数场景（如打印前刷新）才用 repaint()。
• 另外注意 M 节点：QPainter 是靠析构来 end() 提交的。所以 QPainter painter(this); 用栈对象是标准写法；若用 new QPainter(this) 忘了 delete，绘制永远不会提交。

4.1 BasePainter：Pen、Brush、渐变与基本形状#

1
void BasePainter::paintEvent(QPaintEvent *event)
2
{
3
    base02();                     // ① 分发到具体实验函数
4
}
5

6
void BasePainter::base01()
7
{
8
    int W = width();
9
    int H = height();
10
    QPen pen(Qt::red, 2, Qt::DashLine, Qt::RoundCap, Qt::RoundJoin);   // ②
11
    QLinearGradient gradient(QPoint(W/4, H/4), QPoint(3*W/4, 3*H/4));  // ③
12
    gradient.setColorAt(0,   Qt::yellow);
13
    gradient.setColorAt(0.5, Qt::green);
14
    gradient.setColorAt(1,   Qt::blue);
15
    painter.setBrush(gradient);   // ④ QGradient 可隐式转 QBrush
16
    painter.setPen(pen);
17
    painter.drawRect(H / 4, W / 4, W / 2, H / 2);                      // ⑤ 注意参数顺序
18
}

• ① paintEvent 只做一件事：转发。这是本工程一个很聪明的组织方式——base01/base02 各自是一个独立实验，切换实验只需改这一行。代价是这些函数必须只在 paintEvent 调用链内被调用，因为它们内部构造了 QPainter(this)。
• ② QPen 的五参数构造一次配好全部描边属性，等价于分别调 setColor/setWidth/setStyle/setCapStyle/setJoinStyle（被注释掉的那段代码就是分步写法）。
  • Qt::DashLine 虚线，Qt::RoundCap 圆头端点，Qt::RoundJoin 圆角拐弯。
  • 线宽为 0 是特殊值：表示”cosmetic pen”，无论怎么 scale 都保持 1 像素宽。若希望线宽随缩放变化，必须显式给 ≥1 的宽度。
• ③④ QLinearGradient(起点, 终点) + setColorAt(位置, 颜色)，位置是 [0,1] 的归一化参数。把它塞给 setBrush 就得到渐变填充——Qt 里渐变属于”画刷”，不是独立的绘制命令，这个归类要记牢。
• ⑤ drawRect(H/4, W/4, W/2, H/2) 的前两个参数写反了：应该是 (x, y, w, h)，即 (W/4, H/4, W/2, H/2)。当前写法把高度的 1/4 当成了 x 坐标。在 resize(500,400) 下 W=500、H=400，画出来是 (100, 125, 250, 200)——图形能出来，只是位置偏了，属于”不报错的逻辑 bug”。base02() 里的 QRect rect(H/4, W/4, W/2, H/2) 犯了同样的错。这是很好的提醒：width()/height() 弄混不会有任何编译或运行警告，只能靠眼睛看。

1
void BasePainter::base02()
2
{
3
    int W = width(), H = height();
4
    QPainter painter(this);
5
    painter.setRenderHint(QPainter::Antialiasing);       // ⑥ 单个 hint 用 setRenderHint
6
    painter.setRenderHint(QPainter::TextAntialiasing);
7
    QRect rect(H / 4, W / 4, W / 2, H / 2);
8
    int redius = qMin(rect.width(), rect.height()) / 3;  // ⑦ 圆角半径取短边的 1/3
9
    // painter.drawRect(rect);
10
    // painter.drawEllipse(rect);
11
    // painter.drawRoundedRect(rect, redius, redius);
12
    // painter.drawArc(rect, 90, 30*16);                 // ⑧ 角度单位 1/16 度
13
    // painter.drawPie(rect, 90, 30*16);
14
    // painter.drawChord(rect, 90, 30*16);               // ⑨ 当前全被注释 → 空白窗口
15
}

• ⑥ 这里用的是单数形式 setRenderHint(hint) 连调两次，这是完全正确的写法。对比 ball.cpp 里的 setRenderHints(QPainter::Antialiasing, QPainter::TextAntialiasing)（复数形式 + 两个 hint），后者的第二个参数被当成 bool on 用了——同一个工程里的两种写法，一个对一个错，非常值得对照记忆。
• ⑦ qMin(w, h)/3 让圆角半径自适应，避免窗口变扁时圆角超过边长。
• ⑧ drawArc/drawPie/drawChord 的角度单位是 1/16 度，所以 30 度写成 30*16 = 480。起始角 90 这里其实也应该乘 16（90*16）才是正 90 度——写 90 实际只有 5.625 度。三者区别：drawArc 只画弧线、drawPie 连圆心成扇形、drawChord 用弦封口成弓形。
• ⑨ 当前 base02() 所有绘制语句都被注释了，所以运行 BasePainter 会得到一个纯空白窗口。这不是 bug，是”实验开关”留在了全关状态。想看效果就取消对应注释——但要意识到：paintEvent 里什么都不画，窗口就只有背景色，这本身也验证了”每帧从零重画”的机制。

4.2 SeniorPainter：QPainterPath 布尔运算与坐标变换#

1
void SeniorPainter::base01()
2
{
3
    QPainter painter(this);
4
    painter.setRenderHints(QPainter::Antialiasing | QPainter::TextAntialiasing);  // ① 正确写法
5
    QPainterPath path1;  path1.addEllipse(0, 0, 100, 100);
6
    QPainterPath path2;  path2.addRect(0, 50, 150, 150);
7
    QPainterPath result = path1.united(path2);       // ② 并集
8
    // QPainterPath result = path2.subtracted(path1);   // 差集
9
    // QPainterPath result = path1.intersected(path1);  // 交集
10
    painter.drawPath(result);
11
}

• ① 注意这里用 | 组合了两个 hint，这是唯一正确的批量写法。与 ball.cpp 的逗号写法形成鲜明对比。

• ② QPainterPath 的三个布尔运算是自绘复杂图形的核心武器：

  • united(other) → 并集（合并两个形状）
  • subtracted(other) → 差集（在自己身上挖掉 other）
  • intersected(other) → 交集（只保留重叠部分）

  被注释的第三行 path1.intersected(path1) 是自己和自己求交，结果就是 path1 本身——显然是笔误（本意应是 path1.intersected(path2)）。

1
void SeniorPainter::base02()
2
{
3
    QPainterPath path1;  path1.addEllipse(0,  0, 100, 100);
4
    QPainterPath path2;  path2.addEllipse(20, 0, 100, 100);
5
    QPainterPath moon = path1.intersected(path2);   // ③ 两圆相交 = 月牙（柳叶形）
6
    painter.translate(50, 100);                     // ④ 先平移
7
    painter.rotate(30);                             // ⑤ 再旋转
8
    painter.fillPath(moon, Qt::darkBlue);           // ⑥ 直接填充，不需要 setBrush
9
}

• ③ 两个错位圆求交得到”柳叶形”（严格说月牙是 subtracted）。这是路径运算最经典的教学例子：复杂形状 = 简单形状做布尔运算，比手写贝塞尔曲线容易一个数量级。
• ④⑤ 变换顺序至关重要：translate 再 rotate，是”移到 (50,100) 后绕该点转 30°“；顺序颠倒则是”绕原点转 30° 后，沿转过的坐标轴移动”——结果完全不同。规律是：变换按书写顺序依次作用于坐标系。
• ⑥ fillPath(path, brush) 是”填充但不描边”的快捷方式，省掉 setBrush + setPen(Qt::NoPen) + drawPath 三步。

1
void SeniorPainter::base03()
2
{
3
    qreal W = width(), H = height();
4
    qreal side = qMin(W, H);                         // ⑦ 取短边保证不变形
5
    painter.translate(W/2, H/2);                     // ⑧ 原点移到窗口中心
6
    painter.scale(side/200.0, side/200.0);           // ⑨ 归一化到 200×200 逻辑画布
7
    painter.setPen(Qt::black);
8
    for (int i = 0; i < 12; i++) {
9
        if (i % 3 == 0) {
10
            painter.save();                          // ⑩ 压栈
11
            QPen pen = painter.pen();
12
            pen.setWidth(3);                         // ⑪ 改了 pen 但忘了 setPen！
13
            painter.drawLine(81, 0, 99, 0);
14
            painter.restore();                       // ⑩ 弹栈
15
        } else {
16
            painter.drawLine(81, 0, 99, 0);
17
        }
18
        painter.rotate(30);                          // ⑫ 每次转 30°，12 次转满 360°
19
    }
20
}

• ⑦⑧⑨ 这三行是自适应自绘控件的标准开场：取短边 → 移原点到中心 → 按 200 单位归一化。做完之后，后续所有坐标都可以按”一张 200×200、原点在中心的纸”来写，窗口无论多大都自动适配。qt21 的 SpeedWidget 开头一字不差地复刻了这个套路。
• ⑩ save()/restore() 必须成对。这里的意图是”只让粗线那一次的 pen 改变生效，不污染后续”。
• ⑪ 这是一个典型的”改了副本却没生效”的 bug：painter.pen() 返回的是 QPen 的值拷贝，pen.setWidth(3) 改的是这个局部副本，必须再 painter.setPen(pen) 才会作用到画家上。当前代码缺了这一行，所以”每 3 根一根粗线”的效果根本没出现——12 根刻度全是同样粗细。这个坑的隐蔽性极高：代码读起来完全合理，编译无警告，只是效果不对。凡是 painter.xxx() 返回值类型不是引用的（pen()、brush()、font()），改完都必须 set 回去。
• ⑫ rotate(30) 累积 12 次刚好 360°。因为在 save/restore 之外，所以每次都在上一次基础上累加——这正是想要的。

base04() 是速度表刻度盘的雏形，也是 qt21 的直接前身：

1
int rangeIndex = 24;
2
for (int i = 0; i <= rangeIndex; ++i) {
3
    qreal startAngle = 150, rangeAngle = 240;                  // ⑬ 从 150° 起，跨 240°
4
    painter.save();
5
    qreal currentRotate = startAngle + (i * (rangeAngle / rangeIndex * 1.0));
6
    painter.rotate(currentRotate);                             // ⑭ 绝对角度（因为有 save/restore）
7
    if (i % 2 == 0) {
8
        painter.setPen(QPen(Qt::black, 2));                    // ⑮ 直接构造并 setPen，正确
9
        painter.drawLine(80, 0, 95, 0);                        // 长刻度
10
        int speedValue = i * 10;
11
        QRect textRect(-15, -10, 30, 20);
12
        painter.translate(70, 0);                              // ⑯ 移到刻度内侧
13
        painter.rotate(-currentRotate);                        // ⑰ 反向转回来，让文字保持水平
14
        painter.drawText(textRect, Qt::AlignCenter, QString::number(speedValue));
15
    } else {
16
        painter.setPen(QPen(Qt::black, 1));
17
        painter.drawLine(85, 0, 95, 0);                        // 短刻度
18
    }
19
    painter.restore();
20
}

• ⑬ 150° 起、240° 跨度是汽车仪表盘的经典布局：底部留 120° 的缺口（360-240），刻度从左下经正上到右下。
• ⑭ 因为循环体被 save/restore 包住，每次进来坐标系都是干净的，所以这里算的是绝对角度（startAngle + i*step），而不是 base03 里的增量式 rotate(30)。两种写法都对，但绝对角度 + save/restore 更易读、不会累积误差。
• ⑮ 对比 base03 的 ⑪，这里 painter.setPen(QPen(Qt::black, 2)) 直接构造新 pen 并设置，一步到位、不会犯”改副本”的错。这是更推荐的风格。
• ⑯⑰ “反向旋转让文字保持水平”是仪表盘绘制最精髓的技巧：坐标系已经转了 currentRotate 度，如果直接 drawText，文字会跟着倾斜（想象把书斜着放）。先 translate(70,0) 移到文字该在的位置，再 rotate(-currentRotate) 把坐标系转回水平，文字就正了。记住这个组合：先移动，后转回。 顺序反了位置就错。

4.3 Ball：QTimer + update 驱动的弹球动画#

1
Ball::Ball(QWidget *parent) : QWidget(parent) {
2
    m_posX = 30;  m_speedX = 50;                    // ① 初始位置与速度
3
    m_posY = 0;   m_speedY = 5;
4
    m_radius = 30;
5
    m_timer = new QTimer(this);                     // ② 有 parent，随 widget 自动销毁
6
    m_timer->start(30);                             // ③ 30ms ≈ 33 FPS
7
    setGeometry(100, 100, 500, 500);
8
    connect(m_timer, &QTimer::timeout, this, &Ball::onTimeOutV1);
9
    connect(m_timer, &QTimer::timeout, this, &Ball::onTimeOutV2);   // ④ 一信号两槽
10
    setGeometry(100, 100, 600, 600);                // ⑤ 重复调用，后者生效
11
}
12

13
void Ball::onTimeOutV1() {
14
    m_posX += m_speedX;
15
    if (m_posX + m_radius > width() || m_posX - m_radius < 0) {
16
        m_speedX = -m_speedX;                       // ⑥ 撞墙反弹：速度取反
17
    }
18
    update();                                       // ⑦ 请求重绘
19
}
20

21
void Ball::onTimeOutV2() {
22
    double g = 0.6;                                 // ⑧ 定义了但从未使用
23
    double bounce = 2;                              // ⑨ 反弹系数 > 1，能量不守恒
24
    m_posY += m_speedY;
25
    if (m_posY + m_radius > height()) {
26
        m_posY = height() - m_radius;               // ⑩ 位置修正，防止陷入墙内
27
        m_speedY = -m_speedY * bounce;
28
    } else if (m_posY - m_radius < 0) {
29
        m_posY = m_radius;
30
        m_speedY = -m_speedY * bounce;
31
    }
32
    update();
33
}
34

35
void Ball::paintEvent(QPaintEvent *event) {
36
    QPainter painter(this);
37
    painter.setRenderHints(QPainter::Antialiasing, QPainter::TextAntialiasing);  // ⑪ 误用
38
    painter.setBrush(Qt::black);
39
    painter.drawRect(rect());                       // ⑫ 铺黑底，擦掉上一帧
40
    painter.setBrush(Qt::yellow);
41
    painter.setPen(Qt::NoPen);                      // ⑬ 无边框
42
    painter.drawEllipse(QPointF(m_posX, m_posY), m_radius, m_radius);  // ⑭ 圆心+半径重载
43
}

• ① 位置和速度都是 double，为动画的亚像素平滑留了余量。m_speedX = 50 意味着每帧横移 50 px——在 30ms 间隔下是 1666 px/s，非常快。
• ② new QTimer(this) 挂在对象树上，不用手动 delete。对比 qt19 里”要 moveToThread 就不能有 parent”，这里不需要跨线程，所以给 parent 是最佳实践。
• ③ start(30) 是 30 毫秒间隔。注意 QTimer 精度受事件循环负载影响，不是硬实时；要求严格帧率应该用 QElapsedTimer 测实际间隔并做插值。
• ④ 一个信号连两个槽：timeout 同时触发 X 方向和 Y 方向的更新。执行顺序按 connect 顺序（V1 先，V2 后）。两个槽各调一次 update()，但只重绘一次（见 3.2）。这个拆分方式教学意义大于工程意义——真实项目通常合成一个 advanceFrame()。
• ⑤ setGeometry 被调了两次，第二次 (100,100,600,600) 覆盖第一次。这不是错误，只是遗留代码。但要注意 m_posX/m_posY 的边界判断依赖 width()/height()，所以窗口尺寸变了，弹球范围会自动跟着变——这是用 width() 而非硬编码常量的好处。
• ⑥ 反弹的本质是速度取反，一行 m_speedX = -m_speedX 就够了。注意判断条件用的是 m_posX + m_radius > width()（球的右边缘超出）而不是 m_posX > width()（球心超出），这样球不会半个身子插进墙里。
• ⑦ update() 是动画的引擎。删掉它，m_posX 依然在变，但屏幕永远停在第一帧——因为没人告诉 Qt “该重绘了”。这是最能说明”数据变化 ≠ 画面变化”的实验：注释掉 update() 跑一遍，是本篇最推荐的动手验证。
• ⑧ double g = 0.6; 定义后从未使用——这是重力加速度的占位符。完整的抛体运动应该是 m_speedY += g;（每帧加速下落）。当前代码缺这一行，所以 Y 方向是匀速运动，看起来像”直上直下的乒乓球”而非”自由落体”。想补全物理效果，加上这一行即可。
• ⑨⑩ bounce = 2 意味着每次撞墙速度翻倍——能量不守恒，球会越来越快，几帧之后就快到”每帧跨越整个窗口”，肉眼看到的是疯狂闪烁。物理上正确的反弹系数应该 0 < bounce < 1（如 0.8 表示损失 20% 动能）。⑩ 的位置修正 m_posY = height() - m_radius 是必要的防护：速度太大时球可能一帧就冲出边界很远，不修正就会”卡在墙外反复取反”（抖动 bug）。位置修正 + 速度取反，是所有碰撞响应的标准两步。
• ⑪ 又是 setRenderHints(hint1, hint2) 的误用（详见本篇 API 表格的 Tips）。实际效果 = 只开了 Antialiasing。好在这里没有文字，所以看不出差别——这就是这个 bug 能长期存活的原因。
• ⑫ drawRect(rect()) 铺满黑底是”清屏”。rect() 返回 widget 的整个区域。如果去掉这行，Qt 会用默认背景色擦除（因为 autoFillBackground 等机制），但显式铺色能保证背景确定、也方便改成渐变背景。
• ⑬ setPen(Qt::NoPen) 让小球没有黑边，视觉更干净。忘了这句会得到一个带 1px 黑色描边的球。
• ⑭ drawEllipse(QPointF center, rx, ry) 是”圆心 + 两半径”重载。如果误用 drawEllipse(QRectF) 重载传同样的数字，球会偏移半个直径——这是 QPainter 最容易搞错的重载之一。

4.4 main.cpp 与 CMakeLists#

1
// #include "BasePainter.h"
2
#include "ball.h"
3
#include <QApplication>
4

5
int main(int argc, char *argv[]) {
6
    QApplication a(argc, argv);
7
    // BasePainter w;
8
    Ball ball;
9
    ball.show();
10
    return QCoreApplication::exec();   // ① 静态调用，能跑但不推荐
11
}

• ① QCoreApplication::exec() 是 static 函数，所以这样写能编译能运行。但语义上应该写 a.exec()——表达”运行我创建的这个应用实例”。用静态形式容易让人误以为”不需要 QApplication 对象”，而实际上没有 a 这行程序会直接崩（QWidget 需要 QApplication）。
• 切换实验体的方式是注释/反注释 include 和对象声明。三个类（BasePainter、SeniorPainter、Ball）在 CMakeLists.txt 里全部列入了源文件，都会被编译，只是运行时只实例化一个。SeniorPainter 甚至没有在 main.cpp 里出现过，想看它的效果需要自己加两行。

1
qt_add_executable(qt20_tst_painterbase
2
    WIN32 MACOSX_BUNDLE
3
    main.cpp
4
    BasePainter.cpp BasePainter.h BasePainter.ui   # ② .ui 列入了但代码里没用
5
    ball.h ball.cpp
6
    seniorpainter.h seniorpainter.cpp
7
)
8
target_link_libraries(... PRIVATE Qt::Core Qt::Widgets)   # ③ 绘图不需要额外模块

• ② BasePainter.ui 被列入源文件，但 BasePainter.cpp 里既没有 ui_BasePainter.h 也没有 Ui:: 相关代码——它是 Qt Creator 建类时自动生成的空壳。这说明自绘控件通常不需要 .ui 文件：界面就是代码画出来的，没有可拖拽的子控件。
• ③ QPainter、QPen、QBrush、QPainterPath 全在 Qt::Gui 模块，而 Qt::Widgets 已经依赖 Qt::Gui，所以只链 Core + Widgets 就够了。如果你要做不带窗口的离屏绘制（画到 QImage 存文件），只链 Qt::Gui 即可，不需要 Widgets。

💡 Tips：这几段代码里藏着的关键细节，一句话一条：

• update() 触发重绘，不是立即重绘；删掉它动画就死，改成 repaint() 会同步绘制两次。
• painter.pen() 返回值拷贝，base03 里改了宽度却没 setPen 回去，“每三根一根粗线”的效果根本没生效。凡是返回值不是引用的 getter，改完必须 set 回。
• setRenderHints(a, b) 的第二参是 bool，本工程三处误用；正确写法是 setRenderHints(a | b)。
• save()/restore() 必须成对，循环里画多个旋转元素时是刚需，漏掉一次后面全乱。
• drawArc 用 1/16 度，rotate 用普通度数，同一个类两套单位。
• bounce=2 让能量不守恒、g=0.6 定义了没用——这两个”半成品”恰好演示了动画代码里物理参数的正确用法。

核心知识点#

1. paintEvent 是唯一合法的绘制入口，且是被动调用的。 你能做的是改数据 + update()，绘制时机由 Qt 决定。每次重绘都从零重画整幅内容，所以 paintEvent 必须幂等。
2. QPainter 是状态机：先设 QPen（描边）/QBrush（填充）/QFont（字体），再调 drawXxx。drawText 的颜色由 Pen 决定。
3. update() 会合并：一帧内调 N 次只重绘一次，脏区域取并集。这是性能保险丝，也是”数据改完画面不立刻变”的原因。
4. 坐标变换是自绘控件的核心技巧：translate 到中心 + scale 归一化 → 按固定逻辑尺寸设计，自动适配任意窗口大小。变换按书写顺序累积作用，必须用 save/restore 隔离。
5. QPainterPath 的布尔运算（united/subtracted/intersected） 让复杂形状可以由简单形状拼出来，是画月牙、镂空指针、异形按钮的标准手段。
6. QTimer + update() = 动画循环：定时器改数据 → update() → paintEvent 画新帧。这是 Qt 里最简单也最通用的动画模式。

关键 API#

下一步学习#

• qt21 自定义控件：速度表。本篇的 SeniorPainter::base04() 已经画出了刻度盘，qt21 会把它封装成一个可复用的 SpeedWidget 类，加上 setSpeed() 接口、QPainterPath 镂空指针，并用 QLineEdit + QPushButton 驱动。
• 之后可延伸到：QGraphicsView 图形视图框架（大量图元 + 交互）、QPropertyAnimation 属性动画（比手写 QTimer 更平滑）、QChart 图表模块。

💡 Tips：本篇与 qt21 的挂钩点非常直接——qt21 的 SpeedWidget::paintEvent 前四行就是本篇 base03/base04 的开场三步（translate 到中心 / scale 归一化 / 循环 rotate 画刻度），而它的镂空指针用的正是本篇 base01 学的 subtracted()。可以说 qt20 是零件，qt21 是成品。读完本篇直接进 qt21，会有”原来这些零件是这么装起来的”的畅快感。

最容易忽视的细节#

1. QPainter 靠析构提交绘制。 QPainter painter(this); 是栈对象，函数结束自动 end()。如果写 auto *p = new QPainter(this); 而忘了 delete，绘制内容永远不会出现在屏幕上，而且不会有任何报错——只是”什么都没画出来”。
2. paintEvent 的 event 参数几乎总被忽略，但它是局部重绘的钥匙。 event->rect() 告诉你哪块区域脏了。本工程三个 paintEvent 都没用它（全量重绘），在小控件上没问题，但画复杂图表时用上它能省掉大量无用绘制。
3. 一个信号连多个槽时，update() 调用次数与重绘次数不是 1:1。 Ball 一帧调两次 update() 只重绘一次。这意味着你不能靠”数 update 调用次数”来推断帧率，要在 paintEvent 里计数。
4. width()/height() 在构造函数里可能还不是最终值。 构造时布局还没生效，拿到的是默认或 resize() 设定的值。所以依赖尺寸的计算必须放在 paintEvent 或 resizeEvent 里，不能在构造函数里算好存起来。本工程三个类都在 paintEvent 里现取 width()，这是正确的。
5. 被注释掉的类依然会被编译。 SeniorPainter 在 main.cpp 里从未出现，但它在 CMakeLists.txt 里，所以它的语法错误照样会拦住构建。这既是保护（不会积累坏代码）也是负担（改一个不用的类也要保证能编过）。

踩坑记录#

• “改了线宽却没变化”排查了很久，最后发现是 painter.pen() 返回值拷贝。 这类”getter 返回值 vs 引用”的坑在 Qt 里很普遍（pen()、brush()、font()、QWidget::palette() 都是值语义）。养成条件反射：从 Qt 对象取出的配置类对象，改完一定要 set 回去。
• setRenderHints(A, B) 这个误用在同一个工程里出现了三次，而 setRenderHints(A | B) 的正确写法就在隔壁文件。 说明这类错误极易”复制传播”——写对一次不代表下次会写对。解决办法是把常用绘图初始化封装成一个小函数：static void setupPainter(QPainter &p) { p.setRenderHints(QPainter::Antialiasing | QPainter::TextAntialiasing); }，一处正确处处正确。
• bounce = 2 造成的”闪烁”最初被误判为”帧率问题”。 实际是数值爆炸——速度大到每帧跨越整个窗口。教训：动画异常先打印数值，再怀疑渲染。qDebug() << m_posY << m_speedY; 一行就能定位。
• double g = 0.6; 定义了却没用，编译器只给一个 unused variable 警告（还常被忽略）。 这种”写了一半的物理模型”是学习代码的常态。读别人的示例代码时，注意那些声明了但没用到的变量——它们往往标记着”作者本来想做但没做完的事”，是很好的练手切入点。

与后续章节的衔接#

1. → qt21 速度表：SeniorPainter::base04() 的刻度盘代码几乎原封不动地进化成了 SpeedWidget::paintEvent。区别是 qt21 把它封装成了带 setSpeed() 接口的可复用控件，并用 QPainterPath::subtracted 做了镂空指针。本篇的每个技巧在 qt21 都会被用到。
2. → qt22 数据库：看起来无关，但”把查询结果画成图表”是数据库 + 绘图的经典组合。本篇的 paintEvent + update() 模式就是数据可视化的渲染层。
3. → 与 qt19 线程的呼应：update() 走事件队列，和跨线程信号槽是同一套机制。当绘图数据来自子线程时，链路是 worker emit dataReady(v) → 主线程槽 setValue(v) → update() → paintEvent。qt19 + qt20 + qt21 三篇合起来，就是一条完整的”后台采集 → 线程安全传递 → 自定义可视化”工业级管线。
4. → 后续 QGraphicsView / Qt Quick：本篇是”手动挡”——你管理每一次绘制。QGraphicsView 是”自动挡”——你只描述图元，框架管脏区、层次、碰撞检测。学过手动挡再用自动挡，你会明白框架帮你做了什么、以及它的开销在哪。

设计决策思考#

• 为什么 Qt 要求绘制只能在 paintEvent 里？为什么不允许随时画？ 因为现代 GUI 都是双缓冲 + 脏区合成的。窗口内容存在一块后备缓冲里，系统在合适时机把它合成到屏幕。如果允许你随时往窗口上画，就会出现”画了一半被合成上屏”的撕裂，以及”缓冲被系统重建后你的绘制丢失”的问题。把绘制收敛到 paintEvent 这一个时机，Qt 才能保证”每次绘制开始时缓冲是有效的、结束后一次性提交”。代价是你必须接受”声明式重绘”的思维：不是”我去画”，而是”我脏了，请重画我”。
• 为什么 update() 要合并而不是每次都画？ 因为业务代码里一次逻辑更新常常涉及多个属性变化（本例的 X、Y 分两个槽改），每个都”顺手” update() 一下是最自然的写法。如果不合并，一帧就会重绘 N 次，而屏幕刷新率是固定的（60/120 Hz），多出来的绘制全是浪费。合并机制让”随手调 update() 是安全的”成为一条可以放心遵守的规则——这大幅降低了自绘控件的心智负担。这也是为什么 Qt 不提供”批量更新开始/结束”的显式 API：合并已经自动做了。
• 为什么坐标变换设计成”变换坐标系”而不是”变换图形”？ 因为变换坐标系可以让同一段绘制代码复用在不同位置/角度/尺寸上。base03 里 12 根刻度线的代码是同一行 drawLine(81,0,99,0)，靠 rotate(30) 转 12 次画出一圈——如果是”变换图形”，你就得算出 12 组不同的端点坐标（涉及 sin/cos）。这个设计把三角函数计算从业务代码里赶了出去，是”用变换换取简洁”的经典权衡。代价是必须理解”累积”和 save/restore，这也是初学者最大的门槛。
• 为什么 QPainterPath 提供布尔运算，而不是让用户自己拼曲线？ 因为”两个形状的交/并/差”是人类描述复杂形状最自然的方式（月牙 = 两圆相减、镂空指针 = 大三角减小三角）。而底层实现需要多边形裁剪算法（Weiler-Atherton 之类），普通开发者写不对也不该写。Qt 把这个复杂度封装成三个方法，让”复杂形状”的成本从”研究计算几何”降到”想清楚用哪个运算”。这是库设计中”抽象层次要匹配用户的心智模型”的好例子。