extCreatePen 函数 (wingdi.h)

项目
08/27/2023

ExtCreatePen 函数创建具有指定样式、宽度和画笔属性的逻辑修饰笔或几何笔。

语法

HPEN ExtCreatePen(
  [in] DWORD          iPenStyle,
  [in] DWORD          cWidth,
  [in] const LOGBRUSH *plbrush,
  [in] DWORD          cStyle,
  [in] const DWORD    *pstyle
);

参数

[in] iPenStyle

类型、样式、结束帽和联接属性的组合。使用按位 OR 运算符组合每个类别的值 ( |) 。

笔类型可以是以下值之一。

值	含义
PS_GEOMETRIC	笔是几何的。
PS_COSMETIC	笔是整容的。

笔样式可以是以下值之一。

值	含义
PS_ALTERNATE	笔设置其他像素。（此样式仅适用于整容笔。）
PS_SOLID	触控笔是实心的。
PS_DASH	触控笔虚线。
PS_DOT	笔被点点。
PS_DASHDOT	笔具有交替的短划线和点。
PS_DASHDOTDOT	笔具有交替的短划线和双点。
PS_NULL	笔不可见。
PS_USERSTYLE	笔使用用户提供的样式数组。
PS_INSIDEFRAME	触控笔是实心的。在采用边框的任何 GDI 绘图函数中使用此笔时，图形的尺寸会缩小，使其完全适合边界矩形，同时考虑笔的宽度。这仅适用于几何笔。

仅为几何笔指定端盖。结束上限可以是以下值之一。

值	含义
PS_ENDCAP_ROUND	末端是圆的。
PS_ENDCAP_SQUARE	末端是正的。
PS_ENDCAP_FLAT	末端是平的。

联接仅为几何笔指定。联接可以是以下值之一。

值	含义
PS_JOIN_BEVEL	联接是斜切的。
PS_JOIN_MITER	当联接在 SetMiterLimit 函数设置的当前限制内时，将进行斜接。如果超出此限制，则联接将进行斜角。
PS_JOIN_ROUND	联接是圆的。

[in] cWidth

笔的宽度。如果 dwPenStyle 参数PS_GEOMETRIC，则宽度以逻辑单位提供。如果 dwPenStyle 为PS_COSMETIC，则宽度必须设置为 1。

[in] plbrush

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

[in] cStyle

lpStyle 数组的长度（以 DWORD 为单位）。如果未PS_USERSTYLE dwPenStyle ，则此值必须为零。

样式计数限制为 16。

[in] pstyle

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

如果在线条绘制期间超出 lpStyle 数组，指针将重置为数组的开头。发生这种情况并且 dwStyleCount 为偶数时，短划线和空格的模式将重复。但是，如果 dwStyleCount 为奇数，则指针重置时模式会反转 -- lpStyle 的第一个元素现在引用空格，第二个元素引用短划线，依此类推。

返回值

如果函数成功，则返回值是标识逻辑笔的句柄。

如果函数失败，则返回值为零。

注解

几何笔可以具有任意宽度，并且可以具有画笔的任何属性，例如抖变和图案。整容笔只能是单个像素宽，并且必须是纯色，但整容笔通常比几何笔快。

几何笔的宽度始终以世界单位指定。整容笔的宽度始终为 1。

仅为几何笔指定端帽和联接。

应用程序创建逻辑笔后，可以通过调用 SelectObject 函数将该笔选择到设备上下文中。将笔选入设备上下文后，可用于绘制线条和曲线。

如果 dwPenStyle 是PS_COSMETIC且PS_USERSTYLE， 则 lpStyle 数组中的条目以样式单位指定短划线和空格的长度。样式单位由使用笔绘制线条的设备定义。

如果 dwPenStyle PS_GEOMETRIC且PS_USERSTYLE， 则 lpStyle 数组中的条目以逻辑单元指定短划线和空格的长度。

如果 dwPenStyle 为PS_ALTERNATE，则忽略样式单位并设置其他每个像素。

如果 lplb 指向的 LOGBRUSH 结构的 lbStyle 成员BS_PATTERN，则该结构的 lbHatch 成员指向的位图不能是 DIB 部分。 DIB 节是由 CreateDIBSection 创建的位图。如果该位图是 DIB 部分， 则 ExtCreatePen 函数将失败。

当应用程序不再需要指定的笔时，它应调用 DeleteObject 函数来删除该笔。

Icm： 在创建笔时不执行颜色管理。但是，当将笔选入启用了 ICM 的设备上下文时，将执行颜色管理。

示例

有关示例，请参阅使用笔。

要求


最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	wingdi.h (包括 Windows.h)
Library	Gdi32.lib
DLL	Gdi32.dll