annotate lispref/commands.texi @ 11736:07ac8009368c

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