CDC::DrawText

[アーティクル]
09/17/2008

更新 : 2007 年 11 月

指定した四角形内に、書式設定されたテキストを描画します。追加の書式指定オプションを指定するには、CDC::DrawTextEx を使います。

virtual int DrawText(
   LPCTSTR lpszString,
   int nCount,
   LPRECT lpRect,
   UINT nFormat 
);
int DrawText(
   const CString& str,
   LPRECT lpRect,
   UINT nFormat 
);

パラメータ

lpszString
描画する文字列へのポインタ。パラメータ nCount が -1 のときは、文字列は NULL 文字で終わらせてください。
nCount
文字列のバイト数。パラメータ nCount が -1 のときは、パラメータ lpszString が NULL で終わる文字列への long のポインタと解釈して、DrawText 関数が自動的に文字数を計算します。
lpRect
テキストがフォーマットされる四角形 (論理座標) を表す RECT 構造体または CRect オブジェクトへのポインタ。
str
指定する描画文字列を保持する CString オブジェクト。

nFormat
テキストのフォーマット方法。Windows SDK の「DrawText」にある uFormat パラメータの値を任意に組み合わせることができます。組み合わせにはビットごとの OR 演算子を使います。

メモ :
uFormat フラグの組み合わせ方によっては、渡した文字列が変更されます。DT_MODIFYSTRING と DT_END_ELLIPSIS または DT_PATH_ELLIPSIS を組み合わせると、文字列が変更され、CString のオーバーライドでアサートされることがあります。DT_CALCRECT、DT_EXTERNALLEADING、DT_INTERNAL、DT_NOCLIP、および DT_NOPREFIX は、DT_TABSTOP と同時には指定できません。

uFormat フラグの組み合わせ方によっては、渡した文字列が変更されます。DT_MODIFYSTRING と DT_END_ELLIPSIS または DT_PATH_ELLIPSIS を組み合わせると、文字列が変更され、CString のオーバーライドでアサートされることがあります。DT_CALCRECT、DT_EXTERNALLEADING、DT_INTERNAL、DT_NOCLIP、および DT_NOPREFIX は、DT_TABSTOP と同時には指定できません。

戻り値

関数が正常終了した場合は、テキストの高さを返します。

解説

フォーマットとは、タブを適切なスペースに展開したり、指定された四角形の左、右、中央にテキストを揃えたり、指定された四角形内にテキストが収まるように行を分けたりすることです。フォーマットのタイプはパラメータ nFormat で指定します。

このメンバ関数は、テキストを描画するために、デバイスコンテキストに現在選択されているフォント、テキストの色、背景色を使います。DT_NOCLIP フォーマットを使わない限り、DrawText 関数はテキストをクリップするので、指定された四角形の外にテキストが表示されることはありません。すべてのフォーマットでは、DT_SINGLELINE フォーマットが指定されない限り、複数の行にテキストが表示されます。

選択されたフォントが指定された四角形よりも大きすぎるときでも、DrawText メンバ関数はより小さいフォントに置き換えることはしません。

DT_CALCRECT フラグが指定されているときは、パラメータ lpRect で指定された四角形はテキストを描画するのに必要な幅と高さに更新されます。

TA_UPDATECP テキスト配置フラグが設定されている場合 (CDC::SetTextAlign を参照)、DrawText は指定された四角形の左端ではなく現在の位置を開始位置としてテキストを表示します。TA_UPDATECP フラグが設定されている場合、DrawText はテキストを折り返しません。つまり、DT_WORDBREAK フラグの効果はありません。

テキストの色は CDC::SetTextColor 関数で設定します。