@cindex keyboard events
There are two kinds of input you can get from the keyboard: ordinary
-keys, and function keys. Ordinary keys correspond to characters; the
-events they generate are represented in Lisp as characters. The event
-type of a character event is the character itself (an integer); see
+keys, and function keys. Ordinary keys correspond to (possibly
+modified) characters; the events they generate are represented in Lisp
+as characters. The event type of a character event is the character
+itself (an integer), which might have some modifier bits set; see
@ref{Classifying Events}.
@cindex modifier bits (of input character)
2**26
@end ifnottex
(assuming the terminal supports non-@acronym{ASCII}
-control characters).
+control characters), i.e.@: with the 27th bit set.
@item shift
The
@ifnottex
2**25
@end ifnottex
-bit in the character code indicates an @acronym{ASCII} control
-character typed with the shift key held down.
+bit (the 26th bit) in the character event code indicates an
+@acronym{ASCII} control character typed with the shift key held down.
For letters, the basic code itself indicates upper versus lower case;
for digits and punctuation, the shift key selects an entirely different
@ifnottex
2**25
@end ifnottex
-bit for those characters.
+bit for those character events.
However, @acronym{ASCII} provides no way to distinguish @kbd{C-A} from
@kbd{C-a}, so Emacs uses the
@ifnottex
2**24
@end ifnottex
-bit in the character code indicates a character
+bit in the character event code indicates a character
typed with the hyper key held down.
@item super
@ifnottex
2**23
@end ifnottex
-bit in the character code indicates a character
+bit in the character event code indicates a character
typed with the super key held down.
@item alt
@ifnottex
2**22
@end ifnottex
-bit in the character code indicates a character typed with the alt key
-held down. (The key labeled @key{Alt} on most keyboards is actually
-treated as the meta key, not this.)
+bit in the character event code indicates a character typed with the
+alt key held down. (The key labeled @key{Alt} on most keyboards is
+actually treated as the meta key, not this.)
@end table
It is best to avoid mentioning specific bit numbers in your program.
The modifiers list for a click event explicitly contains @code{click},
but the event symbol name itself does not contain @samp{click}.
+Similarly, the modifiers list for an @acronym{ASCII} control
+character, such as @samp{C-a}, contains @code{control}, even though
+reading such an event via @code{read-char} will return the value 1
+with the control modifier bit removed.
@end defun
@defun event-basic-type event
@end defun
@defun read-char &optional prompt inherit-input-method seconds
-This function reads and returns a character of command input. If the
+This function reads and returns a character input event. If the
user generates an event which is not a character (i.e., a mouse click or
function key event), @code{read-char} signals an error. The arguments
work as in @code{read-event}.
-In the first example, the user types the character @kbd{1} (@acronym{ASCII}
-code 49). The second example shows a keyboard macro definition that
-calls @code{read-char} from the minibuffer using @code{eval-expression}.
-@code{read-char} reads the keyboard macro's very next character, which
-is @kbd{1}. Then @code{eval-expression} displays its return value in
-the echo area.
+If the event has modifiers, Emacs attempts to resolve them and return
+the code of the corresponding character. For example, if the user
+types @kbd{C-a}, the function returns 1, which is the @acronym{ASCII}
+code of the @samp{C-a} character. If some of the modifiers cannot be
+reflected in the character code, @code{read-char} leaves the
+unresolved modifier bits set in the returned event. For example, if
+the user types @kbd{C-M-a}, the function returns 134217729, 8000001 in
+hex, i.e.@: @samp{C-a} with the Meta modifier bit set. This value is
+not a valid character code: it fails the @code{characterp} test
+(@pxref{Character Codes}). Use @code{event-basic-type}
+(@pxref{Classifying Events}) to recover the character code with the
+modifier bits removed; use @code{event-modifiers} to test for
+modifiers in the character event returned by @code{read-char}.
+
+In the first example below, the user types the character @kbd{1}
+(@acronym{ASCII} code 49). The second example shows a keyboard macro
+definition that calls @code{read-char} from the minibuffer using
+@code{eval-expression}. @code{read-char} reads the keyboard macro's
+very next character, which is @kbd{1}. Then @code{eval-expression}
+displays its return value in the echo area.
@example
@group
@end defun
@defun read-char-exclusive &optional prompt inherit-input-method seconds
-This function reads and returns a character of command input. If the
-user generates an event which is not a character,
+This function reads and returns a character input event. If the
+user generates an event which is not a character event,
@code{read-char-exclusive} ignores it and reads another event, until it
-gets a character. The arguments work as in @code{read-event}.
+gets a character. The arguments work as in @code{read-event}. The
+returned value may include modifier bits, as with @code{read-char}.
@end defun
None of the above functions suppress quitting.
DEFUN ("single-key-description", Fsingle_key_description,
Ssingle_key_description, 1, 2, 0,
- doc: /* Return a pretty description of command character KEY.
+ doc: /* Return a pretty description of a character event KEY.
Control characters turn into C-whatever, etc.
Optional argument NO-ANGLES non-nil means don't put angle brackets
-around function keys and event symbols. */)
+around function keys and event symbols.
+
+See `text-char-description' for describing character codes. */)
(Lisp_Object key, Lisp_Object no_angles)
{
USE_SAFE_ALLOCA;
/* This function cannot GC. */
DEFUN ("text-char-description", Ftext_char_description, Stext_char_description, 1, 1, 0,
- doc: /* Return a pretty description of file-character CHARACTER.
-Control characters turn into "^char", etc. This differs from
-`single-key-description' which turns them into "C-char".
-Also, this function recognizes the 2**7 bit as the Meta character,
-whereas `single-key-description' uses the 2**27 bit for Meta.
+ doc: /* Return the description of CHARACTER in standard Emacs notation.
+CHARACTER must be a valid character code that passes the `characterp' test.
+Control characters turn into "^char", the 2**7 bit is treated as Meta, etc.
+This differs from `single-key-description' which accepts character events,
+and thus doesn't enforce the `characterp' condition, turns control
+characters into "C-char", and uses the 2**27 bit for Meta.
See Info node `(elisp)Describing Characters' for examples. */)
(Lisp_Object character)
{
}
DEFUN ("read-char", Fread_char, Sread_char, 0, 3, 0,
- doc: /* Read a character from the command input (keyboard or macro).
+ doc: /* Read a character event from the command input (keyboard or macro).
It is returned as a number.
-If the character has modifiers, they are resolved and reflected to the
-character code if possible (e.g. C-SPC -> 0).
+If the event has modifiers, they are resolved and reflected in the
+returned character code if possible (e.g. C-SPC yields 0 and C-a yields 97).
+If some of the modifiers cannot be reflected in the character code, the
+returned value will include those modifiers, and will not be a valid
+character code: it will fail the `characterp' test. Use `event-basic-type'
+to recover the character code with the modifiers removed.
If the user generates an event which is not a character (i.e. a mouse
click or function key event), `read-char' signals an error. As an
}
DEFUN ("read-char-exclusive", Fread_char_exclusive, Sread_char_exclusive, 0, 3, 0,
- doc: /* Read a character from the command input (keyboard or macro).
+ doc: /* Read a character event from the command input (keyboard or macro).
It is returned as a number. Non-character events are ignored.
-If the character has modifiers, they are resolved and reflected to the
-character code if possible (e.g. C-SPC -> 0).
+If the event has modifiers, they are resolved and reflected in the
+returned character code if possible (e.g. C-SPC yields 0 and C-a yields 97).
+If some of the modifiers cannot be reflected in the character code, the
+returned value will include those modifiers, and will not be a valid
+character code: it will fail the `characterp' test. Use `event-basic-type'
+to recover the character code with the modifiers removed.
If the optional argument PROMPT is non-nil, display that as a prompt.
If the optional argument INHERIT-INPUT-METHOD is non-nil and some
projects / emacs.git / commitdiff