annotate lispref/commands.texi @ 45151:e5a353edec82

*** empty log message ***
author Markus Rost <rost@math.uni-bielefeld.de>
date Mon, 06 May 2002 21:12:42 +0000
parents 7b62d2ff9381
children 60dbe3b230eb
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1 @c -*-texinfo-*-
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2 @c This is part of the GNU Emacs Lisp Reference Manual.
27189
d2e5f1b7d8e2 Update copyrights.
Gerd Moellmann <gerd@gnu.org>
parents: 27187
diff changeset
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
d2e5f1b7d8e2 Update copyrights.
Gerd Moellmann <gerd@gnu.org>
parents: 27187
diff changeset
4 @c Free Software Foundation, Inc.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
5 @c See the file elisp.texi for copying conditions.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
6 @setfilename ../info/commands
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
7 @node Command Loop, Keymaps, Minibuffers, Top
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
8 @chapter Command Loop
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
9 @cindex editor command loop
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
10 @cindex command loop
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
11
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
12 When you run Emacs, it enters the @dfn{editor command loop} almost
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
13 immediately. This loop reads key sequences, executes their definitions,
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
14 and displays the results. In this chapter, we describe how these things
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
15 are done, and the subroutines that allow Lisp programs to do them.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
16
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
17 @menu
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
18 * Command Overview:: How the command loop reads commands.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
19 * Defining Commands:: Specifying how a function should read arguments.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
20 * Interactive Call:: Calling a command, so that it will read arguments.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
21 * Command Loop Info:: Variables set by the command loop for you to examine.
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
22 * Adjusting Point:: Adjustment of point after a command.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
23 * Input Events:: What input looks like when you read it.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
24 * Reading Input:: How to read input events from the keyboard or mouse.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
25 * Special Events:: Events processed immediately and individually.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
26 * Waiting:: Waiting for user input or elapsed time.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
27 * Quitting:: How @kbd{C-g} works. How to catch or defer quitting.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
28 * Prefix Command Arguments:: How the commands to set prefix args work.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
29 * Recursive Editing:: Entering a recursive edit,
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
30 and why you usually shouldn't.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
31 * Disabling Commands:: How the command loop handles disabled commands.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
32 * Command History:: How the command history is set up, and how accessed.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
33 * Keyboard Macros:: How keyboard macros are implemented.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
34 @end menu
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
35
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
36 @node Command Overview
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
37 @section Command Loop Overview
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
38
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
39 The first thing the command loop must do is read a key sequence, which
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
40 is a sequence of events that translates into a command. It does this by
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
41 calling the function @code{read-key-sequence}. Your Lisp code can also
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
42 call this function (@pxref{Key Sequence Input}). Lisp programs can also
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
43 do input at a lower level with @code{read-event} (@pxref{Reading One
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
44 Event}) or discard pending input with @code{discard-input}
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
45 (@pxref{Event Input Misc}).
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
46
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
47 The key sequence is translated into a command through the currently
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
48 active keymaps. @xref{Key Lookup}, for information on how this is done.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
49 The result should be a keyboard macro or an interactively callable
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
50 function. If the key is @kbd{M-x}, then it reads the name of another
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
51 command, which it then calls. This is done by the command
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
52 @code{execute-extended-command} (@pxref{Interactive Call}).
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
53
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
54 To execute a command requires first reading the arguments for it.
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
55 This is done by calling @code{command-execute} (@pxref{Interactive
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
56 Call}). For commands written in Lisp, the @code{interactive}
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
57 specification says how to read the arguments. This may use the prefix
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
58 argument (@pxref{Prefix Command Arguments}) or may read with prompting
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
59 in the minibuffer (@pxref{Minibuffers}). For example, the command
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
60 @code{find-file} has an @code{interactive} specification which says to
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
61 read a file name using the minibuffer. The command's function body does
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
62 not use the minibuffer; if you call this command from Lisp code as a
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
63 function, you must supply the file name string as an ordinary Lisp
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
64 function argument.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
65
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
66 If the command is a string or vector (i.e., a keyboard macro) then
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
67 @code{execute-kbd-macro} is used to execute it. You can call this
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
68 function yourself (@pxref{Keyboard Macros}).
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
69
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
70 To terminate the execution of a running command, type @kbd{C-g}. This
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
71 character causes @dfn{quitting} (@pxref{Quitting}).
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
72
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
73 @defvar pre-command-hook
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
74 The editor command loop runs this normal hook before each command. At
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
75 that time, @code{this-command} contains the command that is about to
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
76 run, and @code{last-command} describes the previous command.
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
77 @xref{Hooks}.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
78 @end defvar
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
79
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
80 @defvar post-command-hook
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
81 The editor command loop runs this normal hook after each command
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
82 (including commands terminated prematurely by quitting or by errors),
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
83 and also when the command loop is first entered. At that time,
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
84 @code{this-command} describes the command that just ran, and
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
85 @code{last-command} describes the command before that. @xref{Hooks}.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
86 @end defvar
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
87
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
88 Quitting is suppressed while running @code{pre-command-hook} and
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
89 @code{post-command-hook}. If an error happens while executing one of
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
90 these hooks, it terminates execution of the hook, and clears the hook
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
91 variable to @code{nil} so as to prevent an infinite loop of errors.
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
92
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
93 @node Defining Commands
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
94 @section Defining Commands
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
95 @cindex defining commands
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
96 @cindex commands, defining
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
97 @cindex functions, making them interactive
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
98 @cindex interactive function
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
99
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
100 A Lisp function becomes a command when its body contains, at top
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
101 level, a form that calls the special form @code{interactive}. This
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
102 form does nothing when actually executed, but its presence serves as a
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
103 flag to indicate that interactive calling is permitted. Its argument
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
104 controls the reading of arguments for an interactive call.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
105
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
106 @menu
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
107 * Using Interactive:: General rules for @code{interactive}.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
108 * Interactive Codes:: The standard letter-codes for reading arguments
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
109 in various ways.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
110 * Interactive Examples:: Examples of how to read interactive arguments.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
111 @end menu
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
112
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
113 @node Using Interactive
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
114 @subsection Using @code{interactive}
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
115
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
116 This section describes how to write the @code{interactive} form that
39210
c717c37b1a2c (Using Interactive): Document interactive-form.
Eli Zaretskii <eliz@gnu.org>
parents: 38603
diff changeset
117 makes a Lisp function an interactively-callable command, and how to
39221
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39210
diff changeset
118 examine a commands's @code{interactive} form.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
119
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
120 @defspec interactive arg-descriptor
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
121 @cindex argument descriptors
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
122 This special form declares that the function in which it appears is a
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
123 command, and that it may therefore be called interactively (via
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
124 @kbd{M-x} or by entering a key sequence bound to it). The argument
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
125 @var{arg-descriptor} declares how to compute the arguments to the
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
126 command when the command is called interactively.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
127
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
128 A command may be called from Lisp programs like any other function, but
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
129 then the caller supplies the arguments and @var{arg-descriptor} has no
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
130 effect.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
131
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
132 The @code{interactive} form has its effect because the command loop
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
133 (actually, its subroutine @code{call-interactively}) scans through the
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
134 function definition looking for it, before calling the function. Once
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
135 the function is called, all its body forms including the
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
136 @code{interactive} form are executed, but at this time
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
137 @code{interactive} simply returns @code{nil} without even evaluating its
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
138 argument.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
139 @end defspec
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
140
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
141 There are three possibilities for the argument @var{arg-descriptor}:
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
142
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
143 @itemize @bullet
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
144 @item
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
145 It may be omitted or @code{nil}; then the command is called with no
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
146 arguments. This leads quickly to an error if the command requires one
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
147 or more arguments.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
148
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
149 @item
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
150 It may be a Lisp expression that is not a string; then it should be a
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
151 form that is evaluated to get a list of arguments to pass to the
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
152 command.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
153 @cindex argument evaluation form
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
154
10834
e79e5c9e7722 Warn that interactive should get point and mark only after minibuffer input.
Richard M. Stallman <rms@gnu.org>
parents: 8532
diff changeset
155 If this expression reads keyboard input (this includes using the
e79e5c9e7722 Warn that interactive should get point and mark only after minibuffer input.
Richard M. Stallman <rms@gnu.org>
parents: 8532
diff changeset
156 minibuffer), keep in mind that the integer value of point or the mark
e79e5c9e7722 Warn that interactive should get point and mark only after minibuffer input.
Richard M. Stallman <rms@gnu.org>
parents: 8532
diff changeset
157 before reading input may be incorrect after reading input. This is
e79e5c9e7722 Warn that interactive should get point and mark only after minibuffer input.
Richard M. Stallman <rms@gnu.org>
parents: 8532
diff changeset
158 because the current buffer may be receiving subprocess output;
e79e5c9e7722 Warn that interactive should get point and mark only after minibuffer input.
Richard M. Stallman <rms@gnu.org>
parents: 8532
diff changeset
159 if subprocess output arrives while the command is waiting for input,
e79e5c9e7722 Warn that interactive should get point and mark only after minibuffer input.
Richard M. Stallman <rms@gnu.org>
parents: 8532
diff changeset
160 it could relocate point and the mark.
e79e5c9e7722 Warn that interactive should get point and mark only after minibuffer input.
Richard M. Stallman <rms@gnu.org>
parents: 8532
diff changeset
161
e79e5c9e7722 Warn that interactive should get point and mark only after minibuffer input.
Richard M. Stallman <rms@gnu.org>
parents: 8532
diff changeset
162 Here's an example of what @emph{not} to do:
e79e5c9e7722 Warn that interactive should get point and mark only after minibuffer input.
Richard M. Stallman <rms@gnu.org>
parents: 8532
diff changeset
163
e79e5c9e7722 Warn that interactive should get point and mark only after minibuffer input.
Richard M. Stallman <rms@gnu.org>
parents: 8532
diff changeset
164 @smallexample
e79e5c9e7722 Warn that interactive should get point and mark only after minibuffer input.
Richard M. Stallman <rms@gnu.org>
parents: 8532
diff changeset
165 (interactive
e79e5c9e7722 Warn that interactive should get point and mark only after minibuffer input.
Richard M. Stallman <rms@gnu.org>
parents: 8532
diff changeset
166 (list (region-beginning) (region-end)
e79e5c9e7722 Warn that interactive should get point and mark only after minibuffer input.
Richard M. Stallman <rms@gnu.org>
parents: 8532
diff changeset
167 (read-string "Foo: " nil 'my-history)))
e79e5c9e7722 Warn that interactive should get point and mark only after minibuffer input.
Richard M. Stallman <rms@gnu.org>
parents: 8532
diff changeset
168 @end smallexample
e79e5c9e7722 Warn that interactive should get point and mark only after minibuffer input.
Richard M. Stallman <rms@gnu.org>
parents: 8532
diff changeset
169
e79e5c9e7722 Warn that interactive should get point and mark only after minibuffer input.
Richard M. Stallman <rms@gnu.org>
parents: 8532
diff changeset
170 @noindent
e79e5c9e7722 Warn that interactive should get point and mark only after minibuffer input.
Richard M. Stallman <rms@gnu.org>
parents: 8532
diff changeset
171 Here's how to avoid the problem, by examining point and the mark only
e79e5c9e7722 Warn that interactive should get point and mark only after minibuffer input.
Richard M. Stallman <rms@gnu.org>
parents: 8532
diff changeset
172 after reading the keyboard input:
e79e5c9e7722 Warn that interactive should get point and mark only after minibuffer input.
Richard M. Stallman <rms@gnu.org>
parents: 8532
diff changeset
173
e79e5c9e7722 Warn that interactive should get point and mark only after minibuffer input.
Richard M. Stallman <rms@gnu.org>
parents: 8532
diff changeset
174 @smallexample
e79e5c9e7722 Warn that interactive should get point and mark only after minibuffer input.
Richard M. Stallman <rms@gnu.org>
parents: 8532
diff changeset
175 (interactive
e79e5c9e7722 Warn that interactive should get point and mark only after minibuffer input.
Richard M. Stallman <rms@gnu.org>
parents: 8532
diff changeset
176 (let ((string (read-string "Foo: " nil 'my-history)))
e79e5c9e7722 Warn that interactive should get point and mark only after minibuffer input.
Richard M. Stallman <rms@gnu.org>
parents: 8532
diff changeset
177 (list (region-beginning) (region-end) string)))
e79e5c9e7722 Warn that interactive should get point and mark only after minibuffer input.
Richard M. Stallman <rms@gnu.org>
parents: 8532
diff changeset
178 @end smallexample
e79e5c9e7722 Warn that interactive should get point and mark only after minibuffer input.
Richard M. Stallman <rms@gnu.org>
parents: 8532
diff changeset
179
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
180 @item
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
181 @cindex argument prompt
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
182 It may be a string; then its contents should consist of a code character
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
183 followed by a prompt (which some code characters use and some ignore).
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
184 The prompt ends either with the end of the string or with a newline.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
185 Here is a simple example:
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
186
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
187 @smallexample
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
188 (interactive "bFrobnicate buffer: ")
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
189 @end smallexample
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
190
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
191 @noindent
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
192 The code letter @samp{b} says to read the name of an existing buffer,
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
193 with completion. The buffer name is the sole argument passed to the
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
194 command. The rest of the string is a prompt.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
195
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
196 If there is a newline character in the string, it terminates the prompt.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
197 If the string does not end there, then the rest of the string should
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
198 contain another code character and prompt, specifying another argument.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
199 You can specify any number of arguments in this way.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
200
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
201 @c Emacs 19 feature
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
202 The prompt string can use @samp{%} to include previous argument values
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
203 (starting with the first argument) in the prompt. This is done using
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
204 @code{format} (@pxref{Formatting Strings}). For example, here is how
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
205 you could read the name of an existing buffer followed by a new name to
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
206 give to that buffer:
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
207
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
208 @smallexample
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
209 @group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
210 (interactive "bBuffer to rename: \nsRename buffer %s to: ")
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
211 @end group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
212 @end smallexample
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
213
39221
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39210
diff changeset
214 @cindex @samp{*} in @code{interactive}
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
215 @cindex read-only buffers in interactive
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
216 If the first character in the string is @samp{*}, then an error is
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
217 signaled if the buffer is read-only.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
218
39221
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39210
diff changeset
219 @cindex @samp{@@} in @code{interactive}
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
220 @c Emacs 19 feature
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
221 If the first character in the string is @samp{@@}, and if the key
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
222 sequence used to invoke the command includes any mouse events, then
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
223 the window associated with the first of those events is selected
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
224 before the command is run.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
225
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
226 You can use @samp{*} and @samp{@@} together; the order does not matter.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
227 Actual reading of arguments is controlled by the rest of the prompt
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
228 string (starting with the first character that is not @samp{*} or
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
229 @samp{@@}).
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
230 @end itemize
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
231
39221
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39210
diff changeset
232 @cindex examining the @code{interactive} form
39210
c717c37b1a2c (Using Interactive): Document interactive-form.
Eli Zaretskii <eliz@gnu.org>
parents: 38603
diff changeset
233 @defun interactive-form function
39221
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39210
diff changeset
234 This function returns the @code{interactive} form of @var{function}. If
39210
c717c37b1a2c (Using Interactive): Document interactive-form.
Eli Zaretskii <eliz@gnu.org>
parents: 38603
diff changeset
235 @var{function} is a command (@pxref{Interactive Call}), the value is a
c717c37b1a2c (Using Interactive): Document interactive-form.
Eli Zaretskii <eliz@gnu.org>
parents: 38603
diff changeset
236 list of the form @code{(interactive @var{spec})}, where @var{spec} is
c717c37b1a2c (Using Interactive): Document interactive-form.
Eli Zaretskii <eliz@gnu.org>
parents: 38603
diff changeset
237 the descriptor specification used by the command's @code{interactive}
c717c37b1a2c (Using Interactive): Document interactive-form.
Eli Zaretskii <eliz@gnu.org>
parents: 38603
diff changeset
238 form to compute the function's arguments (@pxref{Using Interactive}).
c717c37b1a2c (Using Interactive): Document interactive-form.
Eli Zaretskii <eliz@gnu.org>
parents: 38603
diff changeset
239 If @var{function} is not a command, @code{interactive-form} returns
c717c37b1a2c (Using Interactive): Document interactive-form.
Eli Zaretskii <eliz@gnu.org>
parents: 38603
diff changeset
240 @code{nil}.
c717c37b1a2c (Using Interactive): Document interactive-form.
Eli Zaretskii <eliz@gnu.org>
parents: 38603
diff changeset
241 @end defun
c717c37b1a2c (Using Interactive): Document interactive-form.
Eli Zaretskii <eliz@gnu.org>
parents: 38603
diff changeset
242
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
243 @node Interactive Codes
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
244 @comment node-name, next, previous, up
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
245 @subsection Code Characters for @code{interactive}
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
246 @cindex interactive code description
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
247 @cindex description for interactive codes
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
248 @cindex codes, interactive, description of
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
249 @cindex characters for interactive codes
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
250
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
251 The code character descriptions below contain a number of key words,
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
252 defined here as follows:
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
253
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
254 @table @b
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
255 @item Completion
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
256 @cindex interactive completion
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
257 Provide completion. @key{TAB}, @key{SPC}, and @key{RET} perform name
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
258 completion because the argument is read using @code{completing-read}
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
259 (@pxref{Completion}). @kbd{?} displays a list of possible completions.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
261 @item Existing
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
262 Require the name of an existing object. An invalid name is not
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
263 accepted; the commands to exit the minibuffer do not exit if the current
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
264 input is not valid.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
265
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
266 @item Default
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
267 @cindex default argument string
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
268 A default value of some sort is used if the user enters no text in the
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
269 minibuffer. The default depends on the code character.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
270
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
271 @item No I/O
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
272 This code letter computes an argument without reading any input.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
273 Therefore, it does not use a prompt string, and any prompt string you
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
274 supply is ignored.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
275
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
276 Even though the code letter doesn't use a prompt string, you must follow
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
277 it with a newline if it is not the last code character in the string.
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
278
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
279 @item Prompt
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
280 A prompt immediately follows the code character. The prompt ends either
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
281 with the end of the string or with a newline.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
282
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
283 @item Special
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
284 This code character is meaningful only at the beginning of the
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
285 interactive string, and it does not look for a prompt or a newline.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
286 It is a single, isolated character.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
287 @end table
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
288
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
289 @cindex reading interactive arguments
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
290 Here are the code character descriptions for use with @code{interactive}:
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
291
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
292 @table @samp
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
293 @item *
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
294 Signal an error if the current buffer is read-only. Special.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
295
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
296 @item @@
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
297 Select the window mentioned in the first mouse event in the key
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
298 sequence that invoked this command. Special.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
299
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
300 @item a
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
301 A function name (i.e., a symbol satisfying @code{fboundp}). Existing,
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
302 Completion, Prompt.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
303
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
304 @item b
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
305 The name of an existing buffer. By default, uses the name of the
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
306 current buffer (@pxref{Buffers}). Existing, Completion, Default,
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
307 Prompt.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
308
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
309 @item B
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
310 A buffer name. The buffer need not exist. By default, uses the name of
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
311 a recently used buffer other than the current buffer. Completion,
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
312 Default, Prompt.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
313
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
314 @item c
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
315 A character. The cursor does not move into the echo area. Prompt.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
316
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
317 @item C
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
318 A command name (i.e., a symbol satisfying @code{commandp}). Existing,
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
319 Completion, Prompt.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
320
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
321 @item d
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
322 @cindex position argument
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
323 The position of point, as an integer (@pxref{Point}). No I/O.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
324
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
325 @item D
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
326 A directory name. The default is the current default directory of the
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
327 current buffer, @code{default-directory} (@pxref{System Environment}).
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
328 Existing, Completion, Default, Prompt.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
329
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
330 @item e
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
331 The first or next mouse event in the key sequence that invoked the command.
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
332 More precisely, @samp{e} gets events that are lists, so you can look at
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
333 the data in the lists. @xref{Input Events}. No I/O.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
334
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
335 You can use @samp{e} more than once in a single command's interactive
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
336 specification. If the key sequence that invoked the command has
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
337 @var{n} events that are lists, the @var{n}th @samp{e} provides the
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
338 @var{n}th such event. Events that are not lists, such as function keys
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
339 and @sc{ascii} characters, do not count where @samp{e} is concerned.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
340
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
341 @item f
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
342 A file name of an existing file (@pxref{File Names}). The default
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
343 directory is @code{default-directory}. Existing, Completion, Default,
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
344 Prompt.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
345
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
346 @item F
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
347 A file name. The file need not exist. Completion, Default, Prompt.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
348
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
349 @item i
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
350 An irrelevant argument. This code always supplies @code{nil} as
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
351 the argument's value. No I/O.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
352
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
353 @item k
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
354 A key sequence (@pxref{Keymap Terminology}). This keeps reading events
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
355 until a command (or undefined command) is found in the current key
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
356 maps. The key sequence argument is represented as a string or vector.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
357 The cursor does not move into the echo area. Prompt.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
358
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
359 This kind of input is used by commands such as @code{describe-key} and
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
360 @code{global-set-key}.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
361
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10834
diff changeset
362 @item K
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10834
diff changeset
363 A key sequence, whose definition you intend to change. This works like
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10834
diff changeset
364 @samp{k}, except that it suppresses, for the last input event in the key
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10834
diff changeset
365 sequence, the conversions that are normally used (when necessary) to
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10834
diff changeset
366 convert an undefined key into a defined one.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10834
diff changeset
367
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
368 @item m
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
369 @cindex marker argument
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
370 The position of the mark, as an integer. No I/O.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
371
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
372 @item M
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
373 Arbitrary text, read in the minibuffer using the current buffer's input
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
374 method, and returned as a string (@pxref{Input Methods,,, emacs, The GNU
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
375 Emacs Manual}). Prompt.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
376
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
377 @item n
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
378 A number read with the minibuffer. If the input is not a number, the
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
379 user is asked to try again. The prefix argument, if any, is not used.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
380 Prompt.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
381
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
382 @item N
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
383 @cindex raw prefix argument usage
13853
7c317c94b1f6 Changed interactive spec N.
Richard M. Stallman <rms@gnu.org>
parents: 13007
diff changeset
384 The numeric prefix argument; but if there is no prefix argument, read a
7c317c94b1f6 Changed interactive spec N.
Richard M. Stallman <rms@gnu.org>
parents: 13007
diff changeset
385 number as with @kbd{n}. Requires a number. @xref{Prefix Command
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
386 Arguments}. Prompt.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
387
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
388 @item p
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
389 @cindex numeric prefix argument usage
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
390 The numeric prefix argument. (Note that this @samp{p} is lower case.)
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
391 No I/O.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
392
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
393 @item P
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
394 The raw prefix argument. (Note that this @samp{P} is upper case.) No
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
395 I/O.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
396
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
397 @item r
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
398 @cindex region argument
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
399 Point and the mark, as two numeric arguments, smallest first. This is
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
400 the only code letter that specifies two successive arguments rather than
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
401 one. No I/O.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
402
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
403 @item s
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
404 Arbitrary text, read in the minibuffer and returned as a string
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
405 (@pxref{Text from Minibuffer}). Terminate the input with either
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
406 @kbd{C-j} or @key{RET}. (@kbd{C-q} may be used to include either of
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
407 these characters in the input.) Prompt.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
408
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
409 @item S
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
410 An interned symbol whose name is read in the minibuffer. Any whitespace
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
411 character terminates the input. (Use @kbd{C-q} to include whitespace in
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
412 the string.) Other characters that normally terminate a symbol (e.g.,
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
413 parentheses and brackets) do not do so here. Prompt.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
414
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
415 @item v
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
416 A variable declared to be a user option (i.e., satisfying the predicate
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
417 @code{user-variable-p}). @xref{High-Level Completion}. Existing,
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
418 Completion, Prompt.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
419
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
420 @item x
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
421 A Lisp object, specified with its read syntax, terminated with a
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
422 @kbd{C-j} or @key{RET}. The object is not evaluated. @xref{Object from
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
423 Minibuffer}. Prompt.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
424
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
425 @item X
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
426 @cindex evaluated expression argument
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
427 A Lisp form is read as with @kbd{x}, but then evaluated so that its
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
428 value becomes the argument for the command. Prompt.
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
429
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
430 @item z
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
431 A coding system name (a symbol). If the user enters null input, the
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
432 argument value is @code{nil}. @xref{Coding Systems}. Completion,
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
433 Existing, Prompt.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
434
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
435 @item Z
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
436 A coding system name (a symbol)---but only if this command has a prefix
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
437 argument. With no prefix argument, @samp{Z} provides @code{nil} as the
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
438 argument value. Completion, Existing, Prompt.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
439 @end table
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
440
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
441 @node Interactive Examples
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
442 @comment node-name, next, previous, up
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
443 @subsection Examples of Using @code{interactive}
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
444 @cindex examples of using @code{interactive}
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
445 @cindex @code{interactive}, examples of using
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
446
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
447 Here are some examples of @code{interactive}:
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
448
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
449 @example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
450 @group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
451 (defun foo1 () ; @r{@code{foo1} takes no arguments,}
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
452 (interactive) ; @r{just moves forward two words.}
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
453 (forward-word 2))
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
454 @result{} foo1
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
455 @end group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
456
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
457 @group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
458 (defun foo2 (n) ; @r{@code{foo2} takes one argument,}
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
459 (interactive "p") ; @r{which is the numeric prefix.}
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
460 (forward-word (* 2 n)))
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
461 @result{} foo2
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
462 @end group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
463
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
464 @group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
465 (defun foo3 (n) ; @r{@code{foo3} takes one argument,}
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
466 (interactive "nCount:") ; @r{which is read with the Minibuffer.}
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
467 (forward-word (* 2 n)))
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
468 @result{} foo3
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
469 @end group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
470
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
471 @group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
472 (defun three-b (b1 b2 b3)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
473 "Select three existing buffers.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
474 Put them into three windows, selecting the last one."
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
475 @end group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
476 (interactive "bBuffer1:\nbBuffer2:\nbBuffer3:")
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
477 (delete-other-windows)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
478 (split-window (selected-window) 8)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
479 (switch-to-buffer b1)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
480 (other-window 1)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
481 (split-window (selected-window) 8)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
482 (switch-to-buffer b2)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
483 (other-window 1)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
484 (switch-to-buffer b3))
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
485 @result{} three-b
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
486 @group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
487 (three-b "*scratch*" "declarations.texi" "*mail*")
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
488 @result{} nil
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
489 @end group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
490 @end example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
491
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
492 @node Interactive Call
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
493 @section Interactive Call
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
494 @cindex interactive call
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
495
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
496 After the command loop has translated a key sequence into a command it
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
497 invokes that command using the function @code{command-execute}. If the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
498 command is a function, @code{command-execute} calls
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
499 @code{call-interactively}, which reads the arguments and calls the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
500 command. You can also call these functions yourself.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
501
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
502 @defun commandp object
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
503 Returns @code{t} if @var{object} is suitable for calling interactively;
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
504 that is, if @var{object} is a command. Otherwise, returns @code{nil}.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
505
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
506 The interactively callable objects include strings and vectors (treated
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
507 as keyboard macros), lambda expressions that contain a top-level call to
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
508 @code{interactive}, byte-code function objects made from such lambda
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
509 expressions, autoload objects that are declared as interactive
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
510 (non-@code{nil} fourth argument to @code{autoload}), and some of the
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
511 primitive functions.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
512
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
513 A symbol satisfies @code{commandp} if its function definition satisfies
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
514 @code{commandp}.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
515
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
516 Keys and keymaps are not commands. Rather, they are used to look up
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
517 commands (@pxref{Keymaps}).
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
518
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
519 See @code{documentation} in @ref{Accessing Documentation}, for a
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
520 realistic example of using @code{commandp}.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
521 @end defun
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
522
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
523 @defun call-interactively command &optional record-flag keys
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
524 This function calls the interactively callable function @var{command},
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
525 reading arguments according to its interactive calling specifications.
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
526 An error is signaled if @var{command} is not a function or if it cannot
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
527 be called interactively (i.e., is not a command). Note that keyboard
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
528 macros (strings and vectors) are not accepted, even though they are
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
529 considered commands, because they are not functions.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
530
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
531 @cindex record command history
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
532 If @var{record-flag} is non-@code{nil}, then this command and its
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
533 arguments are unconditionally added to the list @code{command-history}.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
534 Otherwise, the command is added only if it uses the minibuffer to read
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
535 an argument. @xref{Command History}.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
536
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
537 The argument @var{keys}, if given, specifies the sequence of events to
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
538 supply if the command inquires which events were used to invoke it.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
539 @end defun
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
540
26288
6119687f6888 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25875
diff changeset
541 @defun command-execute command &optional record-flag keys special
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
542 @cindex keyboard macro execution
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
543 This function executes @var{command}. The argument @var{command} must
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
544 satisfy the @code{commandp} predicate; i.e., it must be an interactively
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
545 callable function or a keyboard macro.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
546
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
547 A string or vector as @var{command} is executed with
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
548 @code{execute-kbd-macro}. A function is passed to
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
549 @code{call-interactively}, along with the optional @var{record-flag}.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
550
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
551 A symbol is handled by using its function definition in its place. A
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
552 symbol with an @code{autoload} definition counts as a command if it was
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
553 declared to stand for an interactively callable function. Such a
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
554 definition is handled by loading the specified library and then
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
555 rechecking the definition of the symbol.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
556
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
557 The argument @var{keys}, if given, specifies the sequence of events to
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
558 supply if the command inquires which events were used to invoke it.
26288
6119687f6888 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25875
diff changeset
559
6119687f6888 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25875
diff changeset
560 The argument @var{special}, if given, means to ignore the prefix
6119687f6888 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25875
diff changeset
561 argument and not clear it. This is used for executing special events
6119687f6888 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25875
diff changeset
562 (@pxref{Special Events}).
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
563 @end defun
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
564
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
565 @deffn Command execute-extended-command prefix-argument
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
566 @cindex read command name
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
567 This function reads a command name from the minibuffer using
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
568 @code{completing-read} (@pxref{Completion}). Then it uses
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
569 @code{command-execute} to call the specified command. Whatever that
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
570 command returns becomes the value of @code{execute-extended-command}.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
571
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
572 @cindex execute with prefix argument
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
573 If the command asks for a prefix argument, it receives the value
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
574 @var{prefix-argument}. If @code{execute-extended-command} is called
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
575 interactively, the current raw prefix argument is used for
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
576 @var{prefix-argument}, and thus passed on to whatever command is run.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
577
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
578 @c !!! Should this be @kindex?
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
579 @cindex @kbd{M-x}
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
580 @code{execute-extended-command} is the normal definition of @kbd{M-x},
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
581 so it uses the string @w{@samp{M-x }} as a prompt. (It would be better
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
582 to take the prompt from the events used to invoke
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
583 @code{execute-extended-command}, but that is painful to implement.) A
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
584 description of the value of the prefix argument, if any, also becomes
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
585 part of the prompt.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
586
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
587 @example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
588 @group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
589 (execute-extended-command 1)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
590 ---------- Buffer: Minibuffer ----------
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
591 1 M-x forward-word RET
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
592 ---------- Buffer: Minibuffer ----------
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
593 @result{} t
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
594 @end group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
595 @end example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
596 @end deffn
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
597
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
598 @defun interactive-p
16736
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 15764
diff changeset
599 This function returns @code{t} if the containing function (the one whose
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 15764
diff changeset
600 code includes the call to @code{interactive-p}) was called
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 15764
diff changeset
601 interactively, with the function @code{call-interactively}. (It makes
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 15764
diff changeset
602 no difference whether @code{call-interactively} was called from Lisp or
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 15764
diff changeset
603 directly from the editor command loop.) If the containing function was
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 15764
diff changeset
604 called by Lisp evaluation (or with @code{apply} or @code{funcall}), then
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 15764
diff changeset
605 it was not called interactively.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
606 @end defun
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
607
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
608 The most common use of @code{interactive-p} is for deciding whether to
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
609 print an informative message. As a special exception,
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
610 @code{interactive-p} returns @code{nil} whenever a keyboard macro is
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
611 being run. This is to suppress the informative messages and speed
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
612 execution of the macro.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
613
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
614 For example:
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
615
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
616 @example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
617 @group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
618 (defun foo ()
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
619 (interactive)
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
620 (when (interactive-p)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
621 (message "foo")))
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
622 @result{} foo
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
623 @end group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
624
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
625 @group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
626 (defun bar ()
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
627 (interactive)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
628 (setq foobar (list (foo) (interactive-p))))
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
629 @result{} bar
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
630 @end group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
631
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
632 @group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
633 ;; @r{Type @kbd{M-x foo}.}
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
634 @print{} foo
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
635 @end group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
636
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
637 @group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
638 ;; @r{Type @kbd{M-x bar}.}
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
639 ;; @r{This does not print anything.}
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
640 @end group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
641
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
642 @group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
643 foobar
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
644 @result{} (nil t)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
645 @end group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
646 @end example
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
647
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
648 The other way to do this sort of job is to make the command take an
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
649 argument @code{print-message} which should be non-@code{nil} in an
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
650 interactive call, and use the @code{interactive} spec to make sure it is
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
651 non-@code{nil}. Here's how:
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
652
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
653 @example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
654 (defun foo (&optional print-message)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
655 (interactive "p")
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
656 (when print-message
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
657 (message "foo")))
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
658 @end example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
659
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
660 The numeric prefix argument, provided by @samp{p}, is never @code{nil}.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
661
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
662 @node Command Loop Info
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
663 @comment node-name, next, previous, up
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
664 @section Information from the Command Loop
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
665
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
666 The editor command loop sets several Lisp variables to keep status
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
667 records for itself and for commands that are run.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
668
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
669 @defvar last-command
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
670 This variable records the name of the previous command executed by the
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
671 command loop (the one before the current command). Normally the value
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
672 is a symbol with a function definition, but this is not guaranteed.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
673
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
674 The value is copied from @code{this-command} when a command returns to
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
675 the command loop, except when the command has specified a prefix
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
676 argument for the following command.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
677
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
678 This variable is always local to the current terminal and cannot be
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
679 buffer-local. @xref{Multiple Displays}.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
680 @end defvar
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
681
22440
8a51f757af2c *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
682 @defvar real-last-command
8a51f757af2c *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
683 This variable is set up by Emacs just like @code{last-command},
8a51f757af2c *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
684 but never altered by Lisp programs.
8a51f757af2c *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
685 @end defvar
8a51f757af2c *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
686
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
687 @defvar this-command
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
688 @cindex current command
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
689 This variable records the name of the command now being executed by
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
690 the editor command loop. Like @code{last-command}, it is normally a symbol
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
691 with a function definition.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
692
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
693 The command loop sets this variable just before running a command, and
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
694 copies its value into @code{last-command} when the command finishes
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
695 (unless the command specified a prefix argument for the following
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
696 command).
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
697
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
698 @cindex kill command repetition
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
699 Some commands set this variable during their execution, as a flag for
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
700 whatever command runs next. In particular, the functions for killing text
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
701 set @code{this-command} to @code{kill-region} so that any kill commands
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
702 immediately following will know to append the killed text to the
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
703 previous kill.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
704 @end defvar
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
705
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
706 If you do not want a particular command to be recognized as the previous
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
707 command in the case where it got an error, you must code that command to
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
708 prevent this. One way is to set @code{this-command} to @code{t} at the
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
709 beginning of the command, and set @code{this-command} back to its proper
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
710 value at the end, like this:
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
711
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
712 @example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
713 (defun foo (args@dots{})
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
714 (interactive @dots{})
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
715 (let ((old-this-command this-command))
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
716 (setq this-command t)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
717 @r{@dots{}do the work@dots{}}
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
718 (setq this-command old-this-command)))
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
719 @end example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
720
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
721 @noindent
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
722 We do not bind @code{this-command} with @code{let} because that would
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
723 restore the old value in case of error---a feature of @code{let} which
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
724 in this case does precisely what we want to avoid.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
725
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
726 @defun this-command-keys
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
727 This function returns a string or vector containing the key sequence
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
728 that invoked the present command, plus any previous commands that
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
729 generated the prefix argument for this command. The value is a string
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
730 if all those events were characters. @xref{Input Events}.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
731
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
732 @example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
733 @group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
734 (this-command-keys)
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
735 ;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
736 @result{} "^U^X^E"
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
737 @end group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
738 @end example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
739 @end defun
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
740
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
741 @defun this-command-keys-vector
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
742 Like @code{this-command-keys}, except that it always returns the events
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
743 in a vector, so you don't need to deal with the complexities of storing
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
744 input events in a string (@pxref{Strings of Events}).
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
745 @end defun
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
746
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
747 @tindex clear-this-command-keys
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
748 @defun clear-this-command-keys
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
749 This function empties out the table of events for
39221
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39210
diff changeset
750 @code{this-command-keys} to return, and also empties the records that
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39210
diff changeset
751 the function @code{recent-keys} (@pxref{Recording Input}) will
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39210
diff changeset
752 subsequently return. This is useful after reading a password, to
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39210
diff changeset
753 prevent the password from echoing inadvertently as part of the next
68b26e98aef6 Clarify recent changes.
Richard M. Stallman <rms@gnu.org>
parents: 39210
diff changeset
754 command in certain cases.
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
755 @end defun
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
756
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
757 @defvar last-nonmenu-event
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
758 This variable holds the last input event read as part of a key sequence,
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
759 not counting events resulting from mouse menus.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
760
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
761 One use of this variable is for telling @code{x-popup-menu} where to pop
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
762 up a menu. It is also used internally by @code{y-or-n-p}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
763 (@pxref{Yes-or-No Queries}).
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
764 @end defvar
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
765
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
766 @defvar last-command-event
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
767 @defvarx last-command-char
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
768 This variable is set to the last input event that was read by the
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
769 command loop as part of a command. The principal use of this variable
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
770 is in @code{self-insert-command}, which uses it to decide which
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
771 character to insert.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
772
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
773 @example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
774 @group
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
775 last-command-event
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
776 ;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
777 @result{} 5
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
778 @end group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
779 @end example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
780
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
781 @noindent
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
782 The value is 5 because that is the @sc{ascii} code for @kbd{C-e}.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
783
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
784 The alias @code{last-command-char} exists for compatibility with
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
785 Emacs version 18.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
786 @end defvar
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
787
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
788 @c Emacs 19 feature
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
789 @defvar last-event-frame
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
790 This variable records which frame the last input event was directed to.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
791 Usually this is the frame that was selected when the event was
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
792 generated, but if that frame has redirected input focus to another
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
793 frame, the value is the frame to which the event was redirected.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
794 @xref{Input Focus}.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
795 @end defvar
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
796
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
797 @node Adjusting Point
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
798 @section Adjusting Point After Commands
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
799
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
800 It is not easy to display a value of point in the middle of a sequence
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
801 of text that has the @code{display} or @code{composition} property. So
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
802 after a command finishes and returns to the command loop, if point is
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
803 within such a sequence, the command loop normally moves point to the
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
804 edge of the sequence.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
805
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
806 A command can inhibit this feature by setting the variable
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
807 @code{disable-point-adjustment}:
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
808
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
809 @defvar disable-point-adjustment
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
810 @tindex disable-point-adjustment
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
811 If this variable is non-@code{nil} when a command returns to the command
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
812 loop, then the command loop does not check for text properties such as
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
813 @code{display} and @code{composition}, and does not move point out of
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
814 sequences that have these properties.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
815
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
816 The command loop sets this variable to @code{nil} before each command,
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
817 so if a command sets it, the effect applies only to that command.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
818 @end defvar
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
819
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
820 @defvar global-disable-point-adjustment
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
821 @tindex global-disable-point-adjustment
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
822 If you set this variable to a non-@code{nil} value, the feature of
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
823 moving point out of these sequences is completely turned off.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
824 @end defvar
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
825
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
826 @node Input Events
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
827 @section Input Events
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
828 @cindex events
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
829 @cindex input events
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
830
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
831 The Emacs command loop reads a sequence of @dfn{input events} that
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
832 represent keyboard or mouse activity. The events for keyboard activity
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
833 are characters or symbols; mouse events are always lists. This section
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
834 describes the representation and meaning of input events in detail.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
835
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
836 @defun eventp object
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
837 This function returns non-@code{nil} if @var{object} is an input event
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
838 or event type.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
839
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
840 Note that any symbol might be used as an event or an event type.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
841 @code{eventp} cannot distinguish whether a symbol is intended by Lisp
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
842 code to be used as an event. Instead, it distinguishes whether the
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
843 symbol has actually been used in an event that has been read as input in
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
844 the current Emacs session. If a symbol has not yet been so used,
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
845 @code{eventp} returns @code{nil}.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
846 @end defun
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
847
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
848 @menu
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
849 * Keyboard Events:: Ordinary characters--keys with symbols on them.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
850 * Function Keys:: Function keys--keys with names, not symbols.
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
851 * Mouse Events:: Overview of mouse events.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
852 * Click Events:: Pushing and releasing a mouse button.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
853 * Drag Events:: Moving the mouse before releasing the button.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
854 * Button-Down Events:: A button was pushed and not yet released.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
855 * Repeat Events:: Double and triple click (or drag, or down).
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
856 * Motion Events:: Just moving the mouse, not pushing a button.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
857 * Focus Events:: Moving the mouse between frames.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10834
diff changeset
858 * Misc Events:: Other events window systems can generate.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
859 * Event Examples:: Examples of the lists for mouse events.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
860 * Classifying Events:: Finding the modifier keys in an event symbol.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
861 Event types.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
862 * Accessing Events:: Functions to extract info from events.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
863 * Strings of Events:: Special considerations for putting
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
864 keyboard character events in a string.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
865 @end menu
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
866
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
867 @node Keyboard Events
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
868 @subsection Keyboard Events
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
869
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
870 There are two kinds of input you can get from the keyboard: ordinary
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
871 keys, and function keys. Ordinary keys correspond to characters; the
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
872 events they generate are represented in Lisp as characters. The event
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
873 type of a character event is the character itself (an integer); see
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
874 @ref{Classifying Events}.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
875
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
876 @cindex modifier bits (of input character)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
877 @cindex basic code (of input character)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
878 An input character event consists of a @dfn{basic code} between 0 and
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
879 524287, plus any or all of these @dfn{modifier bits}:
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
880
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
881 @table @asis
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
882 @item meta
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
883 The
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
884 @tex
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
885 @math{2^{27}}
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
886 @end tex
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
887 @ifnottex
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
888 2**27
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
889 @end ifnottex
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
890 bit in the character code indicates a character
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
891 typed with the meta key held down.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
892
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
893 @item control
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
894 The
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
895 @tex
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
896 @math{2^{26}}
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
897 @end tex
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
898 @ifnottex
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
899 2**26
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
900 @end ifnottex
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
901 bit in the character code indicates a non-@sc{ascii}
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
902 control character.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
903
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
904 @sc{ascii} control characters such as @kbd{C-a} have special basic
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
905 codes of their own, so Emacs needs no special bit to indicate them.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
906 Thus, the code for @kbd{C-a} is just 1.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
907
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
908 But if you type a control combination not in @sc{ascii}, such as
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
909 @kbd{%} with the control key, the numeric value you get is the code
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
910 for @kbd{%} plus
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
911 @tex
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
912 @math{2^{26}}
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
913 @end tex
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
914 @ifnottex
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
915 2**26
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
916 @end ifnottex
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
917 (assuming the terminal supports non-@sc{ascii}
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
918 control characters).
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
919
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
920 @item shift
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
921 The
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
922 @tex
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
923 @math{2^{25}}
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
924 @end tex
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
925 @ifnottex
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
926 2**25
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
927 @end ifnottex
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
928 bit in the character code indicates an @sc{ascii} control
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
929 character typed with the shift key held down.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
930
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
931 For letters, the basic code itself indicates upper versus lower case;
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
932 for digits and punctuation, the shift key selects an entirely different
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
933 character with a different basic code. In order to keep within the
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
934 @sc{ascii} character set whenever possible, Emacs avoids using the
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
935 @tex
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
936 @math{2^{25}}
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
937 @end tex
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
938 @ifnottex
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
939 2**25
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
940 @end ifnottex
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
941 bit for those characters.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
942
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
943 However, @sc{ascii} provides no way to distinguish @kbd{C-A} from
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
944 @kbd{C-a}, so Emacs uses the
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
945 @tex
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
946 @math{2^{25}}
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
947 @end tex
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
948 @ifnottex
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
949 2**25
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
950 @end ifnottex
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
951 bit in @kbd{C-A} and not in
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
952 @kbd{C-a}.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
953
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
954 @item hyper
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
955 The
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
956 @tex
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
957 @math{2^{24}}
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
958 @end tex
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
959 @ifnottex
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
960 2**24
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
961 @end ifnottex
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
962 bit in the character code indicates a character
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
963 typed with the hyper key held down.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
964
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
965 @item super
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
966 The
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
967 @tex
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
968 @math{2^{23}}
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
969 @end tex
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
970 @ifnottex
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
971 2**23
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
972 @end ifnottex
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
973 bit in the character code indicates a character
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
974 typed with the super key held down.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
975
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
976 @item alt
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
977 The
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
978 @tex
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
979 @math{2^{22}}
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
980 @end tex
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
981 @ifnottex
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
982 2**22
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
983 @end ifnottex
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
984 bit in the character code indicates a character typed with
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
985 the alt key held down. (On some terminals, the key labeled @key{ALT}
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
986 is actually the meta key.)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
987 @end table
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
988
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
989 It is best to avoid mentioning specific bit numbers in your program.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
990 To test the modifier bits of a character, use the function
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
991 @code{event-modifiers} (@pxref{Classifying Events}). When making key
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
992 bindings, you can use the read syntax for characters with modifier bits
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
993 (@samp{\C-}, @samp{\M-}, and so on). For making key bindings with
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
994 @code{define-key}, you can use lists such as @code{(control hyper ?x)} to
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
995 specify the characters (@pxref{Changing Key Bindings}). The function
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
996 @code{event-convert-list} converts such a list into an event type
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
997 (@pxref{Classifying Events}).
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
998
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
999 @node Function Keys
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1000 @subsection Function Keys
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1001
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1002 @cindex function keys
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1003 Most keyboards also have @dfn{function keys}---keys that have names or
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1004 symbols that are not characters. Function keys are represented in Emacs
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1005 Lisp as symbols; the symbol's name is the function key's label, in lower
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1006 case. For example, pressing a key labeled @key{F1} places the symbol
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1007 @code{f1} in the input stream.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1008
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1009 The event type of a function key event is the event symbol itself.
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1010 @xref{Classifying Events}.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1011
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1012 Here are a few special cases in the symbol-naming convention for
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1013 function keys:
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1014
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1015 @table @asis
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1016 @item @code{backspace}, @code{tab}, @code{newline}, @code{return}, @code{delete}
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
1017 These keys correspond to common @sc{ascii} control characters that have
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1018 special keys on most keyboards.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1019
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
1020 In @sc{ascii}, @kbd{C-i} and @key{TAB} are the same character. If the
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1021 terminal can distinguish between them, Emacs conveys the distinction to
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1022 Lisp programs by representing the former as the integer 9, and the
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1023 latter as the symbol @code{tab}.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1024
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1025 Most of the time, it's not useful to distinguish the two. So normally
15764
870d35f9e086 Add some xrefs.
Richard M. Stallman <rms@gnu.org>
parents: 14499
diff changeset
1026 @code{function-key-map} (@pxref{Translating Input}) is set up to map
870d35f9e086 Add some xrefs.
Richard M. Stallman <rms@gnu.org>
parents: 14499
diff changeset
1027 @code{tab} into 9. Thus, a key binding for character code 9 (the
870d35f9e086 Add some xrefs.
Richard M. Stallman <rms@gnu.org>
parents: 14499
diff changeset
1028 character @kbd{C-i}) also applies to @code{tab}. Likewise for the other
870d35f9e086 Add some xrefs.
Richard M. Stallman <rms@gnu.org>
parents: 14499
diff changeset
1029 symbols in this group. The function @code{read-char} likewise converts
870d35f9e086 Add some xrefs.
Richard M. Stallman <rms@gnu.org>
parents: 14499
diff changeset
1030 these events into characters.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1031
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
1032 In @sc{ascii}, @key{BS} is really @kbd{C-h}. But @code{backspace}
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1033 converts into the character code 127 (@key{DEL}), not into code 8
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1034 (@key{BS}). This is what most users prefer.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1035
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1036 @item @code{left}, @code{up}, @code{right}, @code{down}
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1037 Cursor arrow keys
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1038 @item @code{kp-add}, @code{kp-decimal}, @code{kp-divide}, @dots{}
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1039 Keypad keys (to the right of the regular keyboard).
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1040 @item @code{kp-0}, @code{kp-1}, @dots{}
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1041 Keypad keys with digits.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1042 @item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4}
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1043 Keypad PF keys.
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1044 @item @code{kp-home}, @code{kp-left}, @code{kp-up}, @code{kp-right}, @code{kp-down}
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1045 Keypad arrow keys. Emacs normally translates these into the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1046 corresponding non-keypad keys @code{home}, @code{left}, @dots{}
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1047 @item @code{kp-prior}, @code{kp-next}, @code{kp-end}, @code{kp-begin}, @code{kp-insert}, @code{kp-delete}
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1048 Additional keypad duplicates of keys ordinarily found elsewhere. Emacs
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1049 normally translates these into the like-named non-keypad keys.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1050 @end table
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1051
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1052 You can use the modifier keys @key{ALT}, @key{CTRL}, @key{HYPER},
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1053 @key{META}, @key{SHIFT}, and @key{SUPER} with function keys. The way to
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1054 represent them is with prefixes in the symbol name:
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1055
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1056 @table @samp
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1057 @item A-
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1058 The alt modifier.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1059 @item C-
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1060 The control modifier.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1061 @item H-
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1062 The hyper modifier.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1063 @item M-
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1064 The meta modifier.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1065 @item S-
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1066 The shift modifier.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1067 @item s-
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1068 The super modifier.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1069 @end table
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1070
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1071 Thus, the symbol for the key @key{F3} with @key{META} held down is
8532
4f0b260a8dd0 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
1072 @code{M-f3}. When you use more than one prefix, we recommend you
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1073 write them in alphabetical order; but the order does not matter in
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1074 arguments to the key-binding lookup and modification functions.
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1075
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1076 @node Mouse Events
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1077 @subsection Mouse Events
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1078
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1079 Emacs supports four kinds of mouse events: click events, drag events,
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1080 button-down events, and motion events. All mouse events are represented
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1081 as lists. The @sc{car} of the list is the event type; this says which
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1082 mouse button was involved, and which modifier keys were used with it.
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1083 The event type can also distinguish double or triple button presses
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1084 (@pxref{Repeat Events}). The rest of the list elements give position
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1085 and time information.
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1086
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1087 For key lookup, only the event type matters: two events of the same type
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1088 necessarily run the same command. The command can access the full
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1089 values of these events using the @samp{e} interactive code.
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1090 @xref{Interactive Codes}.
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1091
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1092 A key sequence that starts with a mouse event is read using the keymaps
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1093 of the buffer in the window that the mouse was in, not the current
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1094 buffer. This does not imply that clicking in a window selects that
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1095 window or its buffer---that is entirely under the control of the command
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1096 binding of the key sequence.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1097
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1098 @node Click Events
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1099 @subsection Click Events
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1100 @cindex click event
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1101 @cindex mouse click event
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1102
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1103 When the user presses a mouse button and releases it at the same
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1104 location, that generates a @dfn{click} event. Mouse click events have
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1105 this form:
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1106
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1107 @example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1108 (@var{event-type}
44675
7b62d2ff9381 Line break change.
Richard M. Stallman <rms@gnu.org>
parents: 44540
diff changeset
1109 (@var{window} @var{buffer-pos} (@var{x} . @var{y})
7b62d2ff9381 Line break change.
Richard M. Stallman <rms@gnu.org>
parents: 44540
diff changeset
1110 @var{timestamp})
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1111 @var{click-count})
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1112 @end example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1113
44540
18b15c51ab25 From Dave Love. Description of events in marginal areas.
Gerd Moellmann <gerd@gnu.org>
parents: 39221
diff changeset
1114 or, for clicks on strings in the mode line, header line or marginal
18b15c51ab25 From Dave Love. Description of events in marginal areas.
Gerd Moellmann <gerd@gnu.org>
parents: 39221
diff changeset
1115 areas:
18b15c51ab25 From Dave Love. Description of events in marginal areas.
Gerd Moellmann <gerd@gnu.org>
parents: 39221
diff changeset
1116
18b15c51ab25 From Dave Love. Description of events in marginal areas.
Gerd Moellmann <gerd@gnu.org>
parents: 39221
diff changeset
1117 @example
18b15c51ab25 From Dave Love. Description of events in marginal areas.
Gerd Moellmann <gerd@gnu.org>
parents: 39221
diff changeset
1118 (@var{event-type}
18b15c51ab25 From Dave Love. Description of events in marginal areas.
Gerd Moellmann <gerd@gnu.org>
parents: 39221
diff changeset
1119 (@var{window} @var{buffer-pos} (@var{x} . @var{y}) @var{timestamp} (@var{string} . @var{string-pos})
18b15c51ab25 From Dave Love. Description of events in marginal areas.
Gerd Moellmann <gerd@gnu.org>
parents: 39221
diff changeset
1120 @var{click-count})
18b15c51ab25 From Dave Love. Description of events in marginal areas.
Gerd Moellmann <gerd@gnu.org>
parents: 39221
diff changeset
1121 @end example
18b15c51ab25 From Dave Love. Description of events in marginal areas.
Gerd Moellmann <gerd@gnu.org>
parents: 39221
diff changeset
1122
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1123 Here is what the elements normally mean:
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1124
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1125 @table @asis
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1126 @item @var{event-type}
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1127 This is a symbol that indicates which mouse button was used. It is
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1128 one of the symbols @code{mouse-1}, @code{mouse-2}, @dots{}, where the
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1129 buttons are numbered left to right.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1130
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1131 You can also use prefixes @samp{A-}, @samp{C-}, @samp{H-}, @samp{M-},
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1132 @samp{S-} and @samp{s-} for modifiers alt, control, hyper, meta, shift
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1133 and super, just as you would with function keys.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1134
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1135 This symbol also serves as the event type of the event. Key bindings
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1136 describe events by their types; thus, if there is a key binding for
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1137 @code{mouse-1}, that binding would apply to all events whose
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1138 @var{event-type} is @code{mouse-1}.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1139
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1140 @item @var{window}
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1141 This is the window in which the click occurred.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1142
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1143 @item @var{x}, @var{y}
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1144 These are the pixel-denominated coordinates of the click, relative to
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1145 the top left corner of @var{window}, which is @code{(0 . 0)}.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1146
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1147 @item @var{buffer-pos}
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1148 This is the buffer position of the character clicked on.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1149
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1150 @item @var{timestamp}
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1151 This is the time at which the event occurred, in milliseconds. (Since
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1152 this value wraps around the entire range of Emacs Lisp integers in about
44540
18b15c51ab25 From Dave Love. Description of events in marginal areas.
Gerd Moellmann <gerd@gnu.org>
parents: 39221
diff changeset
1153 five hours, it is useful only for relating the times of nearby
18b15c51ab25 From Dave Love. Description of events in marginal areas.
Gerd Moellmann <gerd@gnu.org>
parents: 39221
diff changeset
1154 events.)
18b15c51ab25 From Dave Love. Description of events in marginal areas.
Gerd Moellmann <gerd@gnu.org>
parents: 39221
diff changeset
1155
18b15c51ab25 From Dave Love. Description of events in marginal areas.
Gerd Moellmann <gerd@gnu.org>
parents: 39221
diff changeset
1156 @item @var{string}
18b15c51ab25 From Dave Love. Description of events in marginal areas.
Gerd Moellmann <gerd@gnu.org>
parents: 39221
diff changeset
1157 This is the string on which the click occurred, including any
18b15c51ab25 From Dave Love. Description of events in marginal areas.
Gerd Moellmann <gerd@gnu.org>
parents: 39221
diff changeset
1158 properties.
18b15c51ab25 From Dave Love. Description of events in marginal areas.
Gerd Moellmann <gerd@gnu.org>
parents: 39221
diff changeset
1159
18b15c51ab25 From Dave Love. Description of events in marginal areas.
Gerd Moellmann <gerd@gnu.org>
parents: 39221
diff changeset
1160 @item @var{string-pos}
18b15c51ab25 From Dave Love. Description of events in marginal areas.
Gerd Moellmann <gerd@gnu.org>
parents: 39221
diff changeset
1161 This is the position in the string on which the click occurred,
18b15c51ab25 From Dave Love. Description of events in marginal areas.
Gerd Moellmann <gerd@gnu.org>
parents: 39221
diff changeset
1162 relevant if properties at the click need to be looked up.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1163
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1164 @item @var{click-count}
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1165 This is the number of rapid repeated presses so far of the same mouse
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1166 button. @xref{Repeat Events}.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1167 @end table
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1168
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1169 The meanings of @var{buffer-pos}, @var{x} and @var{y} are somewhat
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1170 different when the event location is in a special part of the screen,
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1171 such as the mode line or a scroll bar.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1172
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1173 If the location is in a scroll bar, then @var{buffer-pos} is the symbol
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1174 @code{vertical-scroll-bar} or @code{horizontal-scroll-bar}, and the pair
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1175 @code{(@var{x} . @var{y})} is replaced with a pair @code{(@var{portion}
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1176 . @var{whole})}, where @var{portion} is the distance of the click from
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1177 the top or left end of the scroll bar, and @var{whole} is the length of
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1178 the entire scroll bar.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1179
44540
18b15c51ab25 From Dave Love. Description of events in marginal areas.
Gerd Moellmann <gerd@gnu.org>
parents: 39221
diff changeset
1180 If the position is on a mode line, the vertical line separating
18b15c51ab25 From Dave Love. Description of events in marginal areas.
Gerd Moellmann <gerd@gnu.org>
parents: 39221
diff changeset
1181 @var{window} from its neighbor to the right, or in a marginal area,
18b15c51ab25 From Dave Love. Description of events in marginal areas.
Gerd Moellmann <gerd@gnu.org>
parents: 39221
diff changeset
1182 then @var{buffer-pos} is the symbol @code{mode-line},
18b15c51ab25 From Dave Love. Description of events in marginal areas.
Gerd Moellmann <gerd@gnu.org>
parents: 39221
diff changeset
1183 @code{header-line}, @code{vertical-line}, @code{left-margin}, or
18b15c51ab25 From Dave Love. Description of events in marginal areas.
Gerd Moellmann <gerd@gnu.org>
parents: 39221
diff changeset
1184 @code{right-margin}. For the mode line, @var{y} does not have
26288
6119687f6888 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25875
diff changeset
1185 meaningful data. For the vertical line, @var{x} does not have
6119687f6888 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25875
diff changeset
1186 meaningful data.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1187
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1188 In one special case, @var{buffer-pos} is a list containing a symbol (one
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1189 of the symbols listed above) instead of just the symbol. This happens
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1190 after the imaginary prefix keys for the event are inserted into the
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1191 input stream. @xref{Key Sequence Input}.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1192
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1193 @node Drag Events
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1194 @subsection Drag Events
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1195 @cindex drag event
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1196 @cindex mouse drag event
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1197
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1198 With Emacs, you can have a drag event without even changing your
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1199 clothes. A @dfn{drag event} happens every time the user presses a mouse
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1200 button and then moves the mouse to a different character position before
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1201 releasing the button. Like all mouse events, drag events are
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1202 represented in Lisp as lists. The lists record both the starting mouse
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1203 position and the final position, like this:
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1204
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1205 @example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1206 (@var{event-type}
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1207 (@var{window1} @var{buffer-pos1} (@var{x1} . @var{y1}) @var{timestamp1})
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1208 (@var{window2} @var{buffer-pos2} (@var{x2} . @var{y2}) @var{timestamp2})
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1209 @var{click-count})
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1210 @end example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1211
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1212 For a drag event, the name of the symbol @var{event-type} contains the
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1213 prefix @samp{drag-}. For example, dragging the mouse with button 2 held
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1214 down generates a @code{drag-mouse-2} event. The second and third
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1215 elements of the event give the starting and ending position of the drag.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1216 Aside from that, the data have the same meanings as in a click event
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1217 (@pxref{Click Events}). You can access the second element of any mouse
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1218 event in the same way, with no need to distinguish drag events from
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1219 others.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1220
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1221 The @samp{drag-} prefix follows the modifier key prefixes such as
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1222 @samp{C-} and @samp{M-}.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1223
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1224 If @code{read-key-sequence} receives a drag event that has no key
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1225 binding, and the corresponding click event does have a binding, it
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1226 changes the drag event into a click event at the drag's starting
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1227 position. This means that you don't have to distinguish between click
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1228 and drag events unless you want to.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1229
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1230 @node Button-Down Events
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1231 @subsection Button-Down Events
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1232 @cindex button-down event
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1233
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1234 Click and drag events happen when the user releases a mouse button.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1235 They cannot happen earlier, because there is no way to distinguish a
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1236 click from a drag until the button is released.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1237
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1238 If you want to take action as soon as a button is pressed, you need to
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1239 handle @dfn{button-down} events.@footnote{Button-down is the
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1240 conservative antithesis of drag.} These occur as soon as a button is
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1241 pressed. They are represented by lists that look exactly like click
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1242 events (@pxref{Click Events}), except that the @var{event-type} symbol
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1243 name contains the prefix @samp{down-}. The @samp{down-} prefix follows
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1244 modifier key prefixes such as @samp{C-} and @samp{M-}.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1245
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1246 The function @code{read-key-sequence} ignores any button-down events
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1247 that don't have command bindings; therefore, the Emacs command loop
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1248 ignores them too. This means that you need not worry about defining
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1249 button-down events unless you want them to do something. The usual
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1250 reason to define a button-down event is so that you can track mouse
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1251 motion (by reading motion events) until the button is released.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1252 @xref{Motion Events}.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1253
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1254 @node Repeat Events
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1255 @subsection Repeat Events
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1256 @cindex repeat events
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1257 @cindex double-click events
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1258 @cindex triple-click events
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
1259 @cindex mouse events, repeated
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1261 If you press the same mouse button more than once in quick succession
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1262 without moving the mouse, Emacs generates special @dfn{repeat} mouse
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1263 events for the second and subsequent presses.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1264
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1265 The most common repeat events are @dfn{double-click} events. Emacs
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1266 generates a double-click event when you click a button twice; the event
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1267 happens when you release the button (as is normal for all click
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1268 events).
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1269
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1270 The event type of a double-click event contains the prefix
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1271 @samp{double-}. Thus, a double click on the second mouse button with
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1272 @key{meta} held down comes to the Lisp program as
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1273 @code{M-double-mouse-2}. If a double-click event has no binding, the
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1274 binding of the corresponding ordinary click event is used to execute
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1275 it. Thus, you need not pay attention to the double click feature
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1276 unless you really want to.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1277
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1278 When the user performs a double click, Emacs generates first an ordinary
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1279 click event, and then a double-click event. Therefore, you must design
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1280 the command binding of the double click event to assume that the
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1281 single-click command has already run. It must produce the desired
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1282 results of a double click, starting from the results of a single click.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1283
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1284 This is convenient, if the meaning of a double click somehow ``builds
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1285 on'' the meaning of a single click---which is recommended user interface
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1286 design practice for double clicks.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1287
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1288 If you click a button, then press it down again and start moving the
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1289 mouse with the button held down, then you get a @dfn{double-drag} event
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1290 when you ultimately release the button. Its event type contains
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1291 @samp{double-drag} instead of just @samp{drag}. If a double-drag event
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1292 has no binding, Emacs looks for an alternate binding as if the event
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1293 were an ordinary drag.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1294
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1295 Before the double-click or double-drag event, Emacs generates a
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1296 @dfn{double-down} event when the user presses the button down for the
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1297 second time. Its event type contains @samp{double-down} instead of just
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1298 @samp{down}. If a double-down event has no binding, Emacs looks for an
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1299 alternate binding as if the event were an ordinary button-down event.
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1300 If it finds no binding that way either, the double-down event is
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1301 ignored.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1302
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1303 To summarize, when you click a button and then press it again right
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1304 away, Emacs generates a down event and a click event for the first
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1305 click, a double-down event when you press the button again, and finally
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1306 either a double-click or a double-drag event.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1307
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1308 If you click a button twice and then press it again, all in quick
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1309 succession, Emacs generates a @dfn{triple-down} event, followed by
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1310 either a @dfn{triple-click} or a @dfn{triple-drag}. The event types of
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1311 these events contain @samp{triple} instead of @samp{double}. If any
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1312 triple event has no binding, Emacs uses the binding that it would use
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1313 for the corresponding double event.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1314
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1315 If you click a button three or more times and then press it again, the
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1316 events for the presses beyond the third are all triple events. Emacs
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1317 does not have separate event types for quadruple, quintuple, etc.@:
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1318 events. However, you can look at the event list to find out precisely
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1319 how many times the button was pressed.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1320
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1321 @defun event-click-count event
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1322 This function returns the number of consecutive button presses that led
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1323 up to @var{event}. If @var{event} is a double-down, double-click or
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1324 double-drag event, the value is 2. If @var{event} is a triple event,
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1325 the value is 3 or greater. If @var{event} is an ordinary mouse event
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1326 (not a repeat event), the value is 1.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1327 @end defun
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1328
38603
13029a808e20 (Repeat Events): Add description of double-click-fuzz.
Gerd Moellmann <gerd@gnu.org>
parents: 27301
diff changeset
1329 @defvar double-click-fuzz
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1330 To generate repeat events, successive mouse button presses must be at
38603
13029a808e20 (Repeat Events): Add description of double-click-fuzz.
Gerd Moellmann <gerd@gnu.org>
parents: 27301
diff changeset
1331 approximately the same screen position. The value of
13029a808e20 (Repeat Events): Add description of double-click-fuzz.
Gerd Moellmann <gerd@gnu.org>
parents: 27301
diff changeset
1332 @code{double-click-fuzz} specifies the maximum number of pixels the
13029a808e20 (Repeat Events): Add description of double-click-fuzz.
Gerd Moellmann <gerd@gnu.org>
parents: 27301
diff changeset
1333 mouse may be moved between two successive clicks to make a
13029a808e20 (Repeat Events): Add description of double-click-fuzz.
Gerd Moellmann <gerd@gnu.org>
parents: 27301
diff changeset
1334 double-click.
13029a808e20 (Repeat Events): Add description of double-click-fuzz.
Gerd Moellmann <gerd@gnu.org>
parents: 27301
diff changeset
1335 @end defvar
13029a808e20 (Repeat Events): Add description of double-click-fuzz.
Gerd Moellmann <gerd@gnu.org>
parents: 27301
diff changeset
1336
13029a808e20 (Repeat Events): Add description of double-click-fuzz.
Gerd Moellmann <gerd@gnu.org>
parents: 27301
diff changeset
1337 @defvar double-click-time
13029a808e20 (Repeat Events): Add description of double-click-fuzz.
Gerd Moellmann <gerd@gnu.org>
parents: 27301
diff changeset
1338 To generate repeat events, the number of milliseconds between
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1339 successive button presses must be less than the value of
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1340 @code{double-click-time}. Setting @code{double-click-time} to
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1341 @code{nil} disables multi-click detection entirely. Setting it to
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1342 @code{t} removes the time limit; Emacs then detects multi-clicks by
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1343 position only.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1344 @end defvar
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1345
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1346 @node Motion Events
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1347 @subsection Motion Events
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1348 @cindex motion event
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1349 @cindex mouse motion events
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1350
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1351 Emacs sometimes generates @dfn{mouse motion} events to describe motion
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1352 of the mouse without any button activity. Mouse motion events are
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1353 represented by lists that look like this:
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1354
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1355 @example
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1356 (mouse-movement (@var{window} @var{buffer-pos} (@var{x} . @var{y}) @var{timestamp}))
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1357 @end example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1358
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1359 The second element of the list describes the current position of the
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1360 mouse, just as in a click event (@pxref{Click Events}).
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1361
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1362 The special form @code{track-mouse} enables generation of motion events
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1363 within its body. Outside of @code{track-mouse} forms, Emacs does not
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1364 generate events for mere motion of the mouse, and these events do not
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1365 appear. @xref{Mouse Tracking}.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1366
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1367 @node Focus Events
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1368 @subsection Focus Events
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1369 @cindex focus event
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1370
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1371 Window systems provide general ways for the user to control which window
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1372 gets keyboard input. This choice of window is called the @dfn{focus}.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1373 When the user does something to switch between Emacs frames, that
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1374 generates a @dfn{focus event}. The normal definition of a focus event,
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1375 in the global keymap, is to select a new frame within Emacs, as the user
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1376 would expect. @xref{Input Focus}.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1377
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1378 Focus events are represented in Lisp as lists that look like this:
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1379
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1380 @example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1381 (switch-frame @var{new-frame})
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1382 @end example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1383
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1384 @noindent
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1385 where @var{new-frame} is the frame switched to.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1386
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1387 Most X window managers are set up so that just moving the mouse into a
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1388 window is enough to set the focus there. Emacs appears to do this,
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1389 because it changes the cursor to solid in the new frame. However, there
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1390 is no need for the Lisp program to know about the focus change until
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1391 some other kind of input arrives. So Emacs generates a focus event only
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1392 when the user actually types a keyboard key or presses a mouse button in
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1393 the new frame; just moving the mouse between frames does not generate a
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1394 focus event.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1395
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1396 A focus event in the middle of a key sequence would garble the
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1397 sequence. So Emacs never generates a focus event in the middle of a key
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1398 sequence. If the user changes focus in the middle of a key
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1399 sequence---that is, after a prefix key---then Emacs reorders the events
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1400 so that the focus event comes either before or after the multi-event key
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1401 sequence, and not within it.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1402
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10834
diff changeset
1403 @node Misc Events
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10834
diff changeset
1404 @subsection Miscellaneous Window System Events
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10834
diff changeset
1405
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10834
diff changeset
1406 A few other event types represent occurrences within the window system.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10834
diff changeset
1407
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10834
diff changeset
1408 @table @code
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10834
diff changeset
1409 @cindex @code{delete-frame} event
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10834
diff changeset
1410 @item (delete-frame (@var{frame}))
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10834
diff changeset
1411 This kind of event indicates that the user gave the window manager
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10834
diff changeset
1412 a command to delete a particular window, which happens to be an Emacs frame.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10834
diff changeset
1413
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10834
diff changeset
1414 The standard definition of the @code{delete-frame} event is to delete @var{frame}.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10834
diff changeset
1415
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10834
diff changeset
1416 @cindex @code{iconify-frame} event
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10834
diff changeset
1417 @item (iconify-frame (@var{frame}))
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10834
diff changeset
1418 This kind of event indicates that the user iconified @var{frame} using
13007
8a1252eb804e Fix typos.
Richard M. Stallman <rms@gnu.org>
parents: 12285
diff changeset
1419 the window manager. Its standard definition is @code{ignore}; since the
8a1252eb804e Fix typos.
Richard M. Stallman <rms@gnu.org>
parents: 12285
diff changeset
1420 frame has already been iconified, Emacs has no work to do. The purpose
8a1252eb804e Fix typos.
Richard M. Stallman <rms@gnu.org>
parents: 12285
diff changeset
1421 of this event type is so that you can keep track of such events if you
8a1252eb804e Fix typos.
Richard M. Stallman <rms@gnu.org>
parents: 12285
diff changeset
1422 want to.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10834
diff changeset
1423
12285
1aad1cc93e3f make-frame-visible event was misdescribed as deiconify-frame.
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
1424 @cindex @code{make-frame-visible} event
1aad1cc93e3f make-frame-visible event was misdescribed as deiconify-frame.
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
1425 @item (make-frame-visible (@var{frame}))
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10834
diff changeset
1426 This kind of event indicates that the user deiconified @var{frame} using
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10834
diff changeset
1427 the window manager. Its standard definition is @code{ignore}; since the
13007
8a1252eb804e Fix typos.
Richard M. Stallman <rms@gnu.org>
parents: 12285
diff changeset
1428 frame has already been made visible, Emacs has no work to do.
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1429
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1430 @cindex @code{mouse-wheel} event
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1431 @item (mouse-wheel @var{position} @var{delta})
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1432 This kind of event is generated by moving a wheel on a mouse (such as
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1433 the MS Intellimouse). Its effect is typically a kind of scroll or zoom.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1434
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1435 The element @var{delta} describes the amount and direction of the wheel
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1436 rotation. Its absolute value is the number of increments by which the
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1437 wheel was rotated. A negative @var{delta} indicates that the wheel was
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1438 rotated backwards, towards the user, and a positive @var{delta}
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1439 indicates that the wheel was rotated forward, away from the user.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1440
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1441 The element @var{position} is a list describing the position of the
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1442 event, in the same format as used in a mouse-click event.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1443
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1444 This kind of event is generated only on some kinds of systems.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1445
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1446 @cindex @code{drag-n-drop} event
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1447 @item (drag-n-drop @var{position} @var{files})
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1448 This kind of event is generated when a group of files is
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1449 selected in an application outside of Emacs, and then dragged and
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1450 dropped onto an Emacs frame.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1451
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1452 The element @var{position} is a list describing the position of the
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1453 event, in the same format as used in a mouse-click event, and
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1454 @var{files} is the list of file names that were dragged and dropped.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1455 The usual way to handle this event is by visiting these files.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1456
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1457 This kind of event is generated, at present, only on some kinds of
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1458 systems.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10834
diff changeset
1459 @end table
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10834
diff changeset
1460
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1461 If one of these events arrives in the middle of a key sequence---that
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1462 is, after a prefix key---then Emacs reorders the events so that this
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1463 event comes either before or after the multi-event key sequence, not
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1464 within it.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1465
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1466 @node Event Examples
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1467 @subsection Event Examples
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1468
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1469 If the user presses and releases the left mouse button over the same
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1470 location, that generates a sequence of events like this:
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1471
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1472 @smallexample
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1473 (down-mouse-1 (#<window 18 on NEWS> 2613 (0 . 38) -864320))
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1474 (mouse-1 (#<window 18 on NEWS> 2613 (0 . 38) -864180))
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1475 @end smallexample
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1476
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1477 While holding the control key down, the user might hold down the
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1478 second mouse button, and drag the mouse from one line to the next.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1479 That produces two events, as shown here:
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1480
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1481 @smallexample
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1482 (C-down-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219))
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1483 (C-drag-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1484 (#<window 18 on NEWS> 3510 (0 . 28) -729648))
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1485 @end smallexample
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1486
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1487 While holding down the meta and shift keys, the user might press the
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1488 second mouse button on the window's mode line, and then drag the mouse
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1489 into another window. That produces a pair of events like these:
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1490
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1491 @smallexample
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1492 (M-S-down-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844))
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1493 (M-S-drag-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1494 (#<window 20 on carlton-sanskrit.tex> 161 (33 . 3)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1495 -453816))
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1496 @end smallexample
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1497
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1498 @node Classifying Events
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1499 @subsection Classifying Events
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1500 @cindex event type
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1501
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1502 Every event has an @dfn{event type}, which classifies the event for
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1503 key binding purposes. For a keyboard event, the event type equals the
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1504 event value; thus, the event type for a character is the character, and
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1505 the event type for a function key symbol is the symbol itself. For
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1506 events that are lists, the event type is the symbol in the @sc{car} of
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1507 the list. Thus, the event type is always a symbol or a character.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1508
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1509 Two events of the same type are equivalent where key bindings are
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1510 concerned; thus, they always run the same command. That does not
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1511 necessarily mean they do the same things, however, as some commands look
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1512 at the whole event to decide what to do. For example, some commands use
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1513 the location of a mouse event to decide where in the buffer to act.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1514
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1515 Sometimes broader classifications of events are useful. For example,
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1516 you might want to ask whether an event involved the @key{META} key,
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1517 regardless of which other key or mouse button was used.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1518
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1519 The functions @code{event-modifiers} and @code{event-basic-type} are
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1520 provided to get such information conveniently.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1521
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1522 @defun event-modifiers event
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1523 This function returns a list of the modifiers that @var{event} has. The
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1524 modifiers are symbols; they include @code{shift}, @code{control},
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1525 @code{meta}, @code{alt}, @code{hyper} and @code{super}. In addition,
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1526 the modifiers list of a mouse event symbol always contains one of
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1527 @code{click}, @code{drag}, and @code{down}.
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1528
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1529 The argument @var{event} may be an entire event object, or just an event
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1530 type.
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1531
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1532 Here are some examples:
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1533
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1534 @example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1535 (event-modifiers ?a)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1536 @result{} nil
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1537 (event-modifiers ?\C-a)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1538 @result{} (control)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1539 (event-modifiers ?\C-%)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1540 @result{} (control)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1541 (event-modifiers ?\C-\S-a)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1542 @result{} (control shift)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1543 (event-modifiers 'f5)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1544 @result{} nil
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1545 (event-modifiers 's-f5)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1546 @result{} (super)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1547 (event-modifiers 'M-S-f5)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1548 @result{} (meta shift)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1549 (event-modifiers 'mouse-1)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1550 @result{} (click)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1551 (event-modifiers 'down-mouse-1)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1552 @result{} (down)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1553 @end example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1554
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1555 The modifiers list for a click event explicitly contains @code{click},
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1556 but the event symbol name itself does not contain @samp{click}.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1557 @end defun
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1558
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1559 @defun event-basic-type event
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1560 This function returns the key or mouse button that @var{event}
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1561 describes, with all modifiers removed. For example:
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1562
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1563 @example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1564 (event-basic-type ?a)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1565 @result{} 97
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1566 (event-basic-type ?A)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1567 @result{} 97
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1568 (event-basic-type ?\C-a)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1569 @result{} 97
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1570 (event-basic-type ?\C-\S-a)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1571 @result{} 97
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1572 (event-basic-type 'f5)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1573 @result{} f5
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1574 (event-basic-type 's-f5)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1575 @result{} f5
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1576 (event-basic-type 'M-S-f5)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1577 @result{} f5
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1578 (event-basic-type 'down-mouse-1)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1579 @result{} mouse-1
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1580 @end example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1581 @end defun
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1582
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1583 @defun mouse-movement-p object
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1584 This function returns non-@code{nil} if @var{object} is a mouse movement
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1585 event.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1586 @end defun
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1587
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1588 @defun event-convert-list list
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1589 This function converts a list of modifier names and a basic event type
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1590 to an event type which specifies all of them. For example,
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1591
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1592 @example
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1593 (event-convert-list '(control ?a))
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1594 @result{} 1
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1595 (event-convert-list '(control meta ?a))
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1596 @result{} -134217727
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1597 (event-convert-list '(control super f1))
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1598 @result{} C-s-f1
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1599 @end example
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1600 @end defun
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1601
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1602 @node Accessing Events
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1603 @subsection Accessing Events
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
1604 @cindex mouse events, accessing the data
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
1605 @cindex accessing data of mouse events
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1606
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1607 This section describes convenient functions for accessing the data in
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1608 a mouse button or motion event.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1609
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1610 These two functions return the starting or ending position of a
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1611 mouse-button event, as a list of this form:
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1612
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1613 @example
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1614 (@var{window} @var{buffer-position} (@var{x} . @var{y}) @var{timestamp})
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1615 @end example
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1616
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1617 @defun event-start event
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1618 This returns the starting position of @var{event}.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1619
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1620 If @var{event} is a click or button-down event, this returns the
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1621 location of the event. If @var{event} is a drag event, this returns the
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1622 drag's starting position.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1623 @end defun
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1624
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1625 @defun event-end event
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1626 This returns the ending position of @var{event}.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1627
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1628 If @var{event} is a drag event, this returns the position where the user
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1629 released the mouse button. If @var{event} is a click or button-down
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1630 event, the value is actually the starting position, which is the only
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1631 position such events have.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1632 @end defun
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1633
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
1634 @cindex mouse position list, accessing
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1635 These five functions take a position list as described above, and
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1636 return various parts of it.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1637
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1638 @defun posn-window position
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1639 Return the window that @var{position} is in.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1640 @end defun
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1641
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1642 @defun posn-point position
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1643 Return the buffer position in @var{position}. This is an integer.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1644 @end defun
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1645
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1646 @defun posn-x-y position
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1647 Return the pixel-based x and y coordinates in @var{position}, as a cons
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1648 cell @code{(@var{x} . @var{y})}.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1649 @end defun
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1650
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1651 @defun posn-col-row position
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1652 Return the row and column (in units of characters) of @var{position}, as
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1653 a cons cell @code{(@var{col} . @var{row})}. These are computed from the
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1654 @var{x} and @var{y} values actually found in @var{position}.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1655 @end defun
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1656
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
1657 @cindex mouse event, timestamp
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
1658 @cindex timestamp of a mouse event
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1659 @defun posn-timestamp position
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1660 Return the timestamp in @var{position}.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1661 @end defun
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1662
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1663 These functions are useful for decoding scroll bar events.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1664
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1665 @defun scroll-bar-event-ratio event
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1666 This function returns the fractional vertical position of a scroll bar
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1667 event within the scroll bar. The value is a cons cell
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1668 @code{(@var{portion} . @var{whole})} containing two integers whose ratio
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1669 is the fractional position.
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1670 @end defun
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1671
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1672 @defun scroll-bar-scale ratio total
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1673 This function multiplies (in effect) @var{ratio} by @var{total},
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1674 rounding the result to an integer. The argument @var{ratio} is not a
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1675 number, but rather a pair @code{(@var{num} . @var{denom})}---typically a
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1676 value returned by @code{scroll-bar-event-ratio}.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1677
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1678 This function is handy for scaling a position on a scroll bar into a
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1679 buffer position. Here's how to do that:
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1680
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1681 @example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1682 (+ (point-min)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1683 (scroll-bar-scale
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1684 (posn-x-y (event-start event))
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1685 (- (point-max) (point-min))))
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1686 @end example
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1687
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1688 Recall that scroll bar events have two integers forming a ratio, in place
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1689 of a pair of x and y coordinates.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1690 @end defun
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1691
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1692 @node Strings of Events
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1693 @subsection Putting Keyboard Events in Strings
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
1694 @cindex keyboard events in strings
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
1695 @cindex strings with keyboard events
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1696
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1697 In most of the places where strings are used, we conceptualize the
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1698 string as containing text characters---the same kind of characters found
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1699 in buffers or files. Occasionally Lisp programs use strings that
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1700 conceptually contain keyboard characters; for example, they may be key
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1701 sequences or keyboard macro definitions. However, storing keyboard
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1702 characters in a string is a complex matter, for reasons of historical
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1703 compatibility, and it is not always possible.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1704
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1705 We recommend that new programs avoid dealing with these complexities
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1706 by not storing keyboard events in strings. Here is how to do that:
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1707
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1708 @itemize @bullet
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1709 @item
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1710 Use vectors instead of strings for key sequences, when you plan to use
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1711 them for anything other than as arguments to @code{lookup-key} and
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1712 @code{define-key}. For example, you can use
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1713 @code{read-key-sequence-vector} instead of @code{read-key-sequence}, and
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1714 @code{this-command-keys-vector} instead of @code{this-command-keys}.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1715
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1716 @item
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1717 Use vectors to write key sequence constants containing meta characters,
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1718 even when passing them directly to @code{define-key}.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1719
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1720 @item
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1721 When you have to look at the contents of a key sequence that might be a
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1722 string, use @code{listify-key-sequence} (@pxref{Event Input Misc})
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1723 first, to convert it to a list.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1724 @end itemize
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1725
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1726 The complexities stem from the modifier bits that keyboard input
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1727 characters can include. Aside from the Meta modifier, none of these
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1728 modifier bits can be included in a string, and the Meta modifier is
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1729 allowed only in special cases.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1730
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1731 The earliest GNU Emacs versions represented meta characters as codes
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1732 in the range of 128 to 255. At that time, the basic character codes
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1733 ranged from 0 to 127, so all keyboard character codes did fit in a
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1734 string. Many Lisp programs used @samp{\M-} in string constants to stand
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1735 for meta characters, especially in arguments to @code{define-key} and
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1736 similar functions, and key sequences and sequences of events were always
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1737 represented as strings.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1738
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1739 When we added support for larger basic character codes beyond 127, and
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1740 additional modifier bits, we had to change the representation of meta
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1741 characters. Now the flag that represents the Meta modifier in a
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1742 character is
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1743 @tex
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
1744 @math{2^{27}}
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1745 @end tex
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
1746 @ifnottex
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1747 2**27
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
1748 @end ifnottex
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1749 and such numbers cannot be included in a string.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1750
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1751 To support programs with @samp{\M-} in string constants, there are
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1752 special rules for including certain meta characters in a string.
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1753 Here are the rules for interpreting a string as a sequence of input
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1754 characters:
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1755
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1756 @itemize @bullet
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1757 @item
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1758 If the keyboard character value is in the range of 0 to 127, it can go
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1759 in the string unchanged.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1760
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1761 @item
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1762 The meta variants of those characters, with codes in the range of
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1763 @tex
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
1764 @math{2^{27}}
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1765 @end tex
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
1766 @ifnottex
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1767 2**27
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
1768 @end ifnottex
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1769 to
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1770 @tex
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
1771 @math{2^{27} + 127},
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1772 @end tex
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
1773 @ifnottex
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1774 2**27+127,
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
1775 @end ifnottex
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1776 can also go in the string, but you must change their
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1777 numeric values. You must set the
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1778 @tex
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
1779 @math{2^{7}}
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1780 @end tex
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
1781 @ifnottex
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1782 2**7
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
1783 @end ifnottex
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1784 bit instead of the
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1785 @tex
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
1786 @math{2^{27}}
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1787 @end tex
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
1788 @ifnottex
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1789 2**27
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
1790 @end ifnottex
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1791 bit, resulting in a value between 128 and 255. Only a unibyte string
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1792 can include these codes.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1793
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1794 @item
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
1795 Non-@sc{ascii} characters above 256 can be included in a multibyte string.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1796
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1797 @item
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1798 Other keyboard character events cannot fit in a string. This includes
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1799 keyboard events in the range of 128 to 255.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1800 @end itemize
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1801
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1802 Functions such as @code{read-key-sequence} that construct strings of
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1803 keyboard input characters follow these rules: they construct vectors
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1804 instead of strings, when the events won't fit in a string.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1805
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1806 When you use the read syntax @samp{\M-} in a string, it produces a
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1807 code in the range of 128 to 255---the same code that you get if you
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1808 modify the corresponding keyboard event to put it in the string. Thus,
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1809 meta events in strings work consistently regardless of how they get into
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1810 the strings.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1811
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1812 However, most programs would do well to avoid these issues by
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1813 following the recommendations at the beginning of this section.
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1814
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1815 @node Reading Input
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1816 @section Reading Input
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1817
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1818 The editor command loop reads key sequences using the function
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1819 @code{read-key-sequence}, which uses @code{read-event}. These and other
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1820 functions for event input are also available for use in Lisp programs.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1821 See also @code{momentary-string-display} in @ref{Temporary Displays},
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1822 and @code{sit-for} in @ref{Waiting}. @xref{Terminal Input}, for
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1823 functions and variables for controlling terminal input modes and
15764
870d35f9e086 Add some xrefs.
Richard M. Stallman <rms@gnu.org>
parents: 14499
diff changeset
1824 debugging terminal input. @xref{Translating Input}, for features you
870d35f9e086 Add some xrefs.
Richard M. Stallman <rms@gnu.org>
parents: 14499
diff changeset
1825 can use for translating or modifying input events while reading them.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1826
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1827 For higher-level input facilities, see @ref{Minibuffers}.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1828
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1829 @menu
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1830 * Key Sequence Input:: How to read one key sequence.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1831 * Reading One Event:: How to read just one event.
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
1832 * Invoking the Input Method:: How reading an event uses the input method.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1833 * Quoted Character Input:: Asking the user to specify a character.
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1834 * Event Input Misc:: How to reread or throw away input events.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1835 @end menu
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1836
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1837 @node Key Sequence Input
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1838 @subsection Key Sequence Input
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1839 @cindex key sequence input
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1840
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1841 The command loop reads input a key sequence at a time, by calling
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1842 @code{read-key-sequence}. Lisp programs can also call this function;
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1843 for example, @code{describe-key} uses it to read the key to describe.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1844
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1845 @defun read-key-sequence prompt
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1846 @cindex key sequence
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1847 This function reads a key sequence and returns it as a string or
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1848 vector. It keeps reading events until it has accumulated a complete key
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1849 sequence; that is, enough to specify a non-prefix command using the
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1850 currently active keymaps.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1851
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1852 If the events are all characters and all can fit in a string, then
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1853 @code{read-key-sequence} returns a string (@pxref{Strings of Events}).
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1854 Otherwise, it returns a vector, since a vector can hold all kinds of
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1855 events---characters, symbols, and lists. The elements of the string or
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1856 vector are the events in the key sequence.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1857
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1858 The argument @var{prompt} is either a string to be displayed in the echo
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1859 area as a prompt, or @code{nil}, meaning not to display a prompt.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1860
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1861 In the example below, the prompt @samp{?} is displayed in the echo area,
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1862 and the user types @kbd{C-x C-f}.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1863
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1864 @example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1865 (read-key-sequence "?")
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1866
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1867 @group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1868 ---------- Echo Area ----------
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1869 ?@kbd{C-x C-f}
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1870 ---------- Echo Area ----------
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1871
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1872 @result{} "^X^F"
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1873 @end group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1874 @end example
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1875
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1876 The function @code{read-key-sequence} suppresses quitting: @kbd{C-g}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1877 typed while reading with this function works like any other character,
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1878 and does not set @code{quit-flag}. @xref{Quitting}.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1879 @end defun
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1880
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1881 @defun read-key-sequence-vector prompt
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1882 This is like @code{read-key-sequence} except that it always
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1883 returns the key sequence as a vector, never as a string.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1884 @xref{Strings of Events}.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1885 @end defun
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1886
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1887 @cindex upper case key sequence
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1888 @cindex downcasing in @code{lookup-key}
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1889 If an input character is an upper-case letter and has no key binding,
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1890 but its lower-case equivalent has one, then @code{read-key-sequence}
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1891 converts the character to lower case. Note that @code{lookup-key} does
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1892 not perform case conversion in this way.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1893
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1894 The function @code{read-key-sequence} also transforms some mouse events.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1895 It converts unbound drag events into click events, and discards unbound
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1896 button-down events entirely. It also reshuffles focus events and
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1897 miscellaneous window events so that they never appear in a key sequence
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1898 with any other events.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1899
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
1900 @cindex @code{header-line} prefix key
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
1901 @cindex @code{mode-line} prefix key
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
1902 @cindex @code{vertical-line} prefix key
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
1903 @cindex @code{horizontal-scroll-bar} prefix key
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
1904 @cindex @code{vertical-scroll-bar} prefix key
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
1905 @cindex @code{menu-bar} prefix key
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
1906 @cindex mouse events, in special parts of frame
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1907 When mouse events occur in special parts of a window, such as a mode
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1908 line or a scroll bar, the event type shows nothing special---it is the
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1909 same symbol that would normally represent that combination of mouse
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1910 button and modifier keys. The information about the window part is kept
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1911 elsewhere in the event---in the coordinates. But
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1912 @code{read-key-sequence} translates this information into imaginary
27301
8c79b30d8475 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27193
diff changeset
1913 ``prefix keys'', all of which are symbols: @code{header-line},
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
1914 @code{horizontal-scroll-bar}, @code{menu-bar}, @code{mode-line},
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
1915 @code{vertical-line}, and @code{vertical-scroll-bar}. You can define
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
1916 meanings for mouse clicks in special window parts by defining key
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
1917 sequences using these imaginary prefix keys.
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1918
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1919 For example, if you call @code{read-key-sequence} and then click the
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1920 mouse on the window's mode line, you get two events, like this:
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1921
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1922 @example
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1923 (read-key-sequence "Click on the mode line: ")
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1924 @result{} [mode-line
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1925 (mouse-1
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1926 (#<window 6 on NEWS> mode-line
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1927 (40 . 63) 5959987))]
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1928 @end example
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1929
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1930 @defvar num-input-keys
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1931 @c Emacs 19 feature
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1932 This variable's value is the number of key sequences processed so far in
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1933 this Emacs session. This includes key sequences read from the terminal
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1934 and key sequences read from keyboard macros being executed.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1935 @end defvar
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1936
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1937 @defvar num-nonmacro-input-events
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1938 This variable holds the total number of input events received so far
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1939 from the terminal---not counting those generated by keyboard macros.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1940 @end defvar
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1941
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1942 @node Reading One Event
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1943 @subsection Reading One Event
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
1944 @cindex reading a single event
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
1945 @cindex event, reading only one
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1946
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
1947 The lowest level functions for command input are those that read a
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1948 single event.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1949
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
1950 @defun read-event &optional prompt inherit-input-method
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1951 This function reads and returns the next event of command input, waiting
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1952 if necessary until an event is available. Events can come directly from
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1953 the user or from a keyboard macro.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1954
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
1955 If the optional argument @var{prompt} is non-@code{nil}, it should be a
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
1956 string to display in the echo area as a prompt. Otherwise,
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
1957 @code{read-event} does not display any message to indicate it is waiting
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
1958 for input; instead, it prompts by echoing: it displays descriptions of
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
1959 the events that led to or were read by the current command. @xref{The
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
1960 Echo Area}.
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
1961
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
1962 If @var{inherit-input-method} is non-@code{nil}, then the current input
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
1963 method (if any) is employed to make it possible to enter a
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
1964 non-@sc{ascii} character. Otherwise, input method handling is disabled
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
1965 for reading this event.
23110
0d84817a4973 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22843
diff changeset
1966
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1967 If @code{cursor-in-echo-area} is non-@code{nil}, then @code{read-event}
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1968 moves the cursor temporarily to the echo area, to the end of any message
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1969 displayed there. Otherwise @code{read-event} does not move the cursor.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1970
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1971 If @code{read-event} gets an event that is defined as a help character, in
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1972 some cases @code{read-event} processes the event directly without
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1973 returning. @xref{Help Functions}. Certain other events, called
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1974 @dfn{special events}, are also processed directly within
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1975 @code{read-event} (@pxref{Special Events}).
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1976
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1977 Here is what happens if you call @code{read-event} and then press the
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1978 right-arrow function key:
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1979
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1980 @example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1981 @group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1982 (read-event)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1983 @result{} right
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1984 @end group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1985 @end example
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1986 @end defun
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1987
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
1988 @defun read-char &optional prompt inherit-input-method
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
1989 This function reads and returns a character of command input. If the
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
1990 user generates an event which is not a character (i.e. a mouse click or
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
1991 function key event), @code{read-char} signals an error. The arguments
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
1992 work as in @code{read-event}.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1993
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
1994 In the first example, the user types the character @kbd{1} (@sc{ascii}
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1995 code 49). The second example shows a keyboard macro definition that
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1996 calls @code{read-char} from the minibuffer using @code{eval-expression}.
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1997 @code{read-char} reads the keyboard macro's very next character, which
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1998 is @kbd{1}. Then @code{eval-expression} displays its return value in
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
1999 the echo area.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2000
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2001 @example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2002 @group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2003 (read-char)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2004 @result{} 49
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2005 @end group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2006
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2007 @group
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2008 ;; @r{We assume here you use @kbd{M-:} to evaluate this.}
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2009 (symbol-function 'foo)
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2010 @result{} "^[:(read-char)^M1"
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2011 @end group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2012 @group
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2013 (execute-kbd-macro 'foo)
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2014 @print{} 49
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2015 @result{} nil
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2016 @end group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2017 @end example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2018 @end defun
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2019
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
2020 @defun read-char-exclusive &optional prompt inherit-input-method
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
2021 This function reads and returns a character of command input. If the
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
2022 user generates an event which is not a character,
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
2023 @code{read-char-exclusive} ignores it and reads another event, until it
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
2024 gets a character. The arguments work as in @code{read-event}.
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
2025 @end defun
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
2026
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
2027 @node Invoking the Input Method
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
2028 @subsection Invoking the Input Method
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
2029
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
2030 The event-reading functions invoke the current input method, if any
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
2031 (@pxref{Input Methods}). If the value of @code{input-method-function}
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
2032 is non-@code{nil}, it should be a function; when @code{read-event} reads
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
2033 a printing character (including @key{SPC}) with no modifier bits, it
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
2034 calls that function, passing the character as an argument.
22843
63f6e25f0cbd *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22440
diff changeset
2035
63f6e25f0cbd *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22440
diff changeset
2036 @defvar input-method-function
63f6e25f0cbd *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22440
diff changeset
2037 If this is non-@code{nil}, its value specifies the current input method
63f6e25f0cbd *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22440
diff changeset
2038 function.
23110
0d84817a4973 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22843
diff changeset
2039
0d84817a4973 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22843
diff changeset
2040 @strong{Note:} Don't bind this variable with @code{let}. It is often
0d84817a4973 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22843
diff changeset
2041 buffer-local, and if you bind it around reading input (which is exactly
0d84817a4973 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22843
diff changeset
2042 when you @emph{would} bind it), switching buffers asynchronously while
0d84817a4973 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22843
diff changeset
2043 Emacs is waiting will cause the value to be restored in the wrong
0d84817a4973 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22843
diff changeset
2044 buffer.
22843
63f6e25f0cbd *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22440
diff changeset
2045 @end defvar
63f6e25f0cbd *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22440
diff changeset
2046
63f6e25f0cbd *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22440
diff changeset
2047 The input method function should return a list of events which should
63f6e25f0cbd *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22440
diff changeset
2048 be used as input. (If the list is @code{nil}, that means there is no
63f6e25f0cbd *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22440
diff changeset
2049 input, so @code{read-event} waits for another event.) These events are
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
2050 processed before the events in @code{unread-command-events}
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26288
diff changeset
2051 (@pxref{Event Input Misc}). Events
22843
63f6e25f0cbd *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22440
diff changeset
2052 returned by the input method function are not passed to the input method
63f6e25f0cbd *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22440
diff changeset
2053 function again, even if they are printing characters with no modifier
63f6e25f0cbd *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22440
diff changeset
2054 bits.
63f6e25f0cbd *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22440
diff changeset
2055
63f6e25f0cbd *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22440
diff changeset
2056 If the input method function calls @code{read-event} or
63f6e25f0cbd *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22440
diff changeset
2057 @code{read-key-sequence}, it should bind @code{input-method-function} to
63f6e25f0cbd *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22440
diff changeset
2058 @code{nil} first, to prevent recursion.
63f6e25f0cbd *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22440
diff changeset
2059
63f6e25f0cbd *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22440
diff changeset
2060 The input method function is not called when reading the second and
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
2061 subsequent events of a key sequence. Thus, these characters are not
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
2062 subject to input method processing. The input method function should
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
2063 test the values of @code{overriding-local-map} and
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
2064 @code{overriding-terminal-local-map}; if either of these variables is
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
2065 non-@code{nil}, the input method should put its argument into a list and
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 23110
diff changeset
2066 return that list with no further processing.
22843
63f6e25f0cbd *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22440
diff changeset
2067
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2068 @node Quoted Character Input
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2069 @subsection Quoted Character Input
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2070 @cindex quoted character input
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2071
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
2072 You can use the function @code{read-quoted-char} to ask the user to
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
2073 specify a character, and allow the user to specify a control or meta
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
2074 character conveniently, either literally or as an octal character code.
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
2075 The command @code{quoted-insert} uses this function.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2076
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2077 @defun read-quoted-char &optional prompt
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2078 @cindex octal character input
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2079 @cindex control characters, reading
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2080 @cindex nonprinting characters, reading
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2081 This function is like @code{read-char}, except that if the first
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2082 character read is an octal digit (0-7), it reads any number of octal
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2083 digits (but stopping if a non-octal digit is found), and returns the
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2084 character represented by that numeric character code.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2085
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2086 Quitting is suppressed when the first character is read, so that the
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2087 user can enter a @kbd{C-g}. @xref{Quitting}.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2088
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2089 If @var{prompt} is supplied, it specifies a string for prompting the
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2090 user. The prompt string is always displayed in the echo area, followed
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2091 by a single @samp{-}.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2092
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2093 In the following example, the user types in the octal number 177 (which
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2094 is 127 in decimal).
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2095
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2096 @example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2097 (read-quoted-char "What character")
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2098
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2099 @group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2100 ---------- Echo Area ----------
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2101 What character-@kbd{177}
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2102 ---------- Echo Area ----------
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2103
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2104 @result{} 127
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2105 @end group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2106 @end example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2107 @end defun
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2108
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
2109 @need 2000
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2110 @node Event Input Misc
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2111 @subsection Miscellaneous Event Input Features
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2112
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2113 This section describes how to ``peek ahead'' at events without using
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2114 them up, how to check for pending input, and how to discard pending
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2115 input. See also the function @code{read-passwd} (@pxref{Reading a
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2116 Password}).
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2117
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2118 @defvar unread-command-events
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2119 @cindex next input
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2120 @cindex peeking at input
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2121 This variable holds a list of events waiting to be read as command
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2122 input. The events are used in the order they appear in the list, and
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2123 removed one by one as they are used.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2124
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2125 The variable is needed because in some cases a function reads an event
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2126 and then decides not to use it. Storing the event in this variable
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2127 causes it to be processed normally, by the command loop or by the
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2128 functions to read command input.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2129
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2130 @cindex prefix argument unreading
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2131 For example, the function that implements numeric prefix arguments reads
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2132 any number of digits. When it finds a non-digit event, it must unread
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2133 the event so that it can be read normally by the command loop.
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2134 Likewise, incremental search uses this feature to unread events with no
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2135 special meaning in a search, because these events should exit the search
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2136 and then execute normally.
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2137
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
2138 The reliable and easy way to extract events from a key sequence so as to
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
2139 put them in @code{unread-command-events} is to use
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2140 @code{listify-key-sequence} (@pxref{Strings of Events}).
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2141
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2142 Normally you add events to the front of this list, so that the events
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2143 most recently unread will be reread first.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2144 @end defvar
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2145
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2146 @defun listify-key-sequence key
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2147 This function converts the string or vector @var{key} to a list of
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2148 individual events, which you can put in @code{unread-command-events}.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2149 @end defun
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2150
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2151 @defvar unread-command-char
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2152 This variable holds a character to be read as command input.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2153 A value of -1 means ``empty''.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2154
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2155 This variable is mostly obsolete now that you can use
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2156 @code{unread-command-events} instead; it exists only to support programs
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2157 written for Emacs versions 18 and earlier.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2158 @end defvar
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2159
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2160 @defun input-pending-p
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2161 @cindex waiting for command key input
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2162 This function determines whether any command input is currently
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2163 available to be read. It returns immediately, with value @code{t} if
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2164 there is available input, @code{nil} otherwise. On rare occasions it
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2165 may return @code{t} when no input is available.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2166 @end defun
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2167
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2168 @defvar last-input-event
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2169 @defvarx last-input-char
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2170 This variable records the last terminal input event read, whether
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2171 as part of a command or explicitly by a Lisp program.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2172
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2173 In the example below, the Lisp program reads the character @kbd{1},
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
2174 @sc{ascii} code 49. It becomes the value of @code{last-input-event},
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2175 while @kbd{C-e} (we assume @kbd{C-x C-e} command is used to evaluate
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2176 this expression) remains the value of @code{last-command-event}.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2177
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2178 @example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2179 @group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2180 (progn (print (read-char))
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2181 (print last-command-event)
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2182 last-input-event)
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2183 @print{} 49
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2184 @print{} 5
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2185 @result{} 49
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2186 @end group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2187 @end example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2188
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2189 The alias @code{last-input-char} exists for compatibility with
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2190 Emacs version 18.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2191 @end defvar
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2192
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2193 @defun discard-input
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2194 @cindex flush input
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2195 @cindex discard input
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2196 @cindex terminate keyboard macro
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2197 This function discards the contents of the terminal input buffer and
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2198 cancels any keyboard macro that might be in the process of definition.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2199 It returns @code{nil}.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2200
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2201 In the following example, the user may type a number of characters right
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2202 after starting the evaluation of the form. After the @code{sleep-for}
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2203 finishes sleeping, @code{discard-input} discards any characters typed
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2204 during the sleep.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2205
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2206 @example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2207 (progn (sleep-for 2)
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2208 (discard-input))
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2209 @result{} nil
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2210 @end example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2211 @end defun
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2212
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2213 @node Special Events
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2214 @section Special Events
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2215
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2216 @cindex special events
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2217 Special events are handled at a very low level---as soon as they are
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2218 read. The @code{read-event} function processes these events itself, and
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2219 never returns them.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2220
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2221 Events that are handled in this way do not echo, they are never grouped
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2222 into key sequences, and they never appear in the value of
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2223 @code{last-command-event} or @code{(this-command-keys)}. They do not
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2224 discard a numeric argument, they cannot be unread with
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2225 @code{unread-command-events}, they may not appear in a keyboard macro,
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2226 and they are not recorded in a keyboard macro while you are defining
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2227 one.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2228
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2229 These events do, however, appear in @code{last-input-event} immediately
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2230 after they are read, and this is the way for the event's definition to
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2231 find the actual event.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2232
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2233 The events types @code{iconify-frame}, @code{make-frame-visible} and
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2234 @code{delete-frame} are normally handled in this way. The keymap which
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2235 defines how to handle special events---and which events are special---is
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2236 in the variable @code{special-event-map} (@pxref{Active Keymaps}).
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2237
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2238 @node Waiting
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2239 @section Waiting for Elapsed Time or Input
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2240 @cindex pausing
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2241 @cindex waiting
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2242
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2243 The wait functions are designed to wait for a certain amount of time
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2244 to pass or until there is input. For example, you may wish to pause in
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2245 the middle of a computation to allow the user time to view the display.
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2246 @code{sit-for} pauses and updates the screen, and returns immediately if
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2247 input comes in, while @code{sleep-for} pauses without updating the
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2248 screen.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2249
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2250 @defun sit-for seconds &optional millisec nodisp
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2251 This function performs redisplay (provided there is no pending input
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2252 from the user), then waits @var{seconds} seconds, or until input is
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2253 available. The value is @code{t} if @code{sit-for} waited the full
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2254 time with no input arriving (see @code{input-pending-p} in @ref{Event
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2255 Input Misc}). Otherwise, the value is @code{nil}.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2256
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2257 The argument @var{seconds} need not be an integer. If it is a floating
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2258 point number, @code{sit-for} waits for a fractional number of seconds.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2259 Some systems support only a whole number of seconds; on these systems,
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2260 @var{seconds} is rounded down.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2261
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2262 The optional argument @var{millisec} specifies an additional waiting
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2263 period measured in milliseconds. This adds to the period specified by
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2264 @var{seconds}. If the system doesn't support waiting fractions of a
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2265 second, you get an error if you specify nonzero @var{millisec}.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2266
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
2267 The expression @code{(sit-for 0)} is a convenient way to request a
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24951
diff changeset
2268 redisplay, without any delay. @xref{Forcing Redisplay}.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2269
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2270 If @var{nodisp} is non-@code{nil}, then @code{sit-for} does not
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2271 redisplay, but it still returns as soon as input is available (or when
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2272 the timeout elapses).
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2273
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10834
diff changeset
2274 Iconifying or deiconifying a frame makes @code{sit-for} return, because
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10834
diff changeset
2275 that generates an event. @xref{Misc Events}.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10834
diff changeset
2276
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2277 The usual purpose of @code{sit-for} is to give the user time to read
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2278 text that you display.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2279 @end defun
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2280
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2281 @defun sleep-for seconds &optional millisec
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2282 This function simply pauses for @var{seconds} seconds without updating
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2283 the display. It pays no attention to available input. It returns
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2284 @code{nil}.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2285
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2286 The argument @var{seconds} need not be an integer. If it is a floating
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2287 point number, @code{sleep-for} waits for a fractional number of seconds.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2288 Some systems support only a whole number of seconds; on these systems,
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2289 @var{seconds} is rounded down.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2290
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2291 The optional argument @var{millisec} specifies an additional waiting
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2292 period measured in milliseconds. This adds to the period specified by
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2293 @var{seconds}. If the system doesn't support waiting fractions of a
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2294 second, you get an error if you specify nonzero @var{millisec}.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2295
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2296 Use @code{sleep-for} when you wish to guarantee a delay.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2297 @end defun
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2298
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2299 @xref{Time of Day}, for functions to get the current time.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2300
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2301 @node Quitting
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2302 @section Quitting
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2303 @cindex @kbd{C-g}
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2304 @cindex quitting
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2305
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
2306 Typing @kbd{C-g} while a Lisp function is running causes Emacs to
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
2307 @dfn{quit} whatever it is doing. This means that control returns to the
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
2308 innermost active command loop.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2309
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2310 Typing @kbd{C-g} while the command loop is waiting for keyboard input
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2311 does not cause a quit; it acts as an ordinary input character. In the
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2312 simplest case, you cannot tell the difference, because @kbd{C-g}
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2313 normally runs the command @code{keyboard-quit}, whose effect is to quit.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2314 However, when @kbd{C-g} follows a prefix key, they combine to form an
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2315 undefined key. The effect is to cancel the prefix key as well as any
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2316 prefix argument.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2317
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2318 In the minibuffer, @kbd{C-g} has a different definition: it aborts out
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2319 of the minibuffer. This means, in effect, that it exits the minibuffer
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2320 and then quits. (Simply quitting would return to the command loop
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2321 @emph{within} the minibuffer.) The reason why @kbd{C-g} does not quit
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2322 directly when the command reader is reading input is so that its meaning
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2323 can be redefined in the minibuffer in this way. @kbd{C-g} following a
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2324 prefix key is not redefined in the minibuffer, and it has its normal
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2325 effect of canceling the prefix key and prefix argument. This too
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2326 would not be possible if @kbd{C-g} always quit directly.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2327
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
2328 When @kbd{C-g} does directly quit, it does so by setting the variable
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2329 @code{quit-flag} to @code{t}. Emacs checks this variable at appropriate
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2330 times and quits if it is not @code{nil}. Setting @code{quit-flag}
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2331 non-@code{nil} in any way thus causes a quit.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2332
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2333 At the level of C code, quitting cannot happen just anywhere; only at the
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
2334 special places that check @code{quit-flag}. The reason for this is
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2335 that quitting at other places might leave an inconsistency in Emacs's
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2336 internal state. Because quitting is delayed until a safe place, quitting
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2337 cannot make Emacs crash.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2338
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2339 Certain functions such as @code{read-key-sequence} or
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2340 @code{read-quoted-char} prevent quitting entirely even though they wait
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2341 for input. Instead of quitting, @kbd{C-g} serves as the requested
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2342 input. In the case of @code{read-key-sequence}, this serves to bring
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2343 about the special behavior of @kbd{C-g} in the command loop. In the
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2344 case of @code{read-quoted-char}, this is so that @kbd{C-q} can be used
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2345 to quote a @kbd{C-g}.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2346
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2347 You can prevent quitting for a portion of a Lisp function by binding
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2348 the variable @code{inhibit-quit} to a non-@code{nil} value. Then,
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2349 although @kbd{C-g} still sets @code{quit-flag} to @code{t} as usual, the
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2350 usual result of this---a quit---is prevented. Eventually,
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2351 @code{inhibit-quit} will become @code{nil} again, such as when its
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2352 binding is unwound at the end of a @code{let} form. At that time, if
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2353 @code{quit-flag} is still non-@code{nil}, the requested quit happens
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
2354 immediately. This behavior is ideal when you wish to make sure that
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
2355 quitting does not happen within a ``critical section'' of the program.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2356
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2357 @cindex @code{read-quoted-char} quitting
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2358 In some functions (such as @code{read-quoted-char}), @kbd{C-g} is
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
2359 handled in a special way that does not involve quitting. This is done
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2360 by reading the input with @code{inhibit-quit} bound to @code{t}, and
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2361 setting @code{quit-flag} to @code{nil} before @code{inhibit-quit}
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2362 becomes @code{nil} again. This excerpt from the definition of
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2363 @code{read-quoted-char} shows how this is done; it also shows that
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2364 normal quitting is permitted after the first character of input.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2365
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2366 @example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2367 (defun read-quoted-char (&optional prompt)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2368 "@dots{}@var{documentation}@dots{}"
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2369 (let ((message-log-max nil) done (first t) (code 0) char)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2370 (while (not done)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2371 (let ((inhibit-quit first)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2372 @dots{})
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2373 (and prompt (message "%s-" prompt))
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2374 (setq char (read-event))
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2375 (if inhibit-quit (setq quit-flag nil)))
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2376 @r{@dots{}set the variable @code{code}@dots{}})
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2377 code))
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2378 @end example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2379
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2380 @defvar quit-flag
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2381 If this variable is non-@code{nil}, then Emacs quits immediately, unless
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2382 @code{inhibit-quit} is non-@code{nil}. Typing @kbd{C-g} ordinarily sets
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2383 @code{quit-flag} non-@code{nil}, regardless of @code{inhibit-quit}.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2384 @end defvar
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2385
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2386 @defvar inhibit-quit
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2387 This variable determines whether Emacs should quit when @code{quit-flag}
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2388 is set to a value other than @code{nil}. If @code{inhibit-quit} is
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2389 non-@code{nil}, then @code{quit-flag} has no special effect.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2390 @end defvar
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2391
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2392 @deffn Command keyboard-quit
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2393 This function signals the @code{quit} condition with @code{(signal 'quit
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2394 nil)}. This is the same thing that quitting does. (See @code{signal}
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2395 in @ref{Errors}.)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2396 @end deffn
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2397
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2398 You can specify a character other than @kbd{C-g} to use for quitting.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2399 See the function @code{set-input-mode} in @ref{Terminal Input}.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2400
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2401 @node Prefix Command Arguments
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2402 @section Prefix Command Arguments
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2403 @cindex prefix argument
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2404 @cindex raw prefix argument
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2405 @cindex numeric prefix argument
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2406
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2407 Most Emacs commands can use a @dfn{prefix argument}, a number
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2408 specified before the command itself. (Don't confuse prefix arguments
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
2409 with prefix keys.) The prefix argument is at all times represented by a
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
2410 value, which may be @code{nil}, meaning there is currently no prefix
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
2411 argument. Each command may use the prefix argument or ignore it.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2412
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2413 There are two representations of the prefix argument: @dfn{raw} and
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2414 @dfn{numeric}. The editor command loop uses the raw representation
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2415 internally, and so do the Lisp variables that store the information, but
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2416 commands can request either representation.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2417
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2418 Here are the possible values of a raw prefix argument:
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2419
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2420 @itemize @bullet
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2421 @item
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2422 @code{nil}, meaning there is no prefix argument. Its numeric value is
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2423 1, but numerous commands make a distinction between @code{nil} and the
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2424 integer 1.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2425
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2426 @item
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2427 An integer, which stands for itself.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2428
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2429 @item
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2430 A list of one element, which is an integer. This form of prefix
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2431 argument results from one or a succession of @kbd{C-u}'s with no
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2432 digits. The numeric value is the integer in the list, but some
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2433 commands make a distinction between such a list and an integer alone.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2434
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2435 @item
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2436 The symbol @code{-}. This indicates that @kbd{M--} or @kbd{C-u -} was
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2437 typed, without following digits. The equivalent numeric value is
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2438 @minus{}1, but some commands make a distinction between the integer
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2439 @minus{}1 and the symbol @code{-}.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2440 @end itemize
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2441
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2442 We illustrate these possibilities by calling the following function with
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2443 various prefixes:
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2444
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2445 @example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2446 @group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2447 (defun display-prefix (arg)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2448 "Display the value of the raw prefix arg."
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2449 (interactive "P")
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2450 (message "%s" arg))
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2451 @end group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2452 @end example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2453
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2454 @noindent
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2455 Here are the results of calling @code{display-prefix} with various
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2456 raw prefix arguments:
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2457
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2458 @example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2459 M-x display-prefix @print{} nil
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2460
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2461 C-u M-x display-prefix @print{} (4)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2462
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2463 C-u C-u M-x display-prefix @print{} (16)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2464
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2465 C-u 3 M-x display-prefix @print{} 3
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2466
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2467 M-3 M-x display-prefix @print{} 3 ; @r{(Same as @code{C-u 3}.)}
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2468
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2469 C-u - M-x display-prefix @print{} -
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2470
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2471 M-- M-x display-prefix @print{} - ; @r{(Same as @code{C-u -}.)}
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2472
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2473 C-u - 7 M-x display-prefix @print{} -7
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2474
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2475 M-- 7 M-x display-prefix @print{} -7 ; @r{(Same as @code{C-u -7}.)}
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2476 @end example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2477
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2478 Emacs uses two variables to store the prefix argument:
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2479 @code{prefix-arg} and @code{current-prefix-arg}. Commands such as
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2480 @code{universal-argument} that set up prefix arguments for other
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2481 commands store them in @code{prefix-arg}. In contrast,
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2482 @code{current-prefix-arg} conveys the prefix argument to the current
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2483 command, so setting it has no effect on the prefix arguments for future
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2484 commands.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2485
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2486 Normally, commands specify which representation to use for the prefix
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2487 argument, either numeric or raw, in the @code{interactive} declaration.
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
2488 (@xref{Using Interactive}.) Alternatively, functions may look at the
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2489 value of the prefix argument directly in the variable
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2490 @code{current-prefix-arg}, but this is less clean.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2491
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2492 @defun prefix-numeric-value arg
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2493 This function returns the numeric meaning of a valid raw prefix argument
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2494 value, @var{arg}. The argument may be a symbol, a number, or a list.
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
2495 If it is @code{nil}, the value 1 is returned; if it is @code{-}, the
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
2496 value @minus{}1 is returned; if it is a number, that number is returned;
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
2497 if it is a list, the @sc{car} of that list (which should be a number) is
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
2498 returned.
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2499 @end defun
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2500
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2501 @defvar current-prefix-arg
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2502 This variable holds the raw prefix argument for the @emph{current}
16736
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 15764
diff changeset
2503 command. Commands may examine it directly, but the usual method for
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 15764
diff changeset
2504 accessing it is with @code{(interactive "P")}.
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2505 @end defvar
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2506
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2507 @defvar prefix-arg
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2508 The value of this variable is the raw prefix argument for the
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2509 @emph{next} editing command. Commands such as @code{universal-argument}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2510 that specify prefix arguments for the following command work by setting
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2511 this variable.
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2512 @end defvar
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2513
22440
8a51f757af2c *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
2514 @defvar last-prefix-arg
8a51f757af2c *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
2515 The raw prefix argument value used by the previous command.
8a51f757af2c *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
2516 @end defvar
8a51f757af2c *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
2517
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2518 The following commands exist to set up prefix arguments for the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2519 following command. Do not call them for any other reason.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2520
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2521 @deffn Command universal-argument
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2522 This command reads input and specifies a prefix argument for the
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2523 following command. Don't call this command yourself unless you know
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2524 what you are doing.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2525 @end deffn
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2526
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2527 @deffn Command digit-argument arg
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2528 This command adds to the prefix argument for the following command. The
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2529 argument @var{arg} is the raw prefix argument as it was before this
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2530 command; it is used to compute the updated prefix argument. Don't call
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2531 this command yourself unless you know what you are doing.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2532 @end deffn
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2533
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2534 @deffn Command negative-argument arg
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2535 This command adds to the numeric argument for the next command. The
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2536 argument @var{arg} is the raw prefix argument as it was before this
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2537 command; its value is negated to form the new prefix argument. Don't
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2538 call this command yourself unless you know what you are doing.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2539 @end deffn
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2540
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2541 @node Recursive Editing
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2542 @section Recursive Editing
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2543 @cindex recursive command loop
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2544 @cindex recursive editing level
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2545 @cindex command loop, recursive
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2546
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2547 The Emacs command loop is entered automatically when Emacs starts up.
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2548 This top-level invocation of the command loop never exits; it keeps
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2549 running as long as Emacs does. Lisp programs can also invoke the
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2550 command loop. Since this makes more than one activation of the command
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2551 loop, we call it @dfn{recursive editing}. A recursive editing level has
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2552 the effect of suspending whatever command invoked it and permitting the
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2553 user to do arbitrary editing before resuming that command.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2554
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2555 The commands available during recursive editing are the same ones
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2556 available in the top-level editing loop and defined in the keymaps.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2557 Only a few special commands exit the recursive editing level; the others
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2558 return to the recursive editing level when they finish. (The special
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2559 commands for exiting are always available, but they do nothing when
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2560 recursive editing is not in progress.)
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2561
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2562 All command loops, including recursive ones, set up all-purpose error
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2563 handlers so that an error in a command run from the command loop will
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2564 not exit the loop.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2565
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2566 @cindex minibuffer input
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2567 Minibuffer input is a special kind of recursive editing. It has a few
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2568 special wrinkles, such as enabling display of the minibuffer and the
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2569 minibuffer window, but fewer than you might suppose. Certain keys
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2570 behave differently in the minibuffer, but that is only because of the
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2571 minibuffer's local map; if you switch windows, you get the usual Emacs
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2572 commands.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2573
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2574 @cindex @code{throw} example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2575 @kindex exit
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2576 @cindex exit recursive editing
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2577 @cindex aborting
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2578 To invoke a recursive editing level, call the function
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2579 @code{recursive-edit}. This function contains the command loop; it also
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2580 contains a call to @code{catch} with tag @code{exit}, which makes it
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2581 possible to exit the recursive editing level by throwing to @code{exit}
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2582 (@pxref{Catch and Throw}). If you throw a value other than @code{t},
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2583 then @code{recursive-edit} returns normally to the function that called
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2584 it. The command @kbd{C-M-c} (@code{exit-recursive-edit}) does this.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2585 Throwing a @code{t} value causes @code{recursive-edit} to quit, so that
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2586 control returns to the command loop one level up. This is called
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2587 @dfn{aborting}, and is done by @kbd{C-]} (@code{abort-recursive-edit}).
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2588
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2589 Most applications should not use recursive editing, except as part of
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2590 using the minibuffer. Usually it is more convenient for the user if you
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2591 change the major mode of the current buffer temporarily to a special
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
2592 major mode, which should have a command to go back to the previous mode.
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
2593 (The @kbd{e} command in Rmail uses this technique.) Or, if you wish to
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
2594 give the user different text to edit ``recursively'', create and select
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
2595 a new buffer in a special mode. In this mode, define a command to
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
2596 complete the processing and go back to the previous buffer. (The
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
2597 @kbd{m} command in Rmail does this.)
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2598
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2599 Recursive edits are useful in debugging. You can insert a call to
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2600 @code{debug} into a function definition as a sort of breakpoint, so that
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2601 you can look around when the function gets there. @code{debug} invokes
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2602 a recursive edit but also provides the other features of the debugger.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2603
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2604 Recursive editing levels are also used when you type @kbd{C-r} in
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2605 @code{query-replace} or use @kbd{C-x q} (@code{kbd-macro-query}).
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2606
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2607 @defun recursive-edit
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2608 @cindex suspend evaluation
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2609 This function invokes the editor command loop. It is called
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2610 automatically by the initialization of Emacs, to let the user begin
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2611 editing. When called from a Lisp program, it enters a recursive editing
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2612 level.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2613
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2614 In the following example, the function @code{simple-rec} first
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2615 advances point one word, then enters a recursive edit, printing out a
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2616 message in the echo area. The user can then do any editing desired, and
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2617 then type @kbd{C-M-c} to exit and continue executing @code{simple-rec}.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2618
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2619 @example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2620 (defun simple-rec ()
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2621 (forward-word 1)
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2622 (message "Recursive edit in progress")
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2623 (recursive-edit)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2624 (forward-word 1))
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2625 @result{} simple-rec
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2626 (simple-rec)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2627 @result{} nil
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2628 @end example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2629 @end defun
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2630
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2631 @deffn Command exit-recursive-edit
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2632 This function exits from the innermost recursive edit (including
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2633 minibuffer input). Its definition is effectively @code{(throw 'exit
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2634 nil)}.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2635 @end deffn
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2636
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2637 @deffn Command abort-recursive-edit
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2638 This function aborts the command that requested the innermost recursive
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2639 edit (including minibuffer input), by signaling @code{quit}
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2640 after exiting the recursive edit. Its definition is effectively
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2641 @code{(throw 'exit t)}. @xref{Quitting}.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2642 @end deffn
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2643
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2644 @deffn Command top-level
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2645 This function exits all recursive editing levels; it does not return a
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2646 value, as it jumps completely out of any computation directly back to
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2647 the main command loop.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2648 @end deffn
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2649
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2650 @defun recursion-depth
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2651 This function returns the current depth of recursive edits. When no
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2652 recursive edit is active, it returns 0.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2653 @end defun
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2654
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2655 @node Disabling Commands
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2656 @section Disabling Commands
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2657 @cindex disabled command
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2658
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2659 @dfn{Disabling a command} marks the command as requiring user
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2660 confirmation before it can be executed. Disabling is used for commands
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2661 which might be confusing to beginning users, to prevent them from using
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2662 the commands by accident.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2663
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2664 @kindex disabled
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2665 The low-level mechanism for disabling a command is to put a
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2666 non-@code{nil} @code{disabled} property on the Lisp symbol for the
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2667 command. These properties are normally set up by the user's
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2668 init file (@pxref{Init File}) with Lisp expressions such as this:
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2669
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2670 @example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2671 (put 'upcase-region 'disabled t)
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2672 @end example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2673
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2674 @noindent
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2675 For a few commands, these properties are present by default (you can
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2676 remove them in your init file if you wish).
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2677
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2678 If the value of the @code{disabled} property is a string, the message
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2679 saying the command is disabled includes that string. For example:
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2680
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2681 @example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2682 (put 'delete-region 'disabled
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2683 "Text deleted this way cannot be yanked back!\n")
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2684 @end example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2685
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2686 @xref{Disabling,,, emacs, The GNU Emacs Manual}, for the details on
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2687 what happens when a disabled command is invoked interactively.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2688 Disabling a command has no effect on calling it as a function from Lisp
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2689 programs.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2690
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2691 @deffn Command enable-command command
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2692 Allow @var{command} to be executed without special confirmation from now
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2693 on, and (if the user confirms) alter the user's init file (@pxref{Init
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2694 File}) so that this will apply to future sessions.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2695 @end deffn
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2696
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2697 @deffn Command disable-command command
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2698 Require special confirmation to execute @var{command} from now on, and
25875
6a17c48b52ef *** empty log message ***
Phillip Rulon <pjr@gnu.org>
parents: 25751
diff changeset
2699 (if the user confirms) alter the user's init file so that this
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
2700 will apply to future sessions.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2701 @end deffn
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2702
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2703 @defvar disabled-command-hook
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2704 When the user invokes a disabled command interactively, this normal hook
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2705 is run instead of the disabled command. The hook functions can use
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2706 @code{this-command-keys} to determine what the user typed to run the
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6557
diff changeset
2707 command, and thus find the command itself. @xref{Hooks}.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2708
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2709 By default, @code{disabled-command-hook} contains a function that asks
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2710 the user whether to proceed.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2711 @end defvar
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2712
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2713 @node Command History
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2714 @section Command History
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2715 @cindex command history
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2716 @cindex complex command
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2717 @cindex history of commands
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2718
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2719 The command loop keeps a history of the complex commands that have
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2720 been executed, to make it convenient to repeat these commands. A
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2721 @dfn{complex command} is one for which the interactive argument reading
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2722 uses the minibuffer. This includes any @kbd{M-x} command, any
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2723 @kbd{M-:} command, and any command whose @code{interactive}
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2724 specification reads an argument from the minibuffer. Explicit use of
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2725 the minibuffer during the execution of the command itself does not cause
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2726 the command to be considered complex.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2727
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2728 @defvar command-history
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2729 This variable's value is a list of recent complex commands, each
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2730 represented as a form to evaluate. It continues to accumulate all
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2731 complex commands for the duration of the editing session, but when it
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2732 reaches the maximum size (specified by the variable
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2733 @code{history-length}), the oldest elements are deleted as new ones are
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2734 added.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2735
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2736 @example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2737 @group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2738 command-history
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2739 @result{} ((switch-to-buffer "chistory.texi")
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2740 (describe-key "^X^[")
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2741 (visit-tags-table "~/emacs/src/")
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2742 (find-tag "repeat-complex-command"))
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2743 @end group
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2744 @end example
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2745 @end defvar
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2746
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2747 This history list is actually a special case of minibuffer history
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2748 (@pxref{Minibuffer History}), with one special twist: the elements are
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2749 expressions rather than strings.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2750
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2751 There are a number of commands devoted to the editing and recall of
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2752 previous commands. The commands @code{repeat-complex-command}, and
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2753 @code{list-command-history} are described in the user manual
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2754 (@pxref{Repetition,,, emacs, The GNU Emacs Manual}). Within the
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2755 minibuffer, the usual minibuffer history commands are available.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2756
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2757 @node Keyboard Macros
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2758 @section Keyboard Macros
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2759 @cindex keyboard macros
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2760
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2761 A @dfn{keyboard macro} is a canned sequence of input events that can
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2762 be considered a command and made the definition of a key. The Lisp
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2763 representation of a keyboard macro is a string or vector containing the
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2764 events. Don't confuse keyboard macros with Lisp macros
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2765 (@pxref{Macros}).
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2766
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2767 @defun execute-kbd-macro kbdmacro &optional count
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2768 This function executes @var{kbdmacro} as a sequence of events. If
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2769 @var{kbdmacro} is a string or vector, then the events in it are executed
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2770 exactly as if they had been input by the user. The sequence is
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2771 @emph{not} expected to be a single key sequence; normally a keyboard
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2772 macro definition consists of several key sequences concatenated.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2773
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2774 If @var{kbdmacro} is a symbol, then its function definition is used in
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2775 place of @var{kbdmacro}. If that is another symbol, this process repeats.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2776 Eventually the result should be a string or vector. If the result is
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2777 not a symbol, string, or vector, an error is signaled.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2778
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2779 The argument @var{count} is a repeat count; @var{kbdmacro} is executed that
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2780 many times. If @var{count} is omitted or @code{nil}, @var{kbdmacro} is
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2781 executed once. If it is 0, @var{kbdmacro} is executed over and over until it
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2782 encounters an error or a failing search.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2783
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2784 @xref{Reading One Event}, for an example of using @code{execute-kbd-macro}.
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2785 @end defun
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2786
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2787 @defvar executing-macro
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2788 This variable contains the string or vector that defines the keyboard
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2789 macro that is currently executing. It is @code{nil} if no macro is
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2790 currently executing. A command can test this variable so as to behave
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2791 differently when run from an executing macro. Do not set this variable
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2792 yourself.
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2793 @end defvar
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2794
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2795 @defvar defining-kbd-macro
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2796 This variable indicates whether a keyboard macro is being defined. A
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2797 command can test this variable so as to behave differently while a macro
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
2798 is being defined. The commands @code{start-kbd-macro} and
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2799 @code{end-kbd-macro} set this variable---do not set it yourself.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10834
diff changeset
2800
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2801 The variable is always local to the current terminal and cannot be
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10834
diff changeset
2802 buffer-local. @xref{Multiple Displays}.
6557
74758cf67338 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6260
diff changeset
2803 @end defvar
6260
d8bf24309d5e Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2804
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2805 @defvar last-kbd-macro
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2806 This variable is the definition of the most recently defined keyboard
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2807 macro. Its value is a string or vector, or @code{nil}.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2808
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2809 The variable is always local to the current terminal and cannot be
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2810 buffer-local. @xref{Multiple Displays}.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2811 @end defvar
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2812
39210
c717c37b1a2c (Using Interactive): Document interactive-form.
Eli Zaretskii <eliz@gnu.org>
parents: 38603
diff changeset
2813 @defvar kbd-macro-termination-hook
c717c37b1a2c (Using Interactive): Document interactive-form.
Eli Zaretskii <eliz@gnu.org>
parents: 38603
diff changeset
2814 This normal hook (@pxref{Standard Hooks}) is run when a keyboard
c717c37b1a2c (Using Interactive): Document interactive-form.
Eli Zaretskii <eliz@gnu.org>
parents: 38603
diff changeset
2815 macro terminates, regardless of what caused it to terminate (reaching
c717c37b1a2c (Using Interactive): Document interactive-form.
Eli Zaretskii <eliz@gnu.org>
parents: 38603
diff changeset
2816 the macro end or an error which ended the macro prematurely).
c717c37b1a2c (Using Interactive): Document interactive-form.
Eli Zaretskii <eliz@gnu.org>
parents: 38603
diff changeset
2817 @end defvar