表示

M-text をウィンドウに描画する. [詳解]

データ構造
struct	MDrawControl
	テキスト表示制御の型宣言. [詳解]
struct	MDrawMetric
	グリフとテキストの寸法の型宣言. [詳解]
struct	MDrawGlyphInfo
	グリフに関する情報の型宣言. [詳解]
struct	MDrawGlyph
	グリフの寸法とフォントに関する情報の型宣言. [詳解]

型定義
typedef void *	MDrawWindow
	ウィンドウシステムに依存する、ウィンドウの型宣言.
typedef void *	MDrawRegion
	ウィンドウシステムに依存する、領域の型宣言.

関数
int	mdraw_text (MFrame *frame, MDrawWindow win, int x, int y, MText *mt, int from, int to)
	ウィンドウに M-text を描画する.
int	mdraw_image_text (MFrame *frame, MDrawWindow win, int x, int y, MText *mt, int from, int to)
	ディスプレイにM-text を画像として描く.
int	mdraw_text_with_control (MFrame *frame, MDrawWindow win, int x, int y, MText *mt, int from, int to, MDrawControl *control)
	ディスプレイにM-text を詳細な制御つきで描く.
int	mdraw_text_extents (MFrame *frame, MText *mt, int from, int to, MDrawControl *control, MDrawMetric *overall_ink_return, MDrawMetric *overall_logical_return, MDrawMetric *overall_line_return)
	テキストの幅（ピクセル単位）を計算する.
int	mdraw_text_per_char_extents (MFrame *frame, MText *mt, int from, int to, MDrawControl *control, MDrawMetric *ink_array_return, MDrawMetric *logical_array_return, int array_size, int *num_chars_return, MDrawMetric *overall_ink_return, MDrawMetric *overall_logical_return)
	M-text の各文字の表示範囲を計算する.
int	mdraw_coordinates_position (MFrame *frame, MText *mt, int from, int to, int x_offset, int y_offset, MDrawControl *control)
	指定した座標に最も近い文字の文字位置を得る.
int	mdraw_glyph_info (MFrame *frame, MText *mt, int from, int pos, MDrawControl *control, MDrawGlyphInfo *info)
	グリフに関する情報を計算する.
int	mdraw_glyph_list (MFrame *frame, MText *mt, int from, int to, MDrawControl *control, MDrawGlyph *glyphs, int array_size, int *num_glyphs_return)
	グリフ列に関する情報を計算する.
void	mdraw_text_items (MFrame *frame, MDrawWindow win, int x, int y, MDrawTextItem *items, int nitems)
	textitem を表示する.
int	mdraw_default_line_break (MText *mt, int pos, int from, int to, int line, int y)
	改行位置を計算する.
void	mdraw_per_char_extents (MFrame *frame, MText *mt, MDrawMetric *array_return, MDrawMetric *overall_return)
	M-text の文字毎の表示範囲情報を得る.
void	mdraw_clear_cache (MText *mt)
	キャッシュ情報を消す.

変数
int	mdraw_line_break_option

詳解

M-text をウィンドウに描画する.

m17n-gui API には、M-text を表示するための関数が用意されている。

表示に用いられるフォントは、フォントセットと face のプロパティに基づいて自動的に決定される。また、フォントのサイズや色や下線などの見栄えも face によって決まる。

M-text の描画フォーマットは多様な方法で制御できるので、強力な二次元レイアウト機能が実現できる。

型定義詳解

MDrawWindow

typedef void* MDrawWindow

ウィンドウシステムに依存する、ウィンドウの型宣言.

MDrawWindow はウィンドウ、すなわち幾つかの点でスクリーンのミニチュアとして働く矩形領域用の型である。

実際に何を指すかはウィンドウシステムに依存する。 m17n X ライブラリを利用するプログラムは Drawable 型をこの型に変換しなくてはならない。

MDrawRegion

typedef void* MDrawRegion

ウィンドウシステムに依存する、領域の型宣言.

MDrawRegion は領域、すなわちスクリーン上の任意のピクセルの集合（典型的には矩形領域）用の型である。

実際に何を指すかはウィンドウシステムに依存する。 m17n X ライブラリを利用するプログラムは Region 型をこの型に変換しなくてはならない。

関数詳解

mdraw_text()

int mdraw_text	(	MFrame *	frame,
		MDrawWindow	win,
		int	x,
		int	y,
		MText *	mt,
		int	from,
		int	to
	)

ウィンドウに M-text を描画する.

関数 mdraw_text() は、フレーム frame のウィンドウ win の座標 (x, y) に、M-text mt の from から to までのテキストを描画する。

テキストの見栄え（フォント、スタイル、色など）は、キーが Mface であるテキストプロパティの値によって決まる。M-text の一部あるいは全部にそのようなテキストプロパティが付いていない場合には、frame のデフォルトフェースを代わりに用いる。

M-text の各文字を表示するフォントは、フェースの fontset プロパティの値のうちから、以下のアルゴリズムで選ばれる。

1. その文字のテキストプロパティのうち、キーが Mcharset であるものの値を調べる。この値は文字セットを表わすシンボルか Mnil のどちらかである。::Mnil ならば、次のステップに進む。 そうでなければ、fontset のマッピングテーブルにその文字セット用のフォントがあるかどうかを調べる。 無ければ、次のステップに進む。

   その文字セット用のフォントがみつかれば、それらのうち現在の文字用のグリフを持ち、フェースの各プロパティに最もよく合致するものを使う。
   

   そのようなフォントが無ければ次のステップに進む。

2. その文字の文字プロパティ "script" （スクリプト）を調べる。 そのプロパティが継承されているならばそれ以前の文字の文字プロパティ "script" を調べる。前の文字がなかったり、その文字プロパティを持っていなかった場合には、次のステップに進む。

   その文字のテキストプロパティのうち、キーが @c Mlanguage であるものの値を調べる。
   

   この値は言語を表わすシンボルか Mnil のいずれかである。

   その言語とスクリプトの組み合わせが fontset のマッピングテーブルにあるかどうかを調べる。見つからなければ次のステップに進む。

   見つかったばあいには、それらのフォントのうち現在の文字用のグリフを持ち、フェースの各プロパティに最もよく合致しているものを使う。 そのようなフォントが無ければ次のステップに進む。

3. その文字のグリフを持つフォントを、フォントセットの fall-back テーブルから探す。フォントが見つかればそれを使う。

以上のアルゴリズムでフォントが見つからなければ、この関数はその文字として空の四角形を表示する。

この関数が描画するのはグリフの前景だけである。背景色を指定するには、関数 mdraw_image_text() か関数 mdraw_text_with_control() を使うこと。

この関数は、X ウィンドウにおける関数 XDrawString(), XmbDrawString(), XwcDrawString() に相当する。

戻り値:

処理が成功した場合、mdraw_text() は 0 返す。エラーが検出された場合は -1 を返し、外部変数 merror_code にエラーコードを設定する。

エラー:

MERROR_RANGE

参照:

mdraw_image_text()

mdraw_image_text()

int mdraw_image_text	(	MFrame *	frame,
		MDrawWindow	win,
		int	x,
		int	y,
		MText *	mt,
		int	from,
		int	to
	)

ディスプレイにM-text を画像として描く.

関数 mdraw_image_text() は、フレーム frame のウィンドウ win の座標 (x, y) に、M-text mt の from から to までのテキストを画像として描く。

テキストの描画方法は mdraw_text() とほぼ同じであるが、この関数ではフェースで指定された色で背景も描く点が異なっている。

この関数は、X ウィンドウにおける XDrawImageString(), XmbDrawImageString(), XwcDrawImageString() に相当する。

戻り値:

処理が成功した場合、mdraw_image_text() は 0 を返す。エラーが検出された場合は -1 を返し、外部変数 merror_code にエラーコードを設定する。

エラー:

MERROR_RANGE

参照:

mdraw_text()

mdraw_text_with_control()

int mdraw_text_with_control	(	MFrame *	frame,
		MDrawWindow	win,
		int	x,
		int	y,
		MText *	mt,
		int	from,
		int	to,
		MDrawControl *	control
	)

ディスプレイにM-text を詳細な制御つきで描く.

関数 mdraw_text_with_control() は、フレーム frame のウィンドウ win の座標 (x, y) に、M-text mt の from から to までのテキス トを描く。

テキストの描画方法は mdraw_text() とほぼ同じであるが、この関数は描画制御用のオブジェクト control の指示にも従う点が異なっている。

たとえば control の <two_dimensional> がゼロでなければ、この関数は M-text を2次元的に描く。すなわち M-text 中の改行で行を改め、続く文字は次の行に描く。詳細は構造体 @ MDrawControl の説明を参照すること。

mdraw_text_extents()

int mdraw_text_extents	(	MFrame *	frame,
		MText *	mt,
		int	from,
		int	to,
		MDrawControl *	control,
		MDrawMetric *	overall_ink_return,
		MDrawMetric *	overall_logical_return,
		MDrawMetric *	overall_line_return
	)

テキストの幅（ピクセル単位）を計算する.

関数 mdraw_text_extents() は、関数 mdraw_text_with_control() が描画制御オブジェクト control を用いて M-text mt の from から to までをフレーム frame に表示する際に必要となる幅を返す。

overall_ink_return が NULL でなければ、この関数は M-text の文字のインクのバウンディングボックスも計算し、overall_ink_return が指す構造体のメンバにその結果を設定する。M-text に囲み枠 (surrounding box) を指定するフェースがあれば、それもバウンディングボックスに含む。

overall_logical_return が NULL でなければ、この関数は M-text と他の graphical feature （囲み枠など） との間の最小のスペースを示すバウンディングボックスも計算し、overall_logical_return が指す構造体のメンバにその結果を設定する。

overall_line_return が NULL でなければ、この関数は他の M-text との間の最小のスペースを示すバウンディングボックスも計算し、 overall_line_return が指す構造体のメンバにその結果を設定する。オブジェクト control のメンバ min_line_ascent, min_line_descent, max_line_ascent, max_line_descent がすべて0の時には、この値は overall_ink_return とoverall_logical_return の和となる。

戻り値:

この関数は表示に必要なテキストの幅をピクセル単位で返す。control->two_dimensional が0でなく、テキストが複数の行に渡って描かれる場合には、最大の幅を返す。エラーが生じた場合は -1 を返し、外部変数 merror_code にエラーコードを設定する。

エラー:

MERROR_RANGE

mdraw_text_per_char_extents()

int mdraw_text_per_char_extents	(	MFrame *	frame,
		MText *	mt,
		int	from,
		int	to,
		MDrawControl *	control,
		MDrawMetric *	ink_array_return,
		MDrawMetric *	logical_array_return,
		int	array_size,
		int *	num_chars_return,
		MDrawMetric *	overall_ink_return,
		MDrawMetric *	overall_logical_return
	)

M-text の各文字の表示範囲を計算する.

関数 mdraw_text_per_char_extents() は、関数 mdraw_text_with_control() が描画制御オブジェクト control を用いて M-text mt の from から to までをフレーム frame に表示する際の各文字のサイズを計算する。

array_size によって ink_array_return とlogical_array_return のサイズを指定する。ink_array_return とlogical_array_return の各要素は、それぞれ文字の描画インクと論理サイズ（M-text の表示原点からの相対位値）によって順に埋められる。設定された ink_array_return と logical_array_return の要素の数は、num_chars_return に戻される。

array_size がすべての寸法を戻せないほど小さい場合には、関数は -1 を返し、必要な大きさを num_chars_return に返す。そうでなければ 0 を返す。

ポインタ overall_ink_return と overall_logical_return がNULL でなければ、この関数はテキスト全体のサイズも計算し、結果を overall_ink_return と overall_logical_return で指される構造のメンバに保存する。

control->two_dimensional が0でなければ、この関数は最初の行の文字のサイズだけを計算する。

mdraw_coordinates_position()

int mdraw_coordinates_position	(	MFrame *	frame,
		MText *	mt,
		int	from,
		int	to,
		int	x_offset,
		int	y_offset,
		MDrawControl *	control
	)

指定した座標に最も近い文字の文字位置を得る.

関数 mdraw_coordinates_position() は、関数 mdraw_text_with_control() が描画制御オブジェクト control を用いて、 M-text mt の from から to までを座標 (0, 0) を起点として描画する際に、座標 (x, y) に描画される文字の文字位置を返す。ここで文字位置とは、当該 M-text 中においてその文字が最初から何番目かを示す整数である。ただし最初の文字の文字位置は0とする。

frame はデフォルトのフェースの情報を得るためだけに用いられる。

戻り値:

座標 (x, y) がある文字のグリフで覆われる場合、 関数 mdraw_coordinates_position() はその文字の文字位置を返す。

もし y が描画領域の最小Y座標よりも小さいならば from を返す。

もし y が描画領域の最大Y座標よりも大きいならば to を返す。

もし y が描画領域に乗っていてかつ x が描画領域の最小X座標よりも 小さい場合は、直線 y = y 上に描画される最初の文字の文字位置を返す。

もし y が描画領域に乗っていてかつ x が描画領域の最大X座標よりも 大きい場合は、直線 y = y 上に描画される最後の文字の文字位置を返す。

mdraw_glyph_info()

int mdraw_glyph_info	(	MFrame *	frame,
		MText *	mt,
		int	from,
		int	pos,
		MDrawControl *	control,
		MDrawGlyphInfo *	info
	)

グリフに関する情報を計算する.

関数 mdraw_glyph_info() は、関数 mdraw_text_with_control() が描 画制御オブジェクト control を用いてM-text mt の from から to までをフレーム frame に描画した場合、M-text の文字位置 pos の文字を覆うグリフに関する情報を計算する。

情報はinfo のメンバに保持される。

参照:

MDrawGlyphInfo

mdraw_glyph_list()

int mdraw_glyph_list	(	MFrame *	frame,
		MText *	mt,
		int	from,
		int	to,
		MDrawControl *	control,
		MDrawGlyph *	glyphs,
		int	array_size,
		int *	num_glyphs_return
	)

グリフ列に関する情報を計算する.

関数 mdraw_glyph_list() は、関数 mdraw_text_with_control() が描画制御オブジェクト control を用いてM-text mt の from から to までをフレーム frame に描画した場合の、各グリフの情報を glyphs が指す配列に格納する。 array_size はその配列のサイズである。

もし array_size がすべてのグリフについての情報を格納するのに十分であれば、 num_glyphs_return が指す場所に実際に埋めた要素の数を設定し 0 を返す。

そうでなければ、num_glyphs_return が指す場所に必要な配列のサイズを設定し、 -1 を返す。

参照:

MDrawGlyph

mdraw_text_items()

void mdraw_text_items	(	MFrame *	frame,
		MDrawWindow	win,
		int	x,
		int	y,
		MDrawTextItem *	items,
		int	nitems
	)

textitem を表示する.

関数 mdraw_text_items() は、一個以上のテキストアイテムを、フレーム frame のウィンドウ win の座標 (x, y) に表示する。items は表示すべきテキストアイテムの配列であり、nitems はその個数である。

参照:

MTextItem, mdraw_text().

mdraw_default_line_break()

int mdraw_default_line_break	(	MText *	mt,
		int	pos,
		int	from,
		int	to,
		int	line,
		int	y
	)

改行位置を計算する.

関数 mdraw_default_line_break() は、行が最大幅中に収まらない場合の改行位置を、行番号 line と座標 y に基づいて計算する。 pos は最大幅に収まる最後の文字の次の文字の位置である。 from はその行の最初の文字の位置、to は最大幅が指定されていなければその行に表示される最後の文字の位置である。 line と y は改行文字によって行が改まった際には 0 にリセットされ、最大幅によって行が改まった場合には 1 づつ増やされる。

戻り値:

この関数は改行する文字位置を返す。

mdraw_per_char_extents()

void mdraw_per_char_extents	(	MFrame *	frame,
		MText *	mt,
		MDrawMetric *	array_return,
		MDrawMetric *	overall_return
	)

M-text の文字毎の表示範囲情報を得る.

関数 mdraw_per_char_extents() は、M-text mt 中の各文字の表示範囲を計算する。この計算に用いるフォントは、 mt のテキストプロパティで指定されたフェースと、フレーム frame のデフォルトフェースによって決まる。array_return の各要素は、mt 中の各文字の表示範囲情報によって順に埋められる。表示範囲情報とは、 表示原点からの相対位置と各文字の占める長方形である。array_return の要素数は、M-text 中の文字数以上でなければならない。

ポインタ overall_return が NULL でない場合は、テキスト全体の表示範囲情報も計算し、その結果を overall_return の指す構造体に格納する。

mdraw_clear_cache()

void mdraw_clear_cache

(

MText *

mt

)

キャッシュ情報を消す.

関数 mdraw_clear_cache() は描画関数によって M-text mt に付加されたキャッシュ情報をすべて消去する。MDrawControl の ‘format’ あるいは ‘line_break’ メンバ関数の振舞いが変わった場合にはキャッシュを消去しなくてはならない。

参照:

MDrawControl

変数詳解

mdraw_line_break_option

int mdraw_line_break_option