章节导航#

• 本章重要 API 函数
• 学习前后依赖
• 1. 概述
• 2. 核心概念与原理
  • 2.1 自定义控件的三要素
  • 2.2 坐标归一化：按 200×200 设计，适配任意尺寸
  • 2.3 镂空图形 = 大路径减小路径
• 3. 关键机制：一次 setSpeed 到指针转动的完整链路
  • 3.1 数据驱动重绘流程图
  • 3.2 角度映射公式推导
• 4. 核心代码解析
  • 4.1 SpeedWidget.h：最小对外接口
  • 4.2 paintEvent 第一段：坐标归一化
  • 4.3 paintEvent 第二段：循环画刻度与数字
  • 4.4 paintEvent 第三段：镂空指针
  • 4.5 mainwin.cpp：本工程最值得注意的几处写法
• 5. 运行效果与验证
• 容易踩坑（注意点）
• 学习要点总结
  • 核心知识点
  • 关键 API
  • 下一步学习
• Q&A（常见问题）
• Tips（全局速记）

💡 Tips：本篇的正确读法是对着 qt20 的 SeniorPainter::base04() 一起读。qt21 的 paintEvent 有大半是 base04 的翻版，真正新增的只有两块：setSpeed() 接口 + 镂空指针。把”哪些是复用的、哪些是新增的”分清楚，学习效率会高一倍。

2.1 自定义控件的三要素#

一个合格的自绘控件必须有且只需有三样东西：

1
class SpeedWidget : public QWidget {
2
    Q_OBJECT
3
public:
4
    void setSpeed(qreal speed);          // ② 对外接口：改状态 + 触发重绘
5
protected:
6
    void paintEvent(QPaintEvent*) override;  // ③ 外观：完全由状态决定
7
private:
8
    qreal m_speed = 0;                   // ① 内部状态：唯一的数据源
9
};

• ① 内部状态：控件”当前该显示什么”的全部信息。必须 private，且有默认值（这里 = 0，保证控件在还没被 setSpeed 前也能正确绘制）。
• ② 对外接口（setter）：固定两句——改状态，然后 update()。少了 update()，数据变了画面不动；多做别的事（比如直接画图）就破坏了”绘制只在 paintEvent”的规则。
• ③ paintEvent：纯函数式——只读 m_speed 和 width()/height()，不修改任何状态，不依赖”上次画了什么”。这保证了无论何时被调用（窗口遮挡后恢复、resize、setSpeed 触发）结果都一致。

这个三段式看起来简单到不值一提，但它是 Qt 全部控件（包括 QSlider、QProgressBar）的内部结构。记住它，你就掌握了自定义控件的 80%。

2.2 坐标归一化：按 200×200 设计，适配任意尺寸#

自绘控件最棘手的问题是”窗口大小会变”。硬编码像素（drawLine(180, 200, 195, 200)）在 400px 的控件上好看，在 800px 上就缩在角落。解决方案是坐标归一化：

1
int W = width();
2
int H = height();
3
painter.translate(W/2.0, H/2.0);       // ① 原点搬到控件中心
4
painter.scale(W/200.0, H/200.0);       // ② 逻辑 200×200 → 实际 W×H
5
// 此后所有坐标都按"一张 200×200、原点在中心、四边到边界各 100"的纸来写
6
painter.drawLine(80, 0, 95, 0);        // ③ 距中心 80~95 处的一根横线

做完这两步，你就在一个固定尺寸的虚拟画布上作画：

• 坐标范围是 x ∈ [-100, 100]、y ∈ [-100, 100]；
• 80 表示”从中心到边界的 80%“处，控件放大缩小它都在同一相对位置；
• 所有尺寸、字号、线宽都自动跟着缩放。

这是自绘控件最重要的一个模式，qt20 的 base03/base04 已经预演过，qt21 原封不动地复用。

2.3 镂空图形 = 大路径减小路径#

指针如果只是一个实心三角形，视觉上很”廉价”。真实仪表盘的指针往往是中空的箭头轮廓。手写这个轮廓需要 6~8 个点还要处理拐角，但用路径差集只需两行：

1
QPainterPath bigNeedle;    // 外轮廓：底宽 8、长 80 的细长三角
2
bigNeedle.addPolygon(QPolygonF({QPointF(0,4), QPointF(80,0), QPointF(0,-4)}));
3
QPainterPath smallNeedle;  // 内轮廓：稍小一圈的同形三角
4
smallNeedle.addPolygon(QPolygonF({QPointF(4,2), QPointF(60,0), QPointF(4,-2)}));
5
QPainterPath finalNeedle = bigNeedle.subtracted(smallNeedle);   // 大减小 = 中空

结果是一个”只有边框、内部被挖空”的箭头。这个技巧的通用性极强：镂空箭头、环形进度条（大圆减小圆）、月牙、异形按钮，全是同一招。

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

1. setSpeed() 里的 update() 不是可选的礼貌，而是必需的。 删掉它，m_speed 会被正确改写，但屏幕上的指针一动不动——直到你偶然拖动窗口触发了重绘，指针才”跳”到新位置。这个现象非常迷惑（“有时候能动有时候不能”），根因就是漏了 update()。
2. scale() 之后，所有数字的含义都变了。 drawLine(80, 0, 95, 0) 里的 80 不是 80 像素，是”200 单位画布里的 80 单位”。同理 setPointSize(6) 也不是 6pt。看到 scale 就要切换思维单位，这是读自绘代码的必备开关。
3. scale(W/200.0, H/200.0) 用了两个不同的比例，控件非正方形时会变形。 圆盘会被拉成椭圆、文字会被横向拉伸。qt20 的 base03/base04 用的是 side = qMin(W,H) 然后 scale(side/200.0, side/200.0)（等比缩放），那才是更稳妥的写法。qt21 这里的差异是本工程最值得注意的一处细节，详见 4.2。

3.1 数据驱动重绘流程图#

3.2 角度映射公式推导#

指针角度这一行是整个控件的数学核心：

1
qreal speedAngle = startAngle + (m_speed / max_speed) * rangeAngle;
2
//                  150       + (speed / 240)         * 240

拆解它：

270° 顺时针（因为 rotate 顺时针为正）从”三点钟方向为 0°“起算，落在正上方——120 km/h 是满量程的一半，指针指正上，完全符合直觉。

这个公式是所有量程类控件的通用模板：温度计、油量表、进度环、音量旋钮，把 startAngle/rangeAngle/max 三个常量换掉就能直接用。

💡 Tips：流程图里最关键的三个节点：

• E 判断节点（ok 检查）：这是本工程唯一的输入校验。它的存在保证了”输入 abc 不会让指针乱跳”，但它选择了静默丢弃——用户不知道自己输错了。工程化改进应该是 edt_value->setStyleSheet("border:1px solid red") 或弹提示。
• I 节点（update()）：整个链路的异步分界线。它上面是数据流（同步、立即完成），下面是渲染流（异步、由事件循环调度）。理解这条线，就理解了”为什么 setSpeed 返回后画面还没变”。
• M → O 的顺序：刻度和指针共用同一个归一化坐标系，但刻度循环内部有自己的 save/restore，所以画完刻度后坐标系回到”已归一化、未旋转”的干净状态，指针才能从 rotate(speedAngle) 正确起算。如果刻度循环漏了 restore，指针的角度会被累积的旋转污染——这是最难排查的一类 bug。

4.1 SpeedWidget.h：最小对外接口#

1
class SpeedWidget : public QWidget {
2
    Q_OBJECT;                                        // ① 多了个分号
3
public:
4
    explicit SpeedWidget(QWidget *parent = nullptr);
5
    ~SpeedWidget() override = default;               // ② 默认析构足够
6
    void setSpeed(qreal speed);                      // ③ 唯一的对外接口
7
protected:
8
    void paintEvent(QPaintEvent *event) override;    // ④ protected + override
9
private:
10
    qreal m_speed = 0;                               // ⑤ 唯一状态，有默认值
11
};

• ① Q_OBJECT; 后面这个分号是多余的。Q_OBJECT 展开是一大段声明（含 public: 访问说明符），末尾已经自带分号。多写一个分号会产生一条空声明语句——C++11 起允许类内出现多余分号，所以 MinGW/GCC 编译通过，但 MSVC 的某些警告等级和 clang-tidy 会提示。规范写法是不加分号。
• ② ~SpeedWidget() override = default; ——控件没有裸指针成员，默认析构就够。写 override 是好习惯（基类 QWidget 的析构是 virtual）。
• ③ setSpeed 不是 slot 也不是信号，就是个普通成员函数。这完全够用——MainWin 通过 lambda 直接调用它。如果希望它能被 connect 到别的信号（比如 qt19 的 worker 信号），把它移到 public slots: 下即可（Qt5 新语法下普通成员函数也能连，但声明为 slot 更明确表达意图）。
• ④ paintEvent 必须是 protected（Qt 的设计约定，外部不该调用它）且必须 override。漏了 override 而把参数类型写错（如写成 QEvent*）会变成”新函数”而不是重写，编译通过但永远不会被调用——控件一片空白。override 关键字能在编译期拦住这个错误。
• ⑤ m_speed = 0 的默认值很重要。控件在被 show() 后、setSpeed() 被调用前就会收到第一个 paintEvent。如果 m_speed 未初始化，那次绘制会用随机值算角度，指针指向不确定方向（甚至 NaN 导致绘制异常）。自定义控件的所有状态成员都必须有确定的初值。

4.2 paintEvent 第一段：坐标归一化#

1
void SpeedWidget::paintEvent(QPaintEvent *event)
2
{
3
    QPainter painter(this);
4
    painter.setRenderHints(QPainter::Antialiasing, QPainter::TextAntialiasing);  // ①
5
    int W = width();
6
    int H = height();
7
    painter.translate(W/2.0, H/2.0);      // ② 原点移到中心
8
    painter.scale(W/200.0, H/200.0);      // ③ 归一化，但用了两个不同比例

• ① setRenderHints(hintA, hintB) 又是那个误用（详见 qt20 笔记）。签名是 setRenderHints(RenderHints hints, bool on = true)，第二个参数 QPainter::TextAntialiasing 的枚举值非 0，被隐式转成 true。实际效果 = 只开了 Antialiasing，文字抗锯齿没开。 本工程画了 13 处文字（12 个刻度数字 + km/h），所以这个 bug 在这里是能看出来的——数字边缘比开了文字抗锯齿时略毛糙。正确写法：

  1
  painter.setRenderHints(QPainter::Antialiasing | QPainter::TextAntialiasing);

  这是本工程最值得动手修的一处。修完前后放大截图对比，能直观感受到文字渲染质量的差别。

• ② translate(W/2.0, H/2.0) 用 2.0 而不是 2 保证浮点除法——W/2 在 W 为奇数时会丢半个像素，导致图形轻微偏移。这个 .0 是有意义的。

• ③ scale(W/200.0, H/200.0) 是本工程最值得注意的一处设计选择：它用了 X、Y 两个独立的缩放比例。后果是——

  控件尺寸	sx	sy	效果
  400×400（正方形）	2.0	2.0	✅ 圆盘是正圆，文字正常
  400×200（扁）	2.0	1.0	❌ 圆盘被压成椭圆，文字被横向拉宽
  200×400（高）	1.0	2.0	❌ 圆盘被拉成竖椭圆

  MainWin 里 resize(400,420) 且表盘占 9/10 宽度，所以启动时表盘区域约 360×420 —— 已经不是正方形，仪表盘实际上是轻微竖向拉伸的椭圆。用鼠标把窗口拖成很扁的形状，会看到明显的变形。

  对比 qt20 的正确做法：

  1
  qreal side = qMin(W, H);              // 取短边
  2
  painter.scale(side/200.0, side/200.0); // 等比缩放，永不变形

  SeniorPainter::base03/base04 用的就是这个等比写法。qt21 反而”退化”了——这提醒我们：代码演进不总是单向变好的，抄自己以前的代码时也要盯住关键行。

  为什么等比更好？因为仪表盘的语义是”圆盘”，圆变椭圆就失真了。少数情况下（如横向拉伸的条形图）非等比缩放才是想要的。

4.3 paintEvent 第二段：循环画刻度与数字#

1
    qreal startAngle = 150;
2
    qreal rangeAngle = 240;
3
    for (int i = 1; i <= 24; i++)                     // ① 注意从 1 开始
4
    {
5
        painter.save();                               // ② 压栈，隔离本次变换
6
        qreal cur = startAngle + (i * (rangeAngle/24.0));   // ③ 绝对角度
7
        painter.rotate(cur);
8
        if (i % 2 == 0) {
9
            painter.setPen(QPen(Qt::darkRed, 2));     // ④ 直接构造 + setPen，正确写法
10
            painter.drawLine(80, 0, 95, 0);           // ⑤ 长刻度
11
            int speed_value = i * 10;                 // ⑥ 刻度值
12
            painter.translate(70, 0);                 // ⑦ 移到文字位置
13
            painter.rotate(-cur);                     // ⑧ 反向转回，文字保持水平
14
            QRect textRect(-15, -10, 30, 20);
15
            QFont font = painter.font();
16
            font.setPointSize(6);
17
            painter.setFont(font);                    // ⑨ 改完 set 回去，正确
18
            painter.drawText(textRect, Qt::AlignCenter, QString::number(speed_value));
19
        } else {
20
            painter.setPen(QPen(Qt::yellow, 1));      // ⑩ 短刻度用黄色细线
21
            painter.drawLine(80, 0, 90, 0);
22
        }
23
        painter.restore();                            // ② 弹栈
24
    }

• ① for (int i = 1; i <= 24; i++) 从 1 开始，这是本工程一个隐含的问题。当 i=1 时 cur = 150 + 10 = 160°，也就是说 0 km/h 刻度线（应在 150°）根本没画。对比 qt20 的 base04 用的是 for (int i = 0; i <= rangeIndex; ++i)（从 0 开始，画 25 根，含起点）。

  后果：表盘最左下角少了一根刻度和”0”这个数字，第一根出现的数字是 i=2 时的”20”。而指针在 m_speed=0 时会指向 150° 位置——那里空无一物。运行时能明显看到”指针零位没有刻度”。改成 for (int i = 0; i <= 24; i++) 即可修复。

• ② save()/restore() 包住整个循环体，保证每次进入循环时坐标系都是”已归一化、未旋转”的干净状态。这样 ③ 才能用绝对角度。如果去掉这一对，第 i 次的实际旋转会是前 i 次 cur 的累加，刻度瞬间乱成一团——这是本篇最不能删的两行。

• ③ cur = 150 + i * (240/24.0) = 150 + i*10。注意 240/24.0 写成浮点除法，若写 240/24 是整数除法得 10（这里恰好整除所以没出错，但换成 rangeAngle/25 就会因整除丢精度）。角度计算永远用浮点。

• ④ painter.setPen(QPen(Qt::darkRed, 2)) —— 直接构造新 pen 并设置，避免了 qt20 base03 里”改 painter.pen() 副本忘了 set 回”的经典 bug。这个写法值得学：一步到位，不给自己犯错的机会。

• ⑤⑩ 长刻度 drawLine(80,0,95,0) 长 15 单位、粗 2；短刻度 drawLine(80,0,90,0) 长 10 单位、粗 1。注意两者起点都是 80，所以是”从内向外延伸不同长度”。qt20 的 base04 用的是长刻度 (80,0,95,0)、短刻度 (85,0,95,0) ——“外端对齐、内端不同”。两种风格都常见：外端对齐更整齐（像真实仪表），内端对齐更有层次。

• ⑥ speed_value = i * 10，配合 i 步进 2（只有偶数画数字），所以数字序列是 20、40、60 …… 240，间隔 20。加上缺失的 0，正好是标准车速表标注。

• ⑦⑧ “先 translate 再反向 rotate”是仪表盘文字水平的标准技巧（qt20 已详述）。这里 translate(70, 0) 把原点移到距中心 70 单位处（刻度线内侧），然后 rotate(-cur) 把坐标系转回水平。顺序绝对不能反：先反向转再平移，70 就会沿水平方向走，文字全跑到右边去。

• ⑨ QFont font = painter.font(); font.setPointSize(6); painter.setFont(font); —— 三步齐全。注意 painter.font() 和 painter.pen() 一样返回值拷贝，这里正确地 set 回去了。另外 setPointSize(6) 在 scale 之后意味着实际渲染字号约 6 × (W/200)，在 360px 宽时约 10.8pt，视觉上正合适。

• ⑩ 短刻度用 Qt::yellow，长刻度用 Qt::darkRed。这是纯审美选择，但在白色默认背景上黄色对比度很低，短刻度几乎看不见。改成深色（如 Qt::darkGray）或者给控件铺个深色底会好很多——真实仪表盘几乎都是深底亮字。

4.4 paintEvent 第三段：镂空指针#

1
    qreal max_speed = 240;                            // ① 满量程，与刻度上限一致
2
    painter.save();
3
    qreal speedAngle = startAngle + (m_speed/max_speed) * rangeAngle;   // ② 核心公式
4
    painter.rotate(speedAngle);
5
    // 镂空效果
6
    QPainterPath bigNeedle;
7
    bigNeedle.addPolygon(QPolygonF({QPointF(0,4), QPointF(80,0), QPointF(0,-4)}));   // ③
8
    QPainterPath smallNeedle;
9
    smallNeedle.addPolygon(QPolygonF({QPointF(4,2), QPointF(60,0), QPointF(4,-2)})); // ④
10
    QPainterPath finalNeedle = bigNeedle.subtracted(smallNeedle);       // ⑤ 大减小
11
    painter.setBrush(QColor(255,60,60));              // ⑥ 亮红填充
12
    painter.setPen(QPen(Qt::darkRed, 1));             // ⑦ 深红描边
13
    painter.drawPath(finalNeedle);
14
    painter.restore();
15
    // 画单位
16
    painter.save();
17
    QRect textRect(-20, 60, 40, 20);                  // ⑧ 中心下方
18
    QFont font = painter.font();
19
    font.setPointSize(12);
20
    painter.setFont(font);
21
    painter.drawText(textRect, Qt::AlignCenter, "km/h");
22
    painter.restore();
23
}

• ① max_speed = 240 和刻度的 24 × 10 = 240 必须一致，否则指针指向和刻度标注对不上。当前是硬编码的两处”240”（一处在循环的 i*10，一处在这里），改量程时要同时改两处，很容易漏。工程化改法是提成一个成员常量：

  1
  static constexpr qreal kMaxSpeed = 240.0;
  2
  static constexpr int   kTickCount = 24;
  3
  // 刻度值 = i * (kMaxSpeed / kTickCount)

  这样量程只有一个真相来源。“同一个魔法数字在代码里出现两次”永远是重构信号。

• ② 角度映射公式（推导见 3.2）。注意 m_speed/max_speed 没有做钳位：输入 500 会算出 150 + 2.08*240 = 650°，指针转过一圈半指到奇怪的位置；输入 -100 会指到 150° 左侧。健壮写法应该 m_speed = qBound(0.0, speed, kMaxSpeed); 在 setter 里就钳住。

• ③④ 两个三角形的点集设计：

  • 大三角 (0,4) → (80,0) → (0,-4)：底边在原点处宽 8 单位，尖端伸到 80 单位处。这是一个细长的等腰三角形。
  • 小三角 (4,2) → (60,0) → (4,-2)：底边在 x=4 处宽 4，尖端到 60。整体比大三角小一圈且缩在里面。
  • 关键是小三角必须完全包含在大三角内部，否则 subtracted 会切出奇怪的形状。这里 (4,2) 在大三角内、(60,0) 在大三角轴线上且 60<80，满足条件。

• ⑤ subtracted() 返回新路径。写成 bigNeedle.subtracted(smallNeedle); 丢弃返回值，编译通过但指针会是实心的——一个”看起来正常只是不镂空”的静默失败。

• ⑥⑦ 填充亮红 QColor(255,60,60) + 描边深红。因为路径是镂空的，填充只作用于”大三角减小三角”的环状区域，中间的空洞会透出背景色。这就是镂空效果的视觉来源。如果把 setBrush 去掉，就只剩内外两圈轮廓线——也是一种风格。

• ⑧ QRect textRect(-20, 60, 40, 20) 在归一化坐标里，即”中心下方 60~80 单位处、宽 40 单位”的区域。因为此时坐标系已经 restore 回未旋转状态，所以文字是水平的、位置固定在表盘下半部。setPointSize(12) 在 scale 后约合 21pt，是刻度数字的两倍，视觉层次合理。

• 一个可优化点：bigNeedle/smallNeedle/finalNeedle 每帧都重新构造和做布尔运算。指针形状其实永远不变，只有角度在变，完全可以把 finalNeedle 缓存成成员变量，构造时算一次。当前实现在 30 FPS 下不会有问题（路径只有 3 个点，运算是微秒级），但如果指针形状复杂（几十个控制点 + 贝塞尔），这就是必须做的优化。

4.5 mainwin.cpp：本工程最值得注意的几处写法#

1
class MainWin : public QWidget          // ① 没有 Q_OBJECT 宏
2
{
3
public:
4
    explicit MainWin(QWidget *parent = nullptr);
5
    ~MainWin() override = default;
6
private:
7
    SpeedWidget *m_speed_meter;
8
};

1
MainWin::MainWin(QWidget *parent)       // ② parent 参数被接收但没传给基类！
2
{
3
    auto main_layout = new QHBoxLayout(this);
4
    auto ctl_layout  = new QVBoxLayout();
5
    auto ctl_Widget  = new QWidget(this);
6
    ctl_Widget->setLayout(ctl_layout);              // ③ 手动 setLayout
7
    auto btn_start = new QPushButton("速度设置");    // ④ 无 parent，靠 addWidget 收养
8
    auto edt_value = new QLineEdit();
9
    ctl_layout->addWidget(edt_value);
10
    ctl_layout->addWidget(btn_start);
11

12
    m_speed_meter = new SpeedWidget();              // ④ 同上
13
    main_layout->addWidget(m_speed_meter);
14
    main_layout->addWidget(ctl_Widget);
15
    main_layout->setStretch(0, 9);                  // ⑤ 表盘 : 控制区 = 9 : 1
16
    main_layout->setStretch(1, 1);
17
    resize(400, 420);
18
    connect(btn_start, &QPushButton::clicked, this, [this, edt_value]() {   // ⑥
19
        bool ok = false;
20
        double v = edt_value->text().toDouble(&ok);  // ⑦ 检查 ok，好习惯
21
        if (ok) {
22
            m_speed_meter->setSpeed(v);             // ⑧ 唯一的数据入口
23
        }
24
    });                                             // ⑨ 非法输入静默忽略
25
}

这个文件虽然只有 30 行，但藏着本篇最多的”注意点”，逐条说明：

• ① MainWin 缺少 Q_OBJECT 宏。 后果：

  • 不能定义自己的信号和槽（moc 不为它生成元对象）；
  • qobject_cast<MainWin*> 失效；
  • tr() 翻译、属性系统、className() 都拿不到正确信息。

  那为什么第 ⑥ 行的 connect 还能工作？ 因为 Qt5 新语法的 connect(sender, &Class::signal, context, functor) 只要求 sender 有元对象（QPushButton 当然有），第三个参数 this 仅作为”上下文对象”用于生命周期管理，不需要 MainWin 自己有元对象。所以这里侥幸能跑。但只要哪天想给 MainWin 加一个 signals: void speedChanged(qreal);，就会得到链接错误。任何 QObject 派生类都应该加 Q_OBJECT，没有例外。

• ② MainWin::MainWin(QWidget *parent) 接收了 parent 却没有传给基类——应该写成 MainWin::MainWin(QWidget *parent) : QWidget(parent)。当前写法等价于调用 QWidget() 默认构造，parent 参数被完全丢弃。

  后果：如果有人写 new MainWin(someParent)，这个窗口不会成为 someParent 的子控件，不会随父窗口销毁 → 内存泄漏，也不会跟随父窗口显示/隐藏。本工程 main.cpp 里是 MainWin w;（栈对象、无 parent），所以问题没暴露。这是一个”当前用法下无害、但一旦复用就出错”的定时炮弹，而且编译器不会给任何警告（未使用参数的警告通常被关掉）。

  凡是构造函数签名里有 parent，初始化列表里就必须有 Base(parent)——这是 Qt 类的肌肉记忆。

• ③ ctl_Widget->setLayout(ctl_layout)：ctl_layout 创建时没传 parent（new QVBoxLayout()），所以需要手动 setLayout 建立关联。对比 main_layout = new QHBoxLayout(this) 直接在构造时指定了宿主。两种写法都对，但混用容易搞混”这个 layout 到底装在哪”。建议统一用构造传参：new QVBoxLayout(ctl_Widget)。

• ④ new QPushButton("速度设置")、new QLineEdit()、new SpeedWidget() 都没有传 parent。这不是 bug——layout->addWidget(w) 会自动把 w reparent 到 layout 所属的 widget 上。所以它们最终都挂在对象树上，不会泄漏。

  但要注意这和 qt19 的 moveToThread 场景形成有趣对比：那里”不能有 parent”是硬要求，这里”暂时没有 parent”只是依赖 addWidget 后续收养。如果你 new 了一个 widget 却忘了 addWidget，它就是真的泄漏了（没 parent 也没 layout 管它）。

• ⑤ setStretch(0, 9) / setStretch(1, 1) 让表盘和控制区按 9:1 分配水平空间。在 400px 宽下约 360px 给表盘、40px 给控制区。

  40px 宽的控制区能放下”速度设置”四个字的按钮吗？ 实际上放不下——按钮有最小尺寸约束（sizeHint），布局会优先满足最小宽度，所以实际比例会偏离 9:1。这也解释了为什么运行时控制区看起来比 1/10 宽。setStretch 分配的是”剩余空间”，不是”绝对比例”，这是布局系统一个高频误解点。

• ⑥ lambda 捕获了 this 和 edt_value 两个指针。this 用来访问 m_speed_meter，edt_value 是局部变量所以必须显式捕获（值捕获指针本身）。

  这里有个潜在的生命周期风险：lambda 持有 edt_value 的裸指针，如果 edt_value 先于 btn_start 被销毁，点击按钮就是访问野指针。本例中两者都挂在同一对象树上、生命周期一致，所以安全。但通用做法是把 edt_value 提升为成员变量，或者用第三参数 this 保证”MainWin 销毁时自动断开连接”（这里已经这么做了，是正确的）。

  注意 connect 的第三个参数 this 不是可选装饰：如果写成 connect(btn_start, &QPushButton::clicked, [this, edt_value](){...})（省略 context），那么 MainWin 销毁后连接不会自动断开，若 btn_start 存活更久就会调用已销毁对象的成员 → 崩溃。带 lambda 的 connect 一定要给 context 对象。

• ⑦ toDouble(&ok) 检查了 ok，这是本文件写得最好的一处。QString::toDouble() 在转换失败时返回 0.0，如果不检查，用户输入 “abc” 会让指针归零——一个看起来像 bug 却查不出原因的现象。

• ⑧ setSpeed(v) 是 MainWin 和 SpeedWidget 之间唯一的耦合点。MainWin 不知道表盘里有几根刻度、指针怎么画；SpeedWidget 不知道数据来自输入框还是传感器。这种”窄接口”是控件可复用的根本。想接 qt19 的子线程数据，只需 connect(worker, &Worker::speedReady, meter, &SpeedWidget::setSpeed);（把 setSpeed 挪到 public slots: 即可），一行代码换数据源。

• ⑨ 非法输入被静默忽略——if(ok) 为假时什么都不做，用户看不到任何反馈，会以为”程序卡了”。改进方案：

  1
  if (ok) {
  2
      m_speed_meter->setSpeed(qBound(0.0, v, 240.0));   // 顺手钳位
  3
      edt_value->setStyleSheet("");
  4
  } else {
  5
      edt_value->setStyleSheet("border: 1px solid red");  // 视觉反馈
  6
  }

  或者直接用 QDoubleValidator 从源头限制输入：

  1
  edt_value->setValidator(new QDoubleValidator(0, 240, 1, edt_value));

  “校验通过才用、校验失败给反馈”是完整的输入处理，只做前一半是半成品。

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

• update() 触发重绘——setSpeed 里少了它，指针就只在窗口被动重绘时才跳动。
• save()/restore() 包住刻度循环，删掉后所有刻度的旋转会累积叠加，表盘瞬间报废。
• for i = 1 少画了 0 刻度，指针零位处空无一物；改成 i = 0 修复。
• scale(W/200.0, H/200.0) 非等比，控件非方形时圆盘变椭圆；qt20 的 qMin(W,H) 等比写法更稳。
• setRenderHints(A, B) 第二参是 bool，文字抗锯齿实际没开；改用 A | B。
• MainWin 缺 Q_OBJECT、构造函数丢了 parent——当前能跑，但都是复用时的定时炮弹。
• toDouble(&ok) 检查了 ok（好），但失败后无反馈（半成品）。
• 量程 240 硬编码了两处，改量程容易漏改一处导致指针和刻度对不上。

核心知识点#

1. 自定义控件三要素：private 状态（有默认值）+ public setter（改状态 + update()）+ paintEvent（纯函数式，只依赖状态）。这是 Qt 所有控件的内部结构。
2. 坐标归一化模式：translate 到中心 + scale 到固定逻辑尺寸（200×200）→ 按虚拟画布设计，自动适配任意控件大小。等比缩放（qMin(W,H)）保形，非等比会变形。
3. 量程 → 角度的映射公式：angle = startAngle + (value / maxValue) * rangeAngle。温度计、油量表、进度环、旋钮全都用它，只需换三个常量。
4. 循环画重复元素必须 save()/restore()，这样每次可以用绝对角度而不是累积增量，既易读又无累积误差。
5. “先 translate 再反向 rotate”让旋转坐标系里的文字保持水平，这是仪表盘绘制最精髓的技巧，顺序不可颠倒。
6. QPainterPath::subtracted() 做镂空：大形状减小形状。通用于镂空箭头、环形进度、月牙、异形按钮。
7. 窄接口是复用的前提：SpeedWidget 对外只有 setSpeed(qreal)，所以换任何数据源（输入框/串口/线程/数据库）都不用改绘制代码。

关键 API#

下一步学习#

• qt22 SQLite 数据库：给仪表盘配上数据持久化——把每次采集的速度存进数据库，再查历史记录回放。QSqlQuery 取出的数据经 setSpeed() 送进本篇的控件，就是一个完整的”存储 + 可视化”小系统。
• 之后可延伸：QPropertyAnimation 让指针平滑过渡而不是瞬间跳变（配合 Q_PROPERTY(qreal speed ...)）；离屏缓存把静态刻度盘预渲染成 QPixmap 优化性能；QChart/QCustomPlot 做趋势曲线。

💡 Tips：本篇与 qt22 的挂钩点——本篇解决了”数据怎么显示”，qt22 解决”数据从哪来、存到哪去”。两篇合起来就是一个最小可用的数据采集系统：QSqlQuery 查出速度记录 → setSpeed() → update() → 指针转动。而如果数据源是耗时查询，还要用上 qt19 的 worker 线程避免卡界面。qt19 + qt20 + qt21 + qt22 四篇正好构成一条完整链路：后台采集（线程）→ 数据持久化（SQLite）→ 绘制引擎（QPainter）→ 可复用控件（SpeedWidget）。

最容易忽视的细节#

1. m_speed = 0 的默认初值不是可选的。 控件在 show() 后、setSpeed() 前就会收到第一个 paintEvent。成员未初始化会用随机值算角度，可能得到 NaN 让整个路径绘制失败（表现为”指针不见了”）。所有控件状态成员都要有确定初值。
2. for (int i = 1; i <= 24; ...) 这个 1 让 0 刻度凭空消失。 循环边界错误在绘图代码里特别隐蔽——因为”少画一根线”不会报错，只会让画面”看起来差点意思”。画刻度的循环写完，一定要手算首末角度对不对。
3. scale(W/200.0, H/200.0) 和 scale(qMin(W,H)/200.0, ...) 的差别在方形窗口下完全看不出来。 这类”默认配置掩盖的 bug”必须靠极端参数测试暴露。养成习惯：自绘控件写完，先把窗口拖成 3:1 和 1:3 各看一次。
4. painter.font() 返回值拷贝，和 pen()/brush() 一样。本工程这里写对了（改完 set 回去），但 qt20 的 base03 就在 pen() 上翻了车。Qt 里从对象取出的配置类，改完必须 set 回去。
5. setStretch(0,9) 分配的是”剩余空间”而非绝对比例。 子控件的 minimumSizeHint 优先被满足，所以”速度设置”按钮的最小宽度会挤占表盘空间，实际比例达不到 9:1。想要严格比例得用 setFixedWidth 或 QSizePolicy。
6. connect 带 lambda 时第三个参数 this 是生命周期保险。省略它，MainWin 销毁后连接仍存在，若 sender 存活更久就会访问野指针。本工程正确地传了 this。

踩坑记录#

• “指针有时候能动有时候不能”排查半天，最后是 update() 被注释掉了。 现象之所以迷惑，是因为窗口的被动重绘（拖动、遮挡恢复）会掩盖漏掉 update() 的 bug——你以为程序是间歇性故障，实际是”只有系统重绘时才更新”。遇到”间歇性生效”的绘图问题，第一个怀疑对象永远是 update()。
• Q_OBJECT; 那个多余的分号，MinGW 编过了，换 MSVC 报警告。 这类”某编译器容忍、某编译器不容忍”的写法是跨平台移植的隐形成本。规范写法（不加分号）在所有编译器下都对，没有理由不遵守。
• MainWin 构造函数丢了 parent 这个 bug，编译器一个字都没说。 因为”未使用的参数”警告默认关闭，而”忘了调基类构造”是合法 C++（会调默认构造）。这类 bug 只能靠 code review 和肌肉记忆防御。 建议在 CODEBUDDY.md / 团队规范里写死一条：“Qt 类构造函数有 parent 参数时，初始化列表必须有 Base(parent)”。
• 量程 240 在代码里有两个独立来源（i*10 的隐含 240 和 max_speed=240）。 我曾把 max_speed 改成 300 想扩量程，结果刻度还标到 240、指针却按 300 算，两者错位——查了很久才发现”另一个 240 藏在 i*10 里”。魔法数字出现第二次，就是提取常量的时候。

与后续章节的衔接#

1. → qt22 SQLite：本篇的 setSpeed() 是可视化入口，qt22 提供数据来源。完整链路是 QSqlQuery::next() 取出历史速度 → setSpeed() → 指针转动，就能做”行程回放”。如果查询耗时，还要套上 qt19 的 worker 线程。
2. → 回望 qt19 线程：把数据源换成子线程只需一行 connect(worker, &Worker::speedReady, meter, &SpeedWidget::setSpeed);（前提是 setSpeed 声明为 slot）。跨线程信号自动排队到主线程，update() 在主线程调用，完全符合”UI 只能在主线程”的铁律——本篇的窄接口设计让这个切换毫无成本。
3. → 回望 qt20 绘图：本篇是 qt20 SeniorPainter::base04() 的产品化。对比两者能清楚看到”实验脚本 → 可复用组件”需要补的东西：状态成员、setter、update()、以及把硬编码值参数化。
4. → 后续动画与属性系统：给 SpeedWidget 加 Q_PROPERTY(qreal speed ...) 就能接入 QPropertyAnimation，指针从”跳变”升级为”平滑转动”。这也是 Qt 属性系统最直观的一个应用场景。
5. → 后续性能优化：静态刻度盘每帧重画 24 根线 + 12 段文字是浪费（只有指针在动）。标准优化是把刻度盘预渲染到 QPixmap 缓存，paintEvent 里 drawPixmap + 画指针。这是所有仪表类控件的标配优化，等你做到 10 个仪表同屏刷新时就必须用上。

设计决策思考#

• 为什么把速度表做成独立的 SpeedWidget 类，而不是直接在 MainWin::paintEvent 里画？ 因为复用性和可测试性。独立成类后：① 可以在任何窗口、任何布局里放多个实例（做双表盘、四表盘仪表台）；② 数据源可以随意替换（输入框/串口/线程/数据库），因为它只认 setSpeed；③ 可以单独调试——写个只有一个表盘的 main 快速迭代外观。如果画在 MainWin 里，这三点全部丧失。“一个类只画自己”是自绘控件的第一原则。
• 为什么用”归一化到 200×200”而不是直接用像素坐标？ 因为它把”设计”和”适配”解耦了。设计时你在一张固定大小的纸上思考（刻度在 80~95、文字在 70、指针长 80），完全不用考虑控件多大；适配交给一行 scale。如果用像素坐标，每个数字都得写成 width()*0.4 这样的表达式，代码可读性会崩塌，而且改一处比例要改十几个地方。这是”用一次变换换取全局简洁”的经典权衡，代价是必须始终记住”当前数字是逻辑单位不是像素”。
• 为什么指针用 subtracted 做镂空，而不是画两个三角形（外面红、里面白）？ 因为背景不一定是白色。如果用”里面填白色三角”的假镂空，控件放在深色背景上就会露出一块白斑。真镂空（路径差集）挖出的是透明区域，会正确透出任何背景。这是”看起来一样但本质不同”的两种实现，只有换背景时才暴露差异。做视觉效果时要问一句：“如果周围环境变了，我这个实现还成立吗？”
• 为什么 setSpeed 不做参数校验而把校验放在 MainWin 的 lambda 里？ 当前工程是这么做的（if(ok) 在 MainWin 里），但这个划分其实值得商量。更好的做法是”双层校验”：MainWin 负责”字符串能否转成数字”（输入格式校验，属于 UI 职责），SpeedWidget::setSpeed 负责”数字是否在量程内”（业务约束校验，属于控件职责，用 qBound）。理由是——控件不能假设所有调用者都会先钳位。每个模块都应该对自己的不变式负责，这是防御性编程的基本原则，也是为什么本篇反复强调 setter 里该加 qBound。
• 为什么 paintEvent 要设计成”每次全量重绘”而不是”增量更新指针”？ 增量更新（只擦掉旧指针、画新指针）在理论上更快，但实践中几乎不可行：① 你得精确知道旧指针覆盖了哪些像素（包括抗锯齿的半透明边缘）；② 擦除时要还原被覆盖的刻度和背景；③ 一旦有半透明叠加，增量计算就彻底失效。Qt 选择”全量重绘 + 脏区裁剪 + 双缓冲”这条路：你只管重画全部，Qt 用 event->rect() 裁掉不可见部分、用双缓冲避免闪烁。这是典型的”用简单正确的模型 + 底层优化，替代复杂易错的手工优化”，也是为什么 paintEvent 必须写成幂等的纯函数。