---

29.13.3 Альсты действий для отображения буфера

Альст действий — это ассоциативный список, сопоставляющий предопределённые символы, распознаваемые функциями действий, со значениями, которые эти функции должны соответствующим образом интерпретировать. При каждом вызове 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 означает рассматривать только окна на выбранном фрейме. (Фактически, на последнем использованном фрейме, не являющемся фреймом только с минибуфером.)
• visible означает рассматривать окна на всех видимых фреймах.
• 0 означает рассматривать окна на всех видимых или свёрнутых в иконку фреймах.
• Фрейм означает рассматривать окна только на этом фрейме.
• t означает рассматривать окна на всех фреймах. (Обратите внимание, что это значение редко является правильным выбором — оно может также вернуть фрейм всплывающей подсказки.)

Обратите внимание, что значение 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-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 — целое число, задающее высоту тела выбранного окна в строках фрейма.
• Если значение задаёт функцию, она вызывается с одним аргументом — выбранным окном. Функция должна отрегулировать высоту окна; её возвращаемое значение игнорируется. Подходящими функциями являются fit-window-to-buffer и shrink-window-if-larger-than-buffer, см. Изменение размеров окон.

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

window-width

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

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

window-size

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

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

Эта запись должна обрабатываться только при определённых условиях, которые указаны сразу после этого списка.

dedicated

Если не равно nil, такая запись указывает display-buffer пометить любое создаваемое окно как закреплённое за его буфером (см. Закреплённые окна). Это делается путём вызова 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

Значение определяет альст параметров фрейма для нового фрейма, если он создаётся. display-buffer-pop-up-frame является его единственным адресатом.

pop-up-frames

Значение управляет тем, может ли display-buffer отображать буферы, создавая новые фреймы. Оно имеет тот же смысл, что и переменная pop-up-frames, и имеет приоритет над ней в случае присутствия. Его основное предназначение — переопределить значение переменной, не равное nil, для конкретных буферов, которые пользователь предпочитает оставлять в выбранном фрейме.

parent-frame

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

child-frame-parameters

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

body-function

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

post-command-select-window

Если значение не равно nil, буфер, отображаемый display-buffer, выбирается после выполнения текущей команды путём запуска хука post-command-hook (см. Обзор цикла команд). Если значение равно nil, буфер, выбранный такими функциями, как pop-to-buffer, снимается с выбора, и окно, которое было выбрано до вызова этой функции, останется выбранным независимо от того, какие окна были выбраны впоследствии в пределах этой команды.

category

Если вызывающий display-buffer передаёт запись альста (category . symbol) в своём аргументе action, то вы можете сопоставить отображаемый буфер, используя тот же символ категории в части условия записей display-buffer-alist. См. buffer-match-p. Таким образом, если программа на Lisp использует определённый symbol в качестве категории при вызове display-buffer, пользователи могут настраивать отображение этих буферов, включая такую запись в display-buffer-alist.

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

Если не указана ни одна запись window-height, window-width или window-size, окно всё равно может быть автоматически изменено, если буфер является временным и включён temp-buffer-resize-mode, Временные отображения. В этом случае CDR записи window-height, window-width или window-size можно использовать для подавления или переопределения стандартного поведения temp-buffer-resize-mode для конкретных буферов или вызовов display-buffer.