From 1ada2e55c700e8971a759241c0935060542c8179 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 21 Jul 2012 17:48:17 +0300 Subject: [PATCH] Improve documentation of special events and of the "e" interactive spec. doc/lispref/commands.texi (Special Events): Mention language-change event. (Input Events, Interactive Codes): doc/lispref/keymaps.texi (Key Sequences): Mention events that are non-keyboard but also non-mouse events. --- doc/lispref/ChangeLog | 7 +++++++ doc/lispref/commands.texi | 28 +++++++++++++++++----------- doc/lispref/keymaps.texi | 10 ++++++---- 3 files changed, 30 insertions(+), 15 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index bc01d64c509..addf622d21d 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,10 @@ +2012-07-21 Eli Zaretskii + + * commands.texi (Special Events): Mention language-change event. + (Input Events, Interactive Codes): + * keymaps.texi (Key Sequences): Mention events that are + non-keyboard but also non-mouse events. + 2012-07-17 Chong Yidong * text.texi (Insertion): Document insert-char changes. diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index a5fb4638c9d..7e24de94fbe 100644 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@ -379,9 +379,14 @@ current buffer, @code{default-directory} (@pxref{File Name Expansion}). Existing, Completion, Default, Prompt. @item e -The first or next mouse event in the key sequence that invoked the command. -More precisely, @samp{e} gets events that are lists, so you can look at -the data in the lists. @xref{Input Events}. No I/O. +The first or next non-keyboard event in the key sequence that invoked +the command. More precisely, @samp{e} gets events that are lists, so +you can look at the data in the lists. @xref{Input Events}. No I/O. + +You use @samp{e} for mouse events and for special system events +(@pxref{Misc Events}). The event list that the command receives +depends on the event. @xref{Input Events}, which describes the forms +of the list for each event in the corresponding subsections. You can use @samp{e} more than once in a single command's interactive specification. If the key sequence that invoked the command has @@ -972,9 +977,10 @@ moving point out of these sequences is completely turned off. @cindex input events The Emacs command loop reads a sequence of @dfn{input events} that -represent keyboard or mouse activity. The events for keyboard activity -are characters or symbols; mouse events are always lists. This section -describes the representation and meaning of input events in detail. +represent keyboard or mouse activity, or system events sent to Emacs. +The events for keyboard activity are characters or symbols; other +events are always lists. This section describes the representation +and meaning of input events in detail. @defun eventp object This function returns non-@code{nil} if @var{object} is an input event @@ -2840,11 +2846,11 @@ immediately after they are read, and this is the way for the event's definition to find the actual event. The events types @code{iconify-frame}, @code{make-frame-visible}, -@code{delete-frame}, @code{drag-n-drop}, and user signals like -@code{sigusr1} are normally handled in this way. The keymap which -defines how to handle special events---and which events are -special---is in the variable @code{special-event-map} (@pxref{Active -Keymaps}). +@code{delete-frame}, @code{drag-n-drop}, @code{language-change}, and +user signals like @code{sigusr1} are normally handled in this way. +The keymap which defines how to handle special events---and which +events are special---is in the variable @code{special-event-map} +(@pxref{Active Keymaps}). @node Waiting @section Waiting for Elapsed Time or Input diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi index ac3d9e47580..ad7092a9ed7 100644 --- a/doc/lispref/keymaps.texi +++ b/doc/lispref/keymaps.texi @@ -45,7 +45,8 @@ is found. The whole process is called @dfn{key lookup}. A @dfn{key sequence}, or @dfn{key} for short, is a sequence of one or more input events that form a unit. Input events include -characters, function keys, and mouse actions (@pxref{Input Events}). +characters, function keys, mouse actions, or system events external to +Emacs, such as @code{iconify-frame} (@pxref{Input Events}). The Emacs Lisp representation for a key sequence is a string or vector. Unless otherwise stated, any Emacs Lisp function that accepts a key sequence as an argument can handle both representations. @@ -62,9 +63,10 @@ sequence is the concatenation of the string representations of the constituent events; thus, @code{"\C-xl"} represents the key sequence @kbd{C-x l}. - Key sequences containing function keys, mouse button events, or -non-@acronym{ASCII} characters such as @kbd{C-=} or @kbd{H-a} cannot be -represented as strings; they have to be represented as vectors. + Key sequences containing function keys, mouse button events, system +events, or non-@acronym{ASCII} characters such as @kbd{C-=} or +@kbd{H-a} cannot be represented as strings; they have to be +represented as vectors. In the vector representation, each element of the vector represents an input event, in its Lisp form. @xref{Input Events}. For example, -- 2.39.2