QPen 类

QPen 类定义如何以 QPainter 绘制线条和形状的轮廓。更多...

头：	#include <QPen>
CMake:	find_package(Qt6 REQUIRED COMPONENTS Gui) target_link_libraries(mytarget PRIVATE Qt6::Gui)
qmake:	QT += gui

所有成员列表，包括继承成员
QPen 属于描绘类 and 隐式共享类 .

公共函数

	QPen ()
	QPen (Qt::PenStyle style )
	QPen (const QColor & color )
	QPen (const QBrush & brush , qreal width , Qt::PenStyle style = Qt::SolidLine, Qt::PenCapStyle cap = Qt::SquareCap, Qt::PenJoinStyle join = Qt::BevelJoin)
	QPen (const QPen & pen )
	QPen (QPen && pen )
	~QPen ()
QBrush	brush () const
Qt::PenCapStyle	capStyle () const
QColor	color () const
qreal	dashOffset () const
QList<qreal>	dashPattern () const
bool	isCosmetic () const
bool	isSolid () const
Qt::PenJoinStyle	joinStyle () const
qreal	miterLimit () const
void	setBrush (const QBrush & brush )
void	setCapStyle (Qt::PenCapStyle style )
void	setColor (const QColor & color )
void	setCosmetic (bool cosmetic )
void	setDashOffset (qreal offset )
void	setDashPattern (const QList<qreal> & pattern )
void	setJoinStyle (Qt::PenJoinStyle style )
void	setMiterLimit (qreal limit )
void	setStyle (Qt::PenStyle style )
void	setWidth (int width )
void	setWidthF (qreal width )
Qt::PenStyle	style () const
void	swap (QPen & other )
int	width () const
qreal	widthF () const
QVariant	operator QVariant () const
bool	operator!= (const QPen & pen ) const
QPen &	operator= (const QPen & pen )
QPen &	operator= (QPen && other )
bool	operator== (const QPen & pen ) const

QDataStream &	operator<< (QDataStream & stream , const QPen & pen )
QDataStream &	operator>> (QDataStream & stream , QPen & pen )

详细描述

钢笔拥有 style (), width (), brush (), capStyle () 和 joinStyle ().

钢笔样式定义线条类型。笔刷用于填充采用钢笔生成的笔画。使用 QBrush 类来指定填充样式。帽样式确定可以绘制的线端帽使用 QPainter ，而联接样式描述如何绘制 2 条线之间的联接。可以指定钢笔宽度以整数 ( width ()) 和浮点 ( widthF ()) 精度。线宽 0 指示装饰性钢笔。这意味着钢笔宽度始终绘制一像素宽，独立于 transformation 设置在描绘器。

可以轻松修改各种设置使用相应 setStyle (), setWidth (), setBrush (), setCapStyle () 和 setJoinStyle () 函数 (注意：必须重置描绘器钢笔，当更改钢笔特性时)。

例如：

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 ()方便函数以分别提取和设置钢笔的笔刷颜色。钢笔还可以比较和被流化。

一般而言，有关描绘的更多信息，见描绘系统文档编制。

钢笔样式

Qt 提供了几种内置样式表示通过 Qt::PenStyle 枚举：


Qt::SolidLine	Qt::DashLine	Qt::DotLine

Qt::DashDotLine	Qt::DashDotDotLine	Qt::CustomDashLine

只需使用 setStyle () 函数将钢笔样式转换成内置样式之一，除了 Qt::CustomDashLine 样式将快速回退。将样式设为 Qt::NoPen 告诉描绘器不要绘制线条 (或轮廓)。钢笔样式默认为 Qt::SolidLine .

从 Qt 4.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);

注意，虚线图案是以钢笔宽度为单位指定的 (如：宽度 10 长度 5 的虚线为 50 像素长)。

检索目前设置的虚线图案, 可以使用 dashPattern () 函数。使用 isSolid () 函数能确定钢笔是否拥有实心填充。

帽样式

帽样式定义线条端点是如何绘制的使用 QPainter 。帽样式仅适用于宽线条 (即：当宽度为 1 或更大时)。 Qt::PenCapStyle 枚举提供下列样式：


Qt::SquareCap	Qt::FlatCap	Qt::RoundCap

The Qt::SquareCap 样式是覆盖端点且延伸超出其一半线宽的正方形线端。 Qt::FlatCap 样式是不覆盖线端点的正方形直线端。而 Qt::RoundCap 样式是覆盖端点的圆形线端。

默认为 Qt::SquareCap .

是否绘制端点从属帽样式，当钢笔宽度为 0 (或 1) 时。使用 Qt::SquareCap or Qt::RoundCap 绘制它们，使用 Qt::FlatCap 不绘制它们。

联接样式

联接样式定义如何绘制 2 连接线之间的联接使用 QPainter 。联接样式仅适用于宽线条 (即：当宽度为 1 或更大时)。 Qt::PenJoinStyle 枚举提供下列样式：


Qt::BevelJoin	Qt::MiterJoin	Qt::RoundJoin

The Qt::BevelJoin 样式填充 2 线条之间的三角形凹槽。 Qt::MiterJoin 样式延伸线条以按角度相交。而 Qt::RoundJoin 样式填充 2 线条之间的圆弧。

默认为 Qt::BevelJoin .

当 Qt::MiterJoin 样式被应用，是可能的使用 setMiterLimit () 函数指定斜接联接可以从联接点延伸多远。 miterLimit () 用于缩减线条联接之间的伪影，在哪里线条接近平行。

The miterLimit () 必须以钢笔宽度为单位指定 (如：以宽度 10 为单位的 5 斜接限制是 50 像素长)。默认斜接限制为 2 (即：以像素为单位的 2 倍钢笔宽度)。

路径笔画范例

路径笔画范例展示 Qt 的内置虚线图案和展示如何使用自定义图案以延伸可用图案的范围。

另请参阅 QPainter , QBrush , 路径笔画范例，和涂鸦范例 .

成员函数文档编制

QPen:: QPen ()

构造默认黑色实线钢笔采用 1 宽度。

QPen:: QPen ( Qt::PenStyle style )

构造黑色钢笔采用 1 宽度和给定 style .

另请参阅 setStyle ().

QPen:: QPen (const QColor & color )

构造实线钢笔采用 1 宽度和给定 color .

另请参阅 setBrush () 和 setColor ().

QPen:: QPen (const QBrush & brush , qreal width , Qt::PenStyle style = Qt::SolidLine, Qt::PenCapStyle cap = Qt::SquareCap, Qt::PenJoinStyle join = Qt::BevelJoin)

构造钢笔采用指定 brush , width ，钢笔 style , cap 样式和 join 样式。

另请参阅 setBrush (), setWidth (), setStyle (), setCapStyle ()，和 setJoinStyle ().

`[noexcept]` QPen:: QPen (const QPen & pen )

构造钢笔是副本对于给定 pen .

`[noexcept]` QPen:: QPen ( QPen && pen )

构造钢笔移动自给定 pen .

移动自钢笔只可以赋值、拷贝 (或销毁)。任何其它操作 (先于赋值) 将导致未定义行为。

`[noexcept]` QPen:: ~QPen ()

销毁钢笔。

QBrush QPen:: brush () const

返回用于填充由此钢笔生成的笔画的笔刷。

另请参阅 setBrush ().

Qt::PenCapStyle QPen:: capStyle () const

返回钢笔帽样式。

另请参阅 setCapStyle () 和帽样式 .

QColor QPen:: color () const

返回此钢笔的笔刷颜色。

另请参阅 brush () 和 setColor ().

qreal QPen:: dashOffset () const

返回钢笔的虚线偏移。

另请参阅 setDashOffset ().

QList < qreal > QPen:: dashPattern () const

返回此钢笔的虚线模式。

另请参阅 setDashPattern (), style ()，和 isSolid ().

bool QPen:: isCosmetic () const

返回 true 若钢笔是装饰性的；否则返回 false .

装饰性钢笔用于绘制拥有常量宽度的笔画，不管将任何变换应用到 QPainter 要使用它们。采用装饰性钢笔绘制形状可确保其轮廓在不同比例缩放因子下，都拥有相同厚度。

0 宽钢笔是装饰性的，默认情况下。

另请参阅 setCosmetic () 和 widthF ().

bool QPen:: isSolid () const

返回 true 若钢笔拥有实心填充，否则 false。

另请参阅 style () 和 dashPattern ().

Qt::PenJoinStyle QPen:: joinStyle () const

返回钢笔的联接样式。

另请参阅 setJoinStyle () 和联接样式 .

qreal QPen:: miterLimit () const

返回钢笔的斜接限制。斜接限制才相关，当将联接样式设为 Qt::MiterJoin .

另请参阅 setMiterLimit () 和联接样式 .

void QPen:: setBrush (const QBrush & brush )

将用于填充由此钢笔生成描边的笔画，设为给定 brush .

另请参阅 brush () 和 setColor ().

void QPen:: setCapStyle ( Qt::PenCapStyle style )

将钢笔的帽样式设为给定 style 。默认值为 Qt::SquareCap .

另请参阅 capStyle () 和帽样式 .

void QPen:: setColor (const QColor & color )

将此钢笔的笔刷颜色设为给定 color .

另请参阅 setBrush () 和 color ().

void QPen:: setCosmetic ( bool cosmetic )

将此钢笔设为装饰性 (或非装饰性) 的，从属值 cosmetic .

另请参阅 isCosmetic ().

void QPen:: setDashOffset ( qreal offset )

将此钢笔的虚线偏移 (虚线图案的起点) 设为 offset 指定。根据用于指定虚线图案的单位，测量偏移。

For example, a pattern where each stroke is four units long, followed by a gap of two units, will begin with the stroke when drawn as a line.

However, if the dash offset is set to 4.0, any line drawn will begin with the gap. Values of the offset up to 4.0 will cause part of the stroke to be drawn first, and values of the offset between 4.0 and 6.0 will cause the line to begin with part of the gap.

注意： 这将钢笔样式隐式转换成 Qt::CustomDashLine .

另请参阅 dashOffset ().

void QPen:: setDashPattern (const QList < qreal > & pattern )

将此钢笔的虚线图案设为给定 pattern 。这将钢笔样式隐式转换成 Qt::CustomDashLine .

图案必须按正值条目偶数指定，其中条目 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);

The dash pattern is specified in units of the pens width; e.g. a dash of length 5 in width 10 is 50 pixels long. Note that a pen with zero width is equivalent to a cosmetic pen with a width of 1 pixel.

Each dash is also subject to cap styles so a dash of 1 with square cap set will extend 0.5 pixels out in each direction resulting in a total width of 2.

注意，默认帽样式为 Qt::SquareCap , meaning that a square line end covers the end point and extends beyond it by half the line width.

另请参阅 setStyle (), dashPattern (), setCapStyle ()，和 setCosmetic ().

void QPen:: setJoinStyle ( Qt::PenJoinStyle style )

将钢笔的联接样式设为给定 style 。默认值为 Qt::BevelJoin .

另请参阅 joinStyle () 和联接样式 .

void QPen:: setMiterLimit ( qreal limit )

将此钢笔的斜接限制设为给定 limit .

斜接限制描述斜接联接可以从联接点延伸多远。这用于缩减线条联接之间的伪影，在哪里线条接近平行。

此值才有效，当将钢笔样式设为 Qt::MiterJoin 。值以钢笔宽度为单位指定 (如：以宽度 10 为单位的 5 斜接限制是 50 像素长)。默认斜接限制为 2 (即：以像素为单位的 2 倍钢笔宽度)。

另请参阅 miterLimit (), setJoinStyle ()，和联接样式 .

void QPen:: setStyle ( Qt::PenStyle style )

将钢笔样式设为给定 style .

见 Qt::PenStyle 文档编制了解可用样式列表。从 Qt 4.1 起，指定自定义虚线图案也是可能的使用 setDashPattern () 函数将钢笔样式隐式转换成 Qt::CustomDashLine .

注意： 此函数将虚线偏移重置为 0。

另请参阅 style () 和钢笔样式 .

void QPen:: setWidth ( int width )

将钢笔宽度设为给定 width 以像素为单位按整数精度。

线宽 0 指示装饰性钢笔。这意味着钢笔宽度始终绘制一像素宽，独立于 transformation 设置在描绘器。

不支持采用负值设置钢笔宽度。

另请参阅 setWidthF () 和 width ().

void QPen:: setWidthF ( qreal width )

将钢笔宽度设为给定 width 以像素为单位按浮点精度。

线宽 0 指示装饰性钢笔。这意味着钢笔宽度始终绘制一像素宽，独立于 transformation 在描绘器。

不支持采用负值设置钢笔宽度。

另请参阅 setWidth () 和 widthF ().

Qt::PenStyle QPen:: style () const

返回钢笔样式。

另请参阅 setStyle () 和钢笔样式 .

`[noexcept]` void QPen:: swap ( QPen & other )

交换钢笔 other 与此钢笔。此操作非常快且从不失败。

int QPen:: width () const

按整数精度返回钢笔宽度。

另请参阅 setWidth () 和 widthF ().

qreal QPen:: widthF () const

按浮点精度返回钢笔宽度。

另请参阅 setWidthF () 和 width ().

QVariant QPen:: operator QVariant () const

返回钢笔作为 QVariant .

bool QPen:: operator!= (const QPen & pen ) const

返回 true 若钢笔不同于给定 pen ；否则 false。2 钢笔不同，若它们拥有不同样式、宽度或颜色。

另请参阅 operator== ().

`[noexcept]` QPen &QPen:: operator= (const QPen & pen )

赋值给定 pen 到此钢笔并返回此钢笔的引用。

`[noexcept]` QPen &QPen:: operator= ( QPen && other )

移动赋值 other 到此 QPen 实例。

bool QPen:: operator== (const QPen & pen ) const

返回 true 若钢笔等于给定 pen ；否则 false。2 钢笔相等，若它们拥有相等样式、宽度及颜色。

另请参阅 operator!= ().