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

29.15.3 バッファ表示用のアクションアリスタ

アクションアリストとは、アクション関数が認識する事前定義済みのシンボルと、それらの関数が適宜解釈すべき値とを対応付ける連想リストである。各呼び出しにおいて、display-buffer は新しい(空である可能性もある)アクションアリストを構築し、そのリスト全体を呼び出し先のアクション関数に渡す。

設計上、アクション関数はアクションalistのエントリの解釈において自由です。実際、allow-no-windowやprevious-windowのような一部のエントリは、1つまたは少数のアクション関数においてのみ意味を持ち、それ以外の関数では無視されます。一方、inhibit-same-windowやwindow-parametersのような他のエントリは、アプリケーションプログラムや外部パッケージが提供するものを含め、ほとんどのアクション関数で尊重されることになっています。

前節では、個々のアクション関数が、自身が対象とするアクションalistのエントリをどのように解釈するかについて詳細に説明しました。ここでは、既知のすべてのアクションalistエントリをそのシンボルごとに列挙し、それらの値と、それらを認識するアクション関数(バッファ表示用のアクション関数を参照)を併せて示します。このリスト全体を通して、「バッファ」という用語はバッファ display-buffer が表示対象とするものを指し、「値」という用語はエントリの値を指します。

inhibit-same-window

値が nil 以外の場合、これは選択されたウィンドウをバッファの表示に使用してはならないことを示します。既存のウィンドウを(再)使用するすべてのアクション関数は、この項目に従う必要があります。

previous-window

値には、以前にバッファを表示していた可能性のあるウィンドウを指定する必要があります。display-buffer-in-previous-window は、当該ウィンドウが依然としてアクティブであり、かつ別のバッファに割り当てられていない場合に優先されます。

mode

値は、メジャーモードまたはメジャーモードのリストのいずれかです。display-buffer-reuse-mode-window は、このエントリで指定された値が当該ウィンドウのバッファのメジャーモードと一致する場合に、ウィンドウを再利用することがあります。その他のアクション関数は、このようなエントリを無視します。

frame-predicate

この値は、1つの引数(フレーム)を受け取り、そのフレームがバッファ表示の候補である場合に nil 以外の値を返す関数である必要があります。この項目は display-buffer-use-some-frame で使用されます。

reusable-frames

この値は、既にバッファを表示しているため再利用可能なウィンドウを検索するためのフレーム集合を指定します。以下のように設定できます。

  • nil は、選択したフレーム上のウィンドウのみを考慮することを意味します。(実際には、ミニバッファ専用ではないフレームのうち、最後に使用されたものが対象となります。)
  • visible は、表示されているすべてのフレームのウィンドウを考慮することを意味します。
  • 0は、表示されている、またはアイコン化されたすべてのフレーム上のウィンドウを考慮することを意味します。
  • フレームとは、そのフレーム上のウィンドウのみを考慮することを意味します。
  • t は、すべてのフレームでウィンドウを考慮することを意味します。(なお、この値が適切であることは稀で、ツールチップフレームが返される場合もあります。)

なお、nil の意味は、next-window の引数である all-frames の意味とはわずかに異なります(ウィンドウの循環順序 を参照)。

この主要なクライアントは display-buffer-reuse-window ですが、ウィンドウを再利用しようとする他のすべてのアクション関数も同様に影響を受けます。display-buffer-in-previous-window は、別のフレームで以前にバッファを表示していたウィンドウを検索する際に、これを参照します。

アクション関数 display-buffer-in-tab は、このエントリで特定されたフレームのタブを検索し、値 nil も異なる方法で解釈します。

inhibit-switch-frame

nil 以外の値が指定されている場合、display-buffer で選択されたウィンドウがそこに表示されているときは、別のフレームが昇格または選択されることはありません。主に影響を受けるのは display-buffer-use-some-frame と display-buffer-reuse-window です。理想的には display-buffer-pop-up-frame も影響を受けるべきですが、ウィンドウマネージャがこれに準拠するという保証はありません。

window-parameters

この値は、選択したウィンドウに設定するウィンドウパラメータのalistを指定します。ウィンドウを選択するすべてのアクション関数は、このエントリを処理する必要があります。

window-min-width

この値は、使用するウィンドウの最小幅を正準フレーム列単位で指定します。特殊値 full-width は、選択したウィンドウのフレーム内において、その左右に他のウィンドウが存在しないものであることを意味します。

このエントリは現在、display-buffer-use-some-window と display-buffer-use-least-recent-window によって管理されており、これらは、エントリを満たさない直近に使用されていないウィンドウを返すことを避けるよう努めています。

なお、このようなエントリを記述しただけでは、必ずしもウィンドウの幅がその値で指定された通りになるとは限りません。既存のウィンドウを実際にリサイズしたり、新しいウィンドウをこのエントリの値で指定された幅にしたりするには、その値を指定する window-width エントリも併せて記述する必要があります。ただし、このような window-width エントリでは全く別の値を指定したり、ウィンドウの幅をバッファの幅に合わせるよう指定したりすることができ、その場合、window-min-width エントリがウィンドウの保証された最小幅を規定します。

window-min-height

この値は、使用するウィンドウの最小高さを正準フレーム行単位で指定します。特殊値 full-height は、選択したウィンドウをフルハイトウィンドウ、つまりそのフレーム内に上下に他のウィンドウが存在しないウィンドウにすることを意味します。

このエントリは現在 display-buffer-below-selected によって遵守されており、同エントリで指定された高さに満たないウィンドウは使用されません。また、display-buffer-use-some-window および display-buffer-use-least-recent-window によっても遵守されており、これらの制約を満たさない場合に、より最近使用されていないウィンドウを返すことは極力避けられます。

なお、このようなエントリを記述しただけでは、必ずしもウィンドウの高さがその値で指定された通りになるとは限りません。既存のウィンドウを実際にリサイズしたり、新しいウィンドウをその値で指定された高さにしたりするには、その値を指定する window-height エントリも併せて記述する必要があります。ただし、このような window-height エントリで全く別の値を指定したり、ウィンドウの高さをバッファの高さに合わせるよう指示したりすることも可能です。その場合、window-min-height エントリによって使用されるウィンドウの保証された最小高さが指定されます。

window-height

この値は、選択したウィンドウの高さを調整するかどうか、およびその方法を指定するもので、以下のいずれかとなります。

  • nil は、選択したウィンドウの高さを変更しないことを意味します。
  • 整数で、選択したウィンドウの希望の総高さを行単位で指定します。
  • 浮動小数点数は、選択したウィンドウの希望の全高が、フレームのルートウィンドウの全高に占める割合を指定します。
  • CAR が body-lines であり、CDR が選択されたウィンドウのボディの高さをフレーム行数で指定する整数である cons セル。
  • 値が関数を指定している場合、その関数は1つの引数(選択されたウィンドウ)とともに呼び出されます。この関数はウィンドウの高さを調整するためのものであり、戻り値は無視されます。適切な関数には fit-window-to-buffer や shrink-window-if-larger-than-buffer があります。ウィンドウのサイズ変更を参照してください。

慣例として、選択したウィンドウの高さが調整されるのは、そのウィンドウが垂直方向の組み合わせ(ウィンドウとフレームを参照)の一部である場合に限られます。これは、無関係な他のウィンドウの高さが変わるのを防ぐためです。また、この項目は、このリストの直下で規定されている特定の条件下でのみ処理されるものとします。

window-width

このエントリは、前述の window-height エントリと同様ですが、代わりに選択したウィンドウの幅を調整するために使用されます。値は以下のいずれかとなります:

  • nil は、選択したウィンドウの幅をそのままにすることを意味します。
  • 整数で、選択したウィンドウの希望の総幅(列数)を指定します。
  • 浮動小数点数は、フレームのルートウィンドウの全幅に対する、選択したウィンドウの希望総幅の割合を指定します。
  • CAR が body-columns であり、CDR が選択されたウィンドウ本体のフレーム列方向の幅を指定する整数である cons セル。
  • 値が関数を指定している場合、その関数は1つの引数(選択されたウィンドウ)とともに呼び出されます。この関数はウィンドウの幅を調整する役割を担っており、戻り値は無視されます。
window-size

このエントリは前述の2つのエントリを組み合わせたもので、選択したウィンドウの高さおよび幅を調整するために使用できます。ウィンドウは他のウィンドウに影響を与えることなく一方向のみにリサイズできるため、window-sizeはフレーム上に単独で表示されるウィンドウのサイズを設定する場合にのみ有効です。値は以下のいずれかとなります:

  • nil は、選択したウィンドウのサイズをそのままにすることを意味します。
  • 2つの整数からなる cons セルは、選択したウィンドウの希望の総幅と高さを行数と列数で指定します。これにより、フレームのサイズがそれに応じて調整されます。
  • CAR が body-chars であり、CDR が2つの整数—フレームの列および行における、選択したウィンドウの所望の本体幅と高さ—からなるコンスセル。その効果は、それに応じてフレームのサイズを調整することである。
  • 値が関数を指定している場合、その関数は1つの引数(選択されたウィンドウ)とともに呼び出されます。この関数はウィンドウのフレームサイズを調整する役割を担っており、戻り値は無視されます。

本項目は、本リストの直下に規定される特定の条件下においてのみ処理されるものとする。

dedicated

nil 以外の場合、このようなエントリは display-buffer に対し、自身が作成する任意のウィンドウをそのバッファ専用としてマークするよう指示します(専用ウィンドウ を参照)。これは、選択したウィンドウを第1引数として、エントリの値を第2引数として set-window-dedicated-p を呼び出すことで行われます。サイドウィンドウは、デフォルトで値 side により専用としてマークされます(サイドウィンドウのオプションと関数 を参照)。再利用されるウィンドウは、以前にそのバッファを表示していたかどうかにかかわらず、専用としてマークされません。バッファ専用のウィンドウが、同じバッファを再度表示するために再利用される場合、その専用フラグはそのまま保持されます。

preserve-size

nil 以外の場合、このエントリは Emacs に対し、選択したウィンドウのサイズを保持するよう指示します(ウィンドウサイズの保持 を参照)。値は、ウィンドウの幅を保持する場合は (t . nil)、高さを保持する場合は (nil . t)、幅と高さの両方を保持する場合は (t . t) のいずれかである必要があります。このエントリは、このリストの直後に規定されている特定の条件下でのみ処理されます。

lru-frames

この値は、バッファの表示に使用できるウィンドウを検索するためのフレーム集合を指定します。他のバッファを表示している、より最近使用されていないウィンドウを探そうとする際、display-buffer-use-some-window および display-buffer-use-least-recent-window でこの値が参照されます。その値は、前述の reusable-frames エントリと同じです。

lru-time

この値は、使用時刻を指定するものです(ウィンドウの選択を参照)。他のバッファを表示している、より最近使用されていないウィンドウを探そうとする際、display-buffer-use-some-window および display-buffer-use-least-recent-window はこのエントリを参照します。ウィンドウの使用時刻がこのオプションで指定された値よりも大きい場合、これらのアクション関数はそのウィンドウをバッファ表示の候補として考慮しません。

bump-use-time

nil 以外の場合、このようなエントリがあると、display-buffer は使用しているウィンドウの使用時刻を繰り上げます(ウィンドウの選択を参照)。これにより、display-buffer-use-some-window や display-buffer-use-least-recent-window といったアクション関数が別のバッファを表示するためにこのウィンドウを後から使用することを防げるはずです。

このエントリを使用する場合と、アクション関数 display-buffer-use-least-recent-window を使用する場合との間には、微妙な違いがあります。後者を呼び出すということは、その関数がバッファの表示に使用しているウィンドウの使用時間のみを加算することを意味します。ここで説明するエントリを使用すると、display-buffer はバッファの表示に使用されているあらゆるウィンドウの使用時間を加算します。

pop-up-frame-parameters

この値は、新しいフレームが作成される場合に指定するフレームパラメータのalistを表します。display-buffer-pop-up-frame がその唯一の宛先となります。

pop-up-frames

この値は、display-buffer が新しいフレームを作成してバッファを表示できるかどうかを制御します。pop-up-frames 変数と同じ意味を持ち、存在する場合にはそちらよりも優先されます。主な目的は、ユーザーが選択したフレームに保持しておきたい特定のバッファに対して、nil 以外の変数値を上書きすることです。

parent-frame

この値は、バッファを子フレームに表示する際に使用する親フレームを指定します。この項目は display-buffer-in-child-frame でのみ使用されます。

child-frame-parameters

この値は、バッファを子フレームに表示する際に使用するフレームパラメータのalistを指定します。この項目はdisplay-buffer-in-child-frameでのみ使用されます。

side

この値は、バッファを表示する新しいウィンドウを作成するフレームまたはウィンドウの側を示します。このエントリは、display-buffer-in-side-window によって新しいサイドウィンドウを配置するフレームの側を示すために使用されます(サイドウィンドウへのバッファの表示を参照)。また、display-buffer-in-atom-window によって、新しいウィンドウを配置する既存ウィンドウの側を示すためにも使用されます(アトミックウィンドウを参照)。

slot

nil 以外の場合、その値はバッファを表示する側ウィンドウのスロットを指定します。このエントリは display-buffer-in-side-window でのみ使用されます。

direction

この値は方向を指定し、window エントリと併せて、display-buffer-in-direction がバッファを表示するためのウィンドウの位置を特定できるようにします。

window

この値は、display-buffer で選択されたウィンドウと何らかの関連を持つウィンドウを指定します。このエントリは現在、display-buffer-in-atom-window によって、新しいウィンドウをどちら側に作成するかを示すために使用されています。また、display-buffer-in-direction によって、結果として得られるウィンドウをどちら側に表示させるかという参照ウィンドウを指定するためにも使用されます。

allow-no-window

値が nil 以外の場合、display-buffer が必ずしもバッファを表示するとは限らず、呼び出し側はそれを許容する用意がある。display-buffer の任意の呼び出し元が、バッファを表示するウィンドウが存在しないケースに対処できるという保証はないため、このエントリはユーザーによるカスタマイズを想定したものではない。display-buffer-no-window は、このエントリを考慮する唯一のアクション関数である。

some-window

値が nil または lru の場合、display-buffer-use-some-window はフル幅ではないウィンドウや別のフレームにあるウィンドウの選択を避けつつ、最も最近使用されていないウィンドウを優先します。値が mru の場合、選択中のウィンドウおよび選択中のフレーム以外のフレームにあるウィンドウを考慮せず、最も最近使用されたウィンドウを優先します。値が関数である場合、その関数はバッファとalistの2つの引数で呼び出され、バッファを表示するウィンドウを返す必要があります。

body-function

値は、1つの引数(表示ウィンドウ)を取る関数である必要があります。この関数を使用して、表示ウィンドウの本体を、ウィンドウの寸法に依存する可能性のある内容で埋めることができます。この関数は、バッファが表示された後、かつ、挿入された内容に合わせてウィンドウのサイズを変更する可能性のあるエントリ window-height、window-width、preserve-size が適用される前に呼び出されます。

post-command-select-window

値が nil 以外の場合、フック post-command-hook を実行して現在のコマンドを処理した後、display-buffer で表示されるバッファが選択されます(コマンドループの概要 を参照)。値が nil の場合、pop-to-buffer などの関数で選択されていたバッファの選択が解除され、この関数を呼び出す前に選択されていたウィンドウは、本コマンド内でその後どのウィンドウが選択されたかにかかわらず、選択されたままとなります。

category

display-buffer の呼び出し元が action 引数にアリストのエントリ (category . symbol) を渡す場合、display-buffer-alist および display-buffer-default-alist エントリの条件部に同じカテゴリシンボルを使用することで、表示されるバッファをマッチングできます。buffer-match-p を参照してください。したがって、Lisp プログラムが display-buffer を呼び出す際に特定の symbol をカテゴリとして使用する場合、ユーザーは display-buffer-alist にそのようなエントリを含めることで、これらのバッファの表示方法をカスタマイズできます。プログラムは display-buffer-default-alist を let-bind することで同様の効果を得られます。

tab-name

この値は、バッファを表示すべきタブを指定します。このエントリは display-buffer-in-new-tab および(条件に応じて)display-buffer-in-tab で使用されます。

tab-group

この値は、新しいタブを作成する際に使用するタブグループを指定し、ユーザーオプション tab-bar-new-tab-group を上書きします。この項目は display-buffer-in-new-tab および display-buffer-in-tab で使用されます。

慣例として、エントリ window-height、window-width、および preserve-size は、選択したウィンドウのバッファが設定された後に適用され、かつ、そのウィンドウがそれまで一度も別のバッファを表示したことがない場合に限り適用されます。より厳密に言えば、後者の条件は、そのウィンドウが現在の display-buffer 呼び出しによって作成されたか、あるいは以前に display-buffer によってバッファを表示するために作成され、現在の display-buffer 呼び出しで再利用されるまで、他のバッファの表示に一度も使用されなかったことを意味します。

window-height、window-width、またはwindow-sizeのエントリが指定されていない場合でも、バッファが一時的でtemp-buffer-resize-modeが有効になっているときは、ウィンドウが自動的にリサイズされることがありますTemporary Displays。その場合、window-height、window-width、またはwindow-sizeエントリのCDRを使用して、特定のバッファやdisplay-bufferの呼び出しにおけるtemp-buffer-resize-modeのデフォルト動作を抑制または上書きできます。