Списки действий для отображения буфера

Список действий — это список ассоциаций, сопоставляющий предопределенные символы, распознаваемые функциями действий, со значениями, которые эти функции должны интерпретировать соответственно. При каждом вызове display-buffer строит новый, возможно пустой, список действий и передает весь этот список любой функции действия, которую он вызывает.

По своему назначению, функции действий свободны в своей интерпретации записей списка действий. Фактически, некоторые записи, такие как allow-no-window или previous-window, имеют смысл только для одной или нескольких функций действий и игнорируются остальными. Другие записи, такие как inhibit-same-window или window-parameters, должны учитываться большинством функций действий, включая те, которые предоставляются приложениями и внешними пакетами.

В предыдущем подразделе мы подробно описали, как отдельные функции действий интерпретируют записи списка действий, которые им важны. Здесь мы предоставляем справочный список всех известных записей списка действий по их символам, вместе со значениями и функциями действий (см. Функции действий отображения буфера), которые их распознают. В этом списке термин «буфер» будет относиться к буферу display-buffer, который должен отображаться, а «значение» относится к значению записи.

inhibit-same-window

Если значение является не-nil, это сигнализирует о том, что выбранное окно не должно использоваться для отображения буфера. Все функции действий, которые (пере)используют существующее окно, должны учитывать эту запись.

previous-window

Значение должно указать окно, которое, возможно, ранее отображало буфер. display-buffer-in-previous-window отдаст предпочтение такому окну, при условии, что оно все еще активно и не выделено для другого буфера.

mode

Значение является либо основным режимом, либо списком основных режимов. display-buffer-reuse-mode-window может повторно использовать окно, когда заданное этим значением основное окно соответствует основному режиму буфера этого окна. Другие функции действий игнорируют такие записи.

frame-predicate

Значение должно быть функцией, принимающей один аргумент (фрейм), которая должна возвращать не-nil, если этот фрейм является кандидатом для отображения буфера. Эта запись используется display-buffer-use-some-frame.

reusable-frames

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

• nil означает учитывать только окна на выбранном фрейме. (Фактически, последний используемый фрейм, который не является фреймом только для мини-буфера.)
• t означает учитывать окна на всех фреймах.
• visible означает учитывать окна на всех видимых фреймах.
• 0 означает учитывать окна на всех видимых или минимизированных фреймах.
• Фрейм означает учитывать только окна на этом фрейме.

Обратите внимание, что значение nil немного отличается от значения аргумента all-frames для next-window (см. Циклический порядок окон).

Основным клиентом этого является display-buffer-reuse-window, но все остальные функции действий, которые пытаются повторно использовать окно, также затронуты. display-buffer-in-previous-window использует его при поиске окна, которое ранее отображало буфер на другом фрейме.

inhibit-switch-frame

Не-nil значение предотвращает поднятие или выбор другого фрейма, если окно, выбранное display-buffer, отображается там. В первую очередь это затронет display-buffer-use-some-frame и display-buffer-reuse-window. В идеале, display-buffer-pop-up-frame также должен быть затронут, но нет гарантии, что диспетчер окон будет этому следовать.

window-parameters

Значение определяет список параметров окна, которые необходимо передать выбранному окну. Все функции действий, которые выбирают окно, должны обрабатывать эту запись.

window-min-height

Значение задаёт минимальную высоту используемого окна в строках. Если окно не может или не будет иметь высоту, указанную в этой записи, то окно не рассматривается для использования. В настоящее время единственный клиент этой записи — display-buffer-below-selected.

Обратите внимание, что предоставление такой записи само по себе не гарантирует, что окно будет иметь высоту, указанную в её значении. Для фактического изменения размера существующего окна или создания нового окна с заданной высотой необходимо также предоставить запись window-height с указанным значением. Такая запись window-height, однако, может задавать совершенно иное значение или просить высоту окна быть соответствующей высоте буфера, в котором случае запись window-min-height обеспечивает гарантированную минимальную высоту используемого окна.

window-height

Значение задаёт, как и нужно ли регулировать высоту выбранного окна и может принимать следующие значения:

• nil означает оставить высоту выбранного окна без изменений.
• Целое число задаёт желаемую общую высоту выбранного окна в строках.
• Вещественное число задаёт долю желаемой общей высоты выбранного окна относительно общей высоты корневого окна фрейма.
• Если значение определяет функцию, эта функция вызывается с одним аргументом — выбранным окном. Функция должна отрегулировать высоту окна; возвращаемое значение игнорируется. Подходящие функции — fit-window-to-buffer и shrink-window-if-larger-than-buffer, см. Изменение размеров окон.

По соглашению, высота выбранного окна изменяется только если окно является частью вертикальной комбинации (см. Окна и фреймы), чтобы избежать изменения высоты других, не связанных окон. Также эта запись должна обрабатываться только при определенных условиях, которые указаны непосредственно под этим списком.

window-width

Эта запись похожа на запись window-height, описанную ранее, но используется для изменения ширины выбранного окна вместо высоты. Значение может быть одним из следующих:

• nil означает оставить ширину выбранного окна без изменений.
• Целое число задаёт желаемую общую ширину выбранного окна в колонках.
• Вещественное число задаёт долю желаемой общей ширины выбранного окна относительно общей ширины корневого окна фрейма.
• Если значение определяет функцию, эта функция вызывается с одним аргументом — выбранным окном. Функция должна отрегулировать ширину окна; возвращаемое значение игнорируется.

По соглашению, ширина выбранного окна изменяется только если окно является частью горизонтальной комбинации (см. Окна и фреймы), чтобы избежать изменения ширины других, не связанных окон. Также эта запись должна обрабатываться только при определенных условиях, которые указаны непосредственно под этим списком.

dedicated

Если не-nil, такая запись сообщает display-buffer отметить любое созданное им окно как выделенное для его буфера (см. Выделенные окна). Это делается путем вызова set-window-dedicated-p с выбранным окном в качестве первого аргумента и значением записи во втором. По умолчанию боковые окна выделяются со значением side (см. Параметры и функции боковых окон).

preserve-size

Если не-nil, такая запись сообщает Emacs сохранить размер выбранного окна (см. Сохранение размеров окон). Значение должно быть либо (t . nil) для сохранения ширины окна, (nil . t) для сохранения его высоты или (t . t) для сохранения как ширины, так и высоты. Эта запись должна обрабатываться только при определенных условиях, указанных непосредственно после этого списка.

pop-up-frame-parameters

Значение задаёт родительский фрейм для использования, когда буфер отображается в дочернем фрейме. Эта запись используется только функцией display-buffer-in-child-frame.

parent-frame

Значение задаёт список параметров фрейма для использования, когда буфер отображается в дочернем фрейме. Эта запись используется только функцией 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 является единственной функцией действия, которая обращает внимание на эту запись.

body-function

Значение должно быть функцией, принимающей один аргумент (отображённое окно). Эта функция может быть использована для заполнения тела отображаемого окна некоторым содержимым, которое может зависеть от размеров отображаемого окна. Она вызывается *после* отображения буфера и *перед* применением записей window-height, window-width и preserve-size, которые могут изменить размер окна для подгонки его к вставленному содержимому.

По соглашению, записи window-height, window-width и preserve-size применяются после настройки буфера выбранного окна и только в том случае, если это окно никогда не отображало другой буфер ранее. Более точно, это означает, что окно должно быть либо создано текущим вызовом display-buffer, либо окно было создано ранее вызовом display-buffer для отображения буфера и никогда не использовалось для отображения другого буфера до его повторного использования текущим вызовом display-buffer.