Commit 5cf282d6 authored by Eli Zaretskii's avatar Eli Zaretskii

Clarify documentation of functions reading character events

* doc/lispref/help.texi (Describing Characters):
* doc/lispref/commands.texi (Keyboard Events)
(Reading One Event, Classifying Events): Make the distinction
between characters and character events more explicit.

* src/keymap.c (Ftext_char_description)
(Fsingle_key_description):
* src/lread.c (Fread_char, Fread_char_exclusive): Doc fixes,
to make a clear distinction between a character input event
and a character code.  (Bug#32562)
parent 96281c5e
......@@ -1076,9 +1076,10 @@ the current Emacs session. If a symbol has not yet been so used,
@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)
......@@ -1123,7 +1124,7 @@ for @kbd{%} plus
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
......@@ -1133,8 +1134,8 @@ 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
......@@ -1146,7 +1147,7 @@ character with a different basic code. In order to keep within the
@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
......@@ -1167,7 +1168,7 @@ 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
......@@ -1178,7 +1179,7 @@ The
@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
......@@ -1189,9 +1190,9 @@ The
@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.
......@@ -1949,6 +1950,10 @@ Here are some examples:
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
......@@ -2545,17 +2550,31 @@ right-arrow function key:
@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
......@@ -2577,10 +2596,11 @@ the echo area.
@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.
......
......@@ -556,13 +556,13 @@ brackets.
@defun text-char-description character
This function returns a string describing @var{character} in the
standard Emacs notation for characters that appear in text---like
@code{single-key-description}, except that control characters are
represented with a leading caret (which is how control characters in
Emacs buffers are usually displayed). Another difference is that
@code{text-char-description} recognizes the 2**7 bit as the Meta
character, whereas @code{single-key-description} uses the 2**27 bit
for Meta.
standard Emacs notation for characters that can appear in text---like
@code{single-key-description}, except that the argument must be a
valid character code that passes a @code{characterp} test
(@pxref{Character Codes}), control characters are represented with a
leading caret (which is how control characters in Emacs buffers are
usually displayed), and the 2**7 bit is treated as the Meta bit,
whereas @code{single-key-description} uses the 2**27 bit for Meta.
@smallexample
@group
......
......@@ -2205,10 +2205,12 @@ push_key_description (EMACS_INT ch, char *p)
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;
......@@ -2282,11 +2284,12 @@ push_text_char_description (register unsigned int c, register char *p)
/* 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)
{
......
......@@ -735,10 +735,14 @@ read_filtered_event (bool no_switch_frame, bool ascii_required,
}
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
......@@ -785,10 +789,14 @@ floating-point value. */)
}
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
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment