CPen::CreatePen

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

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

Return Value

Nonzero, or the handle of a logical pen, if successful; otherwise 0.

Parameters

nPenStyle

Specifies the style for the pen. For a list of possible values, see the nPenStyle parameter in the CPen constructor.

nWidth

Specifies the width of the pen.

For the first version of CreatePen, if this value is 0, the width in device units is always 1 pixel, regardless of the mapping mode.
For the second version of CreatePen, if nPenStyle is PS_GEOMETRIC, the width is given in logical units. If nPenStyle is PS_COSMETIC, the width must be set to 1.

crColor

Contains an RGB color for the pen.

pLogBrush

Points to a LOGBRUSH structure. If nPenStyle is PS_COSMETIC, the lbColor member of the LOGBRUSH structure specifies the color of the pen and the lbStyle member of the LOGBRUSH structure must be set to BS_SOLID. If nPenStyle is PS_GEOMETRIC, all members must be used to specify the brush attributes of the pen.

nStyleCount

Specifies the length, in doubleword units, of the lpStyle array. This value must be zero if nPenStyle is not PS_USERSTYLE.

lpStyle

Points to an array of doubleword values. The first value specifies the length of the first dash in a user-defined style, the second value specifies the length of the first space, and so on. This pointer must be NULL if nPenStyle is not PS_USERSTYLE.

Remarks

The first version of CreatePen initializes a pen with the specified style, width, and color. The pen can be subsequently selected as the current pen for any device context.

Pens that have a width greater than 1 pixel should always have either the PS_NULL, PS_SOLID, or PS_INSIDEFRAME style.

If a pen has the PS_INSIDEFRAME style and a color that does not match a color in the logical color table, the pen is drawn with a dithered color. The PS_SOLID pen style cannot be used to create a pen with a dithered color. The style PS_INSIDEFRAME is identical to PS_SOLID if the pen width is less than or equal to 1.

The second version of CreatePen initializes a logical cosmetic or geometric pen that has the specified style, width, and brush attributes. The width of a cosmetic pen is always 1; the width of a geometric pen is always specified in world units. After an application creates a logical pen, it can select that pen into a device context by calling the CDC::SelectObject function. After a pen is selected into a device context, it can be used to draw lines and curves.

If nPenStyle is PS_COSMETIC and PS_USERSTYLE, the entries in the lpStyle array specify lengths of dashes and spaces in style units. A style unit is defined by the device in which the pen is used to draw a line.
If nPenStyle is PS_GEOMETRIC and PS_USERSTYLE, the entries in the lpStyle array specify lengths of dashes and spaces in logical units.
If nPenStyle is PS_ALTERNATE, the style unit is ignored and every other pixel is set.

When an application no longer requires a given pen, it should call the CGdiObject::DeleteObject member function or destroy the CPen object so the resource is no longer in use. An application should not delete a pen when the pen is selected in a device context.

CPen Overview | Class Members | Hierarchy Chart