Отображение сообщений в области эха

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

Функция: message format-string &rest arguments

Эта функция отображает сообщение в области эха. format-string — это строка формата, а arguments — объекты для спецификаторов формата, как в функции format-message (см. Форматирование строк). Полученная строка формата отображается в области эха; если она содержит свойства текста face, она отображается с указанными начертаниями (см. Начертания). Строка также добавляется в буфер *Messages*, но без свойств текста (см. Запись сообщений в *Messages*).

Как правило, обратный апостроф и апостроф в строке формата преобразуются в соответствующие парные типографские кавычки, например, "Missing `%s'" может превратиться в "Missing ‘foo’". О том, как управлять этим преобразованием или отключить его, см. Стиль кавычек в тексте.

В пакетном режиме сообщение выводится в стандартный поток ошибок с последующим символом новой строки.

Если inhibit-message не равно nil, сообщение не отображается в области эха, а только записывается в «*Messages*».

Если format-string равно nil или пустой строке, message очищает область эха; если область эха была автоматически расширена, она возвращается к обычному размеру. Если активен минибуфер, его содержимое немедленно снова отображается на экране.

(message "Reverting `%s'..." (buffer-name))
 -| Reverting ‘subr.el’...
⇒ "Reverting ‘subr.el’..."

---------- Echo Area ----------
Reverting ‘subr.el’...
---------- Echo Area ----------

Чтобы автоматически отображать сообщение в области эха или во всплывающем буфере в зависимости от его размера, используйте display-message-or-buffer (см. ниже).

Предупреждение: Если вы хотите использовать собственную строку сообщения без изменений, не пишите просто (message string). Если string содержит «%», «`» или «'», форматирование строки может измениться, что приведёт к нежелательным результатам. Вместо этого используйте (message "%s" string).

Следующие средства позволяют пользователям и программам на Lisp управлять отображением сообщений в области эха.

Переменная: set-message-function

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

Значение по умолчанию вызывает set-minibuffer-message, описанную ниже.

Переменная: clear-message-function

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

Обычно эта функция вызывается при поступлении следующего события ввода после отображения сообщения в области эха. Предполагается, что функция очищает сообщение, отображённое соответствующей функцией, указанной в set-message-function, но это необязательно. Если функция должна оставить область эха неочищенной, она должна вернуть символ dont-clear-message; любое другое значение приведёт к очистке области эха.

Значение по умолчанию — функция, которая очищает сообщение, отображённое в активном минибуфере.

Параметр пользователя: set-message-functions

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

Ниже описаны три полезные функции, которые можно включить в список — значение этого параметра.

Функция: set-minibuffer-message message

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

По умолчанию эта функция является единственным элементом списка в set-message-functions.

Функция: inhibit-message message

Если сообщение message для области эха соответствует любому регулярному выражению в списке — значении параметра пользователя inhibit-message-regexps, эта функция подавляет отображение сообщения и возвращает значение, не равное nil и не являющееся строкой. Поэтому, если эта функция находится в списке set-message-functions, остальные функции списка не будут вызваны, когда message соответствует регулярным выражениям из inhibit-message-regexps. Чтобы соответствующее message никогда не отображалось, поместите эту функцию первым элементом списка в set-message-functions.

Функция: set-multi-message message

Эта функция накапливает несколько сообщений для области эха, выданных одно за другим, и возвращает их в виде одной строки, в которой отдельные сообщения разделены символами новой строки. Можно накопить до multi-message-max последних сообщений. Накопленные сообщения отбрасываются, если с момента выдачи первого сообщения прошло более multi-message-timeout секунд.

Переменная: inhibit-message

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

Макрос: with-temp-message message &rest body

Эта конструкция временно отображает сообщение в области эха во время выполнения body. Она отображает message, выполняет body, а затем возвращает значение последней формы тела, восстанавливая предыдущее содержимое области эха.

Функция: message-or-box format-string &rest arguments

Эта функция отображает сообщение, как message, но может вывести его в диалоговом окне вместо области эха. Если эта функция вызывается в команде, запущенной с помощью мыши, — точнее, если last-nonmenu-event (см. Информация от цикла команд) равно nil или является списком, — для отображения сообщения используется диалоговое окно или всплывающее меню. В противном случае используется область эха. (Этот же критерий применяется в y-or-n-p для аналогичного выбора; см. Запросы с ответом «да» или «нет».)

Можно принудительно использовать мышь или область эха, связав last-nonmenu-event с подходящим значением на время вызова.

Функция: message-box format-string &rest arguments

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

Функция: display-message-or-buffer message &optional buffer-name action frame

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

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

Если message — строка, необязательный аргумент buffer-name задаёт имя буфера, используемого для её отображения во всплывающем буфере; по умолчанию это *Message*. Если message — строка, отображённая в области эха, не определено, вставляется ли её содержимое в буфер в любом случае.

Необязательные аргументы action и frame используются так же, как в display-buffer, и применяются только при отображении буфера.

Функция: current-message

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