Команда display-buffer гибко выбирает окно для отображения и отображает указанный буфер в этом окне. Ее можно вызвать интерактивно, используя сочетание клавиш C-x 4 C-o. Она также используется как подпрограмма многими функциями и командами, включая switch-to-buffer и pop-to-buffer (см. Переключение на буфер в окне).
Эта команда выполняет несколько сложных шагов для поиска окна для отображения. Эти шаги описываются с помощью действий отображения (display actions), которые имеют вид (functions . alist). Здесь functions — это либо одна функция, либо список функций, называемых «функциями действий» (action functions) (см. Функции действий для отображения буфера); а alist — это ассоциативный список, называемый «ассоциативным списком действий» (action alist) (см. Ассоциативные списки действий для отображения буфера).
См. Дзен отображения буфера для примеров действий отображения.
Функция действия принимает два аргумента: буфер для отображения и ассоциативный список действий. Она пытается отобразить буфер в каком-либо окне, выбирая или создавая окно в соответствии со своими критериями. Если это удается, она возвращает окно; в противном случае возвращает nil.
display-buffer работает путем объединения действий отображения из нескольких источников и последовательного вызова функций действий до тех пор, пока одна из них не сможет отобразить буфер и не вернет не-nil значение.
Эта команда заставляет buffer-or-name появиться в каком-либо окне, не выбирая окно и не делая буфер текущим. Аргумент buffer-or-name должен быть буфером или именем существующего буфера. Возвращаемое значение — это окно, выбранное для отображения буфера, или nil, если подходящее окно не найдено.
Необязательный аргумент action, если он не nil, обычно должен быть действием отображения (описанным выше). display-buffer строит список функций действий и ассоциативный список действий, объединяя действия отображения из следующих источников (в порядке их приоритета, от самого высокого к самому низкому):
display-buffer-overriding-action.
display-buffer-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.
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 обрабатывает с наивысшим приоритетом. Значение по умолчанию — это пустое действие отображения, т.е. (nil . nil).
Значение этого варианта — это ассоциативный список, сопоставляющий условия действиям отображения. Каждое условие передается в 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 сопоставляет эту категорию для всех буферов, отображаемых с той же категорией. Это позволяет избежать необходимости построения сложного регулярного выражения, которое соответствует имени буфера.
Значение этого варианта должно быть действием отображения. Этот вариант может использоваться для определения стандартного действия отображения для вызовов display-buffer.
Это действие отображения определяет поведение по умолчанию для display-buffer, если не указаны другие действия отображения.