★ FEATURED ARTICLE 很多人学Qt都是从打开一个Demo开始但大部分人的路线是跑起来、截个图、关掉。我一开始也是这样直到某个项目里需要在自定义控件上绘制一个带渐变、阴影、不规则路径的图表界面才发现连QPainter的坐标系都没完全搞明白。后来把Qt 5.14.2自带的2D Painting示例从头到尾拆了一遍才真正开窍。这篇博客就是记录我拆解这个示例的过程内容包括示例的运行效果、核心类结构、QPainter绘图机制的底层理解以及我实际运行和改造成项目代码时踩过的坑。如果你正准备入门Qt自定义绘图或者想系统的搞懂图形绘制的底层流程这篇文章可以帮你省下不少弯路。1. 为什么我建议每个Qt新手都先跑一遍2D Painting示例先说说我眼中的2D Painting到底是什么。它是Qt自带示例集中位于widgets/painting目录下的一个标准示例打开后你会看到一个类似画布的主窗口左侧是各种画笔、画刷、渐变的演示区域右侧是对应的控制面板可以切换不同的图形形状、笔刷样式、渐变方式画面会实时变化。这个示例展示的东西覆盖了Qt 2D绘制的核心知识面基本图形绘制、画笔QPen样式、画刷QBrush样式、三种渐变、抗锯齿开关、图形变换平移、旋转、缩放、扭曲以及合成模式。换句话说凡是你在Qt里手动画界面需要用到的绘制概念它几乎都做了可视化展示。对于新手来说它就像一本配了运行环境的活教材可以边改参数边看效果比单纯看文档直观得多。我当时跑通这个示例之后又把它里面的核心代码拿出来逐行分析才发现它并不只是一个“能跑”的demo而是非常值得读源码的教学案例。它的设计其实很规范一个控制窗口MainWindow一个绘制画布PaintWidget一个形状枚举Shape通过QPainter在paintEvent中根据当前配置绘制不同形状和效果。这类示例最容易被忽略的价值在于它把这些看起来零散的绘制API串成了一个完整的“状态管理”流程。你需要理解的不只是某个API怎么用而是UI控件状态变化之后如何触发生成一张新画面。这个思路放到实际业务里其实就是你自定义控件的全部工作模型。所以我的建议很直接如果你刚开始接触Qt别急着写复杂项目先把2D Painting示例跑起来再花一个下午把它的源码逐行读一遍把每个控制参数和绘制结果对应起来。这个步骤完成后你再看其他绘图相关代码基本不会有理解障碍了。2. 示例文件结构拆解从工程文件到PaintWidget绘制流程2.1 工程文件与目录布局在标准安装的Qt 5.14.2环境下示例位于安装目录的Examples/Qt-5.14.2/widgets/painting/painter子目录中。整个工程的文件并不复杂核心文件包括painter.proqmake工程文件负责指定源文件、头文件和Qt模块依赖main.cpp程序入口创建MainWindow并显示mainwindow.h/.cpp主窗口负责布置左侧控制面板和右侧绘制区域paintwidget.h/.cpp核心画布控件重写paintEvent根据状态执行绘制helper.h/.cpp定义Shape枚举、Painter绘图类settings相关代码管理当前绘图配置形状、颜色、渐变、变换等。我记得第一次看这个目录时并没有立刻找到所有绘制代码因为示例刻意把“状态定义”和“绘制动作”拆开了。MainWindow只负责接收用户操作并保存配置真正的绘图逻辑都集中在Painter::draw和PaintWidget::paintEvent里。这个分层方式和我们在真实项目中做自定义控件的思路是一样的界面只负责输入绘制层只负责输出。如果你是用Qt Creator打开这个工程建议先直接点击运行。构建时注意选择与你机器匹配的套件我用的环境是Windows下的MinGW 64-bit套件直接点绿色运行按钮就能出来窗口。如果弹出缺少QT widgets之类的报错检查一下.pro文件里是否包含了对应的模块声明5.14版本的QApplication和控件类都已经移到widgets模块里了。2.2 核心入口MainWindow与状态配置MainWindow做的事情直观但容易忽略它维护了一个配置对象记录当前选中的Shape、Pen属性、Brush属性、渐变类型、变换开关、抗锯齿开关等。左侧面板上的各种下拉框、复选框、滑块改动之后会更新这个配置对象然后调用paintWidget-update()触发重绘。这里有个很关键的设计点update()不是同步重绘的。它只是给Qt的事件循环打了一个“需要重绘”的标记等到主循环空闲时才真正调用paintEvent。这样设计的好处是高频操作比如拖动滑块不会让界面卡顿Qt会把多次update()合并成一次实际绘制。我在早期的代码里曾经误以为update()会立刻执行重绘导致依赖绘制结果做逻辑判断结果调试了半天。如果你也这么干过记住这个机制它就是一个异步标记。2.3 PaintWidget与paintEvent的绘制流程PaintWidget继承了QWidget并把自身设置成视口尺寸。它重写的paintEvent(QPaintEvent *)是整个示例最核心的入口。每次重绘时它会先创建一个QPainter对象再对helper执行绘制调用。示例里的Painter::draw函数负责所有具体图形的绘制按配置枚举值分发到不同的绘制分支矩形、椭圆、三角形、文本、菱形、直线等。整个流程可以简化为依据控件尺寸计算绘制区域中心点保存当前绘制状态设置抗锯齿、变换矩阵、画笔、画刷根据Shape枚举调用对应的绘制函数恢复绘制状态结束绘制。这里要重点提一下save()和restore()。QPainter是一个有状态的对象画笔、颜色、变换矩阵、合成模式都会持续生效。如果你在绘制过程中改变了状态而没有恢复后续所有绘制的元素都会受影响。示例中的做法是在draw函数开头保存状态在末尾恢复这样既不影响外部调用方也让内部各绘制分支互不干扰。你可以在自己代码里用大括号限定QPainter作用域来达到类似效果但显式save/restore的可读性和可控性更高。我在读这份代码时最在意的部分是示例对坐标系的理解。控件坐标原点默认在左上角x向右增大y向下增大。示例里用painter-translate(rect.center())把原点移到了控件中心然后所有图形都按中心对称的方式来画。这种变换在手动画对称图形时非常好用因为可以避免反复计算偏移量。稍微延伸一下如果你要绘制时钟表盘、雷达扫描、仪表指针这类元素这个技巧能省掉大量坐标换算工作。2.4 Painter类的绘制分发Painter::draw函数根据Shape枚举值进入不同分支。每个分支都创建对应的QPainterPath或直接调用drawRect、drawEllipse、drawLine等基础绘图API。QPainterPath值得单独说一下它可以被理解为“一个可复用的绘图指令集合”你可以在路径中依次添加直线、弧线、贝塞尔曲线然后再用drawPath一次性输出。示例中很多复杂图形比如圆角矩形、连线图、五角形路径都是先构造路径再绘制而不是直接用现成的绘图API。原因是路径绘制更灵活并且可以被fill、stroke、clip多种方式复用。很多初学者容易跳过QPainterPath因为直接画矩形和线条就能应付简单需求。但在实际项目里不规则控件裁剪、自定义气泡框、曲线图表基本都要靠它。2D Painting示例虽然没有专门讲解路径机制但它的绘制代码本身就是在展示路径的典型用法只是它没有敲黑板告诉你“这里用的是路径请注意”。3. QPainter绘制机制的几个关键理解3.1 为什么绘制代码必须写在paintEvent里这是新手最容易困惑的问题。为什么Qt不让你在任意函数里直接画原因是Qt的绘制系统依赖于窗口系统的底层“曝光”机制。当窗口被遮挡、放大缩小、最小化恢复时系统会要求组件把损坏的区域重新绘制一遍。如果绘制不在paintEvent里完成窗口每次被遮挡再露出内容就会变成空白或者产生残影。2D Painting示例的paintWidget每次收到事件都会完整重绘。它在paintEvent里重新计算全部图形所以在窗口缩放时效果始终是清晰的。实际项目中有时会因为性能考虑把绘制结果先缓存到QPixmap在paintEvent里直接drawPixmap但无论如何第一次内容生成必须在事件回调里完成。我调试过很多次类似问题界面上明明调用了某个绘制函数但运行后什么都没有。原因基本都是绘图代码放在了构造函数或者业务回调里窗口一旦重绘内容就消失了。如果你也遇到这种“偶尔出现一遮挡就消失”的问题先看看绘制代码是不是在paintEvent里。3.2 设备坐标系与逻辑坐标的偏差Qt的坐标系统有两层逻辑坐标系和物理设备坐标系。在默认情况下两者是一致的但遇到高DPI屏幕、变换矩阵时就不一样了。2D Painting示例通过scale变换让图形放大缩小本质上是修改了逻辑坐标到物理坐标的映射关系。此时QPainter在绘图时会把你的逻辑坐标乘以当前变换矩阵再映射到屏幕上的物理像素。举个例子你用painter-scale(2, 2)之后再画一个从(10, 10)到(30, 30)的矩形它实际上会占据屏幕上(20, 20)到(60, 60)的区域。这个机制在做缩略图、图表缩放时非常有用但也容易踩坑尤其是你在绘制区域里还使用了鼠标坐标时。鼠标返回的是控件坐标而你的绘图坐标可能已经经过变换二者不统一就会画偏。解决思路一般是把业务逻辑里的坐标统一用“原始逻辑坐标”只在最后画到QPainter时才应用变换。3.3 save/restore与绘制状态栈QPainter内部维护了一个状态栈。save()会把当前画笔、画刷、字体、变换矩阵、合成模式、裁剪区域全部压入栈内restore()会从栈顶弹出并恢复。这个机制是示例代码能够优雅切换各种效果的关键。假设你不使用save/restore那么在一个绘制函数里改动了画笔颜色之后所有绘制都会用这个颜色除非你手动再改回来。状态一多就会混乱。尤其是当你封装公共绘制函数供多个控件调用时一个函数不小心污染了全局绘制状态后面的所有输出都会异常。所以我的建议是每个独立的绘制分支入口处save()出口处restore()保持状态干净。这算不上高级技巧却能避免大量低级但隐蔽的显示问题。3.4 抗锯齿与绘制质量示例中有一个“Antialiasing”复选框勾选与不勾选的效果差异肉眼可见。开启抗锯齿后图形边缘会通过半透明像素过渡消除“锯齿感”视觉效果平滑许多。QPainter的对应设置是painter-setRenderHint(QPainter::Antialiasing, true);除了Antialiasing还有TextAntialiasing、SmoothPixmapTransform等渲染提示。具体到2D绘图场景Antialiasing对形状和曲线的作用最明显。但要注意开启抗锯齿会增加额外计算量对大量实时绘制比如高频刷新图表有明显开销。我通常的做法是静止画面开启高频动画且性能敏感时关闭或者采用“非核心技术用位图缓存位图本身开启平滑变换”的方式折中处理。4. 影响绘制效果的三件小事画笔、画刷与合成模式4.1 QPen样式不只是颜色和粗细2D Painting示例的右侧面板中Pen部分可以设置颜色、线宽、线型实线、虚线、点线等和笔帽样式。QPen看起来简单但有很多细节会影响最终效果。线型选择上Qt::DashLine等虚线样式在setStyle里直接指定但线宽大于1时虚线段的实际长度受dashPattern控制。示例里没有深入演示但你在绘制边界框、坐标轴、网格线时一定会用到。比如网格线用1像素实线辅助线用虚线重点区域用宽一点的半透明线这些视觉层次全靠QPen调出来。另外圆角连接和笔帽样式在绘制粗线条折线时尤为关键。默认的Qt::MiterJoin在折线角度尖锐时会产生尖刺延伸改成Qt::RoundJoin则更圆润。如果绘制的是监控折线图或者折线路径建议设置Qt::RoundCap和Qt::RoundJoin能让线条看起来更自然。4.2 QBrush样式填充效果的变化画刷负责封闭图形的填充。2D Painting示例中可以看到纯色填充、纹理填充和渐变填充的区别。QBrush不仅仅能设置颜色还可以设置样式比如Qt::CrossPattern、Qt::DensePattern等。在实际项目中这些线性或蜂窝状纹理常被用来做半透明的覆盖图层比如地图上的热区遮挡。更常用的是渐变画刷Qt提供了三种线性渐变QLinearGradient、辐射渐变QRadialGradient、锥形渐变QConicalGradient。示例会分别展示这三种效果并演示渐变方向和焦点位置的调整。用渐变做背景、做柱状图的高光、做进度条的光泽效果都离不开它们。使用渐变时有一个常见误区渐变坐标是在逻辑坐标系里定义的一旦你对QPainter做了缩放或平移变换渐变效果也会跟着变化。示例里由于图形经过变换绘制为了方便演示在某些分支里会重新计算渐变坐标保证渐变方向和形状比例匹配。你可以把这理解为“渐变也活在同一个坐标空间”需要变换时别忘了重新映射。4.3 合成模式叠加出来的效果合成模式决定新绘制的像素如何与已有像素混合。默认的SourceOver模式就是普通覆盖新内容覆盖旧内容但其他模式如Plus叠加变亮、Multiply正片叠底、Difference差值会产生完全不同的视觉效果。2D Painting示例中提供了一个合成模式下拉框你可以直接看到圆形、矩形等图形在重叠区域的混合效果。这个特性的实战价值在于制作“发光”“投影”“高亮”等效果。比如用CompositionMode_Plus模式绘制柔和的半透明光晕多次叠加之后会越来越亮用CompositionMode_Multiply做纹理相乘可以把渐变纹理映射到图形上。需要留意的是合成模式对底层绘制有依赖如果底层是QImage或QPixmap不同图像格式对结果也会有影响。示例的绘制控件默认是不透明的但如果你在做图层类的工具建议给画布显式填充一个不透明底色再叠加其他模式否则容易出现意外的透明区域。5. 构建运行这个示例时我踩过的5个坑5.1 中文路径导致构建失败这是一个很常见的意外。把整个示例目录拷贝到带中文名的路径下比如D:\测试代码\painterQt Creator在qmake阶段或编译阶段可能会报各种找不到文件的错误。原因是部分编译器工具链对非ASCII路径支持不好或者生成的文件路径里出现中文导致依赖项解析异常。这种问题排查起来很迷惑因为错误提示并不直接说有中文路径问题而是报一些“无法打开文件”“cannot find -l”之类的错误。解决办法很简单把代码放到纯英文路径下。看起来很低级但真的能卡住很多人。5.2 套件选择不对导致编译报错Qt 5.14.2一般自带MinGW和MSVC两套编译链装的时候可以都选。如果示例是用MinGW写的你用MSVC打开直接在构建时可能会遇到moc工具生成的头文件不匹配或者glu32之类的链接错误。多数情况下把构建套件切换成同系列的编译器就能解决。如果你非要用MSVC可能需要重新执行qmake并清理缓存。我建议新手先统一用一套编译器不要混着来否则会分散学习精力。5.3 高DPI屏幕上坐标偏移在高分屏环境下比如Windows显示缩放比例设为125%或150%如果不做任何适配2D Painting示例的图形可能出现轻微模糊或坐标偏移。原因是Qt需要感知物理DPI和逻辑DPI的比率。5.14版本中可以在main.cpp里设置QApplication::setAttribute(Qt::AA_EnableHighDpiScaling); QApplication::setAttribute(Qt::AA_UseHighDpiPixmaps);这样可以保证坐标系和像素图在不同缩放级别下保持一致。如果你在自己的绘图程序中遇到控件位置和鼠标点击位置对不上而系统又开了缩放很可能就是DPI适配没有处理。5.4 在paintEvent之外调用QPainter我自己早期犯过的错在某个按钮点击回调里创建QPainter画布想直接把内容画到控件上结果窗口一刷新内容就消失甚至控制台还会输出“QPainter::begin: Paint device returned engine false”的警告。这个警告的意思很明确当前设备不允许此时绘制。正确做法是把绘制代码放到paintEvent里按钮点击只负责修改数据状态然后调用update()请求重绘。如果你需要在按钮点击后立刻看到效果update()加事件循环的异步机制已经足够了。5.5 窗口缩放导致的闪烁问题2D Painting示例本身不会闪烁因为你用的是Qt::WA_OpaquePaintEvent或普通背景重绘。但如果你仿照它的模式绘制复杂、耗时的内容在窗口放大缩小时会看到明显的闪烁。闪烁的本质是背景先被擦除再绘制新内容中间产生了白屏帧。解决思路有三个一是在paintEvent里用双缓冲QPainter绘制到QPixmap再一次性drawPixmap到控件二是设置setAutoFillBackground(false)并手动绘制背景三是用Qt::WA_OpaquePaintEvent告诉系统不要自动擦背景。实际项目里双缓冲最常用稳定也最可控。6. 把这个示例改造成项目级绘图组件时我常用的思路6.1 绘制内容缓存到QPixmap2D Painting示例每次重绘都会重新计算所有图形这对演示来说没问题但到了真实项目里就会遇到性能瓶颈。我的习惯是如果图形内容不是频繁变化就先画到一个QPixmap上作为“画布缓存”然后在paintEvent里直接把这个QPixmap贴到控件上。QPixmap cachePixmap(size(), QPixmap::devicePixelRatio()); cachePixmap.fill(Qt::transparent); QPainter painter(cachePixmap); // 在这里画所有内容 painter.end(); QPainter widgetPainter(this); widgetPainter.drawPixmap(0, 0, cachePixmap);这样做的最大好处是重绘开销变成一次像素拷贝而不是重新执行几十次绘制指令。尤其在绘制复杂图表、网格、纹理时性能提升非常明显。6.2 用增量更新代替全量重绘如果你的绘图组件需要频繁更新比如鼠标拖动画笔轨迹、实时显示波形、进度动画全量重绘就很浪费。Qt提供了QWidget::update(const QRect)接口来指定需要更新的局部区域。你可以只对“新增的那一小块区域”请求重绘系统会把这个区域裁剪出来只绘制这部分内容。配合位图缓存这种增量更新策略能让界面流畅度提升一个档次。不过要注意如果图形内容做的是整体平移、缩放这类全局变换增量更新就不划算了反而是全量重绘更直接。判断标准很简单局部变化用局部更新整体变化用全量更新不要在局部更新逻辑里画一大堆全局元素那只会让代码变复杂。6.3 让业务数据和绘制逻辑解耦2D Painting示例里MainWindow持有“配置”PaintWidget根据配置绘制。这个分层关系可以直接迁移到业务项目。我现在的习惯是定义独立的“数据模型”结构体或类比如图表数据、节点列表、样式配置然后让绘制类只依赖这个模型。这样当你需要换肤、换数据源、支持多视图时绘制代码几乎不用改。解耦的另一个好处是便于单元测试。纯绘图逻辑如果要验证往往需要截图对比或者肉眼观察但如果你把“模型如何转换成绘制指令”单独抽出来就可以在无界面的环境下测试指令序列是否正确。对于复杂绘图系统这是一个很实用的工程化解法。6.4 如果再深入一点自定义控件与交互示例本身不涉及鼠标交互但实际绘图组件几乎必然要处理鼠标事件。一个典型扩展是在PaintWidget上重写mousePressEvent、mouseMoveEvent将鼠标坐标转换为逻辑坐标然后更新模型并触发重绘。这个过程中最容易翻车的点就是坐标系转换尤其当你使用了painter-scale或者painter-rotate之后鼠标坐标直接被视为绘制坐标画出来的图形位置就会错乱。正确的做法是在事件处理函数里做矩阵逆变换把光标位置映射回“逻辑坐标”再交给业务逻辑处理。Qt的QTransform支持求逆矩阵比如QTransform transform; transform.translate(rect.center().x(), rect.center().y()); transform.scale(scaleFactor, scaleFactor); QPointF logicalPos transform.inverted().map(event-pos());这部分内容已经超出2D Painting示例的范畴但只有走到这一步你才真正把示例里的那些变换技巧应用到了实际项目中。总的来说2D Painting示例的价值并不是让你记住几个绘制API的用法而是帮你建立一套“状态管理、事件触达、绘制执行”的完整心智模型。我后来做自定义仪表盘、股票K线图、流程图编辑器时底层思路基本都能追溯到对这个示例的拆解。如果你现在正卡在绘制坐标混乱、重绘逻辑不清、窗口更新闪烁这类问题上回到这个示例把每一步的触发关系和状态变化理清楚多半能找到答案。
阅读完成 · 觉得有帮助？
