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

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

Функция действий display-buffer-in-tab ищет вкладки в кадре или кадрах, заданных этим элементом, а также иначе интерпретирует значение nil.

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

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

window-width

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

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

window-size

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

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

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

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.

tab-name

Значение задаёт вкладку, в которой следует отобразить буфер. Этот элемент используется функцией display-buffer-in-new-tab и (при определённых условиях) функцией display-buffer-in-tab.

tab-group

Значение задаёт группу вкладок, используемую при создании новой вкладки, и переопределяет пользовательский параметр tab-bar-new-tab-group. Этот элемент используется функциями display-buffer-in-new-tab и display-buffer-in-tab.

По соглашению элементы 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.