GetCharacterPlacementW

GetCharacterPlacement 関数は、文字列に関する情報(文字幅、キャレット位置決め、文字列内の順序、グリフ描画など)を取得する。(Unicode)

GetCharacterPlacementW hdc, lpString, nCount, nMexExtent, lpResults, dwFlags

hdc : [intptr] デバイスコンテキストのハンドル。
lpString : [wstr] 処理対象の文字列へのポインタ。nCount で長さが指定されるため、NULL 終端である必要はない。
nCount : [int] lpString が指す文字列の長さ。
nMexExtent : [int] 文字列を処理する最大長(論理単位)。処理するとこの長さを超える文字は無視される。必要な順序付けやグリフ配列の計算は、含まれる文字にのみ適用される。このパラメータは dwFlags に GCP_MAXEXTENT 値が指定された場合にのみ使用される。関数が入力文字列を処理する際、合計長がまだ最大を超えていない場合にのみ、各文字とその長さが出力、長さ、その他の配列に追加される。上限に達すると処理が停止する。
lpResults : [var] 関数の結果を受け取る GCP_RESULTS 構造体へのポインタ。
dwFlags : [int] 

(プラグイン / モジュール : gdi32.dll)

解説

GetCharacterPlacement
関数は、文字列に関する情報(文字幅、キャレット位置決め、文字列内の順序、グリフ描画など)を取得する。(Unicode)

[戻り値]
関数が成功した場合、戻り値は文字列の幅と高さ(論理単位)である。幅は下位ワード、高さは上位ワードである。失敗した場合は 0 を返す。

[備考]
GetCharacterPlacement
は、国際設定や利用可能なフォントの種類に関係なくアプリケーションがテキストを正しく処理できるようにする。アプリケーションはこの関数を
ExtTextOut 関数の前に、また GetTextExtentPoint32 関数の代わりに(場合により GetCharWidth32
や GetCharABCWidths 関数の代わりに)使用する。GetCharacterPlacement
を使って文字間隔やインデックス配列を取得する必要があるのは、通常は揃えやカーニングが必要な場合のみである。非ラテン系フォントでは、アプリケーションは
ExtTextOut を呼ぶ前に GetCharacterPlacement
を使って文字間隔やインデックス配列を取得することで、ExtTextOut
のテキスト描画速度を向上できる。これは、同じテキストを繰り返し描画する場合や、キャレット位置決めに文字間隔を使う場合に特に有効である。ExtTextOut
の呼び出しで lpGlyphs 出力配列を使用する場合、ETO_GLYPH_INDEX
フラグを設定する必要がある。GetCharacterPlacement は GCP_RESULTS 構造体の
lpOrder、lpDX、lpCaretPos、lpOutString、lpGlyphs メンバを確認し、これらのメンバが NULL
でなければ対応する配列を埋める。配列を埋められない場合、対応するメンバを NULL
に設定する。有効な情報の取得を保証するため、アプリケーションは関数呼び出し前にメンバを有効なアドレスに設定し、呼び出し後にメンバの値を確認する責任を負う。GCP_JUSTIFY
または GCP_USEKERNING 値が指定された場合、lpDX あるいは lpCaretPos
メンバは有効なアドレスを持たなければならない。GCP_RESULTS.lpGlyphs
で返されるグリフインデックスはデバイスコンテキスト内の現在のフォントに固有であり、そのフォントが選択されている間にそのデバイスコンテキストでテキストを描画する目的でのみ使用すべきである点に注意。揃えを計算する際、文字列の末尾文字がスペースの場合、関数は計算前に文字列の長さを縮めてスペースを除去する。配列がスペースのみで構成されている場合、関数はエラーを返す。
ExtTextOut は DBCS 文字列のバイトごとに lpDx エントリを期待するが、GetCharacterPlacement
はグリフごとに lpDX エントリを割り当てる。この組み合わせで使うときの不整合を修正するには、GetGlyphIndices
を使用するか、DBCS バイトペアの 2 バイト目に対応する幅 0 のエントリを lpDX
配列に追加する。論理幅が入力文字列の先頭文字の幅より小さい場合、GCP_RESULTS.nMaxFit
に不正な値が返される。このような場合には、まず GetCharacterPlacement でグリフインデックスと lpDX
配列を取得し、次に各文字の前進幅を使って lpDX 配列で長さ計算を行う。nMaxFit
は先頭文字の幅より前進幅の合計が小さい文字数である。
> [!NOTE] > wingdi.h ヘッダは GetCharacterPlacement
をエイリアスとして定義しており、UNICODE プリプロセッサ定数の有無に応じてこの関数の ANSI 版または Unicode
版が自動的に選択される。エンコーディング中立なエイリアスと非中立コードを混在させると、コンパイルまたは実行時エラーの原因となる不整合を引き起こすことがある。詳細は
[関数プロトタイプの規則](/windows/win32/intl/conventions-for-function-prototypes)
を参照。

情報