CDC::GrayString

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

指定された位置に淡色表示 (灰色) のテキストを描画します。淡色表示のテキストは、メモリビットマップにテキストを書き込み、そのビットマップを淡色表示にしてからディスプレイにコピーして表示します。

virtual BOOL GrayString(
   CBrush* pBrush,
   BOOL ( CALLBACK* lpfnOutput )( HDC, LPARAM, int ),
   LPARAM lpData,
   int nCount,
   int x,
   int y,
   int nWidth,
   int nHeight
);

パラメーター

pBrush
淡色表示 (灰色表示) に使うブラシを識別します。
lpfnOutput
アプリケーションが提供する文字列を描画するためのコールバック関数のプロシージャインスタンスアドレスを指定します。詳細については、Windows から OutputFunc への「CDC::GrayString 用コールバック関数」の説明を参照してください。このパラメーターが NULL のときは、システムは文字列を描画するために Windows の TextOut 関数を使います。このとき、lpData は出力される文字列への long のポインターと仮定します。
lpData
出力関数に渡されるデータへの far ポインターを指定します。 lpfnOutput が NULL のときは、lpData は出力される文字列への long のポインターにする必要があります。
nCount
出力される文字数を指定します。このパラメーターが 0 のときは、GrayString は文字列の長さを計算します。lpData は文字列へのポインターと仮定します。 nCount が -1 で、lpfnOutput で指定される関数が 0 を返すときは、イメージは表示されますが淡色表示はされません。
x
文字列を囲む四角形の始点の論理 x 座標を指定します。
y
文字列を囲む四角形の始点の論理 y 座標を指定します。
nWidth
文字列を囲む四角形の幅を (論理単位で) 指定します。 nWidth が 0 のときは、GrayString は lpData が文字列へのポインターと仮定して領域の幅を計算します。
nHeight
文字列を囲む四角形の高さを (論理単位で) 指定します。 nHeight が 0 のときは、GrayString は lpData が文字列へのポインターと仮定して領域の高さを計算します。

戻り値

文字列が描画できた場合は 0 以外の値を返します。TextOut 関数またはアプリケーション提供の出力関数が 0 を返した場合、または淡色表示のためのメモリビットマップを作成するのに十分なメモリがなかった場合は 0 を返します。

解説

このとき、テキストは選択されたブラシとバックグラウンドに関係なく淡色表示されます。 GrayString メンバー関数は現在選択されているフォントを使って表示します。この関数を使う前に、MM_TEXT マップモードが選択されている必要があります。

純色の灰色をサポートしているデバイスに淡色 (灰色) 表示の文字列を描画するときは、GrayString メンバー関数を呼び出す必要はありません。システムカラーの COLOR_GRAYTEXT は、選択不可能なテキストを描画するときに使う純色の灰色のシステムカラーです。アプリケーションでは、COLOR_GRAYTEXT のカラー値を取得するのに GetSysColor Windows 関数を使用できます。カラー値が 0 (黒) 以外の場合は、テキストの色をそのカラー値にするために SetTextColor メンバー関数を使うことができ、設定後直接文字列を描画できます。取得したカラー値が黒のときは、淡色 (灰色) 表示のテキストを描画するために GrayString メンバー関数を呼び出す必要があります。

lpfnOutput が NULL のときは、GDI は Windows の TextOut 関数を使用します。このとき、lpData には出力される文字への far ポインターを指定する必要があります。出力する文字列が TextOut メンバー関数で扱えないとき (文字列がビットマップとして保存されているときなど)、アプリケーションは固有の出力関数を用意する必要があります。

また、コールバック関数の外側で例外をスローすることができないので、Windows に戻る前にすべてのコールバック関数は MFC の例外を残らずキャッチする必要があることに注意してください。例外の詳細については、「例外処理 (MFC)」を参照してください。

GrayString に渡されるコールバック関数は __stdcall 呼び出し規約を使い、__declspec でエクスポートする必要があります。

フレームワークがプレビューモードのとき、GrayString メンバー関数の呼び出しは TextOut メンバー関数の呼び出しに変換され、コールバック関数は呼び出しません。