39.9.1 オーバーレイの管理

このセクションではオーバーレイの作成、削除、移動、およびそれらのコンテンツを調べる関数を説明します。オーバーレイはバッファーのコンテンツの一部ではないので、その変更はバッファーのundoリストに記録されません。

Function: overlayp object

この関数はobjectがオーバーレイならtをリターンする。

Function: make-overlay start end &optional buffer front-advance rear-advance

この関数はbufferに属する、startからendの範囲のオーバーレイを作成してリターンする。startとendはいずれもバッファーの位置を指定しなければならず、整数かマーカーを指定できる。bufferが省略されると、そのオーバーレイはカレントバッファーに作成される。

startとendが同一のバッファー位置を指定するオーバーレイは空(empty)のオーバーレイとして知られる。startとendの間のテキストが削除されれば、非空のオーバーレイも空になり得る。これが発生したとき、デフォルトではオーバーレイは削除されないが、‘evaporate’プロパティを与えることにより削除されるようにできる(evaporate propertyを参照)。

引数front-advanceとrear-advanceはそれぞれオーバーレイの開始と終了にたいするマーカーの挿入タイプを指定する。Marker Insertion Typesを参照のこと。どちらもnil (デフォルト)なら、そのオーバーレイは先頭に挿入された任意のテキストを含むように拡張されるが、終端に挿入されたテキストにたいしては拡張されない。front-advanceが非nilなら、オーバーレイの先頭に挿入されたテキストはオーバーレイから除外される。rear-advanceが非nilなら、オーバーレイの終端に挿入されたテキストはオーバーレイに含まれる。

Function: overlay-start overlay

この関数はoverlayが開始する位置を整数でリターンする。

Function: overlay-end overlay

この関数はoverlayが終了する位置を整数でリターンする。

Function: overlay-buffer overlay

この関数はoverlayが所属するバッファーをリターンする。overlayが削除されていたらnilをリターンする。

Function: delete-overlay overlay

この関数はoverlayを削除する。そのオーバーレイはLispオブジェクトとして存在し続けて、そのプロパティリストは変更されないがバッファーへの所属と表示にたいするすべての効果を失う。

削除済みオーバーレイが永続的に非接続という訳ではない。move-overlayを呼び出すことによりバッファー内の位置を与えることができる。

Function: move-overlay overlay start end &optional buffer

この関数はoverlayをbufferに移動して、その境界をstartとendに配置する。startとendの引数はいずれもバッファーの位置を指定しなければならず、整数かマーカーを指定できる。

bufferが省略された場合、overlayはすでに関連付けられている同じバッファーに留まる。さらにoverlayが削除されていたら、それをカレントバッファーに所属させる。

リターン値はoverlay。

これはオーバーレイの両端位置を変更する唯一の有効な方法である。手作業でオーバーレイ内のマーカーの変更を試みてはならない。それにより他の重要なデータ構造の更新が失敗して、いくつかのオーバーレイが失われる可能性がある。

Function: remove-overlays &optional start end name value

この関数はプロパティnameが値valueをもつような、startとendの間のすべてのオーバーレイを削除する。これによりオーバーレイの両端位置が変更されたり分割される可能がある。

nameが省略かnilなら、それは指定されたリージョン内のすべてのオーバーレイを削除することを意味する。startおよび/またはendが省略かnilなら、それぞれバッファーの先頭と終端を意味する。したがって(remove-overlays)はカレントバッファー内のすべてのオーバーレイを削除する。

Function: copy-overlay overlay

この関数はoverlayのコピーをリターンする。このコピーはoverlayと同じ両端位置とプロパティをもつ。しかしオーバーレイの開始と終了にたいするマーカー挿入タイプはデフォルト値にセットされる(Marker Insertion Typesを参照)。

以下にいくつか例を示します:

;; オーバーレイの作成
(setq foo (make-overlay 1 10))
     ⇒ #<overlay from 1 to 10 in display-ja.texi>
(overlay-start foo)
     ⇒ 1
(overlay-end foo)
     ⇒ 10
(overlay-buffer foo)
     ⇒ #<buffer display-ja.texi>
;; 後でチェックできるようプロパティ付与
(overlay-put foo 'happy t)
     ⇒ t
;; プロパティが付与されたか検証
(overlay-get foo 'happy)
     ⇒ t
;; オーバーレイを移動
(move-overlay foo 5 20)
     ⇒ #<overlay from 5 to 20 in display-ja.texi>
(overlay-start foo)
     ⇒ 5
(overlay-end foo)
     ⇒ 20
;; オーバーレイを削除
(delete-overlay foo)
     ⇒ nil
;; 削除されたか検証
foo
     ⇒ #<overlay in no buffer>
;; 削除済みオーバーレイは位置をもたない
(overlay-start foo)
     ⇒ nil
(overlay-end foo)
     ⇒ nil
(overlay-buffer foo)
     ⇒ nil
;; オーバーレイの削除取り消し
(move-overlay foo 1 20)
     ⇒ #<overlay from 1 to 20 in display-ja.texi>
;; 結果の検証
(overlay-start foo)
     ⇒ 1
(overlay-end foo)
     ⇒ 20
(overlay-buffer foo)
     ⇒ #<buffer display-ja.texi>
;; オーバーレイの移動と削除では、オーバーレイのプロパティは変更されない
(overlay-get foo 'happy)
     ⇒ t

Emacsはそれぞれのバッファーのオーバーレイを任意の中心位置(center position)で分割される2つのリストに格納します。一方のリストはバッファーの中心位置から後方に拡張されて、もう一方は中心位置から前方へと拡張されます。中心位置はバッファーの任意の位置をとることができます。

Function: overlay-recenter pos

この関数はカレントバッファーのオーバーレイを位置posの周辺に再センタリングする。これにより位置pos近傍のオーバーレイの照合は高速になるが、posから離れた位置にたいしては低速になる。

バッファーを前方にスキャンしてオーバーレイを作成するループは、最初に(overlay-recenter (point-max))を行うことにより高速になる可能性があります。