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

Функция действия — это функция, которую display-buffer вызывает для выбора окна отображения буфера. Функции действия принимают два аргумента: buffer, буфер для отображения, и alist, список действий (см. Списки действий отображения буфера). Они должны возвращать окно, отображающее buffer, если успешно, и nil в случае неудачи.

Следующие основные функции действия определены в Emacs.

Функция: display-buffer-same-window buffer alist

Эта функция пытается отобразить buffer в выбранном окне. Она терпит неудачу, если выбранное окно является минибуферным окном или выделено для другого буфера (см. Выделенные окна). Она также терпит неудачу, если alist содержит не-nil inhibit-same-window запись.

Функция: display-buffer-reuse-window buffer alist

Эта функция пытается отобразить buffer, найдя окно, которое уже отображает его. Окна на выбранной вкладке предпочтительнее окон на других вкладках.

Если alist содержит не-nil inhibit-same-window запись, выбранное окно не подходит для повторного использования. Набор вкладок, в которых необходимо искать окно, отображающее buffer, может быть указан с помощью записи в списке действий reusable-frames. Если alist не содержит записи reusable-frames, эта функция ищет только на выбранной вкладке.

Если эта функция выбирает окно на другой вкладке, она делает эту вкладку видимой и, если alist не содержит записи inhibit-switch-frame, поднимает эту вкладку, если необходимо.

Функция: display-buffer-reuse-mode-window buffer alist

Эта функция пытается отобразить buffer, найдя окно, которое отображает буфер в заданном режиме.

Если alist содержит запись mode, ее значение определяет основной режим (символ) или список основных режимов. Если alist не содержит записи mode, вместо этого используется текущий основной режим buffer. Окно является кандидатом, если оно отображает буфер, чья мода происходит от одного из указанных режимов.

Поведение также контролируется записями alist для inhibit-same-window, reusable-frames и inhibit-switch-frame, как и display-buffer-reuse-window.

Функция: display-buffer-pop-up-window buffer alist

Эта функция пытается отобразить buffer, разделив самое большое или наименее недавно используемое окно (обычно расположенное на выбранной вкладке). Она фактически выполняет разделение, вызывая функцию, указанную в split-window-preferred-function (см. Выбор параметров окна).

Размер нового окна можно настроить, предоставив записи window-height и window-width в alist. Если alist содержит запись preserve-size, Emacs также попытается сохранить размер нового окна во время будущих операций изменения размера (см. Сохранение размеров окна).

Функция терпит неудачу, если ни одно окно нельзя разделить. Чаще всего это происходит потому, что ни одно окно недостаточно велико, чтобы позволить разделение. Уменьшение значений split-height-threshold или split-width-threshold может помочь в этом отношении. Разделение также терпит неудачу, когда у выбранной вкладки есть параметр вкладки unsplittable; см. Параметры буфера.

Функция: display-buffer-in-previous-window buffer alist

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

Если alist содержит не-nil inhibit-same-window запись, выбранное окно не подходит для использования. Выделенное окно пригодно только в том случае, если оно уже показывает buffer. Если alist содержит запись previous-window, окно, указанное этой записью, пригодно для использования даже если оно никогда раньше не показывало buffer.

Если alist содержит запись reusable-frames (см. Списки действий отображения буфера), ее значение определяет, какие вкладки необходимо искать для подходящего окна. Если alist не содержит записи reusable-frames, эта функция ищет только на выбранной вкладке, если display-buffer-reuse-frames и pop-up-frames оба nil; она ищет все вкладки на текущем терминале, если хотя бы одна из этих переменных не-nil.

Если несколько окон подходят для использования в соответствии с этими правилами, эта функция делает выбор в следующем порядке предпочтения:

• Окно, указанное любой записью previous-window alist, при условии, что это не выбранное окно.
• Окно, которое ранее показывало buffer, при условии, что это не выбранное окно.
• Выбранное окно, если оно указано записью previous-window alist или ранее показывало buffer.

Функция: display-buffer-use-some-window buffer alist

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

Функция: display-buffer-use-least-recent-window buffer alist

Эта функция похожа на display-buffer-use-some-window, но не будет повторно использовать текущее окно и будет использовать окно, к которому последний раз обращались.

Функция: display-buffer-in-direction buffer alist

Эта функция пытается отобразить buffer в заданном alist местоположении. Для этого alist должен содержать запись direction, значением которой является один из left, above (или up), right и below (или down). Другие значения обычно интерпретируются как below.

Если alist также содержит запись window, ее значение определяет окно-ссылку. Это значение может быть специальным символом, например main, который обозначает основное окно выбранной вкладки (см. Параметры и функции бокового окна) или root, обозначающее корневое окно выбранной вкладки (см. Окна и вкладки). Это также может быть любое другое допустимое окно. Любое другое значение (или полное отсутствие записи window) означает использование выбранного окна в качестве окна-ссылки.

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

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

Если окно-ссылка внутреннее, повторно используемое окно должно совмещать с ним сторону, указанную записью direction. Поэтому, если, например, окно-ссылка является корневым окном вкладки, и значение записи direction равно left, повторно используемое окно должно быть слева от вкладки. Это означает, что левая граница выбранного окна и левая граница окна-ссылки будут одинаковыми.

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

Четыре специальных значения для записей direction позволяют неявно указать основное окно выбранной вкладки в качестве окна-ссылки: leftmost, top, rightmost и bottom. Это означает, что вместо, например, (direction . left) (window . main) можно просто указать (direction . leftmost). Существующая запись window alist игнорируется в таких случаях.

Функция: display-buffer-below-selected buffer alist

Эта функция пытается отобразить buffer в окне ниже выбранного окна. Если ниже выбранного окна есть окно, которое уже отображает buffer, оно будет повторно использовано.

Если такого окна нет, эта функция пытается создать новое окно путем разделения выбранного, и отображает buffer там. Она также попытается настроить размер этого окна, если alist содержит соответствующую запись window-height или window-width, см. выше.

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

Если alist содержит запись window-min-height, эта функция гарантирует, что используемое окно будет или сможет стать по крайней мере таким же высоким, как указано в значении этой записи. Обратите внимание, что это только гарантия. Чтобы фактически изменить размер используемого окна, alist также должен содержать соответствующую запись window-height.

Функция: display-buffer-at-bottom buffer alist

Эта функция пытается отобразить buffer в окне внизу выбранной вкладки.

Это либо пытается разделить окно внизу вкладки, или корневое окно вкладки, или повторно использовать существующее окно внизу выбранной вкладки.

Функция: display-buffer-pop-up-frame buffer alist

Эта функция создаёт новый фрейм и отображает буфер в окне этого фрейма. Фрейм создаётся путём вызова функции, указанной в pop-up-frame-function (см. Выбор параметров окна). Если alist содержит запись pop-up-frame-parameters, соответствующее значение добавляется в параметры вновь созданного фрейма.

Функция: display-buffer-in-child-frame buffer alist

Эта функция пытается отобразить buffer в дочернем фрейме (см. Дочерние фреймы) выбранного фрейма, либо повторно используя существующий дочерний фрейм, либо создавая новый. Если alist имеет запись, отличную от nil child-frame-parameters, соответствующее значение представляет собой список параметров фрейма, которые будут переданы новому фрейму. По умолчанию предоставляется параметр parent-frame, указывающий на выбранный фрейм. Если дочерний фрейм должен стать дочерним фреймом другого фрейма, соответствующая запись должна быть добавлена в alist.

Внешний вид дочерних фреймов в значительной степени зависит от параметров, предоставленных через alist. Рекомендуется использовать, как минимум, пропорции для указания размера (см. Параметры размера) и положения (см. Параметры позиции) дочернего фрейма, а также добавить параметр keep-ratio (см. Параметры взаимодействия фреймов), чтобы убедиться, что дочерний фрейм остаётся видимым. Для других параметров, которые следует учесть, см. Дочерние фреймы.

Функция: display-buffer-use-some-frame buffer alist

Эта функция пытается отобразить buffer, найдя фрейм, который удовлетворяет определённому условию (по умолчанию – любой фрейм, кроме выбранного).

Если эта функция выбирает окно на другом фрейме, она делает этот фрейм видимым и, если в alist нет записи inhibit-switch-frame, поднимает этот фрейм при необходимости.

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

Если alist имеет запись, отличную от nil inhibit-same-window, выбранное окно не используется; таким образом, если у выбранного фрейма есть только одно окно, оно не используется.

Функция: display-buffer-no-window buffer alist

Если alist содержит запись, отличную от nil allow-no-window, функция не отображает buffer и возвращает символ fail. Это единственное исключение из правила, что функция действия возвращает либо nil, либо окно, отображающее buffer. Если в alist нет такой записи allow-no-window, функция возвращает nil.

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

Предполагается, что когда вызывающий display-buffer указывает запись, отличную от nil allow-no-window, он также способен обработать возвращаемое значение nil.

Две другие функции действия описаны в соответствующих разделах – display-buffer-in-side-window (см. Отображение буферов в боковых окнах) и display-buffer-in-atom-window (см. Атомарные окна).