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

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

Макрос: with-output-to-temp-buffer имя-буфера тело…

Эта функция выполняет формы в теле, обеспечивая вставку любого вывода, который они печатают, в буфер с именем имя-буфера, который создается при необходимости, и переводится в режим справки. (См. аналогичную форму ниже.) Наконец, буфер отображается в некотором окне, но это окно не выбирается.

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

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

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

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

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

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

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

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

Макрос: with-temp-buffer-window буфер-или-имя действие функция-выхода тело…

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

Аргумент буфер-или-имя определяет временный буфер. Он может быть либо буфером, который должен уже существовать, либо строкой, в этом случае буфер с этим именем создается при необходимости. Буфер помечается как не измененный и только для чтения, когда with-temp-buffer-window завершает работу.

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

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

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

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

Макрос: with-current-buffer-window буфер-или-имя действие функция-выхода &rest тело

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

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

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

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

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

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

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

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

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

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

Функция: momentary-string-display строка позиция &опционально символ сообщение

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

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

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

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

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

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

---------- 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 ----------