Чтение одного события

Функции самого низкого уровня для ввода команд — read-event, read-char и read-char-exclusive.

Если вам нужна функция для чтения символа с помощью минибуфера, используйте read-char-from-minibuffer (см. Вопросы с несколькими вариантами ответа).

Функция: read-event &optional prompt inherit-input-method seconds

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

Возвращаемое событие может поступить непосредственно от пользователя или из клавиатурного макроса. Оно не декодируется системой кодирования ввода клавиатуры (см. Кодирование ввода-вывода терминала).

Если необязательный аргумент prompt не равен nil, он должен быть строкой, отображаемой в области эха в качестве подсказки. Если prompt равен nil или строке «""», read-event не отображает сообщение о том, что ожидает ввода; вместо этого она выводит подсказку посредством эха: отображает описания событий, которые привели к выполнению текущей команды или были ею прочитаны. См. Область эха.

Если inherit-input-method не равен nil, для ввода символов, не относящихся к ASCII, используется текущий метод ввода (если он задан). В противном случае обработка методом ввода при чтении этого события отключается.

Если cursor-in-echo-area не равен nil, read-event временно перемещает курсор в область эха, в конец отображаемого там сообщения. В противном случае read-event не перемещает курсор.

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

Если seconds равно nil, Emacs считается бездействующим, пока ожидает ввода от пользователя. Таймеры бездействия — созданные с помощью run-with-idle-timer (см. Таймеры бездействия) — могут срабатывать в этот период. Однако если seconds не равен nil, состояние бездействия не меняется. Если при вызове read-event Emacs активен, он останется активным на протяжении всего выполнения read-event; если Emacs бездействует (что возможно, если вызов происходит внутри таймера бездействия), он останется бездействующим.

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

Вот что произойдёт, если вызвать read-event, а затем нажать клавишу со стрелкой вправо:

(read-event)
     ⇒ right

Функция: read-char &optional prompt inherit-input-method seconds

Эта функция считывает и возвращает событие ввода символа. Если пользователь создаёт событие, не являющееся символом (например, щелчок мышью или событие клавиши функции), read-char сигнализирует об ошибке. Аргументы действуют так же, как в read-event.

Если у события есть модификаторы, Emacs пытается разрешить их и вернуть код соответствующего символа. Например, если пользователь вводит C-a, функция возвращает 1 — код символа «C-a» в ASCII. Если некоторые модификаторы нельзя отразить в коде символа, read-char оставляет соответствующие неразрешённым модификаторам биты установленными в возвращаемом событии. Например, если пользователь вводит C-M-a, функция возвращает 134217729 (8000001 в шестнадцатеричной системе), то есть «C-a» с установленным битом модификатора Meta. Это значение не является допустимым кодом символа: оно не проходит проверку characterp (см. Коды символов). Используйте event-basic-type (см. Классификация событий), чтобы получить код символа без битов модификаторов; используйте event-modifiers для проверки модификаторов в событии символа, возвращённом read-char.

В первом примере ниже пользователь вводит символ 1 (код ASCII 49). Во втором примере показано определение клавиатурного макроса, который вызывает read-char из минибуфера с помощью eval-expression. read-char считывает следующий символ клавиатурного макроса — 1. Затем eval-expression отображает возвращённое значение в области эха.

(read-char)
     ⇒ 49

;; We assume here you use M-: to evaluate this.
(symbol-function 'foo)
     ⇒ "^[:(read-char)^M1"

(execute-kbd-macro 'foo)
     -| 49
     ⇒ nil

Функция: read-char-exclusive &optional prompt inherit-input-method seconds

Эта функция считывает и возвращает событие ввода символа. Если пользователь создаёт событие, не являющееся событием символа, read-char-exclusive игнорирует его и считывает следующее событие, пока не получит символ. Аргументы действуют так же, как в read-event. Возвращаемое значение может включать биты модификаторов, как и в случае с read-char.

Ни одна из перечисленных выше функций не подавляет прерывание.

Переменная: num-nonmacro-input-events

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

Обратите внимание: в отличие от read-key-sequence, функции read-event, read-char и read-char-exclusive не выполняют преобразования, описанные в разделе Клавиатурные карты для преобразования последовательностей событий. Если вам нужно считать одну клавишу с учётом этих преобразований (например, клавиши клавиатуры в терминале или события мыши из xterm-mouse-mode), используйте функцию read-key:

Функция: read-key &optional prompt disable-fallbacks

Эта функция считывает одну клавишу. Она занимает промежуточное положение между read-key-sequence и read-event. В отличие от первой, она считывает одну клавишу, а не последовательность клавиш. В отличие от второй, она возвращает не необработанное событие, а декодирует и преобразует пользовательский ввод согласно input-decode-map, local-function-key-map и key-translation-map (см. Клавиатурные карты для преобразования последовательностей событий).

Аргумент prompt — это либо строка, отображаемая в области эха в качестве подсказки, либо nil, означающее, что подсказку отображать не нужно.

Если аргумент disable-fallbacks не равен nil, обычная логика обработки резервных вариантов для несвязанных клавиш в read-key-sequence не применяется. Это означает, что события нажатия кнопки мыши и многократного щелчка не будут отбрасываться, а local-function-key-map и key-translation-map не будут применяться. Если аргумент равен nil или не указан, отключается только резервное преобразование последнего события в нижний регистр.

Функция: read-char-choice prompt chars &optional inhibit-quit

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

Необязательный аргумент inhibit-quit по умолчанию игнорируется, но если переменная read-char-choice-use-read-key не равна nil, эта функция использует read-key вместо read-from-minibuffer; в этом случае значение inhibit-quit, не равное nil, означает, что события keyboard-quit игнорируются во время ожидания допустимого ввода. Кроме того, если read-char-choice-use-read-key не равен nil, привязка help-form (см. Функции справки) к значению, не равному nil, во время вызова этой функции заставляет её вычислить help-form и отобразить результат при нажатии пользователем help-char; после этого функция продолжает ожидать допустимый символ ввода или keyboard-quit.

Функция: read-multiple-choice prompt choices &optional help-string show-help long-form

Задаёт пользователю вопрос с несколькими вариантами ответа и возвращает выбранный вариант. prompt должна быть строкой, отображаемой в качестве подсказки.

choices — это ассоциативный список, в котором первый элемент каждой записи — символ, который может ввести пользователь, второй элемент — короткое название варианта, отображаемое при запросе ответа (при нехватке места оно может быть сокращено), а третий, необязательный элемент — более подробное объяснение, отображаемое в буфере справки по запросу пользователя.

Возвращаемое значение — это запись из choices, соответствующая введённому пользователем символу.

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

Если необязательный аргумент show-help не равен nil, буфер справки будет показан сразу, до ввода пользователя. Если аргумент является строкой, она используется в качестве имени буфера справки.

Если необязательный аргумент long-form не равен nil, пользователю потребуется вводить ответы полностью (используя completing-read), а не нажимать одну клавишу. Ответы должны совпадать со вторыми элементами значений в списке choices.

По умолчанию эта функция использует read-from-minibuffer (см. Чтение текстовых строк с помощью минибуфера) для чтения пользовательского ввода, но если переменная read-char-choice-use-read-key не равна nil, вместо неё используется read-key.

(read-multiple-choice
 "Continue connecting?"
 '((?a "always" "Accept certificate for this and future sessions.")
   (?s "session only" "Accept certificate this session only.")
   (?n "no" "Refuse to use certificate, close connection.")))

На графических терминалах для выделения совпадающих символов в строке названия используется начертание read-multiple-choice-face.