绘图系统 QPainter
QPainter 绘制、坐标变换与 GraphicsView
#三层架构:QPaintDevice / QPainter / QPaintEngine
Qt 的绘图系统是一个经典的三层设计,理解它你就明白了为什么"同一段绘制代码"能输出到窗口、图片、打印机、PDF:
| 层 | 类 | 职责 |
|---|---|---|
| 绘制设备 | QPaintDevice | 能被画的东西:QWidget、QPixmap、QImage、QPrinter… |
| 画笔 | QPainter | 你唯一需要打交道的 API:drawLine()、drawText()… |
| 绘制引擎 | QPaintEngine | 把 QPainter 的指令翻译成具体设备的原生命令 |
QPaintEngine 对应用开发者几乎不可见,但它是"一次编写、到处绘制"的关键。你调用 painter.drawRect(),在屏幕上它变成系统的 GDI/Direct2D 调用,在 PDF 上变成一段矢量指令,在 QImage 上变成像素运算——你的代码一行都不用改。
这意味着一个重要的实践:把绘制逻辑写成"与设备无关"的代码,只依赖传入的 QPainter 和 rect(),这样同一份代码可以直接用于屏幕渲染和导出高清图片。
#坐标系统与变换
Qt 的坐标原点在左上角,x 向右为正,y 向下为正(与数学坐标相反,和绝大多数 GUI 框架一致)。
QPainter 内置一个变换矩阵,提供了四个常用操作。理解它们的关键在于:变换是累积的,且作用顺序与调用顺序相反(矩阵右乘)。
| 方法 | 作用 | 常见用途 |
|---|---|---|
translate(dx, dy) | 平移原点 | 把原点移到控件中心,方便画极坐标图形 |
scale(sx, sy) | 缩放 | 绘制缩略图、翻转(负值) |
rotate(deg) | 顺时针旋转 | 仪表指针、刻度 |
shear(sh, sv) | 错切 | 斜体效果,少用 |
黄金搭档是 save() / restore():绘制前 save() 保存矩阵与画笔画刷状态,绘制后 restore() 恢复。它们必须成对出现,否则绘制状态会"泄漏"到后续代码,产生极难排查的错位 bug。
// 自定义控件:绘制时钟表盘
#include <QWidget>
#include <QPainter>
#include <QPaintEvent>
#include <QTime>
#include <cmath>
// 该类在 paintEvent 中绘制一个圆形表盘
class ClockWidget : public QWidget
{
Q_OBJECT
public:
explicit ClockWidget(QWidget *parent = nullptr) : QWidget(parent)
{
setMinimumSize(200, 200);
}
protected:
void paintEvent(QPaintEvent *) override
{
QPainter p(this);
p.setRenderHint(QPainter::Antialiasing, true); // 抗锯齿
const qreal side = qMin(width(), height());
const QPointF center(width() / 2.0, height() / 2.0);
p.save();
p.translate(center); // 原点移到中心
p.scale(side / 200.0, side / 200.0); // 归一化到 200×200 逻辑坐标
// 表盘背景
p.setPen(Qt::NoPen);
p.setBrush(QColor("#ffffff"));
p.drawEllipse(QPointF(0, 0), 100, 100);
// 12 个刻度
for (int i = 0; i < 12; ++i) {
p.save();
p.rotate(i * 30.0); // 每次绕新原点旋转
p.setPen(QPen(QColor("#333333"), (i % 3 == 0) ? 3 : 1));
p.drawLine(QPointF(0, -88), QPointF(0, -96));
p.restore(); // 恢复,避免累积旋转
}
const QTime now = QTime::currentTime();
// 时针
p.save();
p.rotate(30.0 * (now.hour() % 12) + 0.5 * now.minute());
p.setPen(QPen(QColor("#1a1a1a"), 6, Qt::SolidLine, Qt::RoundCap));
p.drawLine(QPointF(0, 0), QPointF(0, -45));
p.restore();
// 分针
p.save();
p.rotate(6.0 * now.minute() + 0.1 * now.second());
p.setPen(QPen(QColor("#444444"), 3, Qt::SolidLine, Qt::RoundCap));
p.drawLine(QPointF(0, 0), QPointF(0, -72));
p.restore();
p.restore(); // 与外层 save 配对
}
};这个例子展示了变换的精髓:先 translate 到中心,再用逻辑坐标(半径 100)绘图,最后用 scale 适配实际控件尺寸。这样无论控件多大,绘制代码都不用改——这是自绘控件适应 DPI 缩放和窗口拉伸的标准做法。
注意循环里的 save()/restore() 包住了 rotate()。如果省掉,12 次旋转会累积(0°、30°、60°…360°),刻度会 spiral 出去。
#抗锯齿的代价
QPainter::Antialiasing 让边缘平滑,但代价是性能下降,尤其在低端设备或大面积绘制时。建议:
- 静态内容、图表、文字:开启;
- 高速刷新的波形、实时曲线:关闭或用
QPainter::Antialiasing配合脏矩形优化; - 文字另有
QPainter::TextAntialiasing。
#画笔、画刷与渐变
QPen 管线条,QBrush 管填充。渐变是让界面"有质感"的性价比最高的手段。
#include <QPainter>
#include <QLinearGradient>
#include <QRadialGradient>
#include <QConicalGradient>
void drawGradients(QPainter &p, const QRect &rect)
{
// 线性渐变:沿对角线从蓝到紫
QLinearGradient lg(rect.topLeft(), rect.bottomRight());
lg.setColorAt(0.0, QColor("#4facfe"));
lg.setColorAt(1.0, QColor("#7c3aed"));
p.setPen(Qt::NoPen);
p.setBrush(lg);
p.drawRoundedRect(rect.adjusted(10, 10, -10, -10), 12, 12);
// 径向渐变:模拟高光球体
QRadialGradient rg(rect.center(), rect.width() / 4.0);
rg.setColorAt(0.0, QColor(255, 255, 255, 200));
rg.setColorAt(1.0, QColor(255, 255, 255, 0));
p.setBrush(rg);
p.drawEllipse(rect.center(), rect.width() / 4, rect.height() / 4);
// 锥形渐变:适合做色环、仪表盘
QConicalGradient cg(rect.center(), 90);
cg.setColorAt(0.0, QColor("#ff6b6b"));
cg.setColorAt(0.5, QColor("#feca57"));
cg.setColorAt(1.0, QColor("#ff6b6b"));
p.setBrush(cg);
p.drawEllipse(rect.center(), 60, 60);
// 画笔:虚线、端点、连接样式
p.setBrush(Qt::NoBrush);
p.setPen(QPen(QColor("#2d7ff9"), 2, Qt::DashLine, Qt::RoundCap, Qt::RoundJoin));
p.drawRect(rect.adjusted(4, 4, -4, -4));
}三种渐变各有主场:QLinearGradient 用于按钮、面板背景;QRadialGradient 用于高光、聚光效果;QConicalGradient 用于色环、旋钮。渐变坐标默认使用逻辑坐标,会跟随 QPainter 的变换,这点与 CSS 渐变(相对元素盒子)不同,要留意。
#绘制文本与图片
#include <QPainter>
#include <QFontMetrics>
#include <QPixmap>
void drawTextAndImage(QPainter &p, const QRect &rect, const QPixmap &logo)
{
QFont f = p.font();
f.setPixelSize(16);
f.setBold(true);
p.setFont(f);
p.setPen(QColor("#1a1a1a"));
// 单行文本:指定对齐与区域
p.drawText(rect, Qt::AlignLeft | Qt::AlignVCenter, "Qt 绘图系统");
// 文本省略:用 QFontMetrics 手动裁剪
QFontMetrics fm(f);
QString elided = fm.elidedText("这是一段很长的标题文字需要省略",
Qt::ElideRight, 200);
p.drawText(rect.adjusted(0, 24, 0, 0), Qt::AlignLeft, elided);
// 图片:保持宽高比缩放绘制
QPixmap scaled = logo.scaled(64, 64, Qt::KeepAspectRatio,
Qt::SmoothTransformation);
p.drawPixmap(rect.topRight() - QPoint(scaled.width() + 8, -8), scaled);
}Qt::SmoothTransformation 会做双线性插值,缩略图质量明显好于默认的 FastTransformation,代价是慢;只在最终显示时用,拖动过程中可用快速模式。
#QPixmap / QImage / QPicture 怎么选
这三个类都能"装图",但定位完全不同,选错会严重影响性能:
| 类 | 存储位置 | 优化方向 | 用途 |
|---|---|---|---|
QPixmap | 显存(平台相关) | 绘制快 | 界面上显示的一切:图标、背景、截图 |
QImage | 内存(与平台无关) | 像素访问快 | 读写像素、图像处理、算法、跨平台 IO |
QPicture | 指令序列 | 回放绘制 | 记录 QPainter 指令并重复播放 |
QSvgRenderer | 矢量指令 | 无损缩放 | 图标、可缩放图形 |
判断口诀:要"画"用 QPixmap,要"算"用 QImage。一个典型错误是在循环里对 QPixmap 逐个像素操作——每次 toImage() 和 fromImage() 都是一次昂贵的格式转换。
#双缓冲:为什么 Qt 里很少手动写
双缓冲的思路是"先在离屏画布上画完,再一次性贴到屏幕",目的是消除闪烁。在 Qt 中:
- Qt 4 之后,QWidget 默认就是双缓冲的(
Qt::WA_PaintOnScreen关闭时),你直接在paintEvent里画,Qt 自动缓冲。 - 需要手动双缓冲的场景是:绘制极耗时且频繁刷新(如示波器)。做法是维护一个
QPixmap m_buffer,在paintEvent中只drawPixmap(),真正的绘制在别处更新 buffer。
#include <QWidget>
#include <QPixmap>
#include <QPainter>
class WaveWidget : public QWidget
{
Q_OBJECT
public:
explicit WaveWidget(QWidget *parent = nullptr) : QWidget(parent) {}
void appendSample(double v)
{
m_samples.append(v);
if (m_samples.size() > width()) {
m_samples.removeFirst();
}
renderBuffer(); // 只在数据变化时重绘缓冲区
update(); // 然后请求一次轻量贴图
}
protected:
void paintEvent(QPaintEvent *) override
{
QPainter p(this);
p.drawPixmap(0, 0, m_buffer); // 极快:一次位块传输
}
void resizeEvent(QResizeEvent *e) override
{
QWidget::resizeEvent(e);
m_buffer = QPixmap(size());
m_buffer.fill(Qt::black);
renderBuffer();
}
private:
void renderBuffer()
{
if (m_buffer.isNull()) {
return;
}
m_buffer.fill(Qt::black);
QPainter bp(&m_buffer);
bp.setPen(QPen(QColor("#3ecf8e"), 1.5));
for (int i = 1; i < m_samples.size(); ++i) {
const double y1 = height() / 2.0 - m_samples.at(i - 1) * height() / 2.0;
const double y2 = height() / 2.0 - m_samples.at(i) * height() / 2.0;
bp.drawLine(QPointF(i - 1, y1), QPointF(i, y2));
}
}
QList<double> m_samples;
QPixmap m_buffer;
};这个模式把"昂贵绘制"和"廉价刷新"解耦:数据每秒来 60 次就画 60 次 buffer,但界面重绘(比如被其他窗口遮挡后恢复)只是贴图,几乎零成本。
#Graphics View 框架入门
QPainter 直接绘制有个致命问题:没有对象概念。你画了 100 个圆,想让用户拖动第 37 个,就得自己写命中检测、自己管 Z 序、自己处理局部刷新。Graphics View 就是为解决这个而生的,它采用 Scene-View-Item 三层:
| 层 | 类 | 职责 |
|---|---|---|
| 场景 | QGraphicsScene | 容纳图元的容器,管理 Z 序、碰撞、选中、索引 |
| 视图 | QGraphicsView | 显示窗口,负责滚动、缩放、坐标变换、事件分发 |
| 图元 | QGraphicsItem | 场景中的一个对象,自己知道怎么画、怎么碰撞 |
坐标系统也分三层:图元坐标 → 场景坐标 → 视图坐标,各有 mapToScene() / mapFromScene() 等转换函数。
#include <QApplication>
#include <QGraphicsScene>
#include <QGraphicsView>
#include <QGraphicsItem>
#include <QGraphicsSceneMouseEvent>
#include <QPainter>
#include <QRandomGenerator>
#include <QDebug>
class NodeItem : public QGraphicsItem
{
public:
explicit NodeItem(const QString &label) : m_label(label)
{
setFlag(ItemIsMovable, true); // 允许拖动
setFlag(ItemIsSelectable, true); // 允许选中
setFlag(ItemSendsGeometryChanges, true); // 位置变化时通知
setZValue(1);
}
QRectF boundingRect() const override
{
return {-40, -20, 80, 40}; // 必须覆盖所有绘制内容
}
void paint(QPainter *p, const QStyleOptionGraphicsItem *, QWidget *) override
{
p->setRenderHint(QPainter::Antialiasing);
p->setPen(QPen(isSelected() ? QColor("#2d7ff9") : QColor("#8892a0"), 2));
p->setBrush(QColor("#ffffff"));
p->drawRoundedRect(boundingRect(), 6, 6);
p->setPen(QColor("#1a1a1a"));
p->drawText(boundingRect(), Qt::AlignCenter, m_label);
}
protected:
// 碰撞:用椭圆区域而非矩形,更贴合视觉
QPainterPath shape() const override
{
QPainterPath path;
path.addRoundedRect(boundingRect(), 6, 6);
return path;
}
QVariant itemChange(GraphicsItemChange change, const QVariant &value) override
{
if (change == ItemPositionChange && scene()) {
qDebug() << "移动到" << value.toPointF(); // 可在此做吸附/边界限制
}
return QGraphicsItem::itemChange(change, value);
}
private:
QString m_label;
};
int main(int argc, char *argv[])
{
QApplication app(argc, argv);
auto *scene = new QGraphicsScene(-200, -150, 400, 300);
for (int i = 0; i < 6; ++i) {
auto *node = new NodeItem(QString("节点 %1").arg(i + 1));
node->setPos(QRandomGenerator::global()->bounded(-150, 150),
QRandomGenerator::global()->bounded(-100, 100));
scene->addItem(node);
}
auto *view = new QGraphicsView(scene);
view->setRenderHint(QPainter::Antialiasing);
view->setDragMode(QGraphicsView::RubberBandDrag); // 框选
view->setViewportUpdateMode(QGraphicsView::SmartViewportUpdate);
view->resize(640, 480);
view->show();
// 碰撞检测示例:找出与第一个图元相交的所有图元
auto *first = scene->items().constFirst();
const QList<QGraphicsItem *> hits = scene->collidingItems(first);
qDebug() << "与首个节点碰撞的图元数:" << hits.size();
return app.exec();
}几个关键点:
boundingRect()必须完整包含所有绘制内容,返回小了会导致残影(重绘区域不够);返回过大会降低性能。shape()可选,不实现就用boundingRect()。实现它可以让碰撞和点击更精确。setFlag(ItemIsMovable)一行就让图元可拖动,这是 Graphics View 相对裸QPainter最大的价值。- 图元的
paint()使用图元局部坐标,原点通常设为图元中心,这样旋转时自然绕中心转。
#该用 QPainter 还是 Graphics View
| 需求 | 选择 |
|---|---|
| 固定图表、仪表盘、自定义控件外观 | QPainter + paintEvent |
| 大量可交互、可移动、可缩放的图元 | Graphics View |
| 需要打印/导出同样内容 | 两者都行,Graphics View 有 scene->render(&painter) |
| 对性能要求极端(百万点) | 手写 QPainter + 脏矩形 |
Qt 5 提示:Qt 6 中
QGraphicsView的绘制后端改为默认使用 OpenGL/软件光栅的自适应选择,API 基本不变。差异点:Qt 6 移除了QPainter::HighQualityAntialiasing(已废弃),统一使用QPainter::Antialiasing;boundingRect()的返回类型在两代中均为QRectF。
#小结
- 绘图三层架构是
QPaintDevice(设备)/QPainter(API)/QPaintEngine(翻译),带来"一次编写、到处绘制"的能力。 - 坐标变换是累积的,
translate+ 逻辑坐标 +scale是自绘控件适配尺寸与 DPI 的标准范式;save()/restore()必须成对。 QPixmap为显示优化(显存),QImage为像素访问优化(内存)——要"画"用 QPixmap,要"算"用 QImage。- QWidget 默认已双缓冲,仅在高频重绘时才需要手动维护
QPixmap缓冲区。 - Graphics View 用 Scene/View/Item 三层提供对象化图元、自动命中检测、Z 序与缩放,适合交互式图形编辑器。
#练习
- 完善
ClockWidget:让秒针每秒走动(QTimer1000ms),并添加刻度数字 1~12。 - 用
QImage实现一个简单的灰度化函数,比较在QImage和QPixmap上逐像素操作的性能差异(QElapsedTimer)。 - 用
QGraphicsView实现一个可拖拽连线的简易流程图:继承QGraphicsItem画节点,用QGraphicsLineItem连接两个节点,拖动节点时更新连线端点。 - 给第 3 题的图元实现
mousePressEvent选中、hoverEnterEvent高亮,并用QGraphicsScene::collidingItems()检测节点重叠并标红。