QT6 源，十章绘图（1）画笔 QPen：画笔也有自己的画刷来描述自身的填充属性 void Qpen::setBrush(QBrush & brush)；以及本类的成员函数与源代码带注释

原创已于 2025-08-01 15:27:10 修改 · 236 阅读

0 ·

CC 4.0 BY-SA版权

文章标签：

#qt

于 2025-07-31 00:23:40 首次发布

QT6.2.4源码阅读(十章绘图) 专栏收录该内容

20 篇文章

订阅专栏

（1）在绘图的时候，画家 QPainter 要设置自己的画笔 QPen 与填充画刷 QBrush 的样式。相关类的继承关系如下：

在这里插入图片描述

++本篇先学习画笔方面的知识。本画笔 QPen 的代码量不大。

（2）本类只有全局成员函数，没有属性，信号与槽函数 ：

在这里插入图片描述

（3）

在这里插入图片描述

++举例：

在这里插入图片描述

++代码显示，对于粗线条，也是可以设置其线条内部的填充样式的，测试一下 ：

在这里插入图片描述

++再举例 ：

在这里插入图片描述

（4）

在这里插入图片描述

（5）

在这里插入图片描述

（6）

在这里插入图片描述
++

在这里插入图片描述

（7）端点样式 ：

在这里插入图片描述

（8）连接样式 ：

在这里插入图片描述

（9）本源代码定义于头文件 qpen . h ：

#ifndef QPEN_H
#define QPEN_H

#include <QtGui/qtguiglobal.h>
#include <QtGui/qcolor.h>
#include <QtGui/qbrush.h>

QT_BEGIN_NAMESPACE


class QVariant;
class QPenPrivate;
class QBrush;
class QPen;


Q_GUI_EXPORT QDataStream & operator<<(QDataStream &, const QPen &);
Q_GUI_EXPORT QDataStream & operator>>(QDataStream &,       QPen &);
Q_GUI_EXPORT QDebug        operator<<(QDebug       , const QPen &);

/*
The QPen class defines how a QPainter should draw lines and outlines of shapes.

Detailed Description ：
A pen has a style(), width(), brush(), capStyle() and joinStyle().
笔型定义了线条类型。画刷用来填充用钢笔产生的笔画。使用QBrush类来指定填充样式。
盖子样式确定了可以使用QPainter绘制的线端盖子，而连接样式描述了如何绘制两条线之间的连接。
笔宽可以用整数(width())和浮点(widthF())两种精度来指定。
行宽为0表示化妆笔。这意味着笔的宽度总是画一个像素宽，与画家设定的变换无关。

这些不同的设置可以通过相应的setStyle()、setWidth()、
setBrush()、setCapStyle()和setJoinStyle()函数轻松地进行修改
(请注意，在更改笔的属性时必须重置绘图者的笔)。

For example:
    QPainter painter(this);
    QPen     pen(Qt::green, 3, Qt::DashDotLine, Qt::RoundCap, Qt::RoundJoin);
    painter.setPen(pen);

这相当于 ：
    QPainter painter(this);
    QPen pen;  // creates a default pen

    pen.setStyle(Qt::DashDotLine);
    pen.setWidth(3);
    pen.setBrush(Qt::green);
    pen.setCapStyle(Qt::RoundCap);
    pen.setJoinStyle(Qt::RoundJoin);

    painter.setPen(pen);

默认的笔是一个宽度为1、方形帽样式(Qt::SquareCap)和斜角连接样式(Qt::BevelJoin)的实心黑色画笔。
此外，QPen提供了color()和setColor()便捷函数，分别用于提取和设置笔刷的颜色。
笔还可以进行对比和流式传输。
有关绘画的一般信息，请参阅Paint系统文档。

Pen Style :
Qt提供了多种内置样式，这些样式由Qt::PenStyle枚举表示.

函数将笔样式转换为内置样式之一，但不包括我们稍后将讨论的Qt::CustomDashLine .
只需使用`setStyle()将样式设置为Qt::NoPen指示绘图器不绘制线条或轮。
默认笔样式是Qt::SolidLine样式。

自Qt4.1以来，还可以使用setDashPattern()函数指定自定义的条纹图案，
该函数隐式地将笔的样式转换为Qt::.CustomDashLine。
模式参数QList必须指定为偶数个qreal条目，其中条目1、3、5是破折号，2、4、6是空格。
例如，上面显示的自定义模式是使用以下代码创建的:
    QPen pen;   QList<qreal> dashes;   qreal space = 4;

    dashes << 1 << space << 3 << space << 9 << space << 27 << space << 9 << space;

    pen.setDashPattern(dashes);

请注意，虚线模式以笔的宽度为单位进行指定，例如，长度为5、宽度为10个像素的虚线是50个像素长。
当前设置的划线样式可以通过`dashPattern()、函数来获取。
使用`isSolid()、函数可以判断笔划是否带有实心填充。

Cap Style 端点样式:
顶角样式定义了使用QPainter绘制线条端点的方式。
顶角样式仅适用于宽线条即宽度为1或更大的线条。Qt::PenCapstyle枚举提供了以下样式:
  SquareCap样式是一个正方形的行结束符，它覆盖了端点，并且超出端点的一半行宽。
Qt::FlatCap样式是一个不覆盖线端点的方线末端。Qt::RoundCap样式是覆盖终点的圆线末端。
默认值是Qt::SquareCap。

当笔宽为0或1时是否绘制端点取决于帽形样式。
使用Qt::SquareCap或Qt::Roundcap时会绘制，使用Qt::Flatcap则不会绘制。

Join Style :
连接样式定义了如何在 QPainter 中绘制两条相连线条之间的连接。
连接样式仅适用于宽线条，即宽度为1或更大的线条。Qt::PenJoinStyle枚举提供了以下样式:

Qt::BevelJoin样式会填充两条线之间的三角形凹槽。
Qt::MiterJoin样式会将两条线延伸使其以特定角度相交。
而Qt::RoundJoin样式会在两条线之间填充一个圆弧。  The default is Qt::BevelJoin.

当应用 Qt::MiterJoin 样式时，可以使用setMiterLimit()函数来指定斜切接合可以从接合点延伸多远。
miterLimit()用于减少当两条线近乎平行时的线接合处的瑕疵。
斜切限制值必须以笔宽为单位指定，例如，宽度为10的斜切限制为5，长度为50像素。
默认的斜切限制为2，即像素中笔宽的两倍。


*/


class Q_GUI_EXPORT QPen
{
private:
    friend Q_GUI_EXPORT QDataStream & operator>>(QDataStream &,       QPen &);
    friend Q_GUI_EXPORT QDataStream & operator<<(QDataStream &, const QPen &);

    void  detach();
    class QPenPrivate * d; //本类的数据成员

public:
    typedef QPenPrivate * DataPtr;

    inline DataPtr & data_ptr() { return d; }

public:

    QPen();                     //构建一个默认的黑色实线笔，宽度为1。

    QPen(Qt::PenStyle style);   //构建一个宽度为1且具有给定样式 style 的黑色笔。

    QPen(const QColor & color); //构造一个宽度为1旦颜色为给定颜色 color 的实线笔。

    //Constructs a pen with the specified brush, width, pen style, cap style and join style.
    QPen(const  QBrush & brush, qreal width, Qt::PenStyle s = Qt::SolidLine,
                Qt::PenCapStyle  c = Qt::SquareCap,
                Qt::PenJoinStyle j = Qt::BevelJoin   );

    QPen(const QPen & pen) noexcept;

    QPen & operator=(const QPen & pen) noexcept;

    QPen(QPen && other) noexcept : d(qExchange(other.d, nullptr)) {}
    QT_MOVE_ASSIGNMENT_OPERATOR_IMPL_VIA_PURE_SWAP(QPen)

    ~QPen();  //以上是本类的构造与析构函数

    void swap(QPen & other) noexcept { qSwap(d, other.d); }

    bool operator==(const QPen & p) const; //比较运算符函数
    inline
    bool operator!=(const QPen & p) const { return !(operator==(p)); }

    operator QVariant() const; //类型转换运算符函数，本类可以自动转换为 QVariant数据格式

    bool                      isDetached();

    //如果笔具有实心填充 enum Qt::BrushStyle::SolidPattern ，则返回true，否则返回false。
    bool                      isSolid() const; //关于笔自身的填充画刷

    QBrush                      brush() const; //返回用于填充此笔生成的描边的画笔。
    void                     setBrush(const QBrush & brush);
    //将用于填充此笔生成的描边的画刷设置为给定的画刷 brush。

    //QBrush::QBrush(QColor & color, Qt::BrushStyle bs = Qt::SolidPattern);
    QColor                      color() const; //返回这支笔的填充刷子的颜色。
    void                     setColor(const QColor & color);
    //将此笔刷的颜色设置为给定的颜色 color。

    //如果笔是装饰性的，则返回true;否则返回false。 默认情况下，宽度为零的笔是装饰性的。
    //化妆笔被用于绘制宽度恒定的线条，无论与之配合的QPainter应用了何种变换，都不会改变线条的宽度。
    //使用化妆笔绘制形状可以确保其轮廓在不同比例系数下保持相同的厚度。
    bool                      isCosmetic() const;  //Cosmetic化妆品
    void                     setCosmetic(bool cosmetic);
    //将此笔设置为化妆品或非化妆品，具体取决于cosmetic的值。

    //返回笔宽，具有整数精度。
    int                         width() const;
    void                     setWidth(int width);
    //将笔宽设置为给定的像素宽度，精度为整数。 设置负值的笔宽是不支持的。
    //行宽为0表示化妆笔。这意味着笔的宽度总是画一个像素宽，与画家设定的变换无关。

    qreal                       widthF() const; //返回带有浮点精度的笔宽。
    void                     setWidthF(qreal width);
    //将笔宽设置为给定的像素宽度 width，使用浮点精度。

    Qt::PenStyle                style() const; //Returns the pen style.
    void                     setStyle(Qt::PenStyle); //设置线型号
    //Sets the pen style to the given style.
    //请参阅 Qt::PenStyle 文档，以获取可用风格的列表。
    //自 Qt4.1起，还可以通过 setDashPattern()函数指定自定义虚线图案，
    //该函数会隐式地将笔的样式转换为 Qt::CustomDashLine。注意:此函数将虚线偏移重置为零。
    /*
    //This enum type defines the pen styles that can be drawn using QPainter.
    enum Qt::PenStyle { // pen style.画笔的属性。用于绘制模型视图里的表格。
                 NoPen, //no line at all.
            //For example, QPainter::drawRect() fills but does not draw any boundary line.
             SolidLine, //A plain line. 实线
              DashLine, //Dashes separated by a few pixels.虚线
               DotLine, //Dots   separated by a few pixels.点线
           DashDotLine, //Alternate dots and dashes.       点虚线
        DashDotDotLine, //One dash, two dots, one dash, two dots.两点虚线
        CustomDashLine, //A custom pattern defined using
                        //  QPainterPathStroker::setDashPattern().
        MPenStyle = 0x0f
    };
    */

    QList<qreal>                 dashPattern() const; //返回此笔的虚线模式。
    void                      setDashPattern(const QList<qreal> & pattern);
    //将此笔的虚线模式设置为给定的模式 pattern。这隐式地将笔的样式转换为Qt::CustomDashLine。
    //模式必须指定为偶数个正项，其中第1、3、5项是破折号，第2、4、6项是空格。例如:
    //划线图案以笔宽为单位进行指定，例如，长度为5、宽度为10的划线长度为50像素。
    //请注意，宽度为0的笔等价于宽度为1的装饰性笔。
    //每个破折号也受截断样式影响，
    //  因此带有方形截断设置的破折号“1”将在每个方向上延伸0.5像素，从而总宽度达到2。
    //请注意，默认的笔画样式是Qt::SquareCap，这意味着一个方形线端覆盖终点并延伸到超过它一半的线条宽度。

    //Returns the dash offset for the pen.
    qreal                        dashOffset() const;
    void                      setDashOffset(qreal   doffset);
    //将本笔的划线偏移量(划线图案上的起点)设置为所指定的偏移量 doffset。
    //偏移量是以指定划线图案时所用的单位来测量的。
    //例如，一个模式中每个笔画长度为四个单位，之后有一个两个单位的间隙，在作为线条绘制时将从笔画开始。
    //然而，如果将 dash offset 设置为 4.0，那么任何绘制的线条都将从间隙处开始。
    //offset的值在 4.0 以下时，会导致部分笔触先被绘制;
    //而当 offset 的值在 4.0 到 6.0 之间时，线条将从间隙的一部分处开始。
    //注:这隐式地将笔的样式转换为Qt::CustomDashLine。

    /*
    //这个枚举类型定义了Qt支持的笔帽样式，即可以使用Painter绘制的线端部。
    enum Qt::PenCapStyle { // line endcap style
          FlatCap      = 0x00, //-个不覆盖线端点的方形线尾。
        SquareCap      = 0x10, //一个方形线端，覆盖终点并延伸到超过终点一半的线宽。
         RoundCap      = 0x20, //a rounded line end.
          MPenCapStyle = 0x30
    };
    */
    Qt::PenCapStyle              capStyle () const; //默认是 Qt::SquareCap.
    void                      setCapStyle (Qt::PenCapStyle   pcs);

    Qt::PenJoinStyle             joinStyle() const; //默认是  Qt::BevelJoin
    void                      setJoinStyle(Qt::PenJoinStyle  pcs);
    /*
    //这个枚举类型定义了Qt支持的笔连接样式，即可以使用Painter绘制两个连接线之间的连接
    enum Qt::PenJoinStyle { // line join style
           MiterJoin      = 0x000, //线条的外边缘被延长以在一定角度相交，并且该区域被填充。
           BevelJoin      = 0x040, //两条线之间的三角形缺口已填充。
           RoundJoin      = 0x080, //两条线之间的圆弧被填充。
        SvgMiterJoin      = 0x100, //-个与SVG 1.2 Tiny规范中对斜接的定义相对应的斜接。
            MPenJoinStyle = 0x1c0
    };
    */
    //返回笔的斜接线限制。当连接样式设置为Qt::MiterJoin时，斜接线限制才相关联。
    qreal                       miterLimit() const;
    void                     setMiterLimit(qreal limit); //默认为 2
    //Sets the miter limit of this pen to the given limit.
    //斜切限制描述了斜切连接可以从连接点延伸多远。这被用于减少当两条线近乎平行时的线连接之间的瑕疵。
    //这个值仅在笔样式设置为Qt::MiterJoin时才有作用。该值以笔的宽度为单位指定，
    //例如，宽度为10的米特尔极限为5，即长度为50像素。默认的米特尔极限为2，即笔宽度的两倍像素。


}; //完结 class QPen

Q_DECLARE_SHARED(QPen)


QT_END_NAMESPACE

#endif // QPEN_H