XLoadFont(3X11)

名前
XLoadFont, XQueryFont, XLoadQueryFont, XFreeFont, XGetFontProperty, XUnloadFont, XCharStruct, XFontProp, XChar2b, XFontStruct - フォントのロードとアンロード、フォント寸法構造体

書式
Font XLoadFont(display, name)
      Display *display;
      char *name;

XFontStruct *XQueryFont(display, font_ID)
      Display *display;
      XID font_ID;

XFontStruct *XLoadQueryFont(display, name)
      Display *display;
      char *name;

XFreeFont(display, font_struct)
      Display *display;
      XFontStruct *font_struct;

Bool XGetFontProperty(font_struct, atom, value_return)
      XFontStruct *font_struct;
      Atom atom;
      unsigned long *value_return;

XUnloadFont(display, font)
      Display *display;
      Font font;

引き数

atom
    求めるプロパティ名に対するアトムを指定。

display
    X サーバへの接続を指定。

font
    フォントを指定。

font_ID
    フォント ID か ID を指定。

font_struct
    フォントに対応する構造体を指定。

gc  GC を指定。

name
    フォントの名前を指定。 これはNULLで終る文字列である。

value_return
    フォントプロパティの値が返される。

説明
関数 は指定したフォントをロードし、対応するフォントIDを返す。 フォント名のエンコーディングがホストポータブル文字エンコーディングでな い場合、実行結果は実装依存である。 大文字や小文字の使用は問題ない。 フォント名に文字 ``?'' や ``*'' が用いられた時、パターンマッチングが行 われマッチしたフォントのどれかが使用される。 パターン中で文字 ``?'' は任意の1文字にマッチし、文字 ``*'' は任意の数 の文字にマッチする。 フォント名の構造化フォーマットはXコンソーシアム標準の X Logical Font Description Conventions で指定されている。 が指定したフォントのロードに失敗した場合、エラー が起こる。 フォントは特定のスクリーンに関連づけされない。一方、任意の GC のコンポー ネントとして格納することはできる。 フォントが不要になった場合は を呼び出すこと。

はエラー を起こすことがある。

関数は 構造体へのポインタを返す。 この構造体はフォントに関連する情報を持っている。 クライアントはフォントやGCに格納されているフォントを問い合わせることが できる。 構造体に含まれるフォントIDは のIDであり、他の関数でこの GC を使うときには注意する必要がある( を参照)。 フォントが存在しなければ は NULL を返す。 このデータを解放するには を使用すること。

はエラー を起こすことがある。

関数 はフォントにアクセスする手段のうち、最も一般的なものである。 は指定したフォントをオープン(ロード)し、適切な 構造体へのポインタを返す。 フォント名のエンコーディングがホストポータブル文字エンコーディングでな い場合、実行結果は実装依存である。 フォントが存在しない場合 は NULL を返す。

関数 はフォントのリソースIDと指定したフォントの関連を削除し、 構造体を解放する。 フォントそのものは他のリソースから参照されなくなったときに解放される。 このデータとフォントは再び参照してはならない。

はエラー を起こすことがある。

プロパティに対するアトムを与えると、 は指定したフォントプロパティの値を返す。 はプロパティが定義されていなければ を返し、定義されていれば を返す。 フォントプロパティとして予め定義されているアトムがあり、これは で定義されている。 これらのアトムにはフォントに関連する標準的なプロパティが含まれている。 保証はされていないが、予め定義されているフォントプロパティはたいてい存 在する。

関数 はフォントリソースIDと指定したフォントの関連を削除する。 フォントそのものは他のリソースから参照されなくなったときに解放される。 このフォントを再び参照してはならない。

はエラー を起こすことがある。

構造体
構造体にはフォントの情報が全て含まれる。この構造体は、フォント固有の情 報や 構造体(フォントに含まれる文字の情報)の配列へのポインタから構成されてい る。 の各構造体の内容を以下に示す。

typedef struct {
    short lbearing;
    short rbearing;
    short width;
    short ascent;
    short descent;
    unsigned short attributes; } XCharStruct;

typedef struct {
    Atom    name;
    unsigned long card32; } XFontProp;

typedef struct {
    unsigned char byte1;
    unsigned char byte2; } XChar2b;

typedef struct {
    XExtData *ext_data;
    Font fid;
    unsigned direction;
    unsigned min_char_or_byte2;
    unsigned max_char_or_byte2;
    unsigned min_byte1;
    unsigned max_byte1;
    Bool all_chars_exist;
    unsigned default_char;
    int n_properties;
    XFontProp *properties;
    XCharStruct min_bounds;
    XCharStruct max_bounds;
    XCharStruct *per_char;
    int ascent;
    int descent; } XFontStruct;

X は 1バイト/文字の形式、2バイト/文字の行列形式と、16ビット文字形式の テキスト操作をサポートしている。 あるフォントはこれらの形式のいずれでも使用できるが、1バイト/文字のテキ ストのリクエストだけが単独のバイト(つまり、2バイトフォントの最初の列) を指定できる。 2バイトフォントは定義された文字の2次元行列として見るべきである。 byte1 はフォントの定義された列の範囲を指定し、byte2 は定義された行の範 囲を定義する。 1バイト/文字のフォントは列が1つ定義されており、構造体で定義された byte2 は文字の範囲を定義する。

文字のバウンディングボックスは文字の によって定義される。 フォントに含まれていない文字があるときにはデフォルト文字が使用される。 フォントの全ての文字のサイズが同じであるとき、 構造体の min_bounds と max_bounds の情報だけが使用される。

のメンバは以下の意味を持つ。

•   direction メンバは か の値を持つ。 これは、 要素の大部分が、正 あるいは負 の文字幅を持っていることを示す単なるヒントに過ぎない。 コアプロトコルでは縦書きテキストのサポートは定義されていない。

•   min_byte1 と max_byte1 メンバがいずれも 0 であれば、min_char_or_byte2 は per_char 配列の最初の要素に対応する線形文字インデックスを指定し、 max_char_or_byte2 は最後の要素の線形文字インデックスを指定する。

    min_byte1 か max_byte1 が 0 でなければ、min_char_or_byte2 と max_char_or_byte2 は256未満であり、per_char 配列要素 N(0から数える)に 対応する2バイト文字インデックス値は以下のようになる。

    	byte1 = N/D + min_byte1
    	byte2 = N\D + min_char_or_byte2

    where:

            D = max_char_or_byte2 - min_char_or_byte2 + 1
             / = 整数の商
             \ = 整数の剰余

•   per_char ポインタが NULL であれば、最初と最後の文字インデックスの間の グリフは全て同じ情報を持つ。これは min_bounds と max_bounds で与えられ る。

•   all_chars_exist が の場合、per_char 配列内の全ての文字は 0 でないバウンディングボックス を持つ。

•   default_char メンバは、未定義の文字や存在しない文字を表示するときに用 いられる文字を指定する。 default_char は(2バイト文字ではなく)16ビット文字である。 2バイト行列形式を使うフォントの場合、default_char は byte1 を最上位バ イト、byte2 を最下位バイトとする。 default_char 自身が未定義あるいは存在しない文字を指定した場合には、未 定義あるいは存在しない文字の表示は行われない。

•   min_bounds と max_bounds メンバは、この配列の全ての要素それぞれ(存在し ない文字は除く)の 要素の最大値、最小値を持つ。 フォントのバウンディングボックス(全ての文字を同じ原点に置いて重ね合わ せ、得られた形状を囲む最少の長方形)の左上の座標は次のようになる:
        [x + min_bounds.lbearing, y - max_bounds.ascent]

    幅は以下のようになる:
        max_bounds.rbearing - min_bounds.lbearing

    高さは以下のようになる:
        max_bounds.ascent + max_bounds.descent

•   ascent メンバは、ベースライン上部のフォントの論理的な広さで、行間を決 定するために用いられる。 特定の文字はこれを越えることがある。

•   descent メンバは、ベースライン下部のフォントの論理的な広さで、行間を決 定するために用いられる(0のこともある)。 特定の文字はこれを越えることがある。

•   ベースラインが Y座標 y にあるとき、フォントの論理的な広さは Y 座標 (y - font.ascent) と (y + font.descent - 1) の内側である。 通常はテキストの行間の最少の送り量は ascent + descent で与えられる。

原点が[x, y]にある文字について、 コンポーネントを用いて記述される、文字のバウンディングボックス(つまり 文字の形を囲む最小の長方形)は、次のようになる:

[x + lbearing, y - ascent]

幅は次のようになる:

rbearing - lbearing

高さは次のようになる:

ascent + descent

隣の文字の原点は次のように定義される:

[x + width, y]

lbearing メンバは原点から文字が実際に描画される部分の左端までの大きさ を定義する。 rbearing メンバは原点から文字が実際に描画される部分の右端までの大きさ を定義する。 ascent メンバは原点から文字が実際に描画される部分の上端までの大きさを 定義する。 descent メンバは原点から文字が実際に描画される部分の下端までの大きさを 定義する。 width メンバは文字の論理的な幅を定義する。

返り値

要求されたリソースかサーバメモリの割り当てにサーバが失敗した。

引き数 Font か GContext の値が、定義されている Font を指していない。

指定したフォントや色の名前が存在しない。

関連項目
XCreateGC(3X11), XListFonts(3X11), XSetFontPath(3X11)
Xlib - C Language X Interface