<Return[G]><Top>

GetCharacterPlacement

Declare Function Api_GetCharacterPlacement& Lib "gdi32" Alias "GetCharacterPlacementA" (ByVal hDC&, ByVal lpString$, ByVal nCount&, ByVal nMaxExtent&, lpResults As GCP_RESULTS, ByVal dwFlags&)

Declare Function GetCharacterPlacement Lib "gdi32" Alias "GetCharacterPlacementA" (ByVal hdc As Long, ByVal lpString As String, ByVal nCount As Long, ByVal nMaxExtent As Long, lpResults As GCP_RESULTS, ByVal dwFlags As Long) As Long

文字幅、キャレット位置、文字列内の順序、グリフレンダリングなどのキャラクタ文字列に関する情報を取得する。返される情報の種類は dwFlags パラメータに依存し、与えられたディスプレイコンテキスト内で現在選択されているフォントに基づく。この関数は、取得した情報を、指定された GCP_RESULTS 構造体か、またはその構造体によって指定された1つ以上の配列にコピーする。
この関数は下位互換性のためにだけ存在し、Uniscribe モジュールの機能で置き換えることができる。

パラメータ
hdc
    デバイスコンテキストのハンドルを指定する。
lpString
    処理する文字列へのポインタを指定する。
nCount
    文字列内の文字数を指定する。
    Windows 95/98:この値は 8192 を超えることはできない。
nMaxExtent
    文字列を処理する場合の最大範囲(論理単位で)を指定する。処理を行う場合、この範囲を超えた文字は無視される。必要な順序または

    グリフ配列に対する処理は、そこに含まれる文字に対してだけ適用される。このパラメータは、dwFlags パラメータの値が

    GCP_MAXEXTENT の場合にだけ使われる。この関数が入力文字列を処理していくときには、全ての範囲が最大範囲を超えない場合に

    限り、個々の文字とその範囲は出力、範囲およびその他の配列に追加される。上限に到達すると、処理は停止する。
lpResults
    この関数の結果を取得する、GCP_RESULTS 構造体へのポインタを指定する。
dwFlags
    文字列を必要な配列として処理する方法を指定する。このパラメータには、次の値を1つ以上指定することができる。
 

    値                                        

意味                                                                                                                                       

    GCP_CLASSIN

 

lpClass 配列に、予め設定された文字の分類が入っていることを表す。分類は出力と同じになる。ある文字に対する特定の分類が未知の場合、それに対応する配列内の位置は 0 に設定される。

    GCP_DIACRITIC

 

 

 文字列内の分音符の取り扱い方法を決定する。この値がセットされていない場合、分音符は幅が 0 の文字列として扱われる。たとえば、ヘブライ語の文字列に分音符が含まれていても、それを表示したくない場合などが該当する。
フォントが分音符をサポートするかどうかを調べるには、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 パラメータで与えられた値と同じにするため、範囲を調節する代わりに、または範囲を調節すると共に、カシダを使う。lpDx 配列内では、カシダは負の位置合わせインデックスとして表される。GCP_KASHIDA は、そのフォント(およびその言語)がカシダをサポートする場合に使われ、必ず GCP_JUSTIFY と共に使われる。現在のフォントがカシダをサポートするかどうかは、GetFontLanguageInfo 関数を使って調べる。
文字列の位置合わせにカシダを使うと、文字列に必要なグリフ数が、入力文字列内の文字数よりも多くなる場合がある。このためカシダを使うと、入力文字列に対して作成した配列のサイズが十分かどうかをアプリケーションが調べることはできない(予想される最大値はおおむね dxPageWidth/dxAveCharWidth になる。ここで、dxPageWidth は文書の幅、dxAveCharWidth は GetTextMetrics 関数を呼び出して戻された平均文字幅である)。
GetFontLanguageInfo 関数は GCP_KASHIDA フラグを返すが、それを必ず GetCharacterPlacement 関数への呼び出しで使わなければならないわけではなく、単に利用可能であるということに注意する。

    GCP_LIGATE

 

 

 

 

 

 

 

 

 

 

文字が連結する部分はすべて合字を使う。合字は 1 つのグリフが 2 つ以上の文字で使われている場合に派生する。たとえば、a と e の合字はæである。しかし、これを使うには、必要なグリフをその言語がサポートし、特にそのフォントは必ずサポートしていなければならない(たとえば、ここで挙げた例は、英語の既定では処理されない)。
GetFontLanguageInfo 関数を使い、現在のフォントが合字をサポートするかどうかを調べる。フォントが合字をサポートし、合字になる文字数固有の最大値が必要な場合、lpGlyphs 配列の最初の要素の値を設定する。通常の合字が必要な場合、この値を 0 にセットする。GCP_LIGATE が与えられていない場合、合字は行われない。
その文字のセットに対して通常 GCP_REORDER の値が必要であるのに、それが与えられていない場合、渡される文字列がすでに表示順に並べられていない場合、出力は無意味になる(つまり、GetCharacterPlacement 関数への1回目の呼び出しで lpGcpResults パラメータから lpOutString パラメータへ格納された結果が、次の呼び出しの入力文字列になる)。
GetFontLanguageInfo 関数は GCP_LIGATE フラグを返すが、それを必ず GetCharacterPlacement 関数への呼び出しで使わなければならないわけではなく、単に利用可能であるということに注意する。

    GCP_MAXEXTENT

 

文字列の範囲が nMaxExtent パラメータで与えられる論理単位での値を超えない場合に限り、それを計算する。

    GCP_NEUTRALOVERRIDE

特定の言語でだけ使われる。通常の中間文字種の処理を無効にし、文字列の読み取り順に合致する強い文字として処理する。GCP_REORDER フラグと共に使われる場合にだけ有用である。

    GCP_NUMERICOVERRIDE

 

特定の言語でだけ使われる。通常の数字の処理を無効にし、文字列の読み取り順に合致する強い文字として処理する。GCP_REORDER フラグと一緒の場合にだけ有用である。

    GCP_NUMERICSLATIN

 

アラビア語とタイ語でだけ使われる。数字に対しては標準のラテングリフを使い、システムの既定を無効にする。その言語のそのフォントでこのオプションが利用可能かどうかを調べるには、GetStringTypeEx 関数を使って、その言語が複数の数字書式をサポートするかどうかを調べる。

    GCP_NUMERICSLOCAL

 

アラビア語とタイ語でだけ使われる。数字に対してローカルグリフを使い、システムの既定を無効にする。その言語のそのフォントでこのオプションが利用可能かどうかを調べるには、GetStringTypeEx 関数を使って、その言語が複数の数字書式をサポートするかどうかを調べる。

    GCP_REORDER

 

 

 

 

 

 

 

文字列を並べ直す。SBCS でなく、読み取り順が左から右である言語で使う。この値が与えられていない場合は、文字列はすでに表示順であるとみなされる。
セム語に対してこのフラグがセットされており、lpClass 配列が使われている場合、読み取り順を文字列の境界を越えて指定するために、配列の最初の 2 つの要素が使われる。文字の順序をセットするには、GCP_CLASS_PREBOUNDRTL および GCP_CLASS_PREBOUNDLTR を使うことができる。文字の順序をあらかじめセットしておく必要がない場合、この値を 0 にセットする。GCPCLASSIN フラグの値がセットされている場合、これらの値は他の値と組み合せることができる。

GCP_REORDERの値が与えられていない場合、これが使われる部分での言語の表示順序は lpString パラメータで決まり、lpOutString および lpOrder フィールドは無視される。
現在のフォントが並べ替えをサポートしているかどうかを調べるには、GetFontLanguageInfo 関数を使う。

    GCP_SYMSWAPOFF

 

 セム語でだけ使われる。交換可能な文字はリセットされないことを表す。たとえば、右から左の文字列では、'('and')' は逆にならない。

    GCP_USEKERNING

 

 

 

 

 

 

 

 幅の配列を作成するときに、そのフォントのカーニング対(存在する場合)を使う。現在のフォントがカーニング対をサポートするかどうかを調べるには、GetFontLanguageInfo 関数を使う。
GetFontLanguageInfo 関数は GCP_USEKERNING フラグを返すが、それを必ず GetCharacterPlacement 関数への呼び出しで使わなければならないわけではなく、単に利用可能であるということに注意する。大部分の True Type フォントにはカーニングテーブルがあるが、使う必要はない。
現在選択されているフォントに対して、GCP_DIACRITIC、GCP_DBCS、GCP_USEKERNING、GCP_LIGATE、GCP_REORDER、GCP_GLYPHSHAPE、および GCP_KASHIDA の値が有効であるかどうかを調べるために、アプリケーションで GetFontLanguageInfo 関数を使うことを推奨する。有効でない場合、GetCharacterPlacement 関数はその値を無視する。
GCP_NODIACRITICS の値は定義から外されているため、使ってはならない。


戻り値
    関数が成功すると、GetTextExtentPoint32 関数の戻り値と同じ、文字列の幅と高さが返る。
    関数が失敗すると、0 が返る。
    Windows NT/2000:拡張エラー情報を取得するには、GetLastError 関数を使う。

解説
    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 メンバ、あるいはその両方が有効なアドレスを持

    つ必要がある。
    位置合わせの計算時に、文字列内の後続文字が空白文字の場合、この関数は、位置合わせの計算の前に空白文字を除去し、文字

    列を短くする。配列が空白文字だけから構成されている場合、関数はエラーを返す。。