CPen::CreatePen

Article
06/30/2006

This method initializes a pen with the specified style, width, and color. The pen can be subsequently selected as the current pen for any device context.

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

Parameters

nPenStyle
Specifies the style for the pen. For a list of possible values, see the nPenStyle parameter in the CPen::CPen constructor.
nWidth
Specifies the width of the pen.
- For the first version of CreatePen, if this value is zero, 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.

Return Value

Nonzero, or the handle of a logical pen, if successful; otherwise, it is zero.

Remarks

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 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 method 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.

Windows CE does not support the following overloaded implementation of the CPen::CreatePen method:

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

In Windows CE version 1.0, only solid pens can draw wide lines.

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

**  Windows CE versions:** 1.0 and later
  Header file: Declared in Afxwin.h
  Platform: H/PC Pro, Palm-size PC, Pocket PC

Share via