GetCharacterPlacementW 関数 (wingdi.h)
GetCharacterPlacement 関数は、文字幅、キャレットの配置、文字列内での順序付け、グリフのレンダリングなど、文字列に関する情報を取得します。 返される情報の種類は dwFlags パラメーターによって異なり、指定された表示コンテキストで現在選択されているフォントに基づいています。 関数は、指定した GCP_RESULTS 構造体または 構造体で指定された 1 つ以上の配列に情報をコピーします。
この関数は、かつては文字列を操作するのに十分でしたが、ますます多くの言語やスクリプトを操作する必要があるため、廃止されました。 Uniscribe モジュールの機能に置き換わりました。 詳細については、「 Uniscribe」を参照してください。
アプリケーションでは GetFontLanguageInfo 関数を使用して、GCP_DIACRITIC、GCP_DBCS、GCP_USEKERNING、GCP_LIGATE、GCP_REORDER、GCP_GLYPHSHAPE、GCP_KASHIDAの値が現在選択されているフォントに対して有効かどうかを判断することをお勧めします。 無効な場合、 GetCharacterPlacement は値を無視します。
GCP_NODIACRITICS値は定義されなくなったので、使用しないでください。
構文
DWORD GetCharacterPlacementW(
[in] HDC hdc,
[in] LPCWSTR lpString,
[in] int nCount,
[in] int nMexExtent,
[in, out] LPGCP_RESULTSW lpResults,
[in] DWORD dwFlags
);
パラメーター
[in] hdc
デバイス コンテキストへのハンドル。
[in] lpString
処理する文字列へのポインター。 nCount は文字列の長さを指定するため、文字列を 0 で終える必要はありません。
[in] nCount
lpStringが指す文字列の長さ。
[in] nMexExtent
文字列が処理される最大エクステント (論理単位)。 このエクステントを超えて処理された文字列は無視されます。 並べ替えやグリフの配列に必要な演算は、範囲に含まれている文字だけに適用されます。 このパラメーターは、 dwFlags パラメーターでGCP_MAXEXTENT値が指定されている場合にのみ使用されます。 入力文字列を処理するときは、エクステントの合計が最大値を超えない限り、各文字と文字のエクステントが出力、エクステント、および他の配列に追加されます。 制限に達すると、処理は停止します。
[in, out] lpResults
関数の結果を受け取る GCP_RESULTS 構造体へのポインター。
[in] dwFlags
必要な配列に挿入される文字列の処理方法を指定します。 このパラメーターには、次の 1 つ以上の値を指定できます。
| 値 | 説明 |
|---|---|
|
lpClass 配列に文字の事前分類が含まれていることを指定します。 分類は、出力時と同じにすることができます。 文字の特定の分類が不明な場合は、配列内の対応する場所を 0 に設定する必要があります。 分類の詳細については、「GCP_RESULTS」を参照してください。 これは、 GetFontLanguageInfo が GCP_REORDER フラグを返した場合にのみ役立ちます。 |
|
文字列内の分音記号を処理する方法を決定します。 この値が設定されていない場合、分音記号はゼロ幅文字として扱われます。 たとえば、ヘブライ語の文字列には分音記号を含めることができますが、表示したくない場合があります。
GetFontLanguageInfo を使用して、フォントが分音記号をサポートしているかどうかを判断します。 その場合は、アプリケーションのニーズに応じて、 GetCharacterPlacement の呼び出しで GCP_DIACRITIC フラグを使用するか使用できません。 |
|
単語内の文字の位置に応じて、並べ替えやグリフの形状が異なる言語の場合、多くの場合、表示できない文字がコード ページに表示されます。 たとえば、ヘブライ語のコード ページには、出力文字列内の文字の最終的な位置を判断するのに役立つ左から右および右から左のマーカーがあります。 通常、これらは表示されず、 lpGlyphs 配列と lpDx 配列から削除されます。 これらの文字を表示するには、GCP_DISPLAYZWG フラグを使用します。 |
|
現在のコード ページで現在選択されているフォントで定義されている標準図形以外の図形を使用して、文字列内の一部またはすべての文字を表示するように指定します。 アラビア語などの一部の言語では、この値が指定されていない限り、グリフの作成をサポートできません。 一般的な規則として、 GetFontLanguageInfo が 文字列に対してこの値を返す場合、この値は GetCharacterPlacement で使用する必要があります。 |
|
文字列の長さが nMaxExtent と同じになるように、lpDx 配列内のエクステントを調整します。 GCP_JUSTIFYは、GCP_MAXEXTENTと組み合わせてのみ使用できます。 |
|
文字列の長さを 変更して、nMaxExtent で指定された値と同じになるように、調整されたエクステントと同様に、またはの代わりに、Kashidas を使用します。 lpDx 配列では、Kashida は負の位置揃えインデックスで示されます。 GCP_KASHIDAは、フォント (および言語) が Kashidas をサポートしている場合にのみ、GCP_JUSTIFYと組み合わせて使用できます。 現在のフォントが Kashidas をサポートしているかどうかを判断するには、 GetFontLanguageInfo を使用します。
Kashidas を使用して文字列を正当化すると、必要なグリフの数が入力文字列の文字数を超える可能性があります。 このため、Kashidas を使用する場合、アプリケーションでは配列を入力文字列のサイズに設定するだけで十分であると想定できません。 (可能な最大値は、約 dxPageWidth/dxAveCharWidth です。ここで、dxPageWidth はドキュメントの幅、dxAveCharWidth は GetTextMetrics 呼び出しから返される平均文字幅です)。 GetFontLanguageInfo が GCP_KASHIDA フラグを返すからといって、GetCharacterPlacement の呼び出しで使用する必要があるわけではなく、オプションが使用可能であるという点に注意してください。 |
|
文字がライゲートする場所では、結紮を使用します。 結紮は、1 つのグリフが 2 つ以上の文字に使用される場合に発生します。 たとえば、文字 a と e は ?にリゲートできます。 ただし、これを使用するには、言語サポートとフォントの両方で必要なグリフをサポートする必要があります (この例は、既定では英語では処理されません)。
GetFontLanguageInfo を使用して、現在のフォントが結紮をサポートしているかどうかを判断します。 を実行し、リゲートする文字数に特定の最大値が必要な場合は、 lpGlyphs 配列の最初の要素に数値を設定します。 通常の結紮が必要な場合は、この値を 0 に設定します。 GCP_LIGATEが指定されていない場合、結紮は行われません。 詳細については、「GCP_RESULTS」を参照してください。 通常、文字セットにGCP_REORDER値が必要ですが、指定されていない場合、渡される文字列が既に視覚的な順序になっている場合を除き、出力は意味がありません (つまり、GetCharacterPlacement への 1 回の呼び出しで lpGcpResults-lpOutString> に格納される結果は、2 番目の呼び出しの入力文字列です)。 GetFontLanguageInfo が GCP_LIGATE フラグを返すからといって、GetCharacterPlacement の呼び出しで使用する必要があるわけではなく、オプションが使用可能であるという点に注意してください。 |
|
結果のエクステント (論理単位) が nMaxExtent パラメーターで指定された値を超えない限り、文字列のエクステントを計算します。 |
|
特定の言語のみ。 ニュートラルの通常の処理をオーバーライドし、文字列の読み取り順序に一致する強力な文字として扱います。 GCP_REORDER フラグでのみ便利です。 |
|
特定の言語のみ。 数値の通常の処理をオーバーライドし、文字列の読み取り順序に一致する強力な文字として扱います。 GCP_REORDER フラグでのみ便利です。 |
|
アラビア語/タイ語のみ。 数値には標準のラテン語グリフを使用し、システムの既定値をオーバーライドします。 このオプションがフォントの言語で使用できるかどうかを判断するには、 GetStringTypeEx を 使用して、言語が複数の数値形式をサポートしているかどうかを確認します。 |
|
アラビア語/タイ語のみ。 数値にはローカル グリフを使用し、システムの既定値をオーバーライドします。 このオプションがフォントの言語で使用できるかどうかを判断するには、 GetStringTypeEx を 使用して、言語が複数の数値形式をサポートしているかどうかを確認します。 |
|
文字列の順序を変更します。 SBCS および左から右の読み取り順序ではない言語に使用します。 この値を指定しない場合、文字列は既に表示順であると見なされます。
このフラグを Semitic 言語に設定し、 lpClass 配列を使用する場合、配列の最初の 2 つの要素を使用して、文字列の境界を超える読み取り順序を指定します。 GCP_CLASS_PREBOUNDRTLとGCP_CLASS_PREBOUNDLTRを使用して順序を設定できます。 事前設定された順序が不要な場合は、値を 0 に設定します。 GCPCLASSIN フラグが設定されている場合は、これらの値を他の値と組み合わせることができます。 GCP_REORDER値が指定されていない場合、 lpString パラメーターは、これが使用される言語に対して視覚的に順序付けされ、 lpOutString フィールドと lpOrder フィールドは無視されます。 GetFontLanguageInfo を使用して、現在のフォントが並べ替えをサポートしているかどうかを判断します。 |
|
半音言語のみ。 スワップ可能な文字がリセットされないことを指定します。 たとえば、右から左への文字列では、'(' と ')' は逆になりません。 |
|
幅配列を作成するときは、フォントでカーニング ペアを使用します (存在する場合)。 GetFontLanguageInfo を使用して、現在のフォントがカーニング ペアをサポートしているかどうかを判断します。
GetFontLanguageInfo が GCP_USEKERNING フラグを返すからといって、GetCharacterPlacement の呼び出しで使用する必要があるわけではないことに注意してください。 ほとんどの TrueType フォントにはカーニング テーブルがありますが、使用する必要はありません。 |
アプリケーションでは 、GetFontLanguageInfo 関数を使用して、GCP_DIACRITIC、GCP_DBCS、GCP_USEKERNING、GCP_LIGATE、GCP_REORDER、GCP_GLYPHSHAPE、およびGCP_KASHIDAの値が現在選択されているフォントに対して有効かどうかを判断することをお勧めします。 無効な場合、 GetCharacterPlacement は値を無視します。
GCP_NODIACRITICS値は定義されなくなり、使用しないでください。
戻り値
関数が正常に終了した場合は、文字列の幅と高さを論理単位で返します。 幅は低い単語で、高さは高い単語です。
関数が失敗した場合は、0 を返します。
解説
GetCharacterPlacement を使用すると、国際的な設定や使用可能なフォントの種類に関係なく、アプリケーションでテキストを正しく処理できます。 アプリケーションでは、 ExtTextOut 関数を使用する前にこの関数を使用し、 GetTextExtentPoint32 関数の代わりに使用します ( また、GetCharWidth32 関数と GetCharABCWidths 関数の代わりに使用する場合があります)。
理由やカーニングが必要でない限り、 GetCharacterPlacement を使用して文字間の間隔とインデックス配列を取得する必要はありません。 ラテン以外のフォントの場合、アプリケーションは、 ExtTextOut を呼び出す前に GetCharacterPlacement を使用して文字間の間隔とインデックス配列を取得することで、 ExtTextOut 関数がテキストをレンダリングする速度を向上させることができます。 これは、同じテキストを繰り返しレンダリングする場合や、文字間の間隔を使用してキャレットを配置する場合に特に便利です。 extTextOut の呼び出しで lpGlyphs 出力配列を使用する場合は、ETO_GLYPH_INDEX フラグを設定する必要があります。
GetCharacterPlacement は、GCP_RESULTS構造体の lpOrder、lpDX、lpCaretPos、lpOutString、lpGlyphs メンバーをチェックし、これらのメンバーが NULL に設定されていない場合は、対応する配列を入力します。 GetCharacterPlacement が配列を埋めることができない場合は、対応するメンバーを NULL に設定します。 有効な情報を確実に取得するには、関数を呼び出す前にメンバーを有効なアドレスに設定し、呼び出し後にメンバーの値を確認する必要があります。 GCP_JUSTIFY値またはGCP_USEKERNING値を指定する場合は、 lpDX メンバーまたは lpCaretPos メンバーに有効なアドレスが必要です。
GCP_RESULTS.lpGlyphs で返されるグリフ インデックスは、デバイス コンテキストの現在のフォントに固有であり、そのフォントが選択されたままデバイス コンテキストでテキストを描画するためにのみ使用する必要があることに注意してください。
理由を計算するときに、文字列の末尾の文字がスペースである場合、関数は文字列の長さを減らし、理由を計算する前にスペースを削除します。 配列がスペースのみで構成されている場合、関数はエラーを返します。
ExtTextOut では、DBCS 文字列の各バイトに lpDX エントリが必要ですが、 GetCharacterPlacement は各グリフに lpDX エントリを割り当てます。 この関数の組み合わせを使用するときにこの不一致を修正するには、 GetGlyphIndices を使用するか、DBCS バイト ペアの対応する 2 番目のバイトの幅が 0 のエントリを持つ lpDX 配列を展開します。
論理幅が入力文字列の先頭文字の幅より小さい場合、GCP_RESULTS.nMaxFit は無効な値を返します。 この場合は、グリフ インデックスと lpDX 配列に対して GetCharacterPlacement を呼び出します。 次に 、lpDX 配列を使用して、各文字の事前幅を使用してエクステント計算を行います。 ここで、nMaxFit は、グリフ インデックスの前の幅が先頭文字の幅より小さい文字数です。
Note
wingdi.h ヘッダーは、Unicode プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして GetCharacterPlacement を定義します。 encoding-neutral エイリアスの使用を encoding-neutral ではないコードと混在すると、コンパイル エラーまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。
要件
| サポートされている最小のクライアント | Windows 2000 Professional [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows 2000 Server [デスクトップ アプリのみ] |
| 対象プラットフォーム | Windows |
| ヘッダー | wingdi.h (Windows.h を含む) |
| Library | Gdi32.lib |
| [DLL] | Gdi32.dll |
関連項目
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示