annotate lispref/commands.texi @ 52674:7490e5357dba

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