Выбор окна для отображения буфера

Команда display-buffer гибко выбирает окно для отображения и показывает указанный буфер в этом окне. Её можно вызвать интерактивно с помощью привязки клавиш C-x 4 C-o. Она также используется в качестве подпрограммы многими функциями и командами, включая switch-to-buffer и pop-to-buffer (см. Переключение на буфер в окне).

Эта команда выполняет несколько сложных шагов, чтобы найти окно для отображения. Эти шаги описываются с помощью действий отображения, имеющих вид (functions . alist). Здесь functions — это одна функция или список функций, называемых «функциями действий» (см. Функции действий для отображения буфера); а alist — это ассоциативный список, называемый «ассоциативным списком действия» (см. Ассоциативные списки действий для отображения буфера). Примеры действий отображения см. в разделе Дзен отображения буфера.

Функция действия принимает два аргумента: отображаемый буфер и ассоциативный список действия. Она пытается отобразить буфер в некотором окне, выбирая или создавая окно согласно собственным критериям. В случае успеха она возвращает окно; в противном случае возвращает nil.

display-buffer работает, объединяя действия отображения из нескольких источников и вызывая по очереди функции действий, пока одна из них не сможет отобразить буфер и не вернёт значение, отличное от nil.

Команда: display-buffer buffer-or-name &optional action frame

Эта команда отображает buffer-or-name в некотором окне, не выбирая это окно и не делая буфер текущим. Аргумент buffer-or-name должен быть буфером или именем существующего буфера. Возвращаемое значение — окно, выбранное для отображения буфера, или nil, если подходящее окно не найдено.

Необязательный аргумент action, если он не равен nil, обычно должен быть действием отображения (описанным выше). display-buffer формирует список функций действий и ассоциативный список, объединяя действия отображения из следующих источников (в порядке убывания приоритета):

• Переменная display-buffer-overriding-action.
• Пользовательский параметр display-buffer-alist.
• Аргумент action.
• Пользовательский параметр 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.

display-buffer по очереди вызывает функции действий из этого списка, передавая буфер в качестве первого аргумента и объединённый ассоциативный список действия в качестве второго, пока одна из функций не вернёт значение, отличное от nil. Примеры обработки display-buffer действий отображения, заданных в разных источниках, см. в разделе Приоритет функций действий.

Обратите внимание, что второй аргумент всегда представляет собой список всех элементов ассоциативного списка действия, заданных перечисленными выше источниками. Следовательно, первым элементом этого списка является первая запись ассоциативного списка действия, указанная в display-buffer-overriding-action, если таковая имеется. Последним его элементом является последняя запись ассоциативного списка в display-buffer-base-action, если таковая имеется (ассоциативный список действия в display-buffer-fallback-action пуст).

Обратите также внимание, что объединённый ассоциативный список действия может содержать повторяющиеся записи и записи для одного и того же ключа с разными значениями. Как правило, функции действий всегда используют первую найденную ассоциацию ключа. Поэтому используемая функцией действия ассоциация не обязательно совпадает с ассоциацией, заданной действием отображения, которое указало эту функцию действия.

Аргумент action также может иметь значение, отличное от nil и не являющееся списком. Это означает, что буфер следует отображать в окне, отличном от выбранного, даже если выбранное окно уже показывает этот буфер. При интерактивном вызове с префиксным аргументом action равен t. Программы на Lisp всегда должны передавать значение-список.

Необязательный аргумент frame, если он не равен nil, указывает, какие кадры проверять при определении того, отображается ли буфер уже где-либо. Это эквивалентно добавлению элемента (reusable-frames . frame) в ассоциативный список действия аргумента action (см. Ассоциативные списки действий для отображения буфера). Аргумент frame предоставлен для совместимости; программы на Lisp не должны его использовать.

Переменная: display-buffer-overriding-action

Значение этой переменной должно быть действием отображения, которому display-buffer отдаёт наивысший приоритет. Значение по умолчанию — пустое действие отображения, то есть (nil . nil).

Пользовательский параметр: display-buffer-alist

Значение этого параметра — ассоциативный список, сопоставляющий условиям действия отображения. Каждое условие передаётся в buffer-match-p (см. Список буферов) вместе с именем буфера и аргументом action, переданным в display-buffer. Если оно возвращает значение, отличное от nil, то display-buffer использует соответствующее действие отображения для показа буфера. Предупреждение: если в качестве условия использовать derived-mode или major-mode, buffer-match-p может не обнаружить совпадение, если display-buffer вызвана до установки основного режима буфера.

Если вызывающий код display-buffer передаёт категорию в виде символа в аргументе action, то для поиска буферов с разными именами в display-buffer-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 сопоставляет эту категорию всем буферам, отображаемым с той же категорией. Это избавляет от необходимости составлять сложное регулярное выражение для сопоставления с именем буфера.

Можно также выполнять сопоставление с текущей выполняемой командой. Это полезно, когда разные команды отображают буферы с одинаковыми именами, но вы хотите, чтобы буферы разных команд отображались по-разному. Например:

(add-to-list 'display-buffer-alist
             '((and "^\\*vc-diff\\*"
                    (not (this-command . vc-root-diff)))
	       nil
	       (post-command-select-window . nil)))

Это означает, что окна с различиями VC, например созданные командой C-x v = (vc-diff, см. Старые редакции в Руководстве по Emacs), не остаются выбранными, за исключением окон с буферами, созданными командой C-x v D (vc-root-diff), которые остаются выбранными.

Пользовательский параметр: display-buffer-base-action

Значением этого параметра должно быть действие отображения. С помощью этого параметра можно задать стандартное действие отображения для вызовов display-buffer.

Константа: display-buffer-fallback-action

Это действие отображения задаёт поведение display-buffer по умолчанию, если другие действия отображения не указаны.