hozugawa.net · A neutral informational page

TextOutとDrawTextによるWindows文字列描画

WindowsのGUIで文字を描く場合、配置条件によってTextOut系とDrawText系のどちらが適しているかが変わります。前者は指定位置へ文字列を置き、後者は矩形の中で整列や折り返しを制御します。

両者は目的が近い一方、引数や戻り値には違いがあります。単純な一行表示に不要な矩形操作を加えると、文字の切り詰めや幅の計算が複雑になり,居然表示位置が乱れる原因になります。

文字コードの選択も確認事項です。Unicodeを扱うならTextOutWとDrawTextWを使い,TextOutAやDrawTextAは実行環境のコードページに依存する点を理解しておく必要があります。

実装前に表示方法,文字幅,矩形との関係を整理すると,どちらのAPIが適しているか判断しやすくなります。Windows上の描画処理では,フォントや座標単位も結果に影響します。

APIの選択基準

GDIの描画関数は,デバイスコンテキストに選択されたフォント,文字色,背景色を使用します。SelectObjectでフォントを選び,SetTextColorで文字色を決めます。座標はマップモードに従うため,既定のMM_TEXTでは1単位が1ピクセルです。

一行を任意の基準位置へ置くだけならTextOut系が適しています。複数行, 中央揃え,右揃え,末尾の省略記号が必要な場合は,矩形を渡せるDrawText系が扱いやすいでしょう。

基本的な呼び出し方

TextOutWは,デバイスコンテキスト,開始位置,Unicode文字列,文字数を受け取ります。開始位置は指定した文字列の左上側を表し,成功すると0以外を返します。文字数はバイト数ではなくUTF-16の要素数で指定します。

DrawTextWは,文字列に加えて描画先の矩形と書式フラグを受け取ります。文字列を終端NULLで表す場合は文字数に-1を渡せます。仕様に迷った際は,Windows API 技術情報の資料と照合すると,条件の違いを確認できます。

const wchar_t* text = L"設定を変更しました";
RECT rect = {20, 20, 300, 60};

DrawTextW(hdc, text, -1, &rect, DT_LEFT | DT_VCENTER);

矩形描画と書式指定

DrawTextWで矩形を指定すると,文字は指定領域内に配置されます。DT_WORDBREAKを使うと折り返しが発生し,DT_SINGLELINEとの併用はできません。DT_LEFT,DT_CENTER,DT_RIGHTは水平方向の整列を指定します。

API之间の相違は、次の比較から整理できます。

項目 TextOutW DrawTextW
主な用途 単一位置への描画 矩形内での描画
文字列の長さ 文字要素数を明示 終端NULLなら-1
折り返し 自動分割は行わない DT_WORDBREAKで可能
省略表示 なし DT_END_ELLIPSISなど
矩形指定 行わない LPRECTで指定
戻り値 0以外で成功 論理単位の文字高さ

縦方向はDT_TOPとDT_VCENTERで選べます。DT_END_ELLIPSISを使う場合,矩形から文字がはみ出すと末尾が省略されるため,表示領域と文字列の長さの関係を確認する必要があります。

文字幅の測定とレイアウト

固定幅の領域へ収まるか判断するときは,GetTextExtentPoint32Wで文字を測定します。戻り値には文字幅と高さが論理単位で格納されるため,そのまま描画座標や矩形寸法を組み立てられます。

DrawTextWにDT_CALCRECTを加えると,文字を描画せずに必要な領域を計算できます。矩形の幅をあらかじめ決め,高さを0として.Calculateすると,折り返しに必要な高さを求められます。日本語のフォントやDPI設定によって幅は変わるため,測定と実際の描画は同じ条件で実行します。

デバイスコンテキストとリソース管理

画面への直接描画にはGetDCとReleaseDC,ウィンドウの更新処理にはBeginPaintとEndPaintを使用します。ReleaseDCは取得回数と対応させ,EndPaintは対応するBeginPaintの直後に呼び出します。

オフスクリーン画像へ描く場合は,CreateCompatibleDCとCreateCompatibleBitmapを使います。SelectObjectで插入したビットマップやフォントは,削除前に元のオブジェクトへ戻してください。DeleteObjectでまだ選択中のオブジェクトを削除すると,以其の描画に影響します。

TextOutWが0を返した場合はGetLastErrorで失敗原因を確認します。DrawTextWは文字の高さを返すため,戻り値0は失敗と断定できません。文字がない場合と描画失敗を区別するには,その後の状態も確認します。

実運用に向けた描画方針

実運用では,描画の再現性と通信保護を分けて確認します。ネットワーク通信を伴うデスクトップ機能では,SSL暗号化の解説も参照し,TLS設定と証明書検証を別の工程で扱います。

Dispose的对象を適切な順序で解放すると,画面更新や再描画の過程でも安定した状態を維持できます。描画条件を変えたときは,同じ文字列とフォントで測定結果と実際の配置を比較してください。

既存実装の整理と移行

既存コードを整理するときは,単純な一行表示と矩形内表示を分けて調べます。前者をDrawTextWへ置換すると矩形や折り返しの条件が増え,意図しない改行が生じる可能性があります。TextOutWへ戻す場合も,開始位置と文字数の指定を確認します。

検証では,日本語と欧文,長文,複数行,異なるフォント,DPI変更後の再描画を含めます。矩形外の文字が预定通り切れるかも確認します。実務上の要点は,Unicodeの要素数と実測した文字幅を尊重し,配置条件に応じてAPIを分けることです。測定済みの寸法を描画処理へ渡せば,TextOutWとDrawTextWのどちらでも再現性のある表示になります。