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

Функция-действие — это функция, которую вызывает 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, при необходимости поднимает его.

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

Функция: 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 (см. Дополнительные параметры отображения буферов).

Размер нового окна можно настроить, добавив в alist записи window-height и window-width. Если 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, выбрав существующее окно и выведя буфер в нём. Сначала она пытается найти давно не использовавшееся окно (см. Циклический порядок окон) в любом кадре, заданном записью lru-frames в alist; если такой записи нет, используется выбранный кадр. Она также отдаёт предпочтение окнам, удовлетворяющим ограничениям, заданным записями window-min-width и window-min-height в alist; если запись window-min-width отсутствует, предпочтение отдаётся окнам на всю ширину. Наконец, функция не возвращает окно, время использования которого больше значения, заданного любой записью lru-time в alist.

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

Описанное выше поведение соответствует случаю, когда запись some-window в alist имеет значение lru или nil, установленное по умолчанию. Ещё одно возможное значение — mru. Например, если для display-buffer-base-action задано значение (nil . ((some-window . mru))), эта функция будет отдавать предпочтение окну, использовавшемуся последним. Тогда несколько буферов, отображаемых при последовательных вызовах display-buffer, будут появляться в одном и том же окне. Рассмотрим конфигурацию из трёх или более окон, в которой пользователь хочет последовательно просматривать в невыбранном окне результаты запроса, распределённые по нескольким буферам. При стратегии lru Emacs может постоянно выбирать другое окно, поскольку наименее недавно использовавшееся окно меняется при каждом вызове display-buffer-use-some-window. При стратегии mru выбранное окно всегда оставалось бы одним и тем же, обеспечивая предсказуемое поведение для пользователя.

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

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

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

Функция: 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-full-frame buffer alist

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

Функция: 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-in-new-tab buffer alist

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

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

Если запись tab-name отсутствует или имеет значение nil, новая вкладка создаётся без явного имени.

Если alist содержит запись nil, отличную от tab-group, она задаёт группу вкладки, переопределяя пользовательский параметр tab-bar-new-tab-group. Значением этой записи также может быть строка или функция, которая вызывается так же, как tab-name.

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

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

Если alist содержит запись nil, отличную от reusable-frames, то в кадрах, указанных её значением, ищется существующая вкладка, в которой уже отображается буфер. Возможные значения reusable-frames:

• t означает рассматривать все существующие кадры.
• visible означает рассматривать все видимые кадры.
• 0 означает рассматривать все кадры на текущем терминале.
• Кадр означает рассматривать только этот кадр.
• Любое другое значение, отличное от nil, означает рассматривать выбранный кадр.
• nil означает не искать кадры (равносильно отсутствию этой записи). Обратите внимание, что это отличается от обычного значения nil для записи reusable-frames в списке действий отображения буфера.

Если alist содержит запись nil, отличную от ignore-current-tab, то при поиске повторно используемой вкладки текущая вкладка пропускается. В противном случае текущая вкладка используется в первую очередь, если в ней уже отображается буфер.

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

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

Если создаётся новая вкладка и alist содержит запись nil, отличную от tab-group, она задаёт группу вкладки, переопределяя пользовательский параметр tab-bar-new-tab-group. Значением этой записи также может быть строка или функция, которая вызывается так же, как tab-name.

Функция: 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 (см. Атомарные окна).