CPen::CreatePen

[アーティクル]
08/09/2011

指定したスタイル、幅、ブラシ属性で論理コスメティックペンまたはジオメトリックペンを作成し、CPen オブジェクトに結び付けます。

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

パラメーター

nPenStyle
ペンのスタイルを指定します。指定できる値は、CPen::CPen コンストラクターのパラメーター nPenStyle を参照してください。
nWidth
ペンの幅を指定します。
- CreatePen の最初の構文では、この値が 0 のときは、マップモードとは無関係に常にデバイス単位で 1 ピクセルの幅になります。
- CreatePen の 2 番目の構文では、nPenStyle が PS_GEOMETRIC のときは、幅を論理単位で指定します。 nPenStyle が PS_COSMETIC の場合、幅を 1 に設定します。
crColor
ペンの色を RGB カラー値で指定します。
pLogBrush
LOGBRUSH 構造体へのポインター。 nPenStyle が PS_COSMETIC の場合、LOGBRUSH 構造体の lbColor メンバーはペンの色を指定します。また、LOGBRUSH 構造体の lbStyle メンバーを BS_SOLID に設定する必要があります。 nPenStyle が PS_GEOMETRIC のときは、ペンのブラシ属性を指定するためにすべてのメンバーを使います。
nStyleCount
lpStyle 配列の長さをダブルワード単位で指定します。 nPenStyle が PS_USERSTYLE ではないときは、この値には 0 を指定します。
lpStyle
ダブルワード値の配列へのポインター。最初の値は、ユーザー定義スタイルの点線の点の部分の長さを指定し、2 番目の値はスペースの部分の長さを指定します。以下同じように続けます。 nPenStyle が PS_USERSTYLE でないときは、このポインターには NULL を指定します。

戻り値

正常終了した場合は 0 以外、または論理ペンのハンドルを返します。それ以外の場合は 0 を返します。

解説

CreatePen の最初の構文では、指定されたスタイル、幅、色でペンを初期化します。初期化後、このペンはすべてのデバイスコンテキストの現在のペンとして選択できます。

ペンの幅が 1 ピクセルよりも大きいとき、このペンは必ず PS_NULL、PS_SOLID、PS_INSIDEFRAME スタイルのいずれかになります。

ペンのスタイルが PS_INSIDEFRAME で、色が論理カラーテーブルの色に一致しない場合、ペンでは描画にディザーカラーが使用されます。 PS_SOLID のペンスタイルを使用して、ディザーカラーのペンを作成することはできません。ペンの幅が 1 以下のときは、PS_INSIDEFRAME スタイルと PS_SOLID スタイルは等しくなります。

CreatePen の 2 番目の構文では、指定したスタイル、幅、ブラシ属性を持つ論理コスメティックペンまたは論理ジオメトリックペンを初期化します。コスメティックペンの幅は常に 1 です。ジオメトリックペンの幅は、常にワールド単位で指定されます。アプリケーションが論理ペンを作成後、CDC::SelectObject 関数を呼び出して、デバイスコンテキストのペンとして選択できます。デバイスコンテキストでペンを選択した後は、そのペンを使用して直線や曲線を描画できます。

nPenStyle が PS_COSMETIC であり PS_USERSTYLE のときは、lpStyle 配列の各エントリはスタイル単位での点線の点の部分とスペースの部分の長さ指定になります。スタイル単位は、線の描画に使うペンのデバイスで定義されます。
nPenStyle が PS_GEOMETRIC であり PS_USERSTYLE のときは、lpStyle 配列のエントリは論理単位での点線の点の部分とスペースの部分の長さを指定します。
nPenStyle が PS_ALTERNATE のときは、スタイル単位を無視し、ピクセルごとに設定します。

アプリケーションで指定したペンが不要になったときは、メンバー関数 CGdiObject::DeleteObject を呼び出すか、または CPen オブジェクトを破棄して、リソースを解放してください。デバイスコンテキストに取り込まれているペンは、アプリケーションで削除できません。

使用例

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