XQueryFont(3) フォントのロードとアンロード、フォント寸法構造体

Other Alias

XLoadFont, 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 か GContext ID を指定。
font_struct
フォントに対応する構造体を指定。
gc
GC を指定。
name
フォントの名前を指定。 これはNULLで終る文字列である。
value_return
フォントプロパティの値が返される。

説明

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

XLoadFont はエラー BadAlloc, BadName を起こすことがある。

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

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

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

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

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

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

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

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

構造体

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

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 は文字の範囲を定義する。

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

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

  • direction メンバは FontLeftToRightFontRightToLeft の値を持つ。 これは、 XCharStruct 要素の大部分が、正 (FontLeftToRight) あるいは負 (FontRightToLeft) の文字幅を持っていることを示す単なるヒントに過ぎない。 コアプロトコルでは縦書きテキストのサポートは定義されていない。
  • 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 が True の場合、per_char 配列内の全ての文字は 0 でないバウンディングボックス を持つ。
  • default_char メンバは、未定義の文字や存在しない文字を表示するときに用 いられる文字を指定する。 default_char は(2バイト文字ではなく)16ビット文字である。 2バイト行列形式を使うフォントの場合、default_char は byte1 を最上位バ イト、byte2 を最下位バイトとする。 default_char 自身が未定義あるいは存在しない文字を指定した場合には、未 定義あるいは存在しない文字の表示は行われない。
  • min_bounds と max_bounds メンバは、この配列の全ての要素それぞれ(存在し ない文字は除く)の XCharStruct 要素の最大値、最小値を持つ。 フォントのバウンディングボックス(全ての文字を同じ原点に置いて重ね合わ せ、得られた形状を囲む最少の長方形)の左上の座標は次のようになる:
         [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]にある文字について、 XCharStruct コンポーネントを用いて記述される、文字のバウンディングボックス(つまり 文字の形を囲む最小の長方形)は、次のようになる:

[x + lbearing, y - ascent]

幅は次のようになる:

rbearing - lbearing

高さは次のようになる:

ascent + descent

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

[x + width, y]

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

返り値

BadAlloc
要求されたリソースかサーバメモリの割り当てにサーバが失敗した。
BadFont
引き数 Font か GContext の値が、定義されている Font を指していない。
BadName
指定したフォントや色の名前が存在しない。