GetTextExtentExPointW

GetTextExtentExPoint 関数は、指定されたスペースに収まる指定文字列内の文字数を取得し、その各文字のテキスト長で配列を満たす。(Unicode)

GetTextExtentExPointW hdc, lpszString, cchString, nMaxExtent, lpnFit, lpnDx, lpSize

hdc : [intptr] デバイスコンテキストのハンドル。
lpszString : [wstr] 長さを取得する対象の NULL 終端文字列へのポインタ。
cchString : [int] lpszStr パラメータが指す文字列内の文字数。ANSI 呼び出しでは文字列長をバイト単位で、Unicode 呼び出しでは WORD 単位で指定する。ANSI 関数では SBCS コードページ内の文字は 1 バイト、DBCS コードページ内のほとんどの文字は 2 バイトである。Unicode 関数では、現在定義されているほとんどの Unicode 文字(基本多言語面 (BMP) 内)は 1 WORD、Unicode サロゲートは 2 WORD である点に注意。
nMaxExtent : [int] 整形された文字列の最大許容幅(論理単位)。
lpnFit : [var] nMaxExtent パラメータで指定されたスペースに収まる文字の最大数を受け取る整数へのポインタ。lpnFit パラメータが NULL の場合、nMaxExtent パラメータは無視される。
lpnDx : [var] 部分文字列長を受け取る整数配列へのポインタ。配列の各要素は、文字列の先頭から nMaxExtent パラメータで指定されたスペースに収まる文字の 1 つまでの距離(論理単位)を示す。この配列は cchString パラメータで指定された文字数以上の要素を持たなければならない(配列全体が内部的に使用される)。関数は lpnFit パラメータで指定された文字数分だけ有効な値で配列を埋める。それ以外の値は無視されるべきである。alpDx が NULL の場合、関数は部分文字列幅を計算しない。複雑スクリプトでは、一連の文字が任意の数のグリフで表現されることがあり、alpDx 配列の lpnFit で指定された数までの値はコードポイントと 1 対 1 で対応する。やはり、alpDx 配列の残りの値は無視すべきである。
lpSize : [var] 文字列の寸法(論理単位)を受け取る SIZE 構造体へのポインタ。このパラメータは NULL であってはならない。

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

解説

GetTextExtentExPoint
関数は、指定されたスペースに収まる指定文字列内の文字数を取得し、その各文字のテキスト長で配列を満たす。(Unicode)

[戻り値]
関数が成功した場合、戻り値は 0 以外である。失敗した場合は 0 である。

[備考]
lpnFit と alpDx パラメータの両方が NULL の場合、GetTextExtentExPoint 関数の呼び出しは
GetTextExtentPoint 関数の呼び出しと等価である。ANSI 版 GetTextExtentExPoint では、lpDx
配列は lpString のバイト数と同じ数の INT 値を持つ。DBCS 文字の 2 バイトに対応する INT
値はそれぞれ合成文字全体の長さとなる。GetTextExtentExPoint の alpDx 値は ExtTextOut の lpDx
値と同じではない点に注意。lpDx で alpDx
値を使うには、最初に処理が必要である。この関数がテキストの長さを返すとき、テキストは水平である(つまり escapement は常に
0)と想定する。これはテキストの水平と垂直の両方の測定に当てはまる。0 以外の escapement
を指定するフォントを使用していても、この関数はテキストの長さを計算する際に角度を使わない。アプリケーションが明示的に変換する必要がある。ただし、グラフィックモードが
GM_ADVANCED に設定され、文字方向が印刷方向から 90
度異なる場合、この関数が返す値はこのルールに従わない。文字方向と印刷方向が一致する場合、この関数は SIZE 構造体として { cx :
116, cy : 18 } のような寸法を返す。文字方向と印刷方向が 90 度異なる場合、SIZE 構造体として { cx : 18,
cy : 116 } を返す。この関数は文字列内の各文字の累積長を返す。これを論理単位に丸めると、各文字の幅を論理単位に丸めて返す
GetCharWidth とは異なる結果となる。
> [!NOTE] > wingdi.h ヘッダは GetTextExtentExPoint
をエイリアスとして定義しており、UNICODE プリプロセッサ定数の有無に応じてこの関数の ANSI 版または Unicode
版が自動的に選択される。エンコーディング中立なエイリアスと非中立コードを混在させると、コンパイルまたは実行時エラーの原因となる不整合を引き起こすことがある。詳細は
[関数プロトタイプの規則](/windows/win32/intl/conventions-for-function-prototypes)
を参照。

情報