テキストプロパティを操作するための関数. [詳解]

型定義
typedef MPlist (	MTextPropSerializeFunc) (void *val)
	シリアライザ関数の型宣言.

typedef void (	MTextPropDeserializeFunc) (MPlist *plist)
	デシリアライザ関数の型宣言.

列挙型
enum	MTextPropertyControl { MTEXTPROP_FRONT_STICKY = 0x01 , MTEXTPROP_REAR_STICKY = 0x02 , MTEXTPROP_VOLATILE_WEAK = 0x04 , MTEXTPROP_VOLATILE_STRONG = 0x08 , MTEXTPROP_NO_MERGE = 0x10 , MTEXTPROP_CONTROL_MAX = 0x1F }
	テキストプロパティを制御するフラグビット. [詳解]

関数
void *	mtext_get_prop (MText *mt, int pos, MSymbol key)
	テキストプロパティの一番上の値を得る.

int	mtext_get_prop_values (MText mt, int pos, MSymbol key, void *values, int num)
	テキストプロパティの値を複数個得る.

int	mtext_get_prop_keys (MText mt, int pos, MSymbol *keys)
	M-text の指定した位置のテキストプロパティのキーのリストを得る.

int	mtext_put_prop (MText mt, int from, int to, MSymbol key, void val)

int	mtext_put_prop_values (MText mt, int from, int to, MSymbol key, void *values, int num)
	同じキーのテキストプロパティを複数設定する.

int	mtext_push_prop (MText mt, int from, int to, MSymbol key, void val)

int	mtext_pop_prop (MText *mt, int from, int to, MSymbol key)

int	mtext_prop_range (MText mt, MSymbol key, int pos, int from, int *to, int deeper)
	テキストプロパティが同じ値をとる範囲を調べる.

MTextProperty *	mtext_property (MSymbol key, void *val, int control_bits)
	テキストプロパティを生成する.

MText *	mtext_property_mtext (MTextProperty *prop)
	あるテキストプロパティを持つ M-text を返す.

MSymbol	mtext_property_key (MTextProperty *prop)
	テキストプロパティのキーを返す.

void *	mtext_property_value (MTextProperty *prop)
	テキストプロパティの値を返す.

int	mtext_property_start (MTextProperty *prop)
	テキストプロパティの開始位置を返す.

int	mtext_property_end (MTextProperty *prop)
	テキストプロパティの終了位置を返す.

MTextProperty *	mtext_get_property (MText *mt, int pos, MSymbol key)
	一番上のテキストプロパティを得る.

int	mtext_get_properties (MText mt, int pos, MSymbol key, MTextProperty *props, int num)
	複数のテキストプロパティを得る.

int	mtext_attach_property (MText mt, int from, int to, MTextProperty prop)
	M-textにテキストプロパティを付加する.

int	mtext_detach_property (MTextProperty *prop)
	M-text からテキストプロパティを分離する.

int	mtext_push_property (MText mt, int from, int to, MTextProperty prop)
	M-text にテキストプロパティをプッシュする.

MText *	mtext_serialize (MText mt, int from, int to, MPlist property_list)

MText *	mtext_deserialize (MText *mt)

変数
MSymbol	Mtext_prop_serializer
	シリアライザ関数を指定するシンボル.

MSymbol	Mtext_prop_deserializer
	デシリアライザ関数を指定するシンボル.

詳解

テキストプロパティを操作するための関数.

M-text 内の各文字は、テキストプロパティ と呼ばれるプロパティを持つことができる。テキストプロパティは、M-text の各部位に付加されたさまざまな情報を保持しており、アプリケーションプログラムはそれらの情報を統一的に扱うことができる。M-text 自体が豊富な情報を持つため、アプリケーションプログラム中の関数を簡素化することができる。

テキストプロパティはキーと値からなる。キーはシンボルであり、値は (void *) 型にキャストできるものなら何でもよい。他のタイプのプロパティと異なり、一つのテキストプロパティが複数の値を持つことが許される。「キーが K であるテキストプロパティ」のことを簡単に「K プロパティ」と呼ぶことがある。

型定義詳解

◆ MTextPropSerializeFunc

typedef MPlist *(* MTextPropSerializeFunc) (void *val)

シリアライザ関数の型宣言.

シリアライザ関数の型である。あるシンボルのプロパティのキーが Mtext_prop_serializer であるとき、値はこの型でなくてはならない。

参照:: mtext_serialize(), Mtext_prop_serializer

◆ MTextPropDeserializeFunc

typedef void *(* MTextPropDeserializeFunc) (MPlist *plist)

デシリアライザ関数の型宣言.

デシリアライザ関数の型である。あるシンボルのプロパティのキーが Mtext_prop_deserializer であるとき、値はこの型でなくてはならない。

参照:: Mtext_prop_deserialize(), Mtext_prop_deserializer

列挙型詳解

◆ MTextPropertyControl

enum MTextPropertyControl

テキストプロパティを制御するフラグビット.

関数 mtext_property() は以下のフラグビットの論理 OR を引数としてとることができる。フラグビットは生成されたテキストプロパティの振舞いを制御する。詳細は各フラグビットの説明を参照。

列挙値
MTEXTPROP_FRONT_STICKY	このビットが on ならば、このテキストプロパティの始まる点あるいは中間に挿入された M-text はこのテキストプロパティを継承する。
MTEXTPROP_REAR_STICKY	このビットが on ならば、このテキストプロパティの終わる点あるいは中間に挿入された M-text はこのテキストプロパティを継承する。
MTEXTPROP_VOLATILE_WEAK	このビットが on ならば、このテキストプロパティの範囲内のテキストが変更された場合テキストプロパティは取り除かれる。
MTEXTPROP_VOLATILE_STRONG	このビットが on ならば、このテキストプロパティの範囲内のテキストあるいは別のテキストプロパティが変更された場合このテキストプロパティは取り除かれる。
MTEXTPROP_NO_MERGE	このビットが on ならば、このテキストプロパティは他のプロパティと自動的にはマージされない。
MTEXTPROP_CONTROL_MAX

関数詳解

◆ mtext_get_prop()

void * mtext_get_prop	(	MText *	mt,
		int	pos,
		MSymbol	key
	)

テキストプロパティの一番上の値を得る.

関数 mtext_get_prop() は、M-text mt 内の位置 pos にある文字のテキストプロパティのうち、キーが key であるものを探す。

戻り値:: テキストプロパティがみつかれば、mtext_get_prop() はそのプロパティの値を返す。値が複数存在するときは、一番上の値を返す。見つからなければ外部変数 merror_code を変更することなく NULL を返す。

エラーが検出された場合 mtext_get_prop() は NULL を返し、外部変数 merror_code にエラーコードを設定する。

覚え書き: エラーなしで NULL が返された場合には二つの可能性がある。

pos の位置の文字は key をキーとするプロパティを持たない。

その文字はそのようなプロパティを持ち、その値が NULL である。

この二つを区別する必要がある場合には、関数 mtext_get_prop_values() を代わりに使用すること。

エラー:: MERROR_RANGE, MERROR_SYMBOL

参照:: mtext_get_prop_values(), mtext_put_prop(), mtext_put_prop_values(), mtext_push_prop(), mtext_pop_prop(), mtext_prop_range()

◆ mtext_get_prop_values()

int mtext_get_prop_values	(	MText *	mt,
		int	pos,
		MSymbol	key,
		void **	values,
		int	num
	)

テキストプロパティの値を複数個得る.

関数 mtext_get_prop_values() は、M-text mt 内で pos という位置にある文字のプロパティのうち、キーが key であるものを探す。もしそのようなプロパティが見つかれば、それが持つ値 (複数可) を values の指すメモリ領域に格納する。num は格納する値の数の上限である。

戻り値:: 処理が成功すれば、mtext_get_prop_values() は実際にメモリに格納された値の数を返す。pos の位置の文字が key をキーとするプロパティを持たなければ 0 を返す。エラーが検出された場合は -1 を返し、外部変数 merror_code にエラーコードを設定する。

エラー:: MERROR_RANGE, MERROR_SYMBOL

参照:: mtext_get_prop(), mtext_put_prop(), mtext_put_prop_values(), mtext_push_prop(), mtext_pop_prop(), mtext_prop_range()

◆ mtext_get_prop_keys()

int mtext_get_prop_keys	(	MText *	mt,
		int	pos,
		MSymbol **	keys
	)

M-text の指定した位置のテキストプロパティのキーのリストを得る.

関数 mtext_get_prop_keys() は、M-text mt 内で pos の位置にあるすべてのテキストプロパティのキーを要素とする配列を作り、その配列のアドレスを *keys に設定する。この配列のために確保されたメモリを解放するのはユーザの責任である。

戻り値:: 処理が成功すれば mtext_get_prop_keys() は得られたリストの長さを返す。そうでなければ -1 を返し、外部変数 merror_code にエラーコードを設定する。

エラー:: MERROR_RANGE

参照:: mtext_get_prop(), mtext_put_prop(), mtext_put_prop_values(), mtext_get_prop_values(), mtext_push_prop(), mtext_pop_prop()

◆ mtext_put_prop()

int mtext_put_prop	(	MText *	mt,
		int	from,
		int	to,
		MSymbol	key,
		void *	val
	)

@brief テキストプロパティを設定する.

関数 mtext_put_prop() は、M-text @b mt の @b from （含まれる）から 
@b to （含まれない）の範囲の文字に、キーが @b key で値が @b val であるよ
うなテキストプロパティを設定する。この関数によって

                         FROM                    TO
M-text:      |<------------|-------- MT ---------|------------>|
PROP:         <------------------ OLD_VAL -------------------->

は次のようになる。

                         FROM                    TO
M-text:       |<------------|-------- MT ---------|------------>|
PROP:          <-- OLD_VAL-><-------- VAL -------><-- OLD_VAL-->

@par 戻り値:
処理が成功すれば mtext_put_prop() は 0 を返す。そうでなければ -1 
を返し、外部変数 #merror_code にエラーコードを設定する。

@latexonly \IPAlabel{mtext_put_prop} @endlatexonly

@par エラー:
@c MERROR_RANGE, @c MERROR_SYMBOL

@par 参照:
mtext_put_prop_values(), mtext_get_prop(),
mtext_get_prop_values(), mtext_push_prop(),
mtext_pop_prop(), mtext_prop_range()

◆ mtext_put_prop_values()

int mtext_put_prop_values	(	MText *	mt,
		int	from,
		int	to,
		MSymbol	key,
		void **	values,
		int	num
	)

同じキーのテキストプロパティを複数設定する.

関数 mtext_put_prop_values() は、M-Text mt のfrom （含まれる）から to （含まれない）の範囲の文字に、テキストプロパティを設定する。テキストプロパティのキーは key によって、値(複数可)は values によって指定される。num は設定される値の個数である。

戻り値:: 処理が成功すれば、mtext_put_prop_values() は 0 を返す。そうでなければ -1 を返し、外部変数 merror_code にエラーコードを設定する。

エラー:: MERROR_RANGE, MERROR_SYMBOL

参照:: mtext_put_prop(), mtext_get_prop(), mtext_get_prop_values(), mtext_push_prop(), mtext_pop_prop(), mtext_prop_range()

◆ mtext_push_prop()

int mtext_push_prop	(	MText *	mt,
		int	from,
		int	to,
		MSymbol	key,
		void *	val
	)

@brief テキストプロパティをプッシュする.

関数 mtext_push_prop() は、キーが @b key で値が @b val であるテキスト
プロパティを、M-text @b mt 中の @b from （含まれる）から @b to （含まれな
い）の範囲の文字にプッシュする。この関数によって

                    FROM                    TO
M-text: |<------------|-------- MT ---------|------------>|
PROP  :  <------------------ OLD_VAL -------------------->

は次のようになる。

                    FROM                    TO
M-text: |<------------|-------- MT ---------|------------>|
PROP  :  <------------------- OLD_VAL ------------------->
PROP  :               <-------- VAL ------->

@par 戻り値:
処理が成功すれば、mtext_push_prop() は 0 を返す。そうでなければ 
-1 を返し、外部変数 #merror_code にエラーコードを設定する。

@latexonly \IPAlabel{mtext_push_prop} @endlatexonly

@par エラー:
@c MERROR_RANGE, @c MERROR_SYMBOL

@par 参照:
mtext_put_prop(), mtext_put_prop_values(),
mtext_get_prop(), mtext_get_prop_values(),
mtext_pop_prop(), mtext_prop_range()

◆ mtext_pop_prop()

int mtext_pop_prop	(	MText *	mt,
		int	from,
		int	to,
		MSymbol	key
	)

@brief テキストプロパティをポップする.

関数 mtext_pop_prop() は、キーが @b key であるテキストプロパティの
うち一番上のものを、M-text @b mt の @b from （含まれる）から @b to（含ま
れない）の範囲の文字から取り除く。

指定範囲の文字がそのようなプロパティを持たないならば、この関数は何
もしない。この関数によって、

                    FROM                    TO
M-text: |<------------|-------- MT ---------|------------>|
PROP  :  <------------------ OLD_VAL -------------------->

は以下のようになる。

                    FROM                    TO
M-text: |<------------|-------- MT ---------|------------>|
PROP  :  <--OLD_VAL-->|                     |<--OLD_VAL-->|

@par 戻り値:
処理が成功すれば、mtext_pop_prop() は 0 を返す。そうでなければ -1 
を返し、外部変数 #merror_code にエラーコードを設定する。

@latexonly \IPAlabel{mtext_pop_prop} @endlatexonly

@par エラー:
@c MERROR_RANGE, @c MERROR_SYMBOL

@par 参照:
mtext_put_prop(), mtext_put_prop_values(),
mtext_get_prop(), mtext_get_prop_values(),
mtext_push_prop(), mtext_prop_range()

◆ mtext_prop_range()

int mtext_prop_range	(	MText *	mt,
		MSymbol	key,
		int	pos,
		int *	from,
		int *	to,
		int	deeper
	)

テキストプロパティが同じ値をとる範囲を調べる.

関数 mtext_prop_range() は、指定したテキストプロパティの値が同じである連続した文字の範囲を調べる。まず M-text mt の pos の位置にある文字のプロパティのうち、キー key で指定されたもの値を見つける。そして前後の文字も key のプロパティの値が同じであるかどうかを調べる。見つけた範囲の最初と最後を、それぞれ from と to にポイントされる変数に保存する。from に保存される文字の位置は見つけた範囲に含まれるが、to は含まれない。（to の前で同じ値をとる範囲は終わる。）この範囲指定法は、関数 mtext_put_prop() などと共通である。

deeper が 0 でなければ、key というキーを持つプロパティのうち一番上のものだけでなく、スタック中のすべてのものが比較される。

from が NULL ならば、範囲の始まりは探索しない。to が NULL ならば、範囲の終りは探索しない。

戻り値:: 処理が成功すれば、mtext_prop_range() は key プロパティの値の数を返す。そうでなければ-1 を返し、外部変数 merror_code にエラーコードを設定する。

エラー:: MERROR_RANGE, MERROR_SYMBOL

参照:: mtext_put_prop(), mtext_put_prop_values(), mtext_get_prop(), mtext_get_prop_values(), mtext_pop_prop(), mtext_push_prop()

◆ mtext_property()

MTextProperty * mtext_property	(	MSymbol	key,
		void *	val,
		int	control_bits
	)

テキストプロパティを生成する.

関数 mtext_property() は key をキー、val を値とする新しく割り当てられたテキストプロパティを返す。生成したテキストプロパティはいかなる M-text にも付加されていない、すなわち分離して (detached) いる。

control_bits は 0 であるか enum MTextPropertyControl の論理 OR でなくてはならない。

◆ mtext_property_mtext()

MText * mtext_property_mtext ( MTextProperty * prop )

あるテキストプロパティを持つ M-text を返す.

関数 mtext_property_mtext() は、テキストプロパティprop が付加されている M-text を返す。その時点で prop が分離していれば NULL を返す。

◆ mtext_property_key()

MSymbol mtext_property_key ( MTextProperty * prop )

テキストプロパティのキーを返す.

関数 mtext_property_key() は、テキストプロパティ prop のキー（シンボル）を返す。

◆ mtext_property_value()

void * mtext_property_value ( MTextProperty * prop )

テキストプロパティの値を返す.

関数 mtext_property_value() は、テキストプロパティ prop の値を返す。

◆ mtext_property_start()

int mtext_property_start ( MTextProperty * prop )

テキストプロパティの開始位置を返す.

関数 mtext_property_start() は、テキストプロパティ prop の開始位置を返す。開始位置とは M-text 中で prop が始まる文字位置である。 prop が分離されていれば、-1 を返す。

◆ mtext_property_end()

int mtext_property_end ( MTextProperty * prop )

テキストプロパティの終了位置を返す.

関数 mtext_property_end() は、テキストプロパティ prop の終了位置を返す。終了位置とは M-text 中で prop が終る文字位置である。prop が分離されていれば、-1 を返す。

◆ mtext_get_property()

MTextProperty * mtext_get_property	(	MText *	mt,
		int	pos,
		MSymbol	key
	)

一番上のテキストプロパティを得る.

関数 mtext_get_property() は M-text mt の位置 pos の文字がキーが key であるテキストプロパティを持つかどうかを調べる。

戻り値:: テキストプロパティが見つかれば、mtext_get_property() はそれを返す。複数ある場合には、一番上のものを返す。見つからなければ、外部変数 merror_code を変えることなく NULL を返す。

エラーが検出された場合 mtext_get_property() は NULL を返し、外部変数 merror_code にエラーコードを設定する。

◆ mtext_get_properties()

int mtext_get_properties	(	MText *	mt,
		int	pos,
		MSymbol	key,
		MTextProperty **	props,
		int	num
	)

複数のテキストプロパティを得る.

関数 mtext_get_properties() は M-text mt の位置 pos の文字がキーが key であるテキストプロパティを持つかどうかを調べる。そのようなプロパティがみつかれば、props が指すメモリ領域に保存する。num は保存されるプロパティの数の上限である。

戻り値:: 処理が成功すれば、mtext_get_properties() は実際に保存したプロパティの数を返す。pos の位置の文字がキーが key であるプロパティを持たなければ、0 が返る。エラーが検出された場合には、 mtext_get_properties() は -1 を返し、外部変数 merror_code にエラーコードを設定する。

◆ mtext_attach_property()

int mtext_attach_property	(	MText *	mt,
		int	from,
		int	to,
		MTextProperty *	prop
	)

M-textにテキストプロパティを付加する.

関数 mtext_attach_property() は、M-text mt の from から to までの領域にテキストプロパティ prop を付加する。もし prop が既に M-text に付加されていれば、mt に付加する前に分離される。

戻り値:: 処理に成功すれば、mtext_attach_property() は 0 を返す。そうでなければ -1 を返して外部変数::merror_code にエラーコードを設定する。

◆ mtext_detach_property()

int mtext_detach_property ( MTextProperty * prop )

M-text からテキストプロパティを分離する.

関数 mtext_detach_property() はテキストプロパティ prop を分離する。

戻り値:: この関数は常に 0 を返す。

◆ mtext_push_property()

int mtext_push_property	(	MText *	mt,
		int	from,
		int	to,
		MTextProperty *	prop
	)

M-text にテキストプロパティをプッシュする.

関数 mtext_push_property() は、テキストプロパティ prop を、 M-text mt 中の from （含まれる）から to （含まれない）の範囲の文字にプッシュする。

戻り値:: 処理に成功すれば、mtext_push_property() は 0 を返す。そうでなければ -1 を返して外部変数::merror_code にエラーコードを設定する。

◆ mtext_serialize()

MText * mtext_serialize	(	MText *	mt,
		int	from,
		int	to,
		MPlist *	property_list
	)

@brief M-text 中のテキストプロパティをシリアライズする.

関数 mtext_serialize() は M-text @b mt の @b from から @b to までのテキ
ストをシリアライズする。シリアライズした結果は XML 形式の M-text で
ある。 @b property_list はシリアライズされるテキストプロパティを限定
する。対象となるテキストプロパティは、そのキーが

@li @b property_list の要素の値として現われ、かつ
@li シンボルプロパティ #Mtext_prop_serializer を持つ

もののみである。この条件を満たすテキストプロパティは、生成される 
XML 表現中で "property" 要素にシリアライズされる。

生成される XML の DTD は以下の通り:

<!DOCTYPE mtext [
  <!ELEMENT mtext (property*,body+)>
  <!ELEMENT property EMPTY>
  <!ELEMENT body (#PCDATA)>
  <!ATTLIST property key CDATA #REQUIRED>
  <!ATTLIST property value CDATA #REQUIRED>
  <!ATTLIST property from CDATA #REQUIRED>
  <!ATTLIST property to CDATA #REQUIRED>
  <!ATTLIST property control CDATA #REQUIRED>
 ]>

この関数は libxml2 ライブラリに依存する。m17n ライブラリがlibxml2 
無しに設定されている場合、この関数は常に失敗する。

@par 戻り値: 
処理に成功すれば、mtext_serialize() は XML 形式で M-text を返す。
そうでなければ @c NULL を返して外部変数#merror_code にエラーコード
を設定する。

@par 参照:
mtext_deserialize(), #Mtext_prop_serializer

◆ mtext_deserialize()

MText * mtext_deserialize ( MText * mt )

@brief M-text 中のテキストプロパティをデシリアライズする.

関数 mtext_deserialize() は M-text @b mt をデシリアライズする。@b mt
は次の DTD を持つ XML でなくてはならない。

<!DOCTYPE mtext [
  <!ELEMENT mtext (property*,body+)>
  <!ELEMENT property EMPTY>
  <!ELEMENT body (#PCDATA)>
  <!ATTLIST property key CDATA #REQUIRED>
  <!ATTLIST property value CDATA #REQUIRED>
  <!ATTLIST property from CDATA #REQUIRED>
  <!ATTLIST property to CDATA #REQUIRED>
  <!ATTLIST property control CDATA #REQUIRED>
 ]>

この関数は libxml2 ライブラリに依存する。m17n ライブラリがlibxml2 
無しに設定されている場合、この関数は常に失敗する。

@par 戻り値: 
処理に成功すれば、mtext_serialize() は得られた M-text を
返す。そうでなければ @c NULL を返して外部変数 #merror_code にエラー
コードを設定する。

@par 参照:
mtext_serialize(), #Mtext_prop_deserializer

変数詳解

◆ Mtext_prop_serializer

MSymbol Mtext_prop_serializer

シリアライザ関数を指定するシンボル.

テキストプロパティをシリアライズするためには、そのテキストプロパティ用のシリアライザ関数を与えなくてはならない。具体的には、 Mtext_prop_serializer をキーとし、適切なシリアライズ関数へのポインタを値とするシンボルプロパティを指定する。

参照:: mtext_serialize(), MTextPropSerializeFunc

◆ Mtext_prop_deserializer

MSymbol Mtext_prop_deserializer

デシリアライザ関数を指定するシンボル.

テキストプロパティをデシリアライズするためには、そのテキストプロパティ用のデシリアライザ関数を与えなくてはならない。具体的には、 Mtext_prop_deserializer をキーとし、適切なデシリアライズ関数へのポインタを値とするシンボルプロパティを指定する。

参照:: mtext_deserialize(), MTextPropSerializeFunc