Hooks for Window Scrolling and Changes — Elisp

Обработчики прокрутки и изменений окон

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

Переменная: window-scroll-functions

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

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

При использовании window-end эти функции должны соблюдать осторожность (см. Начальная и конечная позиции окна); если вам нужно актуальное значение, используйте аргумент update, чтобы гарантированно получить его.

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

Кроме того, можно использовать jit-lock-register для регистрации функции подсветки Font Lock, которая будет вызываться при повторной подсветке частей буфера из-за прокрутки окна или изменения его размера. См. Другие переменные Font Lock.

В оставшейся части раздела рассматриваются шесть обработчиков, которые вызываются во время повторного отображения, если обнаружено значительное изменение окна, не связанное с прокруткой. Для простоты эти обработчики и вызываемые ими функции далее будут совместно называться функциями изменения окон. Как и любой обработчик, их можно установить глобально или локально для буфера с помощью аргумента local функции add-hook (см. Настройка обработчиков) при установке обработчика.

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

Переменная: window-buffer-change-functions

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

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

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

(eq (window-old-buffer window) (current-buffer))

а для обнаружения того, что буфер теперь отображается в window, используйте вместо неё

(eq (window-buffer window) (current-buffer))

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

Переменная: window-size-change-functions

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

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

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

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

Переменная: window-selection-change-functions

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

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

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

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

Переменная: window-state-change-functions

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

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

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

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

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

Переменная: window-configuration-change-hook

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

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

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

Наконец, Emacs запускает обычный обработчик, обобщающий поведение window-state-change-functions.

Переменная: window-state-change-hook

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

Приложениям следует добавлять функцию в этот обработчик, только если они хотят реагировать на изменения, произошедшие в двух или более кадрах (или о которых было сообщено для двух или более кадров) с момента последнего повторного отображения. Во всех остальных случаях предпочтительнее добавлять функцию в window-state-change-functions.

Функции изменения окон вызываются во время повторного отображения для каждого кадра в следующем порядке: сначала выполняются все локальные для буфера функции изменения буфера окна, функции изменения размера окна, функции изменения выбранного окна и функции изменения состояния окна — именно в таком порядке. Затем в том же порядке вызываются функции, заданные значениями по умолчанию. После этого выполняются локальные для буфера функции изменения конфигурации окна, а за ними — функции, заданные значением по умолчанию для этих функций. Наконец, выполняются функции из window-state-change-hook.

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

Если флаг изменения состояния окна кадра установлен, во время следующего повторного отображения будут выполнены значения по умолчанию для window-state-change-functions (для этого кадра) и window-state-change-hook независимо от того, произошло ли в этом кадре фактическое изменение состояния окна. После выполнения любых функций этих обработчиков флаг сбрасывается для каждого кадра. Приложения могут устанавливать этот флаг и проверять его значение с помощью следующих функций.

Функция: set-frame-window-state-change &optional frame arg: Эта функция устанавливает флаг изменения состояния окна кадра frame, если arg не равен nil, и сбрасывает его в противном случае. frame должен быть действующим кадром; по умолчанию используется выбранный кадр.

Функция: frame-window-state-change &optional frame: Эта функция возвращает t, если флаг изменения состояния окна кадра frame установлен, и nil в противном случае. frame должен быть действующим кадром; по умолчанию используется выбранный кадр.

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

Функция: window-old-buffer &optional window: Эта функция возвращает буфер, отображавшийся в window при последнем выполнении функций изменения окон для кадра окна window. Если она возвращает nil, то window является либо внутренним окном, либо было создано позднее. Если она возвращает t, то в тот момент window не отображалось, но впоследствии было восстановлено из ранее сохранённой конфигурации окна. В противном случае возвращаемое значение — это буфер, отображавшийся в window в тот момент. Особый случай: если window было удалено, эта функция возвращает последний буфер, отображавшийся в window в тот момент. window может быть любым окном; по умолчанию используется выбранное окно.

Функция: window-old-pixel-width &optional window: Эта функция возвращает общую ширину window в пикселях на момент последнего выполнения функций изменения окон, когда window было действующим в своём кадре. Если window было создано позднее, возвращается ноль.

Функция: window-old-pixel-height &optional window: Эта функция возвращает общую высоту window в пикселях на момент последнего выполнения функций изменения окон, когда window было действующим в своём кадре. Если window было создано позднее, возвращается ноль.

Функция: window-old-body-pixel-width &optional window: Эта функция возвращает ширину текстовой области window в пикселях на момент последнего выполнения функций изменения окон, когда window было действующим в своём кадре. Если window было создано позднее, возвращается ноль.

Функция: window-old-body-pixel-height &optional window: Эта функция возвращает высоту текстовой области window в пикселях на момент последнего выполнения функций изменения окон, когда window было действующим в своём кадре. Если window было создано позднее, возвращается ноль.

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

Функция: frame-old-selected-window &optional frame: Эта функция возвращает окно кадра frame, выбранное при последнем выполнении функций изменения окон. Если аргумент опущен или равен nil, по умолчанию используется выбранный кадр frame.

Функция: old-selected-window: Эта функция возвращает окно, выбранное при последнем выполнении функций изменения окон.

Функция: old-selected-frame: Эта функция возвращает кадр, выбранный при последнем выполнении функций изменения окон.

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

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

Некоторые операции не приводят к вызову функций изменения окон. К ним относятся отображение другого буфера в окне минибуфера и любые изменения окна подсказки.
Функции изменения окон не должны создавать или удалять окна, изменять буфер, размер или состояние выбора любого окна, поскольку нет гарантии, что сведения о таком изменении будут переданы другим функциям изменения окон. Если такое изменение всё же необходимо, его следует выполнять только последней функцией в списке, заданном значением по умолчанию для window-state-change-hook.
При выполнении функций изменения окон можно использовать макросы, такие как save-window-excursion, with-selected-window или with-current-buffer.
Выполнение функций изменения окон не сохраняет и не восстанавливает данные совпадений. Если не выполняется window-configuration-change-hook, выбранное окно или кадр и текущий буфер также не сохраняются и не восстанавливаются.
Повторное отображение, вызвавшее выполнение функций изменения окон, может быть прервано. Если прерывание произойдёт до того, как функции изменения окон завершатся, они будут выполнены снова с прежними значениями, то есть так, как если бы повторное отображение не выполнялось. Если прерывание произойдёт позже, они будут выполнены с новыми значениями, то есть так, как если бы повторное отображение действительно состоялось.