CPen 类
封装一个 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 的详细信息，请参阅图形对象。
继承层次结构
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，则此值必须为零。
lpStyle
指向双字值的数组。 第一个值指定用户定义的样式中第一条短划线的长度，第二个值指定第一个空格的长度，依此类推。 如果 nPenStyle 不是 PS_USERSTYLE，则此指针必须为 NULL。
返回值
如果成功，则为非零；如果方法失败，则为零。
备注
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;
另请参阅
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈