annotate lispref/commands.texi @ 21530:be8599b6636a

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