GetCharacterPlacementA 関数 (wingdi.h)

[アーティクル]
03/08/2023

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 GetCharacterPlacementA(
  [in]      HDC            hdc,
  [in]      LPCSTR         lpString,
  [in]      int            nCount,
  [in]      int            nMexExtent,
  [in, out] LPGCP_RESULTSA 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 つ以上の値を指定できます。

値	意味
GCP_CLASSIN	lpClass 配列に文字の事前設定された分類が含まれていることを指定します。分類は、出力時と同じにすることができます。文字の特定の分類がわからない場合は、配列内の対応する場所を 0 に設定する必要があります。分類の詳細については、「GCP_RESULTS」を参照してください。これは、 GetFontLanguageInfo が GCP_REORDER フラグを返した場合にのみ役立ちます。
GCP_DIACRITIC	文字列内の分音記号の処理方法を指定します。この値が設定されていない場合、分音記号はゼロ幅文字として扱われます。たとえば、ヘブライ語の文字列には分音記号を含めることができますが、表示したくない場合があります。 GetFontLanguageInfo を使用して、フォントが分音記号をサポートしているかどうかを判断します。その場合は、アプリケーションのニーズに応じて、 GetCharacterPlacement の呼び出しで GCP_DIACRITIC フラグを使用するか使用できません。
GCP_DISPLAYZWG	単語内の文字の位置に応じてグリフの図形を並べ替えたり、異なるグリフ図形を変更したりする必要がある言語の場合、多くの場合、表示できない文字がコードページに表示されます。たとえば、ヘブライ語のコードページには、出力文字列内の文字の最終的な位置を決定するのに役立つ左から右および右から左のマーカーがあります。通常、これらは表示されず、 lpGlyphs 配列と lpDx 配列から削除されます。 GCP_DISPLAYZWG フラグを使用して、これらの文字を表示できます。
GCP_GLYPHSHAPE	現在のコードページで現在選択されているフォントで定義されている標準図形以外の図形を使用して、文字列内の一部またはすべての文字を表示するように指定します。アラビア語などの一部の言語では、この値が指定されていない限り、グリフの作成をサポートできません。一般的な規則として、 GetFontLanguageInfo が文字列に対してこの値を返す場合、この値は GetCharacterPlacement と共に使用する必要があります。
GCP_JUSTIFY	文字列の長さが nMaxExtent と同じになるように lpDx 配列内のエクステントを調整します。 GCP_JUSTIFYは、GCP_MAXEXTENTと組み合わせてのみ使用できます。
GCP_KASHIDA	文字列の長さが nMaxExtent で指定された値と等しくなるように、調整されたエクステントの代わりに、Kashidas を使用します。 lpDx 配列では、Kashida は負の理由付けインデックスで示されます。 GCP_KASHIDAは、フォント (および言語) が Kashidas をサポートしている場合にのみ、GCP_JUSTIFYと組み合わせて使用できます。現在のフォントが Kashidas をサポートしているかどうかを判断するには、 GetFontLanguageInfo を使用します。 Kashidas を使用して文字列を両端揃えすると、必要なグリフの数が入力文字列の文字数を超える可能性があります。このため、Kashidas を使用する場合、アプリケーションでは、配列を入力文字列のサイズに設定するだけで十分であると想定できません。 (可能な最大値は約 dxPageWidth/dxAveCharWidth です。ここで、dxPageWidth はドキュメントの幅、dxAveCharWidth は GetTextMetrics 呼び出しから返される平均文字幅です)。 GetFontLanguageInfo が GCP_KASHIDA フラグを返すからといって、GetCharacterPlacement の呼び出しで使用する必要があるわけではないことに注意してください。
GCP_LIGATE	文字がリゲートする場所では、リゲーションを使用します。結紮は、1 つのグリフが 2 つ以上の文字に使用される場合に発生します。たとえば、文字 a と e はにリゲートできます。ただし、これを使用するには、言語サポートとフォントの両方で必要なグリフをサポートする必要があります (この例は既定では英語では処理されません)。 GetFontLanguageInfo を使用して、現在のフォントがライゲーションをサポートしているかどうかを判断します。を実行し、リゲートする文字数に特定の最大値が必要な場合は、 lpGlyphs 配列の最初の要素に数値を設定します。通常のライゲーションが必要な場合は、この値を 0 に設定します。 GCP_LIGATEが指定されていない場合、結紮は行われません。詳細については、「GCP_RESULTS」を参照してください。通常、文字セットに対してGCP_REORDER値が必要ですが、指定されていない場合、渡される文字列が既に視覚的な順序になっている場合 (つまり、GetCharacterPlacement の 1 回の呼び出しで lpGcpResults-lpOutString> に配置される結果が 2 番目の呼び出しの入力文字列) でない限り、出力は意味がありません。 GetFontLanguageInfo が GCP_LIGATE フラグを返すからといって、GetCharacterPlacement の呼び出しで使用する必要があるわけではないことに注意してください。
GCP_MAXEXTENT	結果のエクステント (論理単位) が nMaxExtent パラメーターで指定された値を超えない限り、文字列のエクステントを計算します。
GCP_NEUTRALOVERRIDE	特定の言語のみ。ニュートラルの通常の処理をオーバーライドし、文字列の読み取り順序に一致する強力な文字として扱います。 GCP_REORDER フラグでのみ便利です。
GCP_NUMERICOVERRIDE	特定の言語のみ。数値の通常の処理をオーバーライドし、文字列の読み取り順序に一致する強力な文字として扱います。 GCP_REORDER フラグでのみ便利です。
GCP_NUMERICSLATIN	アラビア語/タイ語のみ。数値には標準のラテン語グリフを使用し、システムの既定値をオーバーライドします。このオプションがフォントの言語で使用できるかどうかを判断するには、 GetStringTypeEx を使用して、言語が複数の数値形式をサポートしているかどうかを確認します。
GCP_NUMERICSLOCAL	アラビア語/タイ語のみ。数値にローカルグリフを使用し、システムの既定値をオーバーライドします。このオプションがフォントの言語で使用できるかどうかを判断するには、 GetStringTypeEx を使用して、言語が複数の数値形式をサポートしているかどうかを確認します。
GCP_REORDER	文字列の順序を変更します。 SBCS および左から右の読み取り順序ではない言語に使用します。この値を指定しない場合、文字列は既に表示順であると見なされます。 Semitic 言語にこのフラグを設定し、 lpClass 配列を使用する場合、配列の最初の 2 つの要素を使用して、文字列の境界を超える読み取り順序を指定します。 GCP_CLASS_PREBOUNDRTLとGCP_CLASS_PREBOUNDLTRを使用して注文を設定できます。事前設定された順序が不要な場合は、値を 0 に設定します。 GCPCLASSIN フラグが設定されている場合、これらの値を他の値と組み合わせることができます。 GCP_REORDER値が指定されていない場合、 lpString パラメーターは、これが使用される言語に対して視覚的に順序付けされ、 lpOutString フィールドと lpOrder フィールドは無視されます。現在のフォントが並べ替えをサポートしているかどうかを判断するには、 GetFontLanguageInfo を使用します。
GCP_SYMSWAPOFF	半言語のみ。スワップ可能な文字がリセットされないことを指定します。たとえば、右から左の文字列では、'(' と ')' は逆になりません。
GCP_USEKERNING	幅配列を作成するときは、フォント (存在する場合) でカーニングペアを使用します。現在のフォントがカーニングペアをサポートしているかどうかを判断するには、 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 番目のバイトの幅がゼロのエントリを持つ lpDX 配列を展開します。

論理幅が入力文字列の先頭文字の幅より小さい場合、GCP_RESULTS.nMaxFit は無効な値を返します。この場合は、グリフインデックスと lpDX 配列に対して GetCharacterPlacement を呼び出します。次に 、lpDX 配列を使用して、各文字の前の幅を使用してエクステント計算を実行します。 nMaxFit は、グリフインデックスの事前幅が先頭文字の幅より小さい文字数です。

注意

wingdi.h ヘッダーは、GetCharacterPlacement をエイリアスとして定義し、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択します。エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイムエラーが発生する不一致が発生する可能性があります。詳細については、「関数プロトタイプの規則」を参照してください。

要件

要件	値
サポートされている最小のクライアント	Windows 2000 Professional [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows 2000 Server [デスクトップアプリのみ]
対象プラットフォーム	Windows
ヘッダー	wingdi.h (Windows.h を含む)
Library	Gdi32.lib
[DLL]	Gdi32.dll