CPen::CreatePen

Creates a logical cosmetic or geometric pen with the specified style, width, and brush attributes, and attaches it to the CPen object.

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

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.

Return Value

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

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.

Example

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);   

Requirements

Header: afxwin.h

See Also

Reference

CPen Class

Hierarchy Chart

CPen::CreatePenIndirect

CPen::CPen

CGdiObject::DeleteObject

LOGBRUSH

Other Resources

CPen Members