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

Функции самого низкого уровня для ввода команд — это 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, состояние бездействия остается неизменным. Если Emacs не бездействует при вызове read-event, он остается не бездействующим на протяжении всей работы 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, что является кодом ASCII символа ‘C-a’. Если некоторые модификаторы не могут быть отражены в коде символа, 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-key для чтения и возврата одного символа. Она игнорирует любой ввод, который не является членом chars, списка разрешенных символов. Необязательно, она также будет игнорировать события завершения ввода с клавиатуры, пока ожидает действительный ввод. Если вы свяжете help-form (см. Функции справки) с не-nil значением при вызове read-char-choice, то нажатие help-char приведет к вычислению help-form и отображению результата. Затем она продолжает ожидать действительный ввод символа или завершение ввода с клавиатуры.

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

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

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

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

Возвращаемое значение — соответствующее значение из choices.

(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 используется для выделения соответствующих символов в строке имени на графических терминалах.