コマンド display-buffer
は、表示するウィンドウを柔軟に選択し、そのウィンドウに指定したバッファを表示します。キーバインド C-x 4
C-o を介して対話的に呼び出すことができます。また、switch-to-buffer
や pop-to-buffer
を含む多くの関数やコマンドでサブルーチンとしても利用されています（ウィンドウ内のバッファへの切り替え を参照）。
このコマンドは、表示先のウィンドウを見つけるために、いくつかの複雑な手順を実行します。これらの手順は表示アクションを用いて記述され、(functions . alist)という形式をとります。ここで、functionsは単一の関数または関数のリストであり、「アクション関数」と呼ばれます（バッファ表示用のアクション関数を参照）。また、alistは連想リストであり、「アクションアリスト」と呼ばれます（バッファ表示用のアクションアリストを参照）。表示アクションの例については、バッファ表示の禅を参照してください。
アクション関数は、表示対象のバッファとアクションのalistという2つの引数を受け取ります。独自の基準に従ってウィンドウを選択または作成し、いずれかのウィンドウにバッファを表示しようと試みます。成功した場合はそのウィンドウを返し、そうでない場合はnilを返します。
display-bufferは、複数のソースからの表示アクションを組み合わせ、いずれかがバッファの表示に成功してnil以外の値を返すまで、順次アクション関数を呼び出すことで動作します。
このコマンドは、ウィンドウを選択したりバッファをカレントにしたりすることなく、buffer-or-name
をいずれかのウィンドウに表示します。引数 buffer-or-name
には、バッファまたは既存のバッファ名を指定する必要があります。戻り値は、バッファの表示に選択されたウィンドウ、または適切なウィンドウが見つからなかった場合は
nil となります。
オプション引数 action は、nil
でない場合、通常は表示アクション（前述）である必要があります。display-buffer
は、以下のソース（優先順位の高い順に）から表示アクションを集約することで、アクション関数のリストとアクションアリストを作成します：
display-buffer-overriding-action。
display-buffer-alist。
display-buffer-default-alist。
display-buffer-base-action。
display-buffer-fallback-action。
実際には、これは display-buffer
がこれらの表示アクションで指定されたすべてのアクション関数のリストを作成することを意味します。このリストの最初の要素は、display-buffer-overriding-action
で指定された最初のアクション関数（もしあれば）です。最後の要素は display-buffer-pop-up-frame—display-buffer-fallback-action
で指定された最後のアクション関数です。このリストから重複は削除されません—したがって、display-buffer を1回呼び出す間に、同一のアクション関数が複数回呼び出される可能性があります。
display-buffer
は、このリストで指定されたアクション関数を順に呼び出し、第1引数にバッファを、第2引数に結合されたアクションアリスタを渡し、いずれかの関数が
non-nil を返すまで処理を続けます。異なるソースで指定された表示アクションが display-buffer によってどのように処理されるかの例については、アクション関数の優先順位 を参照してください。
なお、第2引数は、常に上記で指定されたソースによって指定されるすべてのアクションalistエントリのリストとなります。したがって、そのリストの最初の要素は、display-buffer-overriding-actionで指定された最初のアクションalistエントリ（もしあれば）となります。最後の要素は、display-buffer-base-actionの最後のalistエントリ（もしあれば）となります（display-buffer-fallback-actionのアクションalistは空です）。
また、統合されたアクションリストには、重複したエントリや、同一キーに対して異なる値を持つエントリが含まれる場合がある点にも注意してください。原則として、アクション関数は常に、最初に見つかったキーの関連付けを使用します。したがって、アクション関数が使用する関連付けは、必ずしもそのアクション関数を指定した表示アクションによって提供された関連付けであるとは限りません。
引数 action には、nil
でもリストでもない値を指定することも可能です。これは、選択中のウィンドウですでに表示されていたとしても、バッファを選択中のウィンドウ以外のウィンドウに表示させるという特別な意味を持ちます。接頭辞引数を用いて対話的に呼び出された場合、action は t となります。Lisp
プログラムでは、常にリスト値を指定する必要があります。
オプション引数 frame は、nil
でない場合、バッファが既に表示されているかを判定する際にどのフレームを確認するかを指定します。これは、action のアクションアリスタに要素 (reusable-frames . frame) を追加することと同等です（バッファ表示用のアクションアリスタ を参照）。frame 引数は互換性のために用意されており、Lisp プログラムで使用すべきではありません。
この変数の値は表示アクションである必要があり、display-buffer
によって最優先で処理されます。デフォルト値は空の表示アクション、すなわち (nil . nil) です。
この変数の値は、条件を表示アクションにマッピングするalistです（display-buffer-alistを参照）。
Lispプログラムでは、この変数をlet-bindすることで、ラップされたdisplay-buffer呼び出しに対する条件付き動作を指定できます。ユーザーがこの変数を設定することは想定されていません。代わりに、より優先度が高く、原則としてLispプログラムによってそのまま保持されるdisplay-buffer-alistをカスタマイズすべきです。
このオプションの値は、条件と表示アクションを対応付けたalistです。各条件は、バッファ名およびdisplay-bufferに渡されるaction引数とともに、buffer-match-p（バッファリストを参照）に渡されます。nil以外の値が返された場合、display-bufferは対応する表示アクションを用いてバッファを表示します。注意点として、derived-modeまたはmajor-modeを条件として使用する場合、バッファのメジャーモードが設定される前にdisplay-bufferが呼び出されると、buffer-match-pがマッチを報告できない可能性があります。
display-buffer の呼び出し元が action 引数にカテゴリをシンボルとして渡す場合、display-buffer-alist および display-buffer-default-alist
でも同じカテゴリを使用して、異なる名前のバッファをマッチングさせることができます。例えば：
(add-to-list 'display-buffer-alist
'((category . comint)
(display-buffer-same-window)
(inhibit-same-window . nil)))
(display-buffer (get-buffer-create "*my-shell*")
'(nil (category . comint)))
buffer-match-pを参照してください。
表示されるバッファ名に関わらず、呼び出し側はシンボル comint
としてカテゴリを定義します。すると、display-buffer-alist や display-buffer-default-alist
は、同じカテゴリで表示されるすべてのバッファに対してこのカテゴリに一致します。これにより、バッファ名にマッチする複雑な正規表現を構築する必要がなくなります。
現在実行中のコマンドでマッチさせることも可能です。これは、異なるコマンドが同じ名前のバッファを表示するものの、コマンドごとにバッファの表示方法を変えたい場合に便利です。例えば：
(add-to-list 'display-buffer-alist
'((and "^\\*vc-diff\\*"
(not (this-command . vc-root-diff)))
nil
(post-command-select-window . nil)))
これは、C-x v =（vc-diff、Emacs マニュアルのOld
Revisionsを参照）によって生成された VC 差分を表示するウィンドウは、C-x v
D（vc-root-diff）によって生成されたバッファを表示するウィンドウを除いて選択状態のままにならないことを意味します。
このオプションの値は、表示アクションである必要があります。このオプションを使用すると、display-buffer への呼び出しに対する標準的な表示アクションを定義できます。
この表示アクションは、他に表示アクションが指定されていない場合の display-buffer
のフォールバック動作を規定します。