| HPEN ExtCreatePen(dwPenStyle, dwWidth, lplb, dwStyleCount, lpStyle) | |||
| DWORD dwPenStyle; | |||
| DWORD dwWidth; | |||
| LPLOGBRUSH lplb; | |||
| DWORD dwStyleCount; | |||
| LPDWORD lpStyle; |
The ExtCreatePen function creates a logical cosmetic- or geometric-pen having the specified style, width, and brush attributes. The pen may subsequently be selected into a device context and used to draw lines and curves.
dwPenStyle
Specifies a combination of type, style, end-cap, and line-join attributes. The values from each category should be OR'd together.
The pen type can be one of the following values:
| Value | Meaning |
| PS_GEOMETRIC | Creates a geometric pen. |
| PS_COSMETIC | Creates a cosmetic pen. |
The pen style can be any one of the following values:
| Value | Meaning |
| PS_ALTERNATE | The pen sets every other pixel. (This style is only applicable for cosmetic pens.) |
| PS_SOLID | The pen is solid. |
| PS_DASH | The pen is dashed. |
| PS_DOT | The pen is dotted. |
| PS_DASHDOT | The pen has alternating dashes and dots. |
| PS_DASHDOTDOT | The pen has alternating dashes and double dots. |
| PS_NULL | The pen is invisible. |
| PS_USERSTYLE | Specifies that a styling array supplied by the user is to be used. |
| PS_INSIDEFRAME | Creates a solid pen. When this pen is used in any GDI drawing function that takes a bounding rectangle, the dimensions of the figure will be shrunk so that it fits entirely in the bounding rectangle, taking into account the width of the pen. This applies only to PS_GEOMETRIC pens. |
The end cap can be any one of the following values:
| Value | Meaning |
| PS_ENDCAP_ROUND | Line end caps are round. |
| PS_ENDCAP_SQUARE | Line end caps are square. |
| PS_ENDCAP_FLAT | Line end caps are flat. |
The line join can be any one of the following values:
| Value | Meaning |
| PS_JOIN_BEVEL | Line joins are beveled. |
| PS_JOIN_MITER | Line joins are mitered when they are within the current SetMiterLimit limit. A join is beveled when it would exceed the limit. |
| PS_JOIN_ROUND | Line joins are round. |
dwWidth
Specifies the width of the pen. If dwPenStyle is PS_GEOMETRIC_SOLID or PS_GEOMETRIC_USER, the width is specified in logical (world) units. If dwPenStyle is PS_COSMETIC_SOLID or PS_COSMETIC_USER, the width is specified in device units.
lplb
Points to a LOGBRUSH data structure that specifies style, color, and optional pattern attributes required by a geometric pen. If dwPenStyle is PS_COSMETIC_SOLID or PS_COSMETIC_USER, the brush attributes are ignored.
dwStyleCount
Specifies the length of the lpStyle array in DWORD units.
This value must be 0 if dwPenStyle is not PS_COSMETIC_USER or PS_GEOMETRIC_USER.
lpStyle
Points to an array of DWORD values. The first value specifies the length of the first dash in a user-defined linestyle, the second value specifies the length of the first space, and so on.
This pointer must be NULL if dwPenStyle is not PS_COSMETIC_USER or PS_GEOMETRIC_USER.
The return value is a handle that identifies a logical pen if the function is successful. Otherwise, it is 0.
The width of cosmetic pens is always specified in device units; the width of geometric pens is always specified in world units.
Once an application creates a logical pen, it can select that pen into a device context by calling the SelectObject function. After a pen is selected into a device context, it can be used to draw lines and curves.
If dwPenStyle is PS_COSMETIC_USER, the entries in the array at which lpStyle points specify lengths of dashes and spaces in style units. A style unit is defined by the device upon which the pen is used to draw a line.
If dwPenStyle is PS_ALTERNATE, the style unit is ignored and every other pixel is set.
If dwPenStyle is PS_GEOMETRIC_USER, the entries in the array at which lpStyle points specify lengths of dashes and spaces in world units.
When an application no longer requires the pen, it should call the DeleteObject function and delete the pen from the device context.
CreatePen CreatePenIndirect DeleteObject GetObject SelectObject