---

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

Самыми низкоуровневыми функциями для ввода команд являются 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

;; Мы предполагаем, что вы используете M-: для вычисления этого.
(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.

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

Переменная: 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, означает игнорировать события прерывания с клавиатуры во время ожидания допустимого ввода. Кроме того, если read-char-choice-use-read-key не равен nil, привязка help-form (см. Функции помощи) к значению, не равному nil, во время вызова этой функции приводит к вычислению help-form и отображению результата, когда пользователь нажимает help-char; затем она продолжает ожидать допустимый вводной символ или прерывание с клавиатуры.

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

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

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

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

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

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

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

(read-multiple-choice
 "Продолжить подключение?"
 '((?a "всегда" "Принять сертификат для этого и будущих сеансов.")
   (?s "только сеанс" "Принять сертификат только для этого сеанса.")
   (?n "нет" "Отказаться от использования сертификата, закрыть соединение.")))

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