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 的详细信息,请参阅 图形对象

继承层次结构

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 ,) 、 PieRectangleRoundRect 、、和 Chord 成员函数。 如果将此样式用于未指定边框的 Windows GDI 输出函数 (例如, LineTo 成员函数) ,则该笔的绘图区域不受帧的限制。

构造函数的第二个版本 CPen 指定类型、样式、结束端和联接属性的组合。 应使用按位 "or" (|) 运算符来合并每个类别的值。 钢笔类型可以是以下值之一:

  • PS_GEOMETRIC 创建几何笔。

  • PS_COSMETIC 创建修饰笔。

    构造函数的第二个版本 CPennPenStyle 添加了以下笔样式:

  • 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个像素。

  • 对于构造函数的第二个版本,如果 nPenStylePS_GEOMETRIC ,则在逻辑单元中给出宽度。 如果 nPenStylePS_COSMETIC ,则宽度必须设置为1。

crColor
包含用于笔的 RGB 颜色。

pLogBrush
LOGBRUSH指向结构。 如果 nPenStylePS_COSMETIClbColor 则结构的成员 LOGBRUSH 指定笔的颜色,并且 lbStyle 结构的成员 LOGBRUSH 必须设置为 BS_SOLID 。 如果 nPenStylePS_GEOMETRIC ,则必须将所有成员用于指定笔的画笔属性。

nStyleCount
指定数组的长度(以双字单位表示) lpStyle 。 如果 nPenStylePS_USERSTYLE 是,该值必须为零。

lpStyle
指向一组双字值。 第一个值指定用户定义样式中第一个短划线的长度,第二个值指定第一个空间的长度,依此类推。 如果 nPenStylePS_USERSTYLE 是,则该指针必须是 NULL

备注

如果使用不带参数的构造函数,则必须使用 CreatePenCreatePenIndirectCreateStockObject 成员函数初始化生成 CPen 的对象。

如果使用采用参数的构造函数,则不需要进行进一步的初始化。 如果遇到错误,带参数的构造函数可能会引发异常,而不带参数的构造函数将始终会成功。

示例

// 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
指定笔的样式。 有关可能值的列表,请参见构造函数中 CPennPenStyle 参数。

nWidth
指定笔的宽度。

  • 对于的第一个版本 CreatePen ,如果此值为0,则无论映射模式如何,设备单位中的宽度始终为1个像素。

  • 对于第二个版本的 CreatePen ,如果 nPenStylePS_GEOMETRIC ,则在逻辑单元中给出宽度。 如果 nPenStylePS_COSMETIC ,则宽度必须设置为1。

crColor
包含用于笔的 RGB 颜色。

pLogBrush
LOGBRUSH指向结构。 如果 nPenStylePS_COSMETIClbColor 则结构的成员 LOGBRUSH 指定笔的颜色,并且 lbStyle 结构的成员 LOGBRUSH 必须设置为 BS_SOLID 。 如果 nPenStylePS_GEOMETRIC ,则必须将所有成员用于指定笔的画笔属性。

nStyleCount
指定数组的长度(以双字单位表示) lpStyle 。 如果 nPenStylePS_USERSTYLE 是,该值必须为零。

lpStyle
指向一组双字值。 第一个值指定用户定义样式中第一个短划线的长度,第二个值指定第一个空间的长度,依此类推。 如果 nPenStylePS_USERSTYLE 是,则该指针必须是 NULL

返回值

如果成功,则为非零; 如果方法失败,则为零。

备注

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

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

如果笔的 PS_INSIDEFRAME 样式和颜色与逻辑颜色表中的颜色不匹配,则笔将绘制为色盲。 笔 PS_SOLID 样式不能用于创建具有热色的笔。 如果笔 PS_INSIDEFRAME 宽小于 PS_SOLID 或等于 1,则样式与 相同。

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

  • 如果 nPenStylePS_COSMETICPS_USERSTYLE,则数组中的 lpStyle 条目以样式单位指定短划线和空格的长度。 样式单位由使用笔绘制线条的设备定义。

  • 如果 nPenStylePS_GEOMETRICPS_USERSTYLE,则数组中的 lpStyle 条目以逻辑单位指定短划线和空格的长度。

  • 如果 nPenStylePS_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
指向WindowsLOGPEN有关笔的信息的表结构。

返回值

如果该函数成功,则为非 0;否则为 0。

备注

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

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

示例

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

返回一个指针,该CPen指针指向给定 GDI 笔Windows句柄的 对象。

static CPen* PASCAL FromHandle(HPEN hPen);

参数

hPen
HPEN用于Windows GDI 笔的句柄。

返回值

如果成功,则指向 CPen 对象的指针;否则为 NULL

备注

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

示例

// 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

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

operator HPEN() const;

返回值

如果成功,则对象Windows表示的 GDI 对象的CPen句柄;否则为 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