简介一套面向Qt初学者与桌面应用开发者的2D绘图教程及源码包以paintExample示例为主线深入浅出地讲解了QPainter绘图、QPaintEvent事件机制、QGraphicsView场景结构、鼠标拖拽绘图、颜色与画笔切换、绘图保存与加载等核心知识点可用于快速搭建绘图类软件原型或课程设计参考。资源共114个文件涵盖cpp源文件、h头文件、ui界面文件、pro工程配置、qrc资源文件、png/jpg图片、pdf说明文档与txt文本其中包含多张界面截图和演示图片各类型分工明确便于按模块研读整个压缩包约3.54MB轻量易用。已有704人学习下载。通过源码研读和实例运行读者可以掌握Qt 2D绘图程序的组织结构理解MainWindow与绘图区类的协作逻辑以及鼠标事件到图形绘制的完整流程同时可在此框架上继续扩展画笔样式、图形库或文件管理等能力尤其适合快速入门、课程设计与二次开发。1. 打开 Qt 绘图项目的正确姿势别急着画线先分清这套资源的边界做 Qt 开发的人多半碰到过这种情况想写个画板工具打开 QtCreator 新建 QWidget 工程重写 paintEvent拖几个按钮结果画出来的图形要么一缩放就花要么抗锯齿开不起作用要么鼠标拖拽坐标反向。这套「Qt 编写绘图软件教程及相关源码」解决的就是这类 2D 绘图的落地问题它把坐标系统、画笔画刷、事件处理、缩放重绘、导出图片的完整流程打包成可直接编译的源码配合教程讲解适合刚摸到 Qt 绘图门路的人也适合想快速搭一个自定义绘图组件的老手拿去改。它是资源包而不是夸大其词的「框架」边界很清楚以 QPainter 为基础的 2D 绘图不是 QML也不是 OpenGL 渲染。搞清楚这个边界后面所有操作才有意义。2. Qt 2D 绘图核心机制坐标系统、画笔画刷与抗锯齿的匹配逻辑2.1 三种坐标系统逻辑坐标、设备坐标与窗口-视口映射Qt 的 2D 绘图里最容易懵的就是坐标变换。教程源码里大量用到了QPainter的drawLine、drawRect、drawPath这些函数的参数默认都在逻辑坐标下也就是你头脑中的「数学坐标」。但真正显示时必须经过两层映射到设备坐标像素。这里有一个很多新手会忽略的点QPainter的坐标原点默认在绘图设备的左上角X 轴向右Y 轴向下这跟数学里的笛卡尔坐标系完全相反。源码里画一个中心在原点附近的圆如果不做坐标变换你看到的是圆跑到窗口右下角去了。常见的做法是先在构造函数里设置setViewport和setWindow人为地把逻辑坐标映射到指定范围。例如我想让画布宽高都为 200 逻辑单位不管窗口实际尺寸多大都映射到整个客户区void PaintWidget::paintEvent(QPaintEvent *) { QPainter painter(this); painter.setRenderHint(QPainter::Antialiasing, true); // 设置逻辑坐标范围x 从 0 到 200y 从 0 到 200 // 窗口大小为 200*200视口为整个 widget 尺寸 painter.setViewport(rect()); painter.setWindow(0, 0, 200, 200); // 此时画一个圆心在(100,100)、半径50的圆 painter.setBrush(QColor(240, 120, 80)); painter.drawEllipse(QPointF(100.0, 100.0), 50.0, 50.0); }这段代码里的setViewport(rect())表示设备像素区域取 widget 整个客户区setWindow(0, 0, 200, 200)表示逻辑坐标从 0 到 200。这样无论窗口尺寸如何变化图形都会跟着等比缩放不会出现画了一半被裁剪的问题。参数说明setViewport的参数是 QRect单位是像素setWindow的参数是逻辑坐标范围。二者必须成比例否则图形会拉伸变形。我在实际调试时见到过有人只设置setWindow不设置setViewport结果图形在窗口变宽时变成椭圆就是因为这个比例关系没有保持。2.2 画笔与画刷样式、宽度和颜色如何影响渲染结果绘图软件的核心就是画笔QPen和画刷QBrush。教程源码里drawWithPen模块展示了不同PenStyle的效果实线、虚线、点线、点划线。这里有个容易踩的细节QPen的宽度是 0 时表示 1 像素的极细线但在设置了setWindow缩放后宽度 0 的线不会缩放而宽度为 1 的线会随着坐标系缩放而变粗。这是 Qt 的一个重要边界线宽默认在逻辑坐标下除非你通过setWidthF指定为设备无关宽度。QPainter painter(this); QPen pen; pen.setColor(QColor(30, 30, 30)); pen.setWidth(0); // 极细线始终1像素 // pen.setWidth(2); // 会随窗口缩放改变粗细 pen.setStyle(Qt::DashLine); painter.setPen(pen); painter.drawLine(QPointF(10, 10), QPointF(190, 10));画刷方面源码里演示了纯色、交叉线纹、渐变三种。渐变是最容易出效果的但也最容易出问题的地方在于渐变坐标是相对于绘制设备本身的而不是相对于某个图元的局部坐标。比如要在圆上用线性渐变填充必须把渐变的起点终点设置为圆所在区域的绝对逻辑坐标QLinearGradient gradient(50, 50, 150, 150); gradient.setColorAt(0.0, QColor(255, 255, 0)); gradient.setColorAt(1.0, QColor(255, 0, 0)); painter.setBrush(gradient); painter.drawEllipse(QPointF(100, 100), 60, 60);这里QLinearGradient的四个参数分别是逻辑坐标下的起点和终点。如果你把渐变范围设置得比实际图形小填充就会截断设置得过大颜色过渡不明显。教程源码里的参数是 (50,50) 到 (150,150)正好覆盖圆心 (100,100) 半径 60 的圆效果是斜向上的黄到红渐变。我在自己画仪表盘时就吃过渐变色范围取默认值的亏——取默认值 (0,0) 到 (width, height) 时如果窗口不是正方形渐变的倾斜角度会被拉伸。2.3 抗锯齿为什么开了和没开看不出区别教程里有一节专门对比Antialiasing开和关的效果。原理上抗锯齿是让图形边缘的像素透明度呈梯度变化消除锯齿边缘。但很多人开了之后发现没变化原因通常是开启了全局渲染提示后QPainter的某些绘制函数如drawPixmap并不受影响只有矢量图元线、矩形、椭圆、路径才走抗锯齿。另外setRenderHint(QPainter::Antialiasing)必须放在任何绘制操作之前并且需要在每次begin之后、end之前设置。如果绘制过程中多次设置画笔和画刷并不会重置渲染提示但如果你调用了painter.resetTransform()或者重新begin则需要注意重新设置。void renderItem(QPainter painter, bool antialias) { painter.setRenderHint(QPainter::Antialiasing, antialias); // 只有关闭/开启这一项对比直线边缘 painter.setPen(QPen(Qt::black, 1.0)); painter.drawLine(10, 10, 200, 10); }QPainter::Antialiasing只是一个布尔开关没有级别调节。如果需要更精细的平滑常见做法是绘制到一张 4 倍大小的QImage上再缩小显示这个思路教程源码里没有直接给但可以自己扩展。我在做某图像处理 Demo 时为了输出高清图就是先渲染大图再缩放效果比直接开抗锯齿更可控。3. 把教程源码跑起来QtCreator 工程配置与三个关键编译点3.1 工程文件 .pro 的正确写法拿到源码包后第一件事不是双击打开.pro而是先检查工程文件的模块声明。这套源码基于 Qt Widgets 模块必须在.pro里声明QT widgets否则编译会报一堆 undefined reference。教程源码里给出了一个最小可用的.pro内容QT core gui widgets TARGET paintdemo TEMPLATE app CONFIG c11 SOURCES \ main.cpp \ MainWindow.cpp \ PaintWidget.cpp HEADERS \ MainWindow.h \ PaintWidget.h RESOURCES \ icons.qrc参数说明TARGET是生成的可执行文件名TEMPLATE app表示生成应用程序而不是库。CONFIG c11启用了 C11 特性源码里用到的override关键字和 lambda 表达式都需要它。如果你用的是 Qt5 以上版本widgets必须写在QT行里因为 Qt5 默认不包含 widgets 模块。我见过有人把QT widgets漏掉qmake 只提示找不到QApplication头文件但其实根本问题是模块没加载。RESOURCES引入图标资源文件编译时 qmake 会自动生成qrc对应的 C 代码。注意.qrc里引用的图片路径是相对.qrc文件所在目录的如果你移动了源码包里的图片目录记得同步修改.qrc里的路径前缀否则编译通过但运行时会提示找不到图标窗口显示空白。3.2 三步跑通主绘图窗口源码包的结构大致是main.cpp作为入口MainWindow负责菜单栏和工具栏PaintWidget承载绘图画布。我用自己的习惯拆解成三步。第一步检查main.cpp的入口逻辑#include QApplication #include MainWindow.h int main(int argc, char *argv[]) { QApplication app(argc, argv); MainWindow w; w.show(); return app.exec(); }这里没什么特别的但要注意QApplication必须要在创建窗口之前实例化因为 GUI 系统初始化依赖它。如果你在测试某些逻辑时先创建了QPainter对象哪怕是临时的也可能因为在构造时没有 QApplication 环境而崩溃。第二步编译运行。在 QtCreator 里打开.pro后选择「构建」→「运行」。如果编译器是 MinGW 且不是默认路径QtCreator 会自动检测但如果是手动用命令行 qmake需要确认环境变量里已经包含了 Qt 的 bin 目录。这个坑非常常见命令行敲qmake却调用了系统里另一个版本的 qmake编译出来一堆版本不匹配的错误。第三步验证绘图事件是否正常触发。运行后在窗口上点鼠标拖拽看是否画出线条。如果画不出来先看控制台有没有打印调试信息。教程源码里在鼠标事件加了一些qDebug()输出我建议初学者不要把qDebug删掉这样能最直接地判断事件是否进入处理函数。3.3 鼠标事件与绘制状态的联动绘图软件的核心交互是鼠标拖拽画线。源码里的做法是按下时记录起点移动时记录当前点并更新临时图形释放时把临时图形固化到图形列表。这里的关键在于update()函数的使用。void PaintWidget::mousePressEvent(QMouseEvent *event) { if (event-button() ! Qt::LeftButton) return; currentPoint event-pos(); drawing true; tempShape Shape(currentPoint, currentPoint); // 起点终点相同 update(); // 触发重绘 } void PaintWidget::mouseMoveEvent(QMouseEvent *event) { if (!drawing) return; tempShape.setEndPoint(event-pos()); update(); } void PaintWidget::mouseReleaseEvent(QMouseEvent *event) { if (event-button() ! Qt::LeftButton) return; drawing false; shapes.append(tempShape); // 固化 tempShape Shape(); update(); }这段代码里每个事件处理末尾都调用了update()。update()是异步请求重绘的它只是设置一个脏标记真正执行paintEvent是在事件循环回到空闲时。这比直接调用repaint()效率高也是避免闪烁的正确姿势。但注意如果你在paintEvent里不断修改数据而不是只读绘制就可能进入死循环因为update()会再次触发paintEvent。我见过有同学在 paintEvent 里调用resize()改窗口大小结果窗口疯狂闪就是没理解这个循环依赖。参数说明event-pos()返回的是相对 widget 的坐标单位是像素。如果你的画布设置了setWindow逻辑坐标那么鼠标返回的像素坐标必须先转换才能匹配逻辑坐标。源码里没有强制转换而是让鼠标坐标也直接用于绘制这样只有在窗口尺寸固定时才是正确的。如果你希望鼠标画线时点位准确必须在mousePressEvent里用QWidget::transform()逆映射QPointF logicalPos QWidget::transform().inverted().map(event-pos());这一步是我后来自己加的如果教程源码里没有逆映射说明它默认没有设置缩放坐标系统。你拿来做实验时可以保持默认但打算做成正式工具时一定要补上。4. 避坑与常见问题Qt 绘制中五个典型翻车现场4.1 中文文本绘制乱码与字体选择现象在画布上用painter.drawText输出中文显示成方框或乱码。原因Qt 默认字体不一定包含中文字符或者没有正确设置字体族。更隐蔽的是源码文件编码不是 UTF-8但tr()宏期望的是 UTF-8导致字符串在运行时被错误解码。解决在main.cpp最早处设置QTextCodec::setCodecForLocale是不推荐的做法正确做法是确保源码文件保存为 UTF-8并且编译器支持-finput-charsetUTF-8。在绘制时显式设置字体QFont font(Microsoft YaHei, 12); painter.setFont(font); painter.drawText(QPointF(20, 20), 测试中文);如果目标平台是 Linux则可能需要换成 WenQuanYi Micro Hei 或 Noto Sans CJK SC。源码包里写死的是微软雅黑在 Windows 上没问题在 Linux 上要改成系统实际存在的字体。我给某跨平台系统做标注功能时就是先查询系统字体列表再回退代码类似QListQByteArray families QFontDatabase().families(); if (!families.contains(Microsoft YaHei)) { font.setFamily(Noto Sans CJK SC); }4.2 窗口缩放后图形被裁剪或变空现象窗口从初始大小拉大后绘制的内容消失或者新的区域显示白色背景。原因paintEvent里缓存了旧的绘制结果没有重新计算视口和窗口。更常见的是在绘图函数里直接用了width()和height()作为坐标上限窗口变大后旧图依然在左上角而新绘制区域没有触发update。解决在resizeEvent里强制更新全量绘制数据。我一般会声明一个isDirty标志或者直接调用update()。如果图形数据是存在QList里的则全量重绘的逻辑应该始终基于逻辑坐标不依赖 widget 尺寸。看这段代码void PaintWidget::resizeEvent(QResizeEvent *event) { QWidget::resizeEvent(event); // 重算视口比例保持逻辑坐标范围不变 painterScaleX double(rect().width()) / logicalWidth; painterScaleY double(rect().height()) / logicalHeight; update(); }这样在paintEvent中setViewport(rect())和setWindow(0, 0, logicalWidth, logicalHeight)成立后图形始终填满画布。血泪经验是千万别把logicalWidth设为动态等于widget()-width()那样逻辑坐标和物理坐标一样缩放就失去了意义。4.3 鼠标坐标与逻辑坐标错位现象画线时鼠标点击和实际绘制的起点相差很远尤其是在窗口最大化之后。原因event-pos()返回的是物理像素坐标而你画图时使用了setWindow设置的逻辑坐标两者之间的映射没有反转。解决在鼠标事件中统一转换坐标。定义两个函数QPointF PaintWidget::toLogical(const QPoint screenPos) const { return QWidget::transform().inverted().map(screenPos); }然后在mousePressEvent中调用QPointF logicalPos toLogical(event-pos())。所有后续的图形数据都存逻辑坐标绘制时再直接交给 QPainter。这个问题的厉害之处在于窗口处于初始大小时物理坐标和逻辑坐标恰好 1:1你根本发现不了一旦窗口拉伸到 2 倍宽度画线位置就整体偏移。这套教程源码如果没有提及属于正常版本迭代的砍掉部分你有需要就自己实现。4.4 虚线看起来像实线或线宽不受控现象设置了Qt::DashLine但画出来是实线或者设置了线宽 3但某些机器上看起来是 1 像素。原因第一没有开启setRenderHint(QPainter::Antialiasing)时虚线在像素对不齐时会连起来第二线宽为 0 时 Qt 会用设备像素的极细线线宽 1 在缩放过大的逻辑坐标下会显得宽或窄但如果你设置了setWindow又没设置setViewport线宽就按照逻辑坐标和物理坐标的比例缩放。解决固定线宽用pen.setWidthF(0)或者把宽度设置成一个相对值。如果需要恒定的 1 像素虚线最好在绘制前暂停坐标变换painter.save(); painter.resetTransform(); // 回到设备坐标 painter.setPen(QPen(Qt::black, 1, Qt::DashLine)); painter.drawLine(rect().topLeft(), rect().topRight()); painter.restore();这个技巧在绘制网格线、边框线时非常有用。否则逻辑坐标下线宽为 1 时窗口放大到 400 宽度后线宽会变成 2 倍物理像素特别难看。4.5 导出图片到文件时背景变黑或画布内容空白现象使用QWidget::grab()保存成 PNG发现背景是全黑的或者明明画了内容但导出为空。原因grab走的路径与普通paintEvent不太一样如果paintEvent里有依赖resizeEvent才初始化的成员变量直接 grab 时可能还没有赋值。另一个原因是没有给 widget 设置透明的背景。解决不要临时 grab而是手动创建一个QImage用同一个 QPainter 逻辑渲染一遍QImage image(logicalWidth, logicalHeight, QImage::Format_ARGB32); image.fill(Qt::white); QPainter imgPainter(image); imgPainter.setRenderHint(QPainter::Antialiasing, true); // 执行和 paintEvent 相同的绘制代码但 QPainter 绑定的是 image paintContent(imgPainter); image.save(output.png);这样导出结果永远不会出现背景变黑。教程源码里如果用了 grab建议你改成这个方案。那种黑背景的玄学我遇到过两次都是因为 widget 的autoFillBackground为 false 且没有在 paintEvent 里画背景而 QImage 默认初始化是透明叠加到黑底上就成了黑图。5. 把示例扩展成自己的绘图工具自定义图元、撤销重做与图像导出5.1 自定义图元类型的抽象教程源码中的Shape类只是保存了起点终点和画笔属性如果你想扩展成多边形、自由曲线就需要把图元抽象成虚函数接口。常见的做法是定义基类AbstractShape子类各自实现绘制和数据加载。我自己重构时用到的是一个相当精简的接口class AbstractShape { public: virtual ~AbstractShape() {} virtual void draw(QPainter painter) const 0; virtual QRectF boundingRect() const 0; virtual QString serialize() const 0; // 用于文件保存 };boundingRect非常重要它用于快速判定鼠标点击是否命中图元也是绘制选择框的依据。比如直线图元的包围盒是一条很窄的矩形你需要在矩形四边扩几个像素以便于点击QRectF LineShape::boundingRect() const { return QRectF(startPoint, endPoint).normalized().adjusted(-4, -4, 4, 4); }注意QRectF的构造要求左上角坐标小于宽高所以必须调用.normalized()否则负宽高的矩形会被压缩成无形状点击检测失效。5.2 撤销重做功能的最小实现绘图软件没有撤销就是半成品。最省内存的做法是保存操作指令栈而不是保存整幅图像。每一步操作记录一个QByteArray内容是序列化后的图元数据。撤销时从后栈弹出一个操作把操作前的状态放回重做栈。核心代码逻辑如下void PaintWidget::undo() { if (undoStack.isEmpty()) return; redoStack.push(undoStack.pop()); reloadFromStack(); update(); }这里的关键是reloadFromStack需要把当前所有图形清空并重建。如果图元数量很大全量重建可能吃力你可以只删除最后添加的图元这里取决于数据结构的复杂度。源码包里的简化实现是维护一个QListAbstractShape*撤销就是把最后一个元素取出来放进删除缓冲区。注意内存管理QList不会自动 delete 元素所以撤销时要把指向的对象暂存在一个deleteLater队列里或者用std::unique_ptr持有图元。5.3 一键导出高清位图导出功能是绘图工具的收尾一环。我一般把导出对话框做成三个选项PNG、JPEG、BMP并且支持按比例放大输出。上面 QImage 方案的好处是你可以直接设置输出尺寸为逻辑尺寸的 2 倍、4 倍用于更清晰的印刷QImage exportImage(QSize outputSize) { QImage img(outputSize, QImage::Format_ARGB32); img.fill(Qt::white); QPainter p(img); p.setRenderHint(QPainter::Antialiasing, true); // 把逻辑坐标统一缩放到目标尺寸 p.scale(double(outputSize.width()) / logicalWidth, double(outputSize.height()) / logicalHeight); // 调用主绘制函数 paintContent(p); p.end(); return img; }这里p.scale的第二个参数是 Y 轴缩放注意要用 double 避免整数除法。我最初写的是outputSize.width() / logicalWidth两个整数相除直接变成 1导致图片只有局部。这个 bug 调试了半小时定位后哭笑不得。从那以后我每次涉及比例计算都会强制写double(...)转换一遍并且把打印qDebug() scaleX scaleY留到确认无误再删。希望帮到你如果你复现这套教程时遇到同样的问题大概率能少走一段弯路。本文还有配套的精品资源点击获取