简介面向Qt初学者的2D绘图开发教程与完整源码包以paintExample示例为主线讲解QPainter绘图、QPaintEvent处理、QGraphicsView/Scene高级图形对象交互等核心机制。压缩包内含114个文件约3.54MB包括18个h头文件与15个cpp源文件、7个ui界面设计文件、4个pro工程文件、52张png示意图及1份PDF说明文档目录结构清晰便于对照学习。资源已有704人学习代码完整覆盖主窗口搭建、绘图区绘制、鼠标拖拽事件、颜色与画笔选择、绘图保存载入等关键功能并针对QPainter属性设置、update()重绘时机等常见细节给出实现参考。通过学习这套源码与教程可快速掌握Qt绘图程序的工程组织方式为进阶开发复杂图形应用打下基础。1. Qt 绘图软件教程与源码这套 2D 绘图工程真正值得吃透的部分拿到“Qt 编写绘图软件教程及相关源码”这类资源包我习惯先不做两件事不急着编译不急着看界面。先翻目录结构再看示例工程里重写了哪些事件函数。实际决定一个 Qt 绘图软件能不能扩展的不是 paintEvent 里那几行画图代码而是坐标转换、图元存储和重绘策略这三块——坑也基本都埋在这三块里。这套资源用 QtCreator Qt Widgets 的常规写法把 2D 绘图的完整路径串了下来。直接跑通只需要十分钟但想把它改成自己能加功能的绘图程序需要把坐标系、鼠标事件、序列化这条路完整走一遍。适合正在学 Qt、准备做白板或标注工具、又不想一上来就依赖 QGraphicsView 的开发者。2. 从 QtCreator 工程到第一个绘制控件QPainter 坐标系与 paintEvent 的前置认知2.1 QPainter 的三层坐标体系画之前先想清楚“画在哪”QPainter 绘制时其实同时存在三套坐标初读源码包的开发者最容易在这上面翻车。第一套是逻辑坐标也就是直接传给 QPainter 的 drawLine、drawRect 这些函数的数值第二套是设备坐标指控件实际的像素尺寸paintEvent 里的 event-rect()、控件的 width() 和 height() 都属于这个层面第三套是窗口与视口映射由 setWindow 和 setViewport 控制用来把逻辑坐标映射到设备坐标。大多数教程源码里前两套会出现第三套往往藏在缩放功能的实现里。坐标系参照对象典型使用方式常见误用逻辑坐标QPainter 绘制接口drawLine、drawRect 的参数把控件像素尺寸当逻辑坐标直接画设备坐标控件实际像素event-rect()、widget-size()缩放逻辑跟着 scale 一起放大窗口/视口QPainter 内部映射setWindow / setViewport理解成窗口大小与控件大小为什么绘图软件一定要区分这套体系因为 paintEvent 里绘制用的是逻辑坐标鼠标事件回传的 QMouseEvent::pos() 是设备坐标这两者不相等。如果你在程序里直接把鼠标坐标拿去画图看起来“画对了”是因为没有做缩放时逻辑坐标与设备坐标恰好一比一一旦加入缩放、平移或者窗口尺寸变化问题就暴露了。所以我看一份 Qt 绘图源码第一件事就是找坐标换算的代码找不到往往说明工程只做了最基础的画布功能。2.2 在 QtCreator 里建立一个最小绘图工程一个类、两个文件、一次重绘这份教程资源的起点通常是一个 Qt Widgets Application。在 QtCreator 里新建工程后默认会生成 main.cpp、mainwindow.cpp 和 mainwindow.ui。最省事的做法不是直接在 MainWindow 里写绘制代码而是新建一个 QWidget 子类比如叫 DrawingWidget然后把主窗口的 centralwidget 提升成这个类。在界面上右键 centralwidget选择“提升为”类名填 DrawingWidget头文件填 drawingwidget.hQtCreator 会自动生成提升代码。这样做的好处是绘制的逻辑独立成类后续加缩放、存文件都不需要动到界面代码。下面是这套绘图软件最核心的一个最小实现我自己拆这种工程时会先把代码缩减到这个程度跑通了再往上加功能// drawingwidget.h #ifndef DRAWINGWIDGET_H #define DRAWINGWIDGET_H #include QWidget #include QPointF class DrawingWidget : public QWidget { Q_OBJECT public: explicit DrawingWidget(QWidget *parent nullptr); protected: void paintEvent(QPaintEvent *event) override; // 所有绘制都进这里 }; #endif// drawingwidget.cpp #include drawingwidget.h #include QPainter DrawingWidget::DrawingWidget(QWidget *parent) : QWidget(parent) { setSizePolicy(QSizePolicy::Expanding, QSizePolicy::Expanding); // 让控件跟随窗口拉伸而不是固定大小 } void DrawingWidget::paintEvent(QPaintEvent *event) { QPainter painter(this); // 以当前控件为画布 painter.setRenderHint(QPainter::Antialiasing, true); // 打开抗锯齿 painter.setPen(QPen(QColor(60, 120, 200), 2.0)); // 蓝色笔宽 2 painter.drawLine(QPointF(20, 20), QPointF(width() - 20, height() - 20)); // 画对角线 }这段代码里有几个参数值得注意。QPainter painter(this) 中的 this 表示画布就是控件自身绘制的结果直接显示在界面上如果传入一个 QPixmap绘制就不会上屏而是画到内存图像里后面保存图片时用得上。setRenderHint(QPainter::Antialiasing, true) 打开抗锯齿画斜线时边缘会更平滑但对性能有一定损耗图元数量多的时候需要谨慎使用。最后的 drawLine 用了 width() 和 height() 动态获取控件尺寸保证窗口拉伸时线能跟着变化这是绘图软件基础但很重要的一个习惯。2.3 update() 是唯一正确的重绘入口别直接调用 paintEvent看完最小工程下一个需要建立的概念是重绘机制。paintEvent 是系统在需要绘制时自动回调的它不会也不应该被手动直接调用。想让窗口重新绘制正确的方式是调用 update()它的工作方式是向事件循环投递一个重绘请求然后由系统在合适时机调用 paintEvent。因此连续多次调用 update()在同一个事件循环批次内会被合并成一次重绘这对高频鼠标拖动场景是好事不用每次移动都做一次完整绘制。一个新手常见的错误是在 paintEvent 里调用 update()这样会形成绘制死循环paintEvent 触发 updateupdate 又调度一次 paintEventCPU 占用直接拉满。我见过有的教程源码里确实写了这种代码多半是作者为了演示“动态重绘”但到了实际项目里这就是性能炸弹。另一个细节是 QtCreator 自动生成的 .ui 文件如果你在界面设计器里给容器设置了样式表某些样式属性会影响子控件的绘制缓冲行为导致自定义绘制的控件显示异常。遇到这类问题优先检查控件的 autoFillBackground 属性和样式表而不是怀疑绘制代码本身。3. 鼠标事件驱动图元从按住、拖拽到松开的完整绘制流程3.1 三段式事件处理press 记录起点move 更新预览release 提交图元画图软件的核心交互是按住鼠标拖动、松手落笔。Qt 里对应三个事件函数mousePressEvent、mouseMoveEvent、mouseReleaseEvent。这套源码里通常会把它们拆成三段来处理按下时记录起点移动时更新一个临时图元用于显示预览松开时把临时图元转成正式图元存入列表。注意 mouseMoveEvent 默认只在按住鼠标按键时才触发如果你想让鼠标悬停也触发移动事件需要调用 setMouseTracking(true)不过对画图来说按住才触发反而是默认的合理行为。// drawingwidget.h 中新增的成员 // QPointF m_startPoint; // 鼠标按下时的起点 // QPointF m_tempEndPoint; // 鼠标移动时的临时终点 // bool m_drawing false; // 是否正在拖拽绘制void DrawingWidget::mousePressEvent(QMouseEvent *event) { if (event-button() Qt::LeftButton) { m_startPoint event-pos(); // 记录按下位置注意是控件局部坐标 m_drawing true; // 进入绘制状态 } QWidget::mousePressEvent(event); // 继续传递事件保持默认行为 } void DrawingWidget::mouseMoveEvent(QMouseEvent *event) { if (m_drawing) { m_tempEndPoint event-pos(); // 每次移动都更新终点 update(); // 请求重绘显示橡皮筋预览 } } void DrawingWidget::mouseReleaseEvent(QMouseEvent *event) { if (event-button() Qt::LeftButton m_drawing) { m_lines.append(QLineF(m_startPoint, event-pos())); // 提交正式图元 m_drawing false; // 退出绘制状态 m_tempEndPoint QPointF(); // 清空临时终点 update(); // 最后一次重绘画上正式线 } QWidget::mouseReleaseEvent(event); }这段代码的关键点有三个。第一event-pos() 返回的是相对于当前控件左上角的设备坐标如果控件嵌在 QScrollArea 里这个坐标不需要额外换算因为绘制也是相对控件自身进行的。第二m_drawing 是一个标志位避免鼠标没有按下时移动事件也触发绘制逻辑。第三临时终点 m_tempEndPoint 单独存储目的是让 paintEvent 里能区分“预览中的图元”和“已经提交的图元”否则鼠标移动时你就会把一条还没画完的线提前写进正式列表。3.2 图元类设计用枚举区分图形类型用 QList 存储所有已画图元随着功能增加绘图软件不可能只画直线。矩形、椭圆、自由笔迹都要加进来。源码包里的做法一般有两种一种是为每种图形单独定义一个类再用继承和多态另一种是用一个结构体加枚举类型配合一个 switch 分支处理不同形状。前一种扩展性好但对新手来说代码量大后一种直接适合教程场景也够支撑几百个图元的轻量绘图软件。// 图元类型枚举 enum class ShapeType { Line, // 直线 Rect, // 矩形 Ellipse, // 椭圆 Freehand // 自由笔迹 }; // 单个图元的数据结构 struct ShapeItem { ShapeType type; // 图元类型绘制时用来决定分支 QPointF start; // 起点或矩形左上角 QPointF end; // 终点或矩形右下角 QColor penColor; // 画笔颜色 int penWidth 2; // 画笔宽度默认 2 QVectorQPointF points; // 自由笔迹的点集其他类型为空 };paintEvent 里遍历这个列表根据 type 走不同的绘制分支。用 QList 存图元是因为 QList 在 Qt 5 里对频繁插入删除的随机操作更友好而绘图场景中撤销、删除、重做都会改变列表结构。到了 Qt 6QList 与 QVector 已经统一直接用 QList 不会错。这里我习惯把图元定义成值类型而不是指针原因有两个值类型在 QList 扩容时自动拷贝不需要手动 new 和 delete避免内存泄漏每个 ShapeItem 数据量很小不同于复杂对象值拷贝的代价完全可以接受。3.3 橡皮筋预览与自由笔迹临时图元单独存点集用完记得清橡皮筋效果是所有绘图软件的基本交互鼠标拖动时从起点到当前鼠标位置实时显示一条跟随的线松手后线固定。实现上只需要 paintEvent 里绘制时在正式图元之后追加绘制一个临时图元。这里有两个细节容易踩坑。一是临时图元的样式应该和正式图元区分开比如用虚线让用户看出“还没定型”二是如果拖动的过程中频繁调用 update()而图元列表里已经保存了几百个图元每次都全部重新绘制会有可感知的卡顿最简单的优化是先用 QPainter::save() 保存状态画完临时图元后 restore()避免状态切换干扰正式图元的样式。自由笔迹的实现比直线复杂一些核心是把鼠标移动经过的点都记录下来// 自由笔迹的移动事件处理 void DrawingWidget::mouseMoveEvent(QMouseEvent *event) { if (m_drawing m_currentType ShapeType::Freehand) { m_tempPoints.append(event-pos()); // 追加采样点 update(); } } // paintEvent 中绘制自由笔迹的分支 painter.setPen(QPen(m_currentColor, m_currentWidth)); QPainterPath path; path.moveTo(m_tempPoints.first()); // 起点 for (int i 1; i m_tempPoints.size(); i) { path.lineTo(m_tempPoints.at(i)); // 依次连线 } painter.drawPath(path);点集采样的密度直接影响笔迹平滑度和内存占用。鼠标事件每帧触发一次如果用户画一条很长的线points 里可能存了几百个点画出来没问题但对后续的序列化和撤销操作会造成压力。我一般会在追加点的时候做一个简单过滤如果新点到上一个点的距离小于 2 像素就跳过这样既能保持笔迹形状又能减少点数量。还需要注意freehand 图元提交到正式列表后m_tempPoints 一定要清空否则下一次画线会把上一条笔迹的残留点一起画出来——这是一个非常隐蔽的界面错乱来源。4. 绘图软件避坑排查五个“看似没问题”的翻车现场4.1 窗口拉伸后图形被裁掉以为是坐标系问题现象图形在初始窗口大小内显示正常把窗口拉大后原本完整的图形缺了一块或者新画的内容显示不出来。原因通常不是坐标系而是绘制依赖了缓存的固定尺寸位图。如果代码里把绘制结果先画到一张固定大小的 QPixmap 上再在 paintEvent 里把这张图直接贴到控件上那么窗口变大后超出位图范围的部分自然就是空的。解决方法是放弃固定尺寸位图直接在 paintEvent 里按当前控件尺寸绘制每次拉伸都会触发 resizeEvent 和 paintEvent图形自然跟随窗口更新。如果性能要求高必须用缓存位图那就在 resizeEvent 里重建位图并重新渲染一次。4.2 画笔样式串到下一个图元QPainter 状态没恢复现象画完一条红色直线后接着画蓝色矩形结果显示矩形也变成了红色。原因是你把 QPen 设置在了同一个 QPainter 对象上。QPainter 是一次性的绘制会话如果你在绘制循环里统一设置样式那么 setPen 的状态会一直保留到下一个 setPen 出现。解决方法是每个图元绘制前都明确设置一次 pen 和 brush或者整段绘制逻辑外面用 painter.save() 包住绘制完再 painter.restore()。我见过一份参考代码它在循环外面只 SetPen 一次然后绘制所有图元结果全部图形都是一个颜色那就是典型的状态污染。4.3 保存图片是空白文件QPixmap 默认尺寸惹的祸现象调用 QPixmap 保存 PNG代码执行完没有报错生成的文件也能打开但里面全是空白。原因基本是 QPixmap pixmap; 这句代码创建了一张宽和高都为 0 的空图片。QPainter 在零尺寸设备上绘制不会崩溃但也不会有任何像素输出。解决方法是构造时指定尺寸比如 QPixmap pixmap(size()); 其中 size() 来自控件的当前尺寸然后用 QPainter 把控件内容画到 pixmap 上最后 pixmap.save(xxx.png)。还有一种更省事的方式直接用 QWidget::render(pixmap)它会把控件及其子控件的绘制结果渲染到目标设备上前提同样是 pixmap 已经初始化了有效尺寸。4.4 界面中文变成方块源文件编码没统一现象在 QtCreator 里打开工程界面控件上的中文显示正常但换一种编译方式后全部变成乱码或方块。原因在于源码文件的保存编码和编译器的默认编码不一致。Qt 从 5 开始默认源代码按 UTF-8 处理但 Windows 上 MSVC 编译器默认按本地代码页读取没有 BOM 的源文件于是中文字符串字面量被错误解码。解决方法是统一三件事源文件都以 UTF-8 保存最好带 BOMMSVC 编译器在 .pro 里加 QMAKE_CXXFLAGS /utf-8工程中所有的字符串常量统一用 QStringLiteral 或 QString::fromLocal8Bit 处理不要直接写 char* 中文字面量。4.5 撤销重做栈索引越界压栈顺序和列表清理没对齐现象连续撤销十几步后程序崩溃调试器指向 list.size() 的某处越界。原因通常是自写撤销栈时只记录了操作没有同步清理重做分支。比如你撤销了一次删除然后又画了一条新线此时重做栈里还留着刚才那条被删除的图元记录下一次撤销时索引就对不上了。正确的做法是每次压入新的撤销命令前先清空重做栈撤销和重做操作都以迭代器而不是整数下标来定位图元每次 push 之前检查图元列表是否为空。这些规则在任何自写状态栈里都通用不只是 Qt 绘图才有。5. 图元数据存储与撤销重做JSON 序列化、回读校验与状态栈设计5.1 自建图元数据格式类型、几何、样式三个字段组绘图软件画出来的内容要能保存文件、下次打开还能还原就必须把图元序列化成一种可持久化的格式。这套源码里如果只做到了“能画能显示”没有“能存能读”那是不完整的。我一般会先定一个图元数据结构它的字段要覆盖三块类型直线、矩形、椭圆、自由笔迹、几何起点、终点或点集、样式颜色、笔宽。注意颜色字段不要存 QColor 对象本身因为 QColor 不能直接被 QDataStream 或者 JSON 友好地序列化要转成字符串或 RGBA 整数分量。enum class ShapeType { Line, Rect, Ellipse, Freehand }; struct ShapeItem { ShapeType type; // 图元类型 QPointF start; // 起点或左上角 QPointF end; // 终点或右下角 QColor penColor; // 画笔颜色 int penWidth 2; // 笔宽 QVectorQPointF points; // 自由笔迹的采样点 };这套结构里我用 QPointF 存坐标是因为浮点坐标可以避免来回缩放后误差累积用 QVector 存自由笔迹的点集是因为 QVector 在内存中是连续存储遍历绘制时缓存友好。实际读到这类源码时我建议你保留这个结构设计不要在上面堆砌额外的功能字段——撤销、选中、层级这些需求应该在更高一层处理而不是把每个图元结构体撑得越来越重。5.2 JSON 序列化颜色存“#rrggbb”坐标存浮点分量JSON 是 Qt 5 之后最方便的跨平台序列化格式QJsonDocument、QJsonObject、QJsonArray 三件套足够处理图元列表。序列化时我习惯按图元逐个生成 QJsonObject然后用类型整数而不是类型字符串来标识图元类型原因很简单字符串在文件里可读性好但解析时每次都要比较字符串而且一旦改类名旧文件全部失效整数枚举稳定且快。// 把单个图元序列化成 JSON 对象 QJsonObject ShapeItem::toJson() const { QJsonObject obj; obj[type] static_castint(type); // 枚举转整数写入 obj[penColor] penColor.name(); // 存 #rrggbb 颜色名 obj[penWidth] penWidth; obj[startX] start.x(); // 坐标分两个字段保存 obj[startY] start.y(); obj[endX] end.x(); obj[endY] end.y(); QJsonArray pointsJson; for (const QPointF p : points) { QJsonObject pointObj; pointObj[x] p.x(); pointObj[y] p.y(); pointsJson.append(pointObj); } obj[points] pointsJson; return obj; }序列化代码里最值得关注的是“颜色怎么存”。QColor::name() 返回的是十六进制颜色值比如 #ff5500这个格式在回读时直接传给 QColor 构造函数就能解析。相反如果你用 color.name(QColor::HexArgb) 或者干脆存 color.red()、green()、blue() 三个分量回读时还得自己组参数多一步就多一个出错机会。坐标存浮点分量而不是存 QPointF 或 QPoint也是同一个道理QPoint 是整数精度图像缩放后坐标偏移会被舍入多次存读之后图形位置明显漂移。QJsonObject 本身不直接支持自定义类型必须拆成基础类型才能写入这是 Qt 序列化的一个基础边界。5.3 撤销重做自写两个栈还是用 QUndoStack撤销重做在绘图软件里是刚需画错了要能退回去。Qt 提供了 QUndoStack 和 QUndoCommand但绝大多数教程源码不会直接用因为它要求每个操作都封装成一个 command 类代码量比自写两个栈大得多。对于图元数量在几百以内的轻量绘图软件我倾向于自写撤销栈理由是用两个 QList 指针就能模拟完整的状态栈逻辑。// 自写撤销栈的核心操作 void DrawingWidget::pushUndo(const QListShapeItem snapshot) { m_undoStack.push(snapshot); // 压入当前图元列表快照 m_redoStack.clear(); // 新操作产生后清空重做分支 } void DrawingWidget::undo() { if (m_undoStack.isEmpty()) return; m_redoStack.push(m_items); // 当前状态进重做栈 m_items m_undoStack.pop(); // 恢复到上一个快照 update(); } void DrawingWidget::redo() { if (m_redoStack.isEmpty()) return; m_undoStack.push(m_items); // 当前状态进撤销栈 m_items m_redoStack.pop(); // 恢复快照 update(); }这种快照式撤销的优缺点是分明的。优点是逻辑简单每个操作不需要自定义命令类撤销任何动作都等价于恢复整张图元列表缺点是每压入一次快照都复制整个列表图元数量大时内存占用成倍增长。折中的做法是只在关键操作画完一个图元、删除、修改属性的时刻压栈而不是鼠标每次移动都压栈这样栈的数量是可控的。绘图软件还有一类特殊坑撤销时 If 你直接对 m_items 做下标删除操作删除后列表元素前移下标和撤销栈里记录的状态就对不齐。所有涉及列表结构变化的地方优先用 QList::erase 配合迭代器或者干脆整体赋值快照这是这套源码里最该被人记住的一个实现细节。6. 进阶调优滚轮缩放、视口平移与渲染架构的取舍6.1 滚轮缩放paintEvent 里先 scale 再 translate坐标映射别算反绘图软件支持滚轮缩放后paintEvent 里的 QPainter 变换就是核心。最常见的方法是 painter.scale(zoom, zoom) 把画布整体放大再用 translate 移动视口。这里的顺序不能反先 scale 再 translate等价于缩放围绕画布原点平移量是逻辑坐标单位如果先 translate 再 scale平移量会被一起缩放鼠标指向的画布位置会跑偏。void DrawingWidget::paintEvent(QPaintEvent *event) { QPainter painter(this); painter.setRenderHint(QPainter::Antialiasing, m_antialias); // 按开关决定 painter.scale(m_zoom, m_zoom); // 缩放画布 painter.translate(-m_offsetX, -m_offsetY); // 平移视口负号表示视角跟随 drawAllItems(painter); // 后续绘制全部按逻辑坐标 } QPointF DrawingWidget::screenToScene(const QPoint pos) const { // 从设备坐标换算回逻辑坐标缩放和平移都要反向处理 return QPointF(pos.x() / m_zoom m_offsetX, pos.y() / m_zoom m_offsetY); }缩放平移之后鼠标事件拿到的坐标是设备坐标必须经过 screenToScene 换算成逻辑坐标才能正确判断用户点在哪个图元上。这个映射函数要和 painter.scale、translate 的参数严格对应否则会出现“点击位置画出的图形偏了”的现象。我在第一次实现缩放时把 scale 和 translate 的顺序写反了拖动图元时总有一个偏移量排查了半小时才发现是绘制变换和坐标换算用的参数顺序不一致。从那以后我每次加缩放功能都会强制把“绘制变换”和“鼠标映射”两段代码放在一起写写完立刻对拍验证一次。6.2 图元数量破千之后再考虑 QGraphicsView 架构自绘方式写 paintEvent 的瓶颈在于每次 update() 都要遍历全部图元重画一遍。图元数量在几十到几百时毫无压力超过一千个加上缩放平移操作帧率会明显下降。解决办法有两个方向一是保持自绘把静态图层预先渲染到 QPixmap 里只有新增或编辑图元时才局部重绘二是弃用自绘改用 QGraphicsView QGraphicsScene让框架帮你做视口裁剪和局部更新。判断标准有一个经验值你需要图元级选中、拖动、分组、层级关系时QGraphicsView 的收益大于迁移成本如果就是简单地画直线、矩形、标注自绘方案反而可控因为 QGraphicsView 的 item 坐标体系和自定义数据结构之间的转换同样需要时间成本去学。反走样在缩放场景下的取舍也要提一句开启 QPainter::Antialiasing 后缩放拖动会更平滑但 CPU 和 GPU 开销同步上升临时禁用抗锯齿做拖动松手后再重绘一次是一个常用技巧代价是拖动过程中图形边缘有锯齿换来的是操作跟手。这套源码如果没做缩放功能你把这节内容加进去其实就是从“能画”到“好画”的关键一步。希望帮到你。本文还有配套的精品资源点击获取
简介面向Qt初学者的2D绘图开发教程与完整源码包以paintExample示例为主线讲解QPainter绘图、QPaintEvent处理、QGraphicsView/Scene高级图形对象交互等核心机制。压缩包内含114个文件约3.54MB包括18个h头文件与15个cpp源文件、7个ui界面设计文件、4个pro工程文件、52张png示意图及1份PDF说明文档目录结构清晰便于对照学习。资源已有704人学习代码完整覆盖主窗口搭建、绘图区绘制、鼠标拖拽事件、颜色与画笔选择、绘图保存载入等关键功能并针对QPainter属性设置、update()重绘时机等常见细节给出实现参考。通过学习这套源码与教程可快速掌握Qt绘图程序的工程组织方式为进阶开发复杂图形应用打下基础。1. Qt 绘图软件教程与源码这套 2D 绘图工程真正值得吃透的部分拿到“Qt 编写绘图软件教程及相关源码”这类资源包我习惯先不做两件事不急着编译不急着看界面。先翻目录结构再看示例工程里重写了哪些事件函数。实际决定一个 Qt 绘图软件能不能扩展的不是 paintEvent 里那几行画图代码而是坐标转换、图元存储和重绘策略这三块——坑也基本都埋在这三块里。这套资源用 QtCreator Qt Widgets 的常规写法把 2D 绘图的完整路径串了下来。直接跑通只需要十分钟但想把它改成自己能加功能的绘图程序需要把坐标系、鼠标事件、序列化这条路完整走一遍。适合正在学 Qt、准备做白板或标注工具、又不想一上来就依赖 QGraphicsView 的开发者。2. 从 QtCreator 工程到第一个绘制控件QPainter 坐标系与 paintEvent 的前置认知2.1 QPainter 的三层坐标体系画之前先想清楚“画在哪”QPainter 绘制时其实同时存在三套坐标初读源码包的开发者最容易在这上面翻车。第一套是逻辑坐标也就是直接传给 QPainter 的 drawLine、drawRect 这些函数的数值第二套是设备坐标指控件实际的像素尺寸paintEvent 里的 event-rect()、控件的 width() 和 height() 都属于这个层面第三套是窗口与视口映射由 setWindow 和 setViewport 控制用来把逻辑坐标映射到设备坐标。大多数教程源码里前两套会出现第三套往往藏在缩放功能的实现里。坐标系参照对象典型使用方式常见误用逻辑坐标QPainter 绘制接口drawLine、drawRect 的参数把控件像素尺寸当逻辑坐标直接画设备坐标控件实际像素event-rect()、widget-size()缩放逻辑跟着 scale 一起放大窗口/视口QPainter 内部映射setWindow / setViewport理解成窗口大小与控件大小为什么绘图软件一定要区分这套体系因为 paintEvent 里绘制用的是逻辑坐标鼠标事件回传的 QMouseEvent::pos() 是设备坐标这两者不相等。如果你在程序里直接把鼠标坐标拿去画图看起来“画对了”是因为没有做缩放时逻辑坐标与设备坐标恰好一比一一旦加入缩放、平移或者窗口尺寸变化问题就暴露了。所以我看一份 Qt 绘图源码第一件事就是找坐标换算的代码找不到往往说明工程只做了最基础的画布功能。2.2 在 QtCreator 里建立一个最小绘图工程一个类、两个文件、一次重绘这份教程资源的起点通常是一个 Qt Widgets Application。在 QtCreator 里新建工程后默认会生成 main.cpp、mainwindow.cpp 和 mainwindow.ui。最省事的做法不是直接在 MainWindow 里写绘制代码而是新建一个 QWidget 子类比如叫 DrawingWidget然后把主窗口的 centralwidget 提升成这个类。在界面上右键 centralwidget选择“提升为”类名填 DrawingWidget头文件填 drawingwidget.hQtCreator 会自动生成提升代码。这样做的好处是绘制的逻辑独立成类后续加缩放、存文件都不需要动到界面代码。下面是这套绘图软件最核心的一个最小实现我自己拆这种工程时会先把代码缩减到这个程度跑通了再往上加功能// drawingwidget.h #ifndef DRAWINGWIDGET_H #define DRAWINGWIDGET_H #include QWidget #include QPointF class DrawingWidget : public QWidget { Q_OBJECT public: explicit DrawingWidget(QWidget *parent nullptr); protected: void paintEvent(QPaintEvent *event) override; // 所有绘制都进这里 }; #endif// drawingwidget.cpp #include drawingwidget.h #include QPainter DrawingWidget::DrawingWidget(QWidget *parent) : QWidget(parent) { setSizePolicy(QSizePolicy::Expanding, QSizePolicy::Expanding); // 让控件跟随窗口拉伸而不是固定大小 } void DrawingWidget::paintEvent(QPaintEvent *event) { QPainter painter(this); // 以当前控件为画布 painter.setRenderHint(QPainter::Antialiasing, true); // 打开抗锯齿 painter.setPen(QPen(QColor(60, 120, 200), 2.0)); // 蓝色笔宽 2 painter.drawLine(QPointF(20, 20), QPointF(width() - 20, height() - 20)); // 画对角线 }这段代码里有几个参数值得注意。QPainter painter(this) 中的 this 表示画布就是控件自身绘制的结果直接显示在界面上如果传入一个 QPixmap绘制就不会上屏而是画到内存图像里后面保存图片时用得上。setRenderHint(QPainter::Antialiasing, true) 打开抗锯齿画斜线时边缘会更平滑但对性能有一定损耗图元数量多的时候需要谨慎使用。最后的 drawLine 用了 width() 和 height() 动态获取控件尺寸保证窗口拉伸时线能跟着变化这是绘图软件基础但很重要的一个习惯。2.3 update() 是唯一正确的重绘入口别直接调用 paintEvent看完最小工程下一个需要建立的概念是重绘机制。paintEvent 是系统在需要绘制时自动回调的它不会也不应该被手动直接调用。想让窗口重新绘制正确的方式是调用 update()它的工作方式是向事件循环投递一个重绘请求然后由系统在合适时机调用 paintEvent。因此连续多次调用 update()在同一个事件循环批次内会被合并成一次重绘这对高频鼠标拖动场景是好事不用每次移动都做一次完整绘制。一个新手常见的错误是在 paintEvent 里调用 update()这样会形成绘制死循环paintEvent 触发 updateupdate 又调度一次 paintEventCPU 占用直接拉满。我见过有的教程源码里确实写了这种代码多半是作者为了演示“动态重绘”但到了实际项目里这就是性能炸弹。另一个细节是 QtCreator 自动生成的 .ui 文件如果你在界面设计器里给容器设置了样式表某些样式属性会影响子控件的绘制缓冲行为导致自定义绘制的控件显示异常。遇到这类问题优先检查控件的 autoFillBackground 属性和样式表而不是怀疑绘制代码本身。3. 鼠标事件驱动图元从按住、拖拽到松开的完整绘制流程3.1 三段式事件处理press 记录起点move 更新预览release 提交图元画图软件的核心交互是按住鼠标拖动、松手落笔。Qt 里对应三个事件函数mousePressEvent、mouseMoveEvent、mouseReleaseEvent。这套源码里通常会把它们拆成三段来处理按下时记录起点移动时更新一个临时图元用于显示预览松开时把临时图元转成正式图元存入列表。注意 mouseMoveEvent 默认只在按住鼠标按键时才触发如果你想让鼠标悬停也触发移动事件需要调用 setMouseTracking(true)不过对画图来说按住才触发反而是默认的合理行为。// drawingwidget.h 中新增的成员 // QPointF m_startPoint; // 鼠标按下时的起点 // QPointF m_tempEndPoint; // 鼠标移动时的临时终点 // bool m_drawing false; // 是否正在拖拽绘制void DrawingWidget::mousePressEvent(QMouseEvent *event) { if (event-button() Qt::LeftButton) { m_startPoint event-pos(); // 记录按下位置注意是控件局部坐标 m_drawing true; // 进入绘制状态 } QWidget::mousePressEvent(event); // 继续传递事件保持默认行为 } void DrawingWidget::mouseMoveEvent(QMouseEvent *event) { if (m_drawing) { m_tempEndPoint event-pos(); // 每次移动都更新终点 update(); // 请求重绘显示橡皮筋预览 } } void DrawingWidget::mouseReleaseEvent(QMouseEvent *event) { if (event-button() Qt::LeftButton m_drawing) { m_lines.append(QLineF(m_startPoint, event-pos())); // 提交正式图元 m_drawing false; // 退出绘制状态 m_tempEndPoint QPointF(); // 清空临时终点 update(); // 最后一次重绘画上正式线 } QWidget::mouseReleaseEvent(event); }这段代码的关键点有三个。第一event-pos() 返回的是相对于当前控件左上角的设备坐标如果控件嵌在 QScrollArea 里这个坐标不需要额外换算因为绘制也是相对控件自身进行的。第二m_drawing 是一个标志位避免鼠标没有按下时移动事件也触发绘制逻辑。第三临时终点 m_tempEndPoint 单独存储目的是让 paintEvent 里能区分“预览中的图元”和“已经提交的图元”否则鼠标移动时你就会把一条还没画完的线提前写进正式列表。3.2 图元类设计用枚举区分图形类型用 QList 存储所有已画图元随着功能增加绘图软件不可能只画直线。矩形、椭圆、自由笔迹都要加进来。源码包里的做法一般有两种一种是为每种图形单独定义一个类再用继承和多态另一种是用一个结构体加枚举类型配合一个 switch 分支处理不同形状。前一种扩展性好但对新手来说代码量大后一种直接适合教程场景也够支撑几百个图元的轻量绘图软件。// 图元类型枚举 enum class ShapeType { Line, // 直线 Rect, // 矩形 Ellipse, // 椭圆 Freehand // 自由笔迹 }; // 单个图元的数据结构 struct ShapeItem { ShapeType type; // 图元类型绘制时用来决定分支 QPointF start; // 起点或矩形左上角 QPointF end; // 终点或矩形右下角 QColor penColor; // 画笔颜色 int penWidth 2; // 画笔宽度默认 2 QVectorQPointF points; // 自由笔迹的点集其他类型为空 };paintEvent 里遍历这个列表根据 type 走不同的绘制分支。用 QList 存图元是因为 QList 在 Qt 5 里对频繁插入删除的随机操作更友好而绘图场景中撤销、删除、重做都会改变列表结构。到了 Qt 6QList 与 QVector 已经统一直接用 QList 不会错。这里我习惯把图元定义成值类型而不是指针原因有两个值类型在 QList 扩容时自动拷贝不需要手动 new 和 delete避免内存泄漏每个 ShapeItem 数据量很小不同于复杂对象值拷贝的代价完全可以接受。3.3 橡皮筋预览与自由笔迹临时图元单独存点集用完记得清橡皮筋效果是所有绘图软件的基本交互鼠标拖动时从起点到当前鼠标位置实时显示一条跟随的线松手后线固定。实现上只需要 paintEvent 里绘制时在正式图元之后追加绘制一个临时图元。这里有两个细节容易踩坑。一是临时图元的样式应该和正式图元区分开比如用虚线让用户看出“还没定型”二是如果拖动的过程中频繁调用 update()而图元列表里已经保存了几百个图元每次都全部重新绘制会有可感知的卡顿最简单的优化是先用 QPainter::save() 保存状态画完临时图元后 restore()避免状态切换干扰正式图元的样式。自由笔迹的实现比直线复杂一些核心是把鼠标移动经过的点都记录下来// 自由笔迹的移动事件处理 void DrawingWidget::mouseMoveEvent(QMouseEvent *event) { if (m_drawing m_currentType ShapeType::Freehand) { m_tempPoints.append(event-pos()); // 追加采样点 update(); } } // paintEvent 中绘制自由笔迹的分支 painter.setPen(QPen(m_currentColor, m_currentWidth)); QPainterPath path; path.moveTo(m_tempPoints.first()); // 起点 for (int i 1; i m_tempPoints.size(); i) { path.lineTo(m_tempPoints.at(i)); // 依次连线 } painter.drawPath(path);点集采样的密度直接影响笔迹平滑度和内存占用。鼠标事件每帧触发一次如果用户画一条很长的线points 里可能存了几百个点画出来没问题但对后续的序列化和撤销操作会造成压力。我一般会在追加点的时候做一个简单过滤如果新点到上一个点的距离小于 2 像素就跳过这样既能保持笔迹形状又能减少点数量。还需要注意freehand 图元提交到正式列表后m_tempPoints 一定要清空否则下一次画线会把上一条笔迹的残留点一起画出来——这是一个非常隐蔽的界面错乱来源。4. 绘图软件避坑排查五个“看似没问题”的翻车现场4.1 窗口拉伸后图形被裁掉以为是坐标系问题现象图形在初始窗口大小内显示正常把窗口拉大后原本完整的图形缺了一块或者新画的内容显示不出来。原因通常不是坐标系而是绘制依赖了缓存的固定尺寸位图。如果代码里把绘制结果先画到一张固定大小的 QPixmap 上再在 paintEvent 里把这张图直接贴到控件上那么窗口变大后超出位图范围的部分自然就是空的。解决方法是放弃固定尺寸位图直接在 paintEvent 里按当前控件尺寸绘制每次拉伸都会触发 resizeEvent 和 paintEvent图形自然跟随窗口更新。如果性能要求高必须用缓存位图那就在 resizeEvent 里重建位图并重新渲染一次。4.2 画笔样式串到下一个图元QPainter 状态没恢复现象画完一条红色直线后接着画蓝色矩形结果显示矩形也变成了红色。原因是你把 QPen 设置在了同一个 QPainter 对象上。QPainter 是一次性的绘制会话如果你在绘制循环里统一设置样式那么 setPen 的状态会一直保留到下一个 setPen 出现。解决方法是每个图元绘制前都明确设置一次 pen 和 brush或者整段绘制逻辑外面用 painter.save() 包住绘制完再 painter.restore()。我见过一份参考代码它在循环外面只 SetPen 一次然后绘制所有图元结果全部图形都是一个颜色那就是典型的状态污染。4.3 保存图片是空白文件QPixmap 默认尺寸惹的祸现象调用 QPixmap 保存 PNG代码执行完没有报错生成的文件也能打开但里面全是空白。原因基本是 QPixmap pixmap; 这句代码创建了一张宽和高都为 0 的空图片。QPainter 在零尺寸设备上绘制不会崩溃但也不会有任何像素输出。解决方法是构造时指定尺寸比如 QPixmap pixmap(size()); 其中 size() 来自控件的当前尺寸然后用 QPainter 把控件内容画到 pixmap 上最后 pixmap.save(xxx.png)。还有一种更省事的方式直接用 QWidget::render(pixmap)它会把控件及其子控件的绘制结果渲染到目标设备上前提同样是 pixmap 已经初始化了有效尺寸。4.4 界面中文变成方块源文件编码没统一现象在 QtCreator 里打开工程界面控件上的中文显示正常但换一种编译方式后全部变成乱码或方块。原因在于源码文件的保存编码和编译器的默认编码不一致。Qt 从 5 开始默认源代码按 UTF-8 处理但 Windows 上 MSVC 编译器默认按本地代码页读取没有 BOM 的源文件于是中文字符串字面量被错误解码。解决方法是统一三件事源文件都以 UTF-8 保存最好带 BOMMSVC 编译器在 .pro 里加 QMAKE_CXXFLAGS /utf-8工程中所有的字符串常量统一用 QStringLiteral 或 QString::fromLocal8Bit 处理不要直接写 char* 中文字面量。4.5 撤销重做栈索引越界压栈顺序和列表清理没对齐现象连续撤销十几步后程序崩溃调试器指向 list.size() 的某处越界。原因通常是自写撤销栈时只记录了操作没有同步清理重做分支。比如你撤销了一次删除然后又画了一条新线此时重做栈里还留着刚才那条被删除的图元记录下一次撤销时索引就对不上了。正确的做法是每次压入新的撤销命令前先清空重做栈撤销和重做操作都以迭代器而不是整数下标来定位图元每次 push 之前检查图元列表是否为空。这些规则在任何自写状态栈里都通用不只是 Qt 绘图才有。5. 图元数据存储与撤销重做JSON 序列化、回读校验与状态栈设计5.1 自建图元数据格式类型、几何、样式三个字段组绘图软件画出来的内容要能保存文件、下次打开还能还原就必须把图元序列化成一种可持久化的格式。这套源码里如果只做到了“能画能显示”没有“能存能读”那是不完整的。我一般会先定一个图元数据结构它的字段要覆盖三块类型直线、矩形、椭圆、自由笔迹、几何起点、终点或点集、样式颜色、笔宽。注意颜色字段不要存 QColor 对象本身因为 QColor 不能直接被 QDataStream 或者 JSON 友好地序列化要转成字符串或 RGBA 整数分量。enum class ShapeType { Line, Rect, Ellipse, Freehand }; struct ShapeItem { ShapeType type; // 图元类型 QPointF start; // 起点或左上角 QPointF end; // 终点或右下角 QColor penColor; // 画笔颜色 int penWidth 2; // 笔宽 QVectorQPointF points; // 自由笔迹的采样点 };这套结构里我用 QPointF 存坐标是因为浮点坐标可以避免来回缩放后误差累积用 QVector 存自由笔迹的点集是因为 QVector 在内存中是连续存储遍历绘制时缓存友好。实际读到这类源码时我建议你保留这个结构设计不要在上面堆砌额外的功能字段——撤销、选中、层级这些需求应该在更高一层处理而不是把每个图元结构体撑得越来越重。5.2 JSON 序列化颜色存“#rrggbb”坐标存浮点分量JSON 是 Qt 5 之后最方便的跨平台序列化格式QJsonDocument、QJsonObject、QJsonArray 三件套足够处理图元列表。序列化时我习惯按图元逐个生成 QJsonObject然后用类型整数而不是类型字符串来标识图元类型原因很简单字符串在文件里可读性好但解析时每次都要比较字符串而且一旦改类名旧文件全部失效整数枚举稳定且快。// 把单个图元序列化成 JSON 对象 QJsonObject ShapeItem::toJson() const { QJsonObject obj; obj[type] static_castint(type); // 枚举转整数写入 obj[penColor] penColor.name(); // 存 #rrggbb 颜色名 obj[penWidth] penWidth; obj[startX] start.x(); // 坐标分两个字段保存 obj[startY] start.y(); obj[endX] end.x(); obj[endY] end.y(); QJsonArray pointsJson; for (const QPointF p : points) { QJsonObject pointObj; pointObj[x] p.x(); pointObj[y] p.y(); pointsJson.append(pointObj); } obj[points] pointsJson; return obj; }序列化代码里最值得关注的是“颜色怎么存”。QColor::name() 返回的是十六进制颜色值比如 #ff5500这个格式在回读时直接传给 QColor 构造函数就能解析。相反如果你用 color.name(QColor::HexArgb) 或者干脆存 color.red()、green()、blue() 三个分量回读时还得自己组参数多一步就多一个出错机会。坐标存浮点分量而不是存 QPointF 或 QPoint也是同一个道理QPoint 是整数精度图像缩放后坐标偏移会被舍入多次存读之后图形位置明显漂移。QJsonObject 本身不直接支持自定义类型必须拆成基础类型才能写入这是 Qt 序列化的一个基础边界。5.3 撤销重做自写两个栈还是用 QUndoStack撤销重做在绘图软件里是刚需画错了要能退回去。Qt 提供了 QUndoStack 和 QUndoCommand但绝大多数教程源码不会直接用因为它要求每个操作都封装成一个 command 类代码量比自写两个栈大得多。对于图元数量在几百以内的轻量绘图软件我倾向于自写撤销栈理由是用两个 QList 指针就能模拟完整的状态栈逻辑。// 自写撤销栈的核心操作 void DrawingWidget::pushUndo(const QListShapeItem snapshot) { m_undoStack.push(snapshot); // 压入当前图元列表快照 m_redoStack.clear(); // 新操作产生后清空重做分支 } void DrawingWidget::undo() { if (m_undoStack.isEmpty()) return; m_redoStack.push(m_items); // 当前状态进重做栈 m_items m_undoStack.pop(); // 恢复到上一个快照 update(); } void DrawingWidget::redo() { if (m_redoStack.isEmpty()) return; m_undoStack.push(m_items); // 当前状态进撤销栈 m_items m_redoStack.pop(); // 恢复快照 update(); }这种快照式撤销的优缺点是分明的。优点是逻辑简单每个操作不需要自定义命令类撤销任何动作都等价于恢复整张图元列表缺点是每压入一次快照都复制整个列表图元数量大时内存占用成倍增长。折中的做法是只在关键操作画完一个图元、删除、修改属性的时刻压栈而不是鼠标每次移动都压栈这样栈的数量是可控的。绘图软件还有一类特殊坑撤销时 If 你直接对 m_items 做下标删除操作删除后列表元素前移下标和撤销栈里记录的状态就对不齐。所有涉及列表结构变化的地方优先用 QList::erase 配合迭代器或者干脆整体赋值快照这是这套源码里最该被人记住的一个实现细节。6. 进阶调优滚轮缩放、视口平移与渲染架构的取舍6.1 滚轮缩放paintEvent 里先 scale 再 translate坐标映射别算反绘图软件支持滚轮缩放后paintEvent 里的 QPainter 变换就是核心。最常见的方法是 painter.scale(zoom, zoom) 把画布整体放大再用 translate 移动视口。这里的顺序不能反先 scale 再 translate等价于缩放围绕画布原点平移量是逻辑坐标单位如果先 translate 再 scale平移量会被一起缩放鼠标指向的画布位置会跑偏。void DrawingWidget::paintEvent(QPaintEvent *event) { QPainter painter(this); painter.setRenderHint(QPainter::Antialiasing, m_antialias); // 按开关决定 painter.scale(m_zoom, m_zoom); // 缩放画布 painter.translate(-m_offsetX, -m_offsetY); // 平移视口负号表示视角跟随 drawAllItems(painter); // 后续绘制全部按逻辑坐标 } QPointF DrawingWidget::screenToScene(const QPoint pos) const { // 从设备坐标换算回逻辑坐标缩放和平移都要反向处理 return QPointF(pos.x() / m_zoom m_offsetX, pos.y() / m_zoom m_offsetY); }缩放平移之后鼠标事件拿到的坐标是设备坐标必须经过 screenToScene 换算成逻辑坐标才能正确判断用户点在哪个图元上。这个映射函数要和 painter.scale、translate 的参数严格对应否则会出现“点击位置画出的图形偏了”的现象。我在第一次实现缩放时把 scale 和 translate 的顺序写反了拖动图元时总有一个偏移量排查了半小时才发现是绘制变换和坐标换算用的参数顺序不一致。从那以后我每次加缩放功能都会强制把“绘制变换”和“鼠标映射”两段代码放在一起写写完立刻对拍验证一次。6.2 图元数量破千之后再考虑 QGraphicsView 架构自绘方式写 paintEvent 的瓶颈在于每次 update() 都要遍历全部图元重画一遍。图元数量在几十到几百时毫无压力超过一千个加上缩放平移操作帧率会明显下降。解决办法有两个方向一是保持自绘把静态图层预先渲染到 QPixmap 里只有新增或编辑图元时才局部重绘二是弃用自绘改用 QGraphicsView QGraphicsScene让框架帮你做视口裁剪和局部更新。判断标准有一个经验值你需要图元级选中、拖动、分组、层级关系时QGraphicsView 的收益大于迁移成本如果就是简单地画直线、矩形、标注自绘方案反而可控因为 QGraphicsView 的 item 坐标体系和自定义数据结构之间的转换同样需要时间成本去学。反走样在缩放场景下的取舍也要提一句开启 QPainter::Antialiasing 后缩放拖动会更平滑但 CPU 和 GPU 开销同步上升临时禁用抗锯齿做拖动松手后再重绘一次是一个常用技巧代价是拖动过程中图形边缘有锯齿换来的是操作跟手。这套源码如果没做缩放功能你把这节内容加进去其实就是从“能画”到“好画”的关键一步。希望帮到你。本文还有配套的精品资源点击获取
