`CPen` 类

项目
10/16/2023

封装一个 Windows 图形设备接口 (GDI) 笔。

语法

class CPen : public CGdiObject

成员

公共构造函数

名称	描述
`CPen::CPen`	构造 `CPen` 对象。

公共方法

名称	描述
`CPen::CreatePen`	创建具有指定样式、宽度和画笔特性的逻辑整容笔或几何笔，并将其附加到 `CPen` 对象。
`CPen::CreatePenIndirect`	使用 `LOGPEN` 结构中给定的样式、宽度和颜色创建笔，并将其附加到 `CPen` 对象。
`CPen::FromHandle`	在给定 Windows HPEN 时返回指向 `CPen` 对象的指针。
`CPen::GetExtLogPen`	获取 `EXTLOGPEN` 基础结构。
`CPen::GetLogPen`	获取 `LOGPEN` 基础结构。

公共运算符

“属性”	描述
`CPen::operator HPEN`	返回附加到 `CPen` 对象的 Windows 句柄。

备注

有关使用 CPen 的详细信息，请参阅图形对象。

继承层次结构

CObject

CGdiObject

CPen

要求

标头：afxwin.h

`CPen::CPen`

构造 CPen 对象。

CPen();

CPen(
    int nPenStyle,
    int nWidth,
    COLORREF crColor);

CPen(
    int nPenStyle,
    int nWidth,
    const LOGBRUSH* pLogBrush,
    int nStyleCount = 0,
    const DWORD* lpStyle = NULL);

参数

nPenStyle
指定笔样式。此参数在构造函数的第一个版本中可以是以下值之一：

PS_SOLID 创建实心笔。
PS_DASH 创建短划线式虚线笔。仅当笔宽为 1 或更小（以设备单位为单位）时有效。
PS_DOT 创建点式虚线笔。仅当笔宽为 1 或更小（以设备单位为单位）时有效。
PS_DASHDOT 创建短划线和点交替的笔。仅当笔宽为 1 或更小（以设备单位为单位）时有效。
PS_DASHDOTDOT 创建短划线和双点交替的笔。仅当笔宽为 1 或更小（以设备单位为单位）时有效。
PS_NULL 创建 null 笔。
PS_INSIDEFRAME 创建可在指定边界矩形的 Windows GDI 输出函数（例如 Ellipse、Rectangle、RoundRect、Pie 和 Chord 成员函数）生成的封闭形状框架内绘制线条的笔。如果此样式与不指定边界矩形的 Windows GDI 输出函数（例如 LineTo 成员函数）一起使用，则笔的绘图区域不受框架限制。

CPen 构造函数的第二个版本指定类型、样式、末端和联接特性的组合。应使用按位“或”(|) 运算符组合每个类别中的值。笔类型可以是下列值之一：

PS_GEOMETRIC 创建几何笔。
PS_COSMETIC 创建整容笔。

CPen 构造函数的第二个版本为 nPenStyle 添加了以下笔样式：
PS_ALTERNATE 创建设置所有其他像素的笔。（此样式仅适用于整容笔。）
PS_USERSTYLE 创建使用用户提供的样式数组的笔。

末端可以是以下值之一：
PS_ENDCAP_ROUND 末端是圆的。
PS_ENDCAP_SQUARE 末端是正的。
PS_ENDCAP_FLAT 末端是平的。

联接可以是以下值之一：
PS_JOIN_BEVEL 联接是斜切的。
PS_JOIN_MITER 当联接位于 SetMiterLimit 函数设置的当前限制内时，联接是斜接的。如果联接超出此限制，则是斜切的。
PS_JOIN_ROUND 联接是圆的。

nWidth
指定笔的宽度。

对于构造函数的第一个版本，值 0 的处理方式与值 1 类似，但宽度不会受到对笔用于图形对象的缩放转换操作的影响：宽度始终为 1 像素。
对于构造函数的第二个版本，如果 nPenStyle 是 PS_GEOMETRIC，则宽度以逻辑单位提供。如果 nPenStyle 是 PS_COSMETIC，则宽度必须设置为 1。

crColor
包含笔的 RGB 颜色。

pLogBrush
指向 LOGBRUSH 结构。如果 nPenStyle 是 PS_COSMETIC，则 LOGBRUSH 结构的 lbColor 成员指定笔的颜色，并且 LOGBRUSH 的 lbStyle 成员必须设置为 BS_SOLID。如果 nPenStyle 是 PS_GEOMETRIC，则必须使用所有成员来指定笔的画笔特性。

nStyleCount
指定 lpStyle 数组的长度（以双字单位为单位）。如果 nPenStyle 不是 PS_USERSTYLE，则此值必须为零。

lpStyle
指向双字值的数组。第一个值指定用户定义的样式中第一条短划线的长度，第二个值指定第一个空格的长度，依此类推。如果 nPenStyle 不是 PS_USERSTYLE，则此指针必须为 NULL。

备注

如果使用没有自变量的构造函数，则必须使用 CPen、CreatePen 或 CreatePenIndirect 成员函数初始化生成的 CreateStockObject 对象。

如果使用采用自变量的构造函数，则无需进一步初始化。如果遇到错误，具有自变量的构造函数可能会引发异常，而没有自变量的构造函数将始终成功。

示例

// Create a solid red pen of width 2.
CPen myPen1(PS_SOLID, 2, RGB(255, 0, 0));

// Create a geometric pen.
LOGBRUSH logBrush;
logBrush.lbStyle = BS_SOLID;
logBrush.lbColor = RGB(0, 255, 0);
CPen myPen2(PS_DOT | PS_GEOMETRIC | PS_ENDCAP_ROUND, 2, &logBrush);

`CPen::CreatePen`

创建具有指定样式、宽度和画笔特性的逻辑整容笔或几何笔，并将其附加到 CPen 对象。

BOOL CreatePen(
    int nPenStyle,
    int nWidth,
    COLORREF crColor);

BOOL CreatePen(
    int nPenStyle,
    int nWidth,
    const LOGBRUSH* pLogBrush,
    int nStyleCount = 0,
    const DWORD* lpStyle = NULL);

参数

nPenStyle
指定笔的样式。有关可能值的列表，请参阅 CPen 构造函数中的 nPenStyle 参数。

nWidth
指定笔的宽度。

对于 CreatePen 的第一个版本，值 0 的处理方式与值 1 类似，但宽度不会受到对笔用于图形对象的缩放转换操作的影响：宽度始终为 1 像素。
对于 CreatePen 的第二个版本，如果 nPenStyle 是 PS_GEOMETRIC，则宽度以逻辑单位提供。如果 nPenStyle 是 PS_COSMETIC，则宽度必须设置为 1。

crColor
包含笔的 RGB 颜色。

pLogBrush
指向 LOGBRUSH 结构。如果 nPenStyle 是 PS_COSMETIC，则 LOGBRUSH 结构的 lbColor 成员指定笔的颜色，并且 LOGBRUSH 的 lbStyle 成员必须设置为 BS_SOLID。如果 nPenStyle 是 PS_GEOMETRIC，则必须使用所有成员来指定笔的画笔特性。

nStyleCount
指定 lpStyle 数组的长度（以双字单位为单位）。如果 nPenStyle 不是 PS_USERSTYLE，则此值必须为零。

返回值

如果成功，则为非零；如果方法失败，则为零。

备注

CreatePen 的第一个版本使用指定的样式、宽度和颜色初始化笔。随后可以选择该笔作为任何设备上下文的当前笔。

宽度大于 1 像素的笔应始终具有 PS_NULL、PS_SOLID 或 PS_INSIDEFRAME 样式。

如果笔的 PS_INSIDEFRAME 样式和颜色与逻辑颜色表中的颜色不匹配，则笔将以抖色进行绘制。 PS_SOLID 笔样式不能用于以抖色创建笔。如果笔宽小于或等于 1，则样式 PS_INSIDEFRAME 与 PS_SOLID 相同。

CreatePen 的第二个版本初始化具有指定样式、宽度和画笔特性的逻辑整容笔或几何笔。整容笔的宽度始终为 1；几何笔的宽度始终以世界单位指定。应用程序在创建逻辑笔后，可以通过调用 CDC::SelectObject 函数将该笔选入设备上下文。将笔选入设备上下文后，可用于绘制线条和曲线。

如果 nPenStyle 是 PS_COSMETIC 和 PS_USERSTYLE，则 lpStyle 数组中的条目以样式单位指定短划线和空格的长度。样式单位由用于绘制线条的设备定义。
如果 nPenStyle 是 PS_GEOMETRIC 和 PS_USERSTYLE，则 lpStyle 数组中的条目以逻辑单位指定短划线和空格的长度。
如果 nPenStyle 是 PS_ALTERNATE，则忽略样式单位，并设置所有其他像素。

当应用程序不再需要给定笔时，它应调用 CGdiObject::DeleteObject 成员函数或销毁 CPen 对象，以便不再使用资源。如果设备上下文中选择了某个笔，则应用程序不应删除笔。

示例

CPen myPen1, myPen2;

// Create a solid red pen of width 2.
myPen1.CreatePen(PS_SOLID, 2, RGB(255, 0, 0));

// Create a geometric pen.
LOGBRUSH logBrush;
logBrush.lbStyle = BS_SOLID;
logBrush.lbColor = RGB(0, 255, 0);
myPen2.CreatePen(PS_DOT | PS_GEOMETRIC | PS_ENDCAP_ROUND, 2, &logBrush);

`CPen::CreatePenIndirect`

初始化一个笔，该笔的样式、宽度和颜色在 lpLogPen 所指向的结构中给出。

BOOL CreatePenIndirect(LPLOGPEN lpLogPen);

参数

lpLogPen
指向包含有关笔的信息的 Windows LOGPEN 结构。

返回值

如果该函数成功，则为非 0；否则为 0。

备注

宽度大于 1 像素的笔应始终具有 PS_NULL、PS_SOLID 或 PS_INSIDEFRAME 样式。

如果笔的 PS_INSIDEFRAME 样式和颜色与逻辑颜色表中的颜色不匹配，则笔将以抖色进行绘制。如果笔宽小于或等于 1，则 PS_INSIDEFRAME 样式与 PS_SOLID 相同。

示例

LOGPEN logpen;
CPen   cMyPen;

// Get the LOGPEN of an existing pen.
penExisting.GetLogPen(&logpen);

// Change the color to red and the width to 2.
logpen.lopnWidth.x = 2;
logpen.lopnColor = RGB(255, 0, 0);

// Create my pen using the new settings.
cMyPen.CreatePenIndirect(&logpen);

`CPen::FromHandle`

在提供了 Windows GDI 笔对象句柄的情况下，返回指向 CPen 对象的指针。

static CPen* PASCAL FromHandle(HPEN hPen);

参数

hPen
Windows GDI 笔的 HPEN 句柄。

返回值

如果成功，则为指向 CPen 对象的指针；否则为 NULL。

备注

如果 CPen 对象未附加到该句柄，则会创建并附加一个临时 CPen 对象。此临时 CPen 对象仅在应用程序下次在其事件循环中有空闲时间之前有效，届时将删除所有临时图形对象。换句话说，该临时对象仅在处理一条 Windows 消息期间有效。

示例

// Convert an HPEN to a CPen*.
// NOTE: hPen is a valid pen handle.
CPen* pPen = CPen::FromHandle(hPen);

`CPen::GetExtLogPen`

获取 EXTLOGPEN 基础结构。

int GetExtLogPen(EXTLOGPEN* pLogPen);

参数

pLogPen
指向包含有关笔的信息的 EXTLOGPEN 结构。

返回值

如果成功，则不为 0；否则为 0。

备注

EXTLOGPEN 结构定义笔的样式、宽度和画笔特性。例如，调用 GetExtLogPen 以匹配笔的特定样式。

有关笔特性的信息，请参阅 Windows SDK 中的以下主题：

示例

下面的代码示例演示了如何调用 GetExtLogPen 以检索笔的特性，然后创建一个具有相同颜色的新整容笔。

EXTLOGPEN extlogpen;
penExisting.GetExtLogPen(&extlogpen);
CPen penOther;
LOGBRUSH LogBrush = { extlogpen.elpBrushStyle, extlogpen.elpColor,
   extlogpen.elpHatch };
penOther.CreatePen(PS_COSMETIC, 1, &LogBrush);

`CPen::GetLogPen`

获取 LOGPEN 基础结构。

int GetLogPen(LOGPEN* pLogPen);

参数

pLogPen
指向包含有关笔的信息的 LOGPEN 结构。

返回值

如果成功，则不为 0；否则为 0。

备注

LOGPEN 结构定义笔的样式、颜色和图案。

例如，调用 GetLogPen 以匹配笔的特定样式。

有关笔特性的信息，请参阅 Windows SDK 中的以下主题：

示例

下面的代码示例演示了如何调用 GetLogPen 以检索一个笔字符，然后创建一个具有相同颜色的新整容笔。

LOGPEN logpen;
penExisting.GetLogPen(&logpen);
CPen penOther(PS_SOLID, 0, logpen.lopnColor);

`CPen::operator HPEN`

获取 CPen 对象的附加 Windows GDI 句柄。

operator HPEN() const;

返回值

如果成功，则由 CPen 对象表示的 Windows GDI 对象的句柄；否则 NULL。

备注

此运算符是强制转换运算符，它支持直接使用 HPEN 对象。

有关使用图形对象的详细信息，请参阅 Windows SDK 中的图形对象一文。

示例

// Create a solid red pen of width 2.
CPen myPen(PS_SOLID, 2, RGB(255, 0, 0));

// Get the handle of the pen object.
HPEN hPen = (HPEN)myPen;

另请参阅

CGdiObject 类
 层次结构图
 CBrush 类

通过

CPen 类

语法

成员

公共构造函数

公共方法

公共运算符

备注

继承层次结构

要求

CPen::CPen

参数

备注

示例

CPen::CreatePen

参数

返回值

备注

示例

CPen::CreatePenIndirect

参数

返回值

备注

示例

CPen::FromHandle

参数

返回值

备注

示例

CPen::GetExtLogPen

参数

返回值

备注

示例

CPen::GetLogPen

参数

返回值

备注

示例

CPen::operator HPEN

返回值

备注

示例