Временное отображение

Временное отображение используется программами на Lisp для вывода данных в буфер с последующим показом пользователю для ознакомления, а не для редактирования. Эта возможность используется многими командами справки.

Макрос: with-output-to-temp-buffer buffer-name body…

Эта функция выполняет формы из body, направляя любой вывод, который они печатают, в буфер с именем buffer-name. Если буфер необходимо создать, он создаётся, а затем переводится в режим справки. (См. аналогичную форму with-temp-buffer-window ниже.) В конце буфер отображается в некотором окне, но это окно не выбирается.

Если формы в body не изменяют основной режим выходного буфера, так что после их выполнения он остаётся в режиме справки, то with-output-to-temp-buffer в конце делает этот буфер доступным только для чтения, а также сканирует его, чтобы превратить имена функций и переменных в кликабельные перекрёстные ссылки. Подробнее см. Советы по строкам документации, в частности раздел о гиперссылках в строках документации.

Строка buffer-name задаёт временный буфер, который необязательно должен уже существовать. Аргумент должен быть строкой, а не буфером. Сначала буфер очищается (без каких-либо вопросов), а после завершения with-output-to-temp-buffer помечается как неизменённый.

with-output-to-temp-buffer привязывает standard-output к временному буферу, а затем вычисляет формы в body. Вывод, создаваемый функциями вывода Lisp внутри body, по умолчанию направляется в этот буфер (однако отображение на экране и сообщения в области эха, хотя в общем смысле слова они и являются «выводом», не затрагиваются). См. Функции вывода.

Для настройки поведения этой конструкции доступны несколько хуков; они перечислены ниже.

Возвращается значение последней формы в body.

---------- Buffer: foo ----------
 This is the contents of foo.
---------- Buffer: foo ----------

(with-output-to-temp-buffer "foo"
    (print 20)
    (print standard-output))
⇒ #<buffer foo>

---------- Buffer: foo ----------

20

#<buffer foo>

---------- Buffer: foo ----------

Пользовательская настройка: temp-buffer-show-function

Если значение этой переменной не равно nil, with-output-to-temp-buffer вызывает её как функцию для отображения буфера справки. Функция получает один аргумент — буфер, который нужно отобразить.

Этой функции рекомендуется выполнять temp-buffer-show-hook так же, как это обычно делает with-output-to-temp-buffer, внутри save-selected-window, когда выбранное окно и буфер являются текущими.

Переменная: temp-buffer-setup-hook

Этот обычный хук запускается with-output-to-temp-buffer перед вычислением body. Во время выполнения хука текущим является временный буфер. Обычно этот хук настраивают так, чтобы функция переводила буфер в режим справки.

Переменная: temp-buffer-show-hook

Этот обычный хук запускается with-output-to-temp-buffer после отображения временного буфера. Во время выполнения хука текущим является временный буфер, а выбранным — окно, в котором он отображается.

Макрос: with-temp-buffer-window buffer-or-name action quit-function body…

Этот макрос похож на with-output-to-temp-buffer. Как и эта конструкция, он выполняет body, направляя любой вывод в буфер с именем buffer-or-name, и отображает этот буфер в некотором окне. Однако, в отличие от with-output-to-temp-buffer, он не переводит буфер автоматически в режим справки.

Аргумент buffer-or-name задаёт временный буфер. Это может быть либо уже существующий буфер, либо строка; в последнем случае при необходимости создаётся буфер с таким именем. После завершения with-temp-buffer-window буфер помечается как неизменённый и доступный только для чтения.

Этот макрос не вызывает temp-buffer-show-function. Вместо этого он передаёт аргумент action функции display-buffer (см. Выбор окна для отображения буфера), чтобы отобразить буфер.

Возвращается значение последней формы в body, если не указан аргумент quit-function. В этом случае он вызывается с двумя аргументами: окном, в котором отображается буфер, и результатом выполнения body. Тогда окончательным возвращаемым значением становится результат, возвращённый quit-function.

Этот макрос использует обычные хуки temp-buffer-window-setup-hook и temp-buffer-window-show-hook вместо аналогичных хуков, запускаемых with-output-to-temp-buffer.

Две описанные далее конструкции в основном идентичны with-temp-buffer-window, но отличаются от него следующим образом:

Макрос: with-current-buffer-window buffer-or-name action quit-function &rest body

Этот макрос похож на with-temp-buffer-window, но, в отличие от него, делает буфер, заданный buffer-or-name, текущим на время выполнения body.

Размер окна с временным буфером можно подогнать под размер буфера с помощью следующего режима:

Пользовательская настройка: temp-buffer-resize-mode

Когда этот второстепенный режим включён, размеры окон с временными буферами автоматически подгоняются под содержимое буферов.

Размер окна изменяется только в том случае, если оно было специально создано для этого буфера. В частности, размеры окон, в которых до этого отображался другой буфер, не изменяются. По умолчанию этот режим использует для изменения размеров fit-window-to-buffer (см. Изменение размеров окон). Можно указать другую функцию, настроив параметры temp-buffer-max-height и temp-buffer-max-width ниже.

Действие этой настройки можно переопределить, задав подходящую запись списка действий window-height, window-width или window-size для display-buffer (см. Списки действий для отображения буфера).

Пользовательская настройка: temp-buffer-max-height

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

Пользовательская настройка: temp-buffer-max-width

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

Следующая функция использует текущий буфер для временного отображения:

Функция: momentary-string-display string position &optional char message

Эта функция на короткое время отображает string в текущем буфере в позиции position. Она не влияет на список отмены или состояние изменения буфера.

Временное отображение сохраняется до следующего события ввода. Если следующим событием ввода является char, momentary-string-display игнорирует его и возвращает управление. В противном случае это событие остаётся в буфере для последующего использования в качестве ввода. Таким образом, нажатие char просто уберёт строку с экрана, а нажатие, например, C-f уберёт строку с экрана и затем (предположительно) переместит точку вперёд. По умолчанию аргумент char равен пробелу.

Возвращаемое значение momentary-string-display не имеет смысла.

Если строка string не содержит управляющих символов, ту же задачу можно решить более универсальным способом: создать (а затем удалить) оверлей со свойством before-string. См. Свойства оверлеев.

Если message не равно nil, оно отображается в области эха, пока string отображается в буфере. Если оно равно nil, выводится сообщение по умолчанию с предложением нажать char, чтобы продолжить.

В этом примере точка изначально находится в начале второй строки:

---------- Buffer: foo ----------
This is the contents of foo.
∗Second line.
---------- Buffer: foo ----------

(momentary-string-display
  "**** Important Message! ****"
  (point) ?\r
  "Type RET when done reading")
⇒ t

---------- Buffer: foo ----------
This is the contents of foo.
**** Important Message! ****Second line.
---------- Buffer: foo ----------

---------- Echo Area ----------
Type RET when done reading
---------- Echo Area ----------