GNU Emacs 32.0.50 (9008bf64c3) のマニュアルを PLaMo 翻訳で機械翻訳したものです。誤訳を含むことがあります。原文: https://www.gnu.org/software/emacs/manual/html_node/elisp/Buffer-Display-Action-Functions.html ・ emacs-doc.conao3.com

29.15.2 バッファ表示用のアクション関数

アクション関数とは、バッファを表示するためのウィンドウを選択するために display-buffer が呼び出す関数のことです。アクション関数は、表示するバッファである buffer と、アクションアリストである alist の2つの引数を取ります(バッファ表示用のアクションアリスト を参照)。これらの関数は、成功した場合は buffer を、失敗した場合は nil を表示するウィンドウを返すことになっています。

Emacsでは、以下の基本的なアクション関数が定義されています。

関数: display-buffer-same-window buffer alist

この関数は、選択中のウィンドウに buffer を表示しようとします。選択中のウィンドウがミニバッファウィンドウであるか、あるいは別のバッファ専用である場合は失敗します(専用ウィンドウを参照)。また、alist に nil 以外の inhibit-same-window エントリがある場合も失敗します。

関数: display-buffer-reuse-window buffer alist

この関数は、すでに buffer を表示しているウィンドウを探し出して、それを表示しようとします。他のフレームのウィンドウよりも、選択したフレーム上のウィンドウが優先されます。

alist に nil inhibit-same-window 以外のエントリがある場合、選択されたウィンドウは再利用の対象外となります。buffer が既に表示されているウィンドウを検索するためのフレーム集合は、reusable-frames アクションアリストのエントリを用いて指定できます。alist に reusable-frames エントリが含まれていない場合、この関数は選択されたフレームのみを検索します。

この関数が別のフレーム上のウィンドウを選択した場合、そのフレームを表示し、alist に inhibit-switch-frame エントリが含まれていない限り、必要に応じてそのフレームを最前面に表示します。

alist に nil 以外の reuse-indirect エントリがあり、かつ buffer を表示しているウィンドウが見つからない場合、この関数は buffer に間接的に関連するウィンドウ――そのウィンドウと buffer を引数とする window-indirect-buffer-p(バッファとウィンドウ を参照)が nil 以外を返すようなウィンドウ――を探そうとします。そのようなウィンドウが見つかり、かつ reuse-indirect エントリの CDR がシンボル buffer と等しい場合、そのウィンドウのバッファを buffer で置き換えることはせず、元のバッファを保持したままそのウィンドウを返します。それ以外の場合は、そのウィンドウに buffer を格納し、そのウィンドウを返します。

関数: display-buffer-reuse-mode-window buffer alist

この関数は、指定されたモードでバッファを表示しているウィンドウを探し、bufferを表示しようとします。

alist に mode エントリが含まれている場合、その値はメジャーモード(シンボル)またはメジャーモードのリストを指定します。alist に mode エントリが含まれていない場合は、代わりに buffer の現在のメジャーモードが使用されます。ウィンドウが、このように指定されたモードのいずれかに由来するモードを持つバッファを表示している場合、そのウィンドウは候補となります。

この挙動は、display-buffer-reuse-windowと同様に、inhibit-same-window、reusable-frames、inhibit-switch-frameに対するalistエントリによっても制御されます。

関数: display-buffer-pop-up-window buffer alist

この関数は、最も大きい、あるいは直近で使用されていないウィンドウ(通常は選択中のフレームにあるもの)を分割することで、buffer を表示しようとします。実際には、split-window-preferred-function で指定された関数を呼び出すことで分割を行います(バッファ表示の追加オプションを参照してください)。

新しいウィンドウのサイズは、alist に window-height および window-width のエントリを指定することで調整できます。alist に preserve-size エントリが含まれている場合、Emacs は今後のサイズ変更操作においても新しいウィンドウのサイズを保持しようとします(ウィンドウサイズの保持 を参照)。

分割可能なウィンドウが存在しない場合、この関数は失敗します。多くの場合、分割を可能にするほど大きなウィンドウが存在しないことが原因です。split-height-threshold または split-width-threshold をより小さい値に設定することで、この問題が解消される場合があります。また、選択されたフレームに unsplittable フレームパラメータが設定されている場合も分割に失敗します。バッファパラメータ を参照してください。

関数: display-buffer-in-previous-window buffer alist

この関数は、以前に表示されていたウィンドウに buffer を表示しようとします。

alist に nil inhibit-same-window 以外のエントリが含まれている場合、選択されたウィンドウは使用できません。専用ウィンドウは、既に buffer が表示されている場合にのみ使用可能です。alist に previous-window のエントリが含まれている場合、そのエントリで指定されたウィンドウは、それまで buffer が表示されていなかったとしても使用可能です。

alist に reusable-frames エントリが含まれている場合(バッファ表示用のアクションアリスタ を参照)、その値によって適切なウィンドウを検索対象とするフレームが決定されます。alist に reusable-frames エントリが含まれていない場合、display-buffer-reuse-frames と pop-up-frames がともに nil であればこの関数は選択されたフレームのみを検索し、これらの変数のいずれかが non-nil であれば現在のターミナル上のすべてのフレームを検索します。

これらのルールに従って使用可能なウィンドウが複数ある場合、この関数は以下の優先順位で選択を行います:

  • いずれかの previous-window alist エントリで指定されたウィンドウ(ただし、選択中のウィンドウではないもの)。
  • 選択中のウィンドウでない場合に、以前は buffer が表示されていたウィンドウ。
  • previous-window alist エントリで指定されているか、または以前に buffer が表示されていた場合の、選択済みウィンドウ。
関数: display-buffer-use-some-window buffer alist

この関数は、既存のウィンドウを選択してそのウィンドウにバッファを表示することで、buffer の表示を試みます。まず、lru-frames および alist エントリで指定されたいずれかのフレームにおいて、最近使用されていないウィンドウ(ウィンドウの循環順序 を参照)を探そうとし、そのようなエントリが存在しない場合は選択済みのフレームを使用します。また、window-min-width および window-min-height および alist エントリで指定された制約を満たすウィンドウを優先し、window-min-width エントリが見つからない場合はフル幅のウィンドウを優先します。最後に、使用時間が alist で指定された lru-time エントリの値よりも長いウィンドウは返しません。

直近で使用されたウィンドウが見つからない場合、この関数は別のウィンドウ(できれば可視フレーム上の大きなウィンドウ)を使用しようとします。すべてのウィンドウが他のバッファに割り当てられている場合は、失敗することがあります(専用ウィンドウを参照)。

上記は、some-window alist エントリがデフォルトの lru または nil である場合の動作について説明したものです。もう一つの取り得る値は mru です。例えば、display-buffer-base-action が (nil . ((some-window . mru))) にカスタマイズされている場合、この関数は最も最近使用されたウィンドウを優先します。これにより、同一ウィンドウ内で display-buffer を連続して呼び出した際に、複数のバッファを表示しようとします。3つ以上のウィンドウがある構成で、ユーザーが選択されていないウィンドウにおいて、複数のバッファに分散しているクエリ結果を一つずつ確認したい場合を考えてみましょう。lru 戦略では、display-buffer-use-some-window を呼び出すたびに最も最近使用されていないウィンドウが変化するため、Emacs が別のウィンドウを継続的に選択することがあります。mru 戦略では、選択されるウィンドウが常に同一に保たれるため、予測可能なユーザー体験が得られます。

関数: display-buffer-use-least-recent-window buffer alist

この関数は display-buffer-use-some-window に似ていますが、最近使用したウィンドウを使用しないようより積極的に試みます。具体的には、選択中のウィンドウは使用しません。さらに、まず buffer が既に表示されているウィンドウの再利用を試み、別のバッファが表示されているウィンドウを使用するかどうかの判断をそのウィンドウの使用時間のみに基づいて行い、利用可能なウィンドウが見つからない場合は新しいウィンドウをポップアップ表示します。

最後に、この関数は、返された任意のウィンドウの使用時間(ウィンドウの選択を参照)をインクリメントします。これにより、後続の呼び出しでそのウィンドウが別のバッファの表示に使用されるのを防ぎます。複数のバッファを連続して表示したいアプリケーションは、lru-time や alist エントリに、あらかじめ選択したウィンドウの使用時間の値を設定しておくことで、この関数を補助できます。すると、この関数が呼び出されるたびに返されたウィンドウの使用時間がそれより高い値にインクリメントされ、その後の呼び出しでは、この関数が以前に返したウィンドウを使用することが抑制されます。

関数: display-buffer-in-direction buffer alist

この関数は、alist で指定された位置に buffer を表示しようとします。このため、alist には、値が left、above(または up)、right、および below(または down)のいずれかである direction エントリが含まれている必要があります。それ以外の値は通常、below として解釈されます。

alist に window エントリも含まれている場合、その値は参照ウィンドウを指定します。この値には、選択されたフレームのメインウィンドウを表す main(サイドウィンドウのオプションと機能 を参照)や、選択されたフレームのルートウィンドウを表す root(ウィンドウとフレーム を参照)といった特殊なシンボルを指定できます。また、任意の有効なウィンドウを指定することも可能です。それ以外の値(または window エントリを完全に省略した場合)は、選択されたウィンドウを参照ウィンドウとして使用することを意味します。

この関数はまず、指定された方向において、すでに buffer を表示しているウィンドウの再利用を試みます。そのようなウィンドウが存在しない場合は、参照ウィンドウを分割して、指定された方向に新しいウィンドウを作成しようとします。これも失敗した場合は、指定された方向にある既存のウィンドウに buffer を表示しようとします。いずれの場合も、選択されたウィンドウは direction エントリで指定された参照ウィンドウの側に表示され、参照ウィンドウと少なくとも1つの辺を共有します。

参照ウィンドウがライブ状態の場合、選択されたウィンドウが共有するエッジは、常に direction エントリで指定されたエッジの反対側になります。例えば、direction エントリの値が left である場合、選択されたウィンドウの右エッジ座標(座標とウィンドウ を参照)は、参照ウィンドウの左エッジ座標と等しくなります。

参照ウィンドウが内部ウィンドウである場合、再利用されるウィンドウはdirectionエントリで指定されたエッジを参照ウィンドウと共有しなければならない。したがって、例えば参照ウィンドウがフレームのルートウィンドウであり、directionエントリの値がleftである場合、再利用されるウィンドウはフレームの左側に配置されなければならない。これは、選択されたウィンドウと参照ウィンドウの左端座標が同一であることを意味する。

ただし、選択したウィンドウが参照ウィンドウと反対側の辺を共有するように、参照ウィンドウを分割することで新しいウィンドウが作成されます。本例では、新しいライブウィンドウと参照ウィンドウを子とする新しいルートウィンドウが作成されます。すると、選択したウィンドウの右端座標は、参照ウィンドウの左端座標と等しくなります。また、その左端座標は、フレームの新しいルートウィンドウの左端座標と等しくなります。

direction エントリ用の4つの特殊値により、選択されたフレームのメインウィンドウを参照ウィンドウとして暗黙的に指定できます:leftmost、top、rightmost、および bottom。つまり、例えば (direction . left) (window . main) の代わりに単に (direction . leftmost) を指定すればよいということです。このような場合、既存の window や alist エントリは無視されます。

関数: display-buffer-below-selected buffer alist

この関数は、選択されたウィンドウの下にあるウィンドウに buffer を表示しようとします。選択されたウィンドウの下に別のウィンドウがあり、そのウィンドウですでに buffer が表示されている場合は、そのウィンドウを再利用します。

そのようなウィンドウが存在しない場合、この関数は選択中のウィンドウを分割して新しいウィンドウを作成し、そこに buffer を表示します。また、alist に適切な window-height または window-width のエントリが含まれている場合は、そのウィンドウのサイズ調整も試みます(上記参照)。

選択したウィンドウの分割に失敗し、かつ選択したウィンドウの下に別のバッファを表示している非専用ウィンドウがある場合、この関数はそのウィンドウをbufferの表示に使用しようとします。

alist に window-min-height エントリが含まれている場合、この関数は、使用されるウィンドウが、そのエントリの値で指定された高さ以上であること、またはなり得ることを保証します。なお、これはあくまで保証であることにご注意ください。実際に使用されるウィンドウのサイズを変更するには、alist でも適切な window-height エントリを提供する必要があります。

関数: display-buffer-at-bottom buffer alist

この関数は、選択したフレームの下部にあるウィンドウに buffer を表示しようとします。

これは、フレーム下部のウィンドウまたはフレームのメインウィンドウを分割しようとするか、あるいは選択されたフレーム下部にある既存のウィンドウを再利用しようとします。

関数: display-buffer-pop-up-frame buffer alist

この関数は新しいフレームを作成し、そのフレームのウィンドウにバッファを表示します。実際には、pop-up-frame-function で指定された関数を呼び出すことでフレームを作成します(バッファ表示の追加オプションを参照)。alist に pop-up-frame-parameters エントリが含まれている場合、対応する値が新規作成されたフレームのパラメータに追加されます。

関数: display-buffer-full-frame buffer alist

この関数は、現在のフレームにバッファを表示し、フレーム全体を占めるように他のすべてのウィンドウを削除します。

関数: display-buffer-in-child-frame buffer alist

この関数は、既存の子フレームを再利用するか、あるいは新しい子フレームを作成することで、選択されたフレームの子フレーム(子フレームを参照)に buffer を表示しようとします。alist に nil 以外の child-frame-parameters エントリがある場合、対応する値は新しいフレームに指定するフレームパラメータのアリスタとなります。選択されたフレームを指定する parent-frame パラメータは、デフォルトで提供されます。子フレームを別のフレームの子とする場合は、alist に対応するエントリを追加する必要があります。

子フレームの表示は、主に alist で指定されるパラメータに依存します。子フレームのサイズ(サイズパラメータ を参照)と位置(位置パラメータ を参照)を指定するには、少なくとも比率を用いることが推奨されます。また、子フレームが表示されたままになるよう、keep-ratio パラメータ(フレーム相互作用パラメータ を参照)を追加してください。その他に考慮すべきパラメータについては、子フレーム を参照してください。

関数: display-buffer-use-some-frame buffer alist

この関数は、述語を満たすフレーム(デフォルトでは選択中のフレーム以外の任意のフレーム)を探すことで、bufferを表示しようとします。

この関数が別のフレーム上のウィンドウを選択した場合、そのフレームを表示し、alist に inhibit-switch-frame エントリが含まれていない限り、必要に応じてそのフレームを最前面に表示します。

alist に nil frame-predicate 以外のエントリがある場合、その値は1つの引数(フレーム)を受け取り、フレームが候補であれば nil 以外を返す関数となります。この関数がデフォルトの述語に代わるものです。

alist に nil inhibit-same-window 以外のエントリがある場合、選択されたウィンドウは使用されません。したがって、選択されたフレームが単一のウィンドウである場合、そのウィンドウは使用されません。

関数: display-buffer-in-new-tab buffer alist

この関数は、bufferを新しいタブで表示しようとします。

alist に nil 以外の tab-name エントリ(文字列または関数)が含まれている場合、バッファはその名称の新しいタブで表示されます。tab-name エントリが関数である場合は、2つの引数(buffer と alist)で呼び出され、タブ名を返す必要があります。

tab-name の記述が省略されているか、あるいは nil の場合、明示的な名前のない新しいタブが作成されます。

alist に nil 以外の tab-group エントリが含まれている場合、これがタブグループを定義し、ユーザーオプション tab-bar-new-tab-group を上書きします。このエントリもまた、文字列、あるいは tab-name と同様の方法で呼び出される関数である場合があります。

関数: display-buffer-in-tab buffer alist

この関数は、新規または既存のタブに buffer を表示しようとします。

alist に nil reusable-frames 以外のエントリが含まれている場合、その値で指定されるフレーム内で、既にバッファを表示している既存のタブが検索されます。reusable-frames の取り得る値は以下の通りです:

  • t は、既存のすべてのフレームを考慮することを意味します。
  • visible は、表示されているすべてのフレームを考慮することを意味します。
  • 0は、現在の端末上のすべてのフレームを考慮することを意味します。
  • フレームとは、そのフレームのみを指す。
  • nil以外の値は、選択されたフレームとみなす。
  • nil は、いかなるフレームも検索しないことを意味します(エントリを省略することと同等です)。なお、これはバッファ表示アクションリストにおける reusable-frames エントリの値 nil の一般的な意味とは異なる点に注意してください。

alist に nil ignore-current-tab 以外のエントリが含まれている場合、再利用可能なタブを検索する際に現在のタブはスキップされます。そうでない場合、現在のタブがすでにバッファを表示していれば、優先的に使用されます。

バッファを表示するウィンドウがいずれかの再利用可能なタブにある場合、そのタブとウィンドウが選択されます。

該当するウィンドウが見つからない場合、バッファは alist エントリ tab-name(文字列または関数)に基づいて、新規または既存のタブに表示されます。この名前のタブが既に存在する場合はそのタブが選択され、そうでない場合はその名前の新しいタブが作成されます。tab-name エントリが関数である場合、2つの引数(buffer と alist)で呼び出され、タブ名を返す必要があります。tab-name エントリが省略されているか、または nil である場合は、明示的な名前のない新しいタブが作成されます。

新しいタブが作成され、alist に nil 以外の tab-group エントリが含まれている場合、これによりタブグループが定義され、ユーザーオプション tab-bar-new-tab-group が上書きされます。このエントリもまた、文字列、あるいは tab-name と同様の方法で呼び出される関数である場合があります。

関数: display-buffer-no-window buffer alist

alist に nil 以外の allow-no-window エントリがある場合、この関数は buffer を表示せず、シンボル fail を返します。これは、アクション関数が nil または buffer を表示するウィンドウのいずれかを返すという規約に対する唯一の例外となります。alist にそのような allow-no-window エントリがない場合、この関数は nil を返します。

この関数が fail を返す場合、display-buffer はそれ以降の表示処理の実行をスキップし、直ちに nil を返します。この関数が nil を返す場合、display-buffer は(もしあれば)次の表示処理へと進みます。

display-buffer の呼び出し元が非 nil allow-no-window エントリを指定する場合、nil の戻り値も扱えるものとする。

その他の2つのアクション関数については、それぞれのセクション—display-buffer-in-side-window(サイドウィンドウでのバッファ表示を参照)およびdisplay-buffer-in-atom-window(アトミックウィンドウを参照)で説明されています。