31.19.2 テキストプロパティの変更

プロパティを変更するプリミティブは、バッファーや文字列内の指定されたテキスト範囲に適用されます。関数set-text-properties (セクションの最後を参照)は、その範囲内のテキストのプロパティリスト全体をセットします。名前を指定することにより特定のプロパティだけを追加、変更、削除するためにも有用です。

テキストプロパティはバッファー(か文字列)のコンテンツの一部とみなされ、かつスクリーン上でのバッファーの見栄えに影響を与えることができるので、バッファー内のテキストプロパティの変更はすべてバッファーを変更済みとマークします。バッファーテキストプロパティの変更もアンドゥできます(Undoを参照)。バッファー内の位置は1から始まりますが、文字列内の位置は0から始まります。

Function: put-text-property start end prop value &optional object

この関数は文字列かバッファーobject内のstartとendの間のテキストにたいして、プロパティpropにvalueをセットする。objectがnilならデフォルトはカレントバッファー。

Function: add-text-properties start end props &optional object

この関数は文字列かバッファーobject内のstartとendの間のテキストにたいして、テキストプロパティを追加またはオーバーライドする。objectがnilならデフォルトはカレントバッファー。

引数propsには追加するプロパティを指定する。これはプロパティリストの形式(Property Listsを参照)、つまりプロパティ名と対応する値が交互に出現するような要素を含むリストであること。

関数が実際に何らかのプロパティの値を変更したらt、それ以外( propsがnil、またはプロパティの値がテキスト内のプロパティの値と一致している場合)はnilがリターン値となる。

たとえば以下はテキストの範囲にcommentとfaceのプロパティをセットする例:

(add-text-properties start end
                     '(comment t face highlight))

Function: remove-text-properties start end props &optional object

この関数は文字列かバッファーobject内のstartとendの間のテキストから、指定されたテキストプロパティを削除する。objectがnilならデフォルトはカレントバッファー。

引数propsは削除するプロパティを指定する。これはプロパティリストの形式(Property Listsを参照)、つまりプロパティ名と対応する値が交互に出現するような要素を含むリストであること。しかし問題となるのは名前であって付随する値は無視される。たとえばfaceプロパティを削除するには以下のようにすればよい。

(remove-text-properties start end '(face nil))

関数が実際に何らかのプロパティの値を変更したらt、それ以外( propsがnil、または指定されたテキスト内にそれらのプロパティをもつ文字がない場合)はnilがリターン値となる。

特定のテキストからすべてのテキストプロパティを削除するには、新たなプロパティリストにnilを指定してset-text-propertiesを使用すればよい。

Function: remove-list-of-text-properties start end list-of-properties &optional object

remove-text-propertiesと同様だが、list-of-propertiesがプロパティ名と値が交互になったリストではなくプロパティ名だけのリストである点が異なる。

Function: set-text-properties start end props &optional object

この関数は文字列かバッファーobject内のstartからendの間のテキストにたいするテキストプロパティリストを完全に置き換える。objectがnilならデフォルトはカレントバッファー。

引数propsは新たなプロパティリスト。これはプロパティ名と対応する値が交互となるような要素のリストであること。

set-text-propertiesのリターン後には、指定された範囲内のすべての文字は等しいプロパティをもつ。

propsがnilなら、指定されたテキスト範囲からすべてのプロパティを取り除く効果がある。以下は例:

(set-text-properties start end nil)

この関数のリターン値を信用してはならない。

Function: add-face-text-property start end face &optional appendp object

この関数はstartとendの間のテキストのテキストプロパティfaceにフェイスfaceを追加するように動作する。faceはフェイス名、もしくはanonymousフェイス(anonymous face: 無名フェイス)のようなfaceプロパティ(Special Propertiesを参照)にたいして有効な値であること(Facesを参照)。

リージョン内の任意のテキストがすでに非nilのfaceプロパティをもつなら、それらのフェイスは保たれる。この関数はfaceプロパティに、最初の要素(デフォルト)がface、以前に存在していたフェイスが残りの要素であるようなフェイスのリストをセットする。オプション引数appendが非nilなら、faceはかわりにリストの最後に追加される。フェイスリスト内では各属性にたいして最初に出現する値が優先されることに注意。

たとえば以下のコードではstartとendの間のテキストにグリーン斜体のフェイスを割り当てるだろう:

(add-face-text-property start end 'italic)
(add-face-text-property start end '(:foreground "red"))
(add-face-text-property start end '(:foreground "green"))

オプション引数objectが非nilなら、それはカレントバッファーではなく動作するバッファーか文字列を指定する。objectが文字列ならstartとendは0基準で文字列内をインデックス付けする。

文字列にテキストプロパティを付するもっとも簡単な方法はpropertizeです:

Function: propertize string &rest properties

この関数はテキストプロパティpropertiesを追加したstringのコピーをリターンする。これらのプロパティはリターンされる文字列内のすべての文字に適用される。以下はfaceプロパティとmouse-faceプロパティとともに文字列を構築する例:

(propertize "foo" 'face 'italic
            'mouse-face 'bold-italic)
     ⇒ #("foo" 0 3 (mouse-face bold-italic face italic))

文字列のさまざまな部分に異なるプロパティをputするには、それぞれの部分をpropertizeで構築して、それらをconcatで結合すればよい:

(concat
 (propertize "foo" 'face 'italic
             'mouse-face 'bold-italic)
 " and "
 (propertize "bar" 'face 'italic
             'mouse-face 'bold-italic))
     ⇒ #("foo and bar"
                 0 3 (face italic mouse-face bold-italic)
                 3 8 nil
                 8 11 (face italic mouse-face bold-italic))

プロパティではなくバッファーからテキストをコピーする関数buffer-substring-no-propertiesについてはBuffer Contentsを参照してください。

バッファーを未変更のままバッファーにテキストプロパティの追加や削除を行いたければ、上記の呼出をwith-silent-modificationsで囲むことができます。