|
0
|
1 @c -*-texinfo-*-
|
|
|
2 @c This is part of the XEmacs Lisp Reference Manual.
|
|
|
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
|
|
|
4 @c See the file lispref.texi for copying conditions.
|
|
|
5 @setfilename ../../info/commands.info
|
|
|
6 @node Command Loop, Keymaps, Minibuffers, Top
|
|
|
7 @chapter Command Loop
|
|
|
8 @cindex editor command loop
|
|
|
9 @cindex command loop
|
|
|
10
|
|
|
11 When you run XEmacs, it enters the @dfn{editor command loop} almost
|
|
|
12 immediately. This loop reads events, executes their definitions,
|
|
|
13 and displays the results. In this chapter, we describe how these things
|
|
|
14 are done, and the subroutines that allow Lisp programs to do them.
|
|
|
15
|
|
|
16 @menu
|
|
|
17 * Command Overview:: How the command loop reads commands.
|
|
|
18 * Defining Commands:: Specifying how a function should read arguments.
|
|
|
19 * Interactive Call:: Calling a command, so that it will read arguments.
|
|
|
20 * Command Loop Info:: Variables set by the command loop for you to examine.
|
|
|
21 * Events:: What input looks like when you read it.
|
|
|
22 * Reading Input:: How to read input events from the keyboard or mouse.
|
|
|
23 * Waiting:: Waiting for user input or elapsed time.
|
|
|
24 * Quitting:: How @kbd{C-g} works. How to catch or defer quitting.
|
|
|
25 * Prefix Command Arguments:: How the commands to set prefix args work.
|
|
|
26 * Recursive Editing:: Entering a recursive edit,
|
|
|
27 and why you usually shouldn't.
|
|
|
28 * Disabling Commands:: How the command loop handles disabled commands.
|
|
|
29 * Command History:: How the command history is set up, and how accessed.
|
|
|
30 * Keyboard Macros:: How keyboard macros are implemented.
|
|
|
31 @end menu
|
|
|
32
|
|
|
33 @node Command Overview
|
|
|
34 @section Command Loop Overview
|
|
|
35
|
|
|
36 The command loop in XEmacs is a standard event loop, reading events
|
|
|
37 one at a time with @code{next-event} and handling them with
|
|
|
38 @code{dispatch-event}. An event is typically a single user action, such
|
|
|
39 as a keypress, mouse movement, or menu selection; but they can also be
|
|
|
40 notifications from the window system, informing XEmacs that (for
|
|
|
41 example) part of its window was just uncovered and needs to be redrawn.
|
|
|
42 @xref{Events}. Pending events are held in a first-in, first-out list
|
|
|
43 called the @dfn{event queue}: events are read from the head of the list,
|
|
|
44 and newly arriving events are added to the tail. In this way, events
|
|
|
45 are always processed in the order in which they arrive.
|
|
|
46
|
|
|
47 @code{dispatch-event} does most of the work of handling user actions.
|
|
|
48 The first thing it must do is put the events together into a key
|
|
|
49 sequence, which is a sequence of events that translates into a command.
|
|
|
50 It does this by consulting the active keymaps, which specify what the
|
|
|
51 valid key sequences are and how to translate them into commands.
|
|
|
52 @xref{Key Lookup}, for information on how this is done. The result of
|
|
|
53 the translation should be a keyboard macro or an interactively callable
|
|
|
54 function. If the key is @kbd{M-x}, then it reads the name of another
|
|
|
55 command, which it then calls. This is done by the command
|
|
|
56 @code{execute-extended-command} (@pxref{Interactive Call}).
|
|
|
57
|
|
|
58 To execute a command requires first reading the arguments for it.
|
|
|
59 This is done by calling @code{command-execute} (@pxref{Interactive
|
|
|
60 Call}). For commands written in Lisp, the @code{interactive}
|
|
|
61 specification says how to read the arguments. This may use the prefix
|
|
|
62 argument (@pxref{Prefix Command Arguments}) or may read with prompting
|
|
|
63 in the minibuffer (@pxref{Minibuffers}). For example, the command
|
|
|
64 @code{find-file} has an @code{interactive} specification which says to
|
|
|
65 read a file name using the minibuffer. The command's function body does
|
|
|
66 not use the minibuffer; if you call this command from Lisp code as a
|
|
|
67 function, you must supply the file name string as an ordinary Lisp
|
|
|
68 function argument.
|
|
|
69
|
|
|
70 If the command is a string or vector (i.e., a keyboard macro) then
|
|
|
71 @code{execute-kbd-macro} is used to execute it. You can call this
|
|
|
72 function yourself (@pxref{Keyboard Macros}).
|
|
|
73
|
|
|
74 To terminate the execution of a running command, type @kbd{C-g}. This
|
|
|
75 character causes @dfn{quitting} (@pxref{Quitting}).
|
|
|
76
|
|
|
77 @defvar pre-command-hook
|
|
|
78 The editor command loop runs this normal hook before each command. At
|
|
|
79 that time, @code{this-command} contains the command that is about to
|
|
|
80 run, and @code{last-command} describes the previous command.
|
|
|
81 @xref{Hooks}.
|
|
|
82 @end defvar
|
|
|
83
|
|
|
84 @defvar post-command-hook
|
|
|
85 The editor command loop runs this normal hook after each command. (In
|
|
|
86 FSF Emacs, it is also run when the command loop is entered, or
|
|
|
87 reentered after an error or quit.) At that time,
|
|
|
88 @code{this-command} describes the command that just ran, and
|
|
|
89 @code{last-command} describes the command before that. @xref{Hooks}.
|
|
|
90 @end defvar
|
|
|
91
|
|
|
92 Quitting is suppressed while running @code{pre-command-hook} and
|
|
|
93 @code{post-command-hook}. If an error happens while executing one of
|
|
|
94 these hooks, it terminates execution of the hook, but that is all it
|
|
|
95 does.
|
|
|
96
|
|
|
97 @node Defining Commands
|
|
|
98 @section Defining Commands
|
|
|
99 @cindex defining commands
|
|
|
100 @cindex commands, defining
|
|
|
101 @cindex functions, making them interactive
|
|
|
102 @cindex interactive function
|
|
|
103
|
|
|
104 A Lisp function becomes a command when its body contains, at top
|
|
|
105 level, a form that calls the special form @code{interactive}. This
|
|
|
106 form does nothing when actually executed, but its presence serves as a
|
|
|
107 flag to indicate that interactive calling is permitted. Its argument
|
|
|
108 controls the reading of arguments for an interactive call.
|
|
|
109
|
|
|
110 @menu
|
|
|
111 * Using Interactive:: General rules for @code{interactive}.
|
|
|
112 * Interactive Codes:: The standard letter-codes for reading arguments
|
|
|
113 in various ways.
|
|
|
114 * Interactive Examples:: Examples of how to read interactive arguments.
|
|
|
115 @end menu
|
|
|
116
|
|
|
117 @node Using Interactive
|
|
|
118 @subsection Using @code{interactive}
|
|
|
119
|
|
|
120 This section describes how to write the @code{interactive} form that
|
|
|
121 makes a Lisp function an interactively-callable command.
|
|
|
122
|
|
|
123 @defspec interactive arg-descriptor
|
|
|
124 @cindex argument descriptors
|
|
|
125 This special form declares that the function in which it appears is a
|
|
|
126 command, and that it may therefore be called interactively (via
|
|
|
127 @kbd{M-x} or by entering a key sequence bound to it). The argument
|
|
|
128 @var{arg-descriptor} declares how to compute the arguments to the
|
|
|
129 command when the command is called interactively.
|
|
|
130
|
|
|
131 A command may be called from Lisp programs like any other function, but
|
|
|
132 then the caller supplies the arguments and @var{arg-descriptor} has no
|
|
|
133 effect.
|
|
|
134
|
|
|
135 The @code{interactive} form has its effect because the command loop
|
|
|
136 (actually, its subroutine @code{call-interactively}) scans through the
|
|
|
137 function definition looking for it, before calling the function. Once
|
|
|
138 the function is called, all its body forms including the
|
|
|
139 @code{interactive} form are executed, but at this time
|
|
|
140 @code{interactive} simply returns @code{nil} without even evaluating its
|
|
|
141 argument.
|
|
|
142 @end defspec
|
|
|
143
|
|
|
144 There are three possibilities for the argument @var{arg-descriptor}:
|
|
|
145
|
|
|
146 @itemize @bullet
|
|
|
147 @item
|
|
|
148 It may be omitted or @code{nil}; then the command is called with no
|
|
|
149 arguments. This leads quickly to an error if the command requires one
|
|
|
150 or more arguments.
|
|
|
151
|
|
|
152 @item
|
|
|
153 It may be a Lisp expression that is not a string; then it should be a
|
|
|
154 form that is evaluated to get a list of arguments to pass to the
|
|
|
155 command.
|
|
|
156 @cindex argument evaluation form
|
|
|
157
|
|
|
158 If this expression reads keyboard input (this includes using the
|
|
|
159 minibuffer), keep in mind that the integer value of point or the mark
|
|
|
160 before reading input may be incorrect after reading input. This is
|
|
|
161 because the current buffer may be receiving subprocess output;
|
|
|
162 if subprocess output arrives while the command is waiting for input,
|
|
|
163 it could relocate point and the mark.
|
|
|
164
|
|
|
165 Here's an example of what @emph{not} to do:
|
|
|
166
|
|
|
167 @smallexample
|
|
|
168 (interactive
|
|
|
169 (list (region-beginning) (region-end)
|
|
|
170 (read-string "Foo: " nil 'my-history)))
|
|
|
171 @end smallexample
|
|
|
172
|
|
|
173 @noindent
|
|
|
174 Here's how to avoid the problem, by examining point and the mark only
|
|
|
175 after reading the keyboard input:
|
|
|
176
|
|
|
177 @smallexample
|
|
|
178 (interactive
|
|
|
179 (let ((string (read-string "Foo: " nil 'my-history)))
|
|
|
180 (list (region-beginning) (region-end) string)))
|
|
|
181 @end smallexample
|
|
|
182
|
|
|
183 @item
|
|
|
184 @cindex argument prompt
|
|
|
185 It may be a string; then its contents should consist of a code character
|
|
|
186 followed by a prompt (which some code characters use and some ignore).
|
|
|
187 The prompt ends either with the end of the string or with a newline.
|
|
|
188 Here is a simple example:
|
|
|
189
|
|
|
190 @smallexample
|
|
|
191 (interactive "bFrobnicate buffer: ")
|
|
|
192 @end smallexample
|
|
|
193
|
|
|
194 @noindent
|
|
|
195 The code letter @samp{b} says to read the name of an existing buffer,
|
|
|
196 with completion. The buffer name is the sole argument passed to the
|
|
|
197 command. The rest of the string is a prompt.
|
|
|
198
|
|
|
199 If there is a newline character in the string, it terminates the prompt.
|
|
|
200 If the string does not end there, then the rest of the string should
|
|
|
201 contain another code character and prompt, specifying another argument.
|
|
|
202 You can specify any number of arguments in this way.
|
|
|
203
|
|
|
204 @c Emacs 19 feature
|
|
|
205 The prompt string can use @samp{%} to include previous argument values
|
|
|
206 (starting with the first argument) in the prompt. This is done using
|
|
|
207 @code{format} (@pxref{Formatting Strings}). For example, here is how
|
|
|
208 you could read the name of an existing buffer followed by a new name to
|
|
|
209 give to that buffer:
|
|
|
210
|
|
|
211 @smallexample
|
|
|
212 @group
|
|
|
213 (interactive "bBuffer to rename: \nsRename buffer %s to: ")
|
|
|
214 @end group
|
|
|
215 @end smallexample
|
|
|
216
|
|
|
217 @cindex @samp{*} in interactive
|
|
|
218 @cindex read-only buffers in interactive
|
|
|
219 If the first character in the string is @samp{*}, then an error is
|
|
|
220 signaled if the buffer is read-only.
|
|
|
221
|
|
|
222 @cindex @samp{@@} in interactive
|
|
|
223 @c Emacs 19 feature
|
|
|
224 If the first character in the string is @samp{@@}, and if the key
|
|
|
225 sequence used to invoke the command includes any mouse events, then
|
|
|
226 the window associated with the first of those events is selected
|
|
|
227 before the command is run.
|
|
|
228
|
|
|
229 @cindex @samp{_} in interactive
|
|
|
230 @c XEmacs feature
|
|
|
231 If the first character in the string is @samp{_}, then this command will
|
|
|
232 not cause the region to be deactivated when it completes; that is,
|
|
|
233 @code{zmacs-region-stays} will be set to @code{t} when the command exits
|
|
|
234 successfully.
|
|
|
235
|
|
|
236 You can use @samp{*}, @samp{@@}, and @samp{_} together; the order does
|
|
|
237 not matter. Actual reading of arguments is controlled by the rest of
|
|
|
238 the prompt string (starting with the first character that is not
|
|
|
239 @samp{*}, @samp{@@}, or @samp{_}).
|
|
|
240 @end itemize
|
|
|
241
|
|
280
|
242 @defun function-interactive function
|
|
|
243 This function retrieves the interactive specification of @var{function},
|
|
|
244 which may be any funcallable object. The specification will be returned
|
|
|
245 as the list of the symbol @code{interactive} and the specs. If
|
|
|
246 @var{function} is not interactive, @code{nil} will be returned.
|
|
|
247 @end defun
|
|
|
248
|
|
0
|
249 @node Interactive Codes
|
|
|
250 @subsection Code Characters for @code{interactive}
|
|
|
251 @cindex interactive code description
|
|
|
252 @cindex description for interactive codes
|
|
|
253 @cindex codes, interactive, description of
|
|
|
254 @cindex characters for interactive codes
|
|
|
255
|
|
|
256 The code character descriptions below contain a number of key words,
|
|
|
257 defined here as follows:
|
|
|
258
|
|
|
259 @table @b
|
|
|
260 @item Completion
|
|
|
261 @cindex interactive completion
|
|
|
262 Provide completion. @key{TAB}, @key{SPC}, and @key{RET} perform name
|
|
|
263 completion because the argument is read using @code{completing-read}
|
|
|
264 (@pxref{Completion}). @kbd{?} displays a list of possible completions.
|
|
|
265
|
|
|
266 @item Existing
|
|
|
267 Require the name of an existing object. An invalid name is not
|
|
|
268 accepted; the commands to exit the minibuffer do not exit if the current
|
|
|
269 input is not valid.
|
|
|
270
|
|
|
271 @item Default
|
|
|
272 @cindex default argument string
|
|
|
273 A default value of some sort is used if the user enters no text in the
|
|
|
274 minibuffer. The default depends on the code character.
|
|
|
275
|
|
|
276 @item No I/O
|
|
|
277 This code letter computes an argument without reading any input.
|
|
|
278 Therefore, it does not use a prompt string, and any prompt string you
|
|
|
279 supply is ignored.
|
|
|
280
|
|
|
281 Even though the code letter doesn't use a prompt string, you must follow
|
|
|
282 it with a newline if it is not the last code character in the string.
|
|
|
283
|
|
|
284 @item Prompt
|
|
|
285 A prompt immediately follows the code character. The prompt ends either
|
|
|
286 with the end of the string or with a newline.
|
|
|
287
|
|
|
288 @item Special
|
|
|
289 This code character is meaningful only at the beginning of the
|
|
|
290 interactive string, and it does not look for a prompt or a newline.
|
|
|
291 It is a single, isolated character.
|
|
|
292 @end table
|
|
|
293
|
|
|
294 @cindex reading interactive arguments
|
|
|
295 Here are the code character descriptions for use with @code{interactive}:
|
|
|
296
|
|
|
297 @table @samp
|
|
|
298 @item *
|
|
|
299 Signal an error if the current buffer is read-only. Special.
|
|
|
300
|
|
|
301 @item @@
|
|
|
302 Select the window mentioned in the first mouse event in the key
|
|
|
303 sequence that invoked this command. Special.
|
|
|
304
|
|
|
305 @item _
|
|
|
306 Do not cause the region to be deactivated when this command completes.
|
|
|
307 Special.
|
|
|
308
|
|
|
309 @item a
|
|
|
310 A function name (i.e., a symbol satisfying @code{fboundp}). Existing,
|
|
|
311 Completion, Prompt.
|
|
|
312
|
|
|
313 @item b
|
|
|
314 The name of an existing buffer. By default, uses the name of the
|
|
|
315 current buffer (@pxref{Buffers}). Existing, Completion, Default,
|
|
|
316 Prompt.
|
|
|
317
|
|
|
318 @item B
|
|
|
319 A buffer name. The buffer need not exist. By default, uses the name of
|
|
|
320 a recently used buffer other than the current buffer. Completion,
|
|
|
321 Default, Prompt.
|
|
|
322
|
|
|
323 @item c
|
|
|
324 A character. The cursor does not move into the echo area. Prompt.
|
|
|
325
|
|
|
326 @item C
|
|
|
327 A command name (i.e., a symbol satisfying @code{commandp}). Existing,
|
|
|
328 Completion, Prompt.
|
|
|
329
|
|
|
330 @item d
|
|
|
331 @cindex position argument
|
|
|
332 The position of point, as an integer (@pxref{Point}). No I/O.
|
|
|
333
|
|
|
334 @item D
|
|
|
335 A directory name. The default is the current default directory of the
|
|
|
336 current buffer, @code{default-directory} (@pxref{System Environment}).
|
|
|
337 Existing, Completion, Default, Prompt.
|
|
|
338
|
|
|
339 @item e
|
|
|
340 The last mouse-button or misc-user event in the key sequence that
|
|
|
341 invoked the command. No I/O.
|
|
|
342
|
|
|
343 You can use @samp{e} more than once in a single command's interactive
|
|
|
344 specification. If the key sequence that invoked the command has @var{n}
|
|
|
345 mouse-button or misc-user events, the @var{n}th @samp{e} provides the
|
|
|
346 @var{n}th such event.
|
|
|
347
|
|
|
348 @item f
|
|
|
349 A file name of an existing file (@pxref{File Names}). The default
|
|
|
350 directory is @code{default-directory}. Existing, Completion, Default,
|
|
|
351 Prompt.
|
|
|
352
|
|
|
353 @item F
|
|
|
354 A file name. The file need not exist. Completion, Default, Prompt.
|
|
|
355
|
|
|
356 @item k
|
|
|
357 A key sequence (@pxref{Keymap Terminology}). This keeps reading events
|
|
|
358 until a command (or undefined command) is found in the current key
|
|
|
359 maps. The key sequence argument is represented as a vector of events.
|
|
|
360 The cursor does not move into the echo area. Prompt.
|
|
|
361
|
|
|
362 This kind of input is used by commands such as @code{describe-key} and
|
|
|
363 @code{global-set-key}.
|
|
|
364
|
|
|
365 @item K
|
|
|
366 A key sequence, whose definition you intend to change. This works like
|
|
|
367 @samp{k}, except that it suppresses, for the last input event in the key
|
|
|
368 sequence, the conversions that are normally used (when necessary) to
|
|
|
369 convert an undefined key into a defined one.
|
|
|
370
|
|
|
371 @item m
|
|
|
372 @cindex marker argument
|
|
|
373 The position of the mark, as an integer. No I/O.
|
|
|
374
|
|
|
375 @item n
|
|
|
376 A number read with the minibuffer. If the input is not a number, the
|
|
|
377 user is asked to try again. The prefix argument, if any, is not used.
|
|
|
378 Prompt.
|
|
|
379
|
|
|
380 @item N
|
|
|
381 @cindex raw prefix argument usage
|
|
|
382 The raw prefix argument. If the prefix argument is @code{nil}, then
|
|
|
383 read a number as with @kbd{n}. Requires a number. @xref{Prefix Command
|
|
|
384 Arguments}. Prompt.
|
|
|
385
|
|
|
386 @item p
|
|
|
387 @cindex numeric prefix argument usage
|
|
|
388 The numeric prefix argument. (Note that this @samp{p} is lower case.)
|
|
|
389 No I/O.
|
|
|
390
|
|
|
391 @item P
|
|
|
392 The raw prefix argument. (Note that this @samp{P} is upper case.) No
|
|
|
393 I/O.
|
|
|
394
|
|
|
395 @item r
|
|
|
396 @cindex region argument
|
|
|
397 Point and the mark, as two numeric arguments, smallest first. This is
|
|
|
398 the only code letter that specifies two successive arguments rather than
|
|
|
399 one. No I/O.
|
|
|
400
|
|
|
401 @item s
|
|
|
402 Arbitrary text, read in the minibuffer and returned as a string
|
|
|
403 (@pxref{Text from Minibuffer}). Terminate the input with either
|
|
|
404 @key{LFD} or @key{RET}. (@kbd{C-q} may be used to include either of
|
|
|
405 these characters in the input.) Prompt.
|
|
|
406
|
|
|
407 @item S
|
|
|
408 An interned symbol whose name is read in the minibuffer. Any whitespace
|
|
|
409 character terminates the input. (Use @kbd{C-q} to include whitespace in
|
|
|
410 the string.) Other characters that normally terminate a symbol (e.g.,
|
|
|
411 parentheses and brackets) do not do so here. Prompt.
|
|
|
412
|
|
|
413 @item v
|
|
|
414 A variable declared to be a user option (i.e., satisfying the predicate
|
|
|
415 @code{user-variable-p}). @xref{High-Level Completion}. Existing,
|
|
|
416 Completion, Prompt.
|
|
|
417
|
|
|
418 @item x
|
|
|
419 A Lisp object, specified with its read syntax, terminated with a
|
|
|
420 @key{LFD} or @key{RET}. The object is not evaluated. @xref{Object from
|
|
|
421 Minibuffer}. Prompt.
|
|
|
422
|
|
|
423 @item X
|
|
|
424 @cindex evaluated expression argument
|
|
|
425 A Lisp form is read as with @kbd{x}, but then evaluated so that its
|
|
|
426 value becomes the argument for the command. Prompt.
|
|
|
427 @end table
|
|
|
428
|
|
|
429 @node Interactive Examples
|
|
|
430 @subsection Examples of Using @code{interactive}
|
|
|
431 @cindex examples of using @code{interactive}
|
|
|
432 @cindex @code{interactive}, examples of using
|
|
|
433
|
|
|
434 Here are some examples of @code{interactive}:
|
|
|
435
|
|
|
436 @example
|
|
|
437 @group
|
|
|
438 (defun foo1 () ; @r{@code{foo1} takes no arguments,}
|
|
|
439 (interactive) ; @r{just moves forward two words.}
|
|
|
440 (forward-word 2))
|
|
|
441 @result{} foo1
|
|
|
442 @end group
|
|
|
443
|
|
|
444 @group
|
|
|
445 (defun foo2 (n) ; @r{@code{foo2} takes one argument,}
|
|
|
446 (interactive "p") ; @r{which is the numeric prefix.}
|
|
|
447 (forward-word (* 2 n)))
|
|
|
448 @result{} foo2
|
|
|
449 @end group
|
|
|
450
|
|
|
451 @group
|
|
|
452 (defun foo3 (n) ; @r{@code{foo3} takes one argument,}
|
|
|
453 (interactive "nCount:") ; @r{which is read with the Minibuffer.}
|
|
|
454 (forward-word (* 2 n)))
|
|
|
455 @result{} foo3
|
|
|
456 @end group
|
|
|
457
|
|
|
458 @group
|
|
|
459 (defun three-b (b1 b2 b3)
|
|
|
460 "Select three existing buffers.
|
|
|
461 Put them into three windows, selecting the last one."
|
|
|
462 @end group
|
|
|
463 (interactive "bBuffer1:\nbBuffer2:\nbBuffer3:")
|
|
|
464 (delete-other-windows)
|
|
|
465 (split-window (selected-window) 8)
|
|
|
466 (switch-to-buffer b1)
|
|
|
467 (other-window 1)
|
|
|
468 (split-window (selected-window) 8)
|
|
|
469 (switch-to-buffer b2)
|
|
|
470 (other-window 1)
|
|
|
471 (switch-to-buffer b3))
|
|
|
472 @result{} three-b
|
|
|
473 @group
|
|
|
474 (three-b "*scratch*" "declarations.texi" "*mail*")
|
|
|
475 @result{} nil
|
|
|
476 @end group
|
|
|
477 @end example
|
|
|
478
|
|
|
479 @node Interactive Call
|
|
|
480 @section Interactive Call
|
|
|
481 @cindex interactive call
|
|
|
482
|
|
|
483 After the command loop has translated a key sequence into a
|
|
|
484 definition, it invokes that definition using the function
|
|
|
485 @code{command-execute}. If the definition is a function that is a
|
|
|
486 command, @code{command-execute} calls @code{call-interactively}, which
|
|
|
487 reads the arguments and calls the command. You can also call these
|
|
|
488 functions yourself.
|
|
|
489
|
|
|
490 @defun commandp object
|
|
|
491 Returns @code{t} if @var{object} is suitable for calling interactively;
|
|
|
492 that is, if @var{object} is a command. Otherwise, returns @code{nil}.
|
|
|
493
|
|
|
494 The interactively callable objects include strings and vectors (treated
|
|
|
495 as keyboard macros), lambda expressions that contain a top-level call to
|
|
|
496 @code{interactive}, compiled-function objects made from such lambda
|
|
|
497 expressions, autoload objects that are declared as interactive
|
|
|
498 (non-@code{nil} fourth argument to @code{autoload}), and some of the
|
|
|
499 primitive functions.
|
|
|
500
|
|
|
501 A symbol is @code{commandp} if its function definition is
|
|
|
502 @code{commandp}.
|
|
|
503
|
|
|
504 Keys and keymaps are not commands. Rather, they are used to look up
|
|
|
505 commands (@pxref{Keymaps}).
|
|
|
506
|
|
|
507 See @code{documentation} in @ref{Accessing Documentation}, for a
|
|
|
508 realistic example of using @code{commandp}.
|
|
|
509 @end defun
|
|
|
510
|
|
|
511 @defun call-interactively command &optional record-flag
|
|
|
512 This function calls the interactively callable function @var{command},
|
|
|
513 reading arguments according to its interactive calling specifications.
|
|
|
514 An error is signaled if @var{command} is not a function or if it cannot
|
|
|
515 be called interactively (i.e., is not a command). Note that keyboard
|
|
|
516 macros (strings and vectors) are not accepted, even though they are
|
|
|
517 considered commands, because they are not functions.
|
|
|
518
|
|
|
519 @c XEmacs feature?
|
|
|
520 If @var{record-flag} is the symbol @code{lambda}, the interactive
|
|
|
521 calling arguments for @code{command} are read and returned as a list,
|
|
|
522 but the function is not called on them.
|
|
|
523
|
|
|
524 @cindex record command history
|
|
|
525 If @var{record-flag} is @code{t}, then this command and its arguments
|
|
|
526 are unconditionally added to the list @code{command-history}.
|
|
|
527 Otherwise, the command is added only if it uses the minibuffer to read
|
|
|
528 an argument. @xref{Command History}.
|
|
|
529 @end defun
|
|
|
530
|
|
|
531 @defun command-execute command &optional record-flag
|
|
|
532 @cindex keyboard macro execution
|
|
|
533 This function executes @var{command} as an editing command. The
|
|
|
534 argument @var{command} must satisfy the @code{commandp} predicate; i.e.,
|
|
|
535 it must be an interactively callable function or a keyboard macro.
|
|
|
536
|
|
|
537 A string or vector as @var{command} is executed with
|
|
|
538 @code{execute-kbd-macro}. A function is passed to
|
|
|
539 @code{call-interactively}, along with the optional @var{record-flag}.
|
|
|
540
|
|
|
541 A symbol is handled by using its function definition in its place. A
|
|
|
542 symbol with an @code{autoload} definition counts as a command if it was
|
|
|
543 declared to stand for an interactively callable function. Such a
|
|
|
544 definition is handled by loading the specified library and then
|
|
|
545 rechecking the definition of the symbol.
|
|
|
546 @end defun
|
|
|
547
|
|
|
548 @deffn Command execute-extended-command prefix-argument
|
|
|
549 @cindex read command name
|
|
|
550 This function reads a command name from the minibuffer using
|
|
|
551 @code{completing-read} (@pxref{Completion}). Then it uses
|
|
|
552 @code{command-execute} to call the specified command. Whatever that
|
|
|
553 command returns becomes the value of @code{execute-extended-command}.
|
|
|
554
|
|
|
555 @cindex execute with prefix argument
|
|
|
556 If the command asks for a prefix argument, it receives the value
|
|
|
557 @var{prefix-argument}. If @code{execute-extended-command} is called
|
|
|
558 interactively, the current raw prefix argument is used for
|
|
|
559 @var{prefix-argument}, and thus passed on to whatever command is run.
|
|
|
560
|
|
|
561 @c !!! Should this be @kindex?
|
|
|
562 @cindex @kbd{M-x}
|
|
|
563 @code{execute-extended-command} is the normal definition of @kbd{M-x},
|
|
|
564 so it uses the string @w{@samp{M-x }} as a prompt. (It would be better
|
|
|
565 to take the prompt from the events used to invoke
|
|
|
566 @code{execute-extended-command}, but that is painful to implement.) A
|
|
|
567 description of the value of the prefix argument, if any, also becomes
|
|
|
568 part of the prompt.
|
|
|
569
|
|
|
570 @example
|
|
|
571 @group
|
|
|
572 (execute-extended-command 1)
|
|
|
573 ---------- Buffer: Minibuffer ----------
|
|
|
574 1 M-x forward-word RET
|
|
|
575 ---------- Buffer: Minibuffer ----------
|
|
|
576 @result{} t
|
|
|
577 @end group
|
|
|
578 @end example
|
|
|
579 @end deffn
|
|
|
580
|
|
|
581 @defun interactive-p
|
|
|
582 This function returns @code{t} if the containing function (the one that
|
|
|
583 called @code{interactive-p}) was called interactively, with the function
|
|
|
584 @code{call-interactively}. (It makes no difference whether
|
|
|
585 @code{call-interactively} was called from Lisp or directly from the
|
|
|
586 editor command loop.) If the containing function was called by Lisp
|
|
|
587 evaluation (or with @code{apply} or @code{funcall}), then it was not
|
|
|
588 called interactively.
|
|
|
589
|
|
|
590 The most common use of @code{interactive-p} is for deciding whether to
|
|
|
591 print an informative message. As a special exception,
|
|
|
592 @code{interactive-p} returns @code{nil} whenever a keyboard macro is
|
|
|
593 being run. This is to suppress the informative messages and speed
|
|
|
594 execution of the macro.
|
|
|
595
|
|
|
596 For example:
|
|
|
597
|
|
|
598 @example
|
|
|
599 @group
|
|
|
600 (defun foo ()
|
|
|
601 (interactive)
|
|
|
602 (and (interactive-p)
|
|
|
603 (message "foo")))
|
|
|
604 @result{} foo
|
|
|
605 @end group
|
|
|
606
|
|
|
607 @group
|
|
|
608 (defun bar ()
|
|
|
609 (interactive)
|
|
|
610 (setq foobar (list (foo) (interactive-p))))
|
|
|
611 @result{} bar
|
|
|
612 @end group
|
|
|
613
|
|
|
614 @group
|
|
|
615 ;; @r{Type @kbd{M-x foo}.}
|
|
|
616 @print{} foo
|
|
|
617 @end group
|
|
|
618
|
|
|
619 @group
|
|
|
620 ;; @r{Type @kbd{M-x bar}.}
|
|
|
621 ;; @r{This does not print anything.}
|
|
|
622 @end group
|
|
|
623
|
|
|
624 @group
|
|
|
625 foobar
|
|
|
626 @result{} (nil t)
|
|
|
627 @end group
|
|
|
628 @end example
|
|
|
629 @end defun
|
|
|
630
|
|
|
631 @node Command Loop Info
|
|
|
632 @section Information from the Command Loop
|
|
|
633
|
|
|
634 The editor command loop sets several Lisp variables to keep status
|
|
|
635 records for itself and for commands that are run.
|
|
|
636
|
|
|
637 @defvar last-command
|
|
|
638 This variable records the name of the previous command executed by the
|
|
|
639 command loop (the one before the current command). Normally the value
|
|
|
640 is a symbol with a function definition, but this is not guaranteed.
|
|
|
641
|
|
|
642 The value is copied from @code{this-command} when a command returns to
|
|
|
643 the command loop, except when the command specifies a prefix argument
|
|
|
644 for the following command.
|
|
|
645 @end defvar
|
|
|
646
|
|
|
647 @defvar this-command
|
|
|
648 @cindex current command
|
|
|
649 This variable records the name of the command now being executed by
|
|
|
650 the editor command loop. Like @code{last-command}, it is normally a symbol
|
|
|
651 with a function definition.
|
|
|
652
|
|
|
653 The command loop sets this variable just before running a command, and
|
|
|
654 copies its value into @code{last-command} when the command finishes
|
|
|
655 (unless the command specifies a prefix argument for the following
|
|
|
656 command).
|
|
|
657
|
|
|
658 @cindex kill command repetition
|
|
|
659 Some commands set this variable during their execution, as a flag for
|
|
|
660 whatever command runs next. In particular, the functions for killing text
|
|
|
661 set @code{this-command} to @code{kill-region} so that any kill commands
|
|
|
662 immediately following will know to append the killed text to the
|
|
|
663 previous kill.
|
|
|
664 @end defvar
|
|
|
665
|
|
|
666 If you do not want a particular command to be recognized as the previous
|
|
|
667 command in the case where it got an error, you must code that command to
|
|
|
668 prevent this. One way is to set @code{this-command} to @code{t} at the
|
|
|
669 beginning of the command, and set @code{this-command} back to its proper
|
|
|
670 value at the end, like this:
|
|
|
671
|
|
|
672 @example
|
|
|
673 (defun foo (args@dots{})
|
|
|
674 (interactive @dots{})
|
|
|
675 (let ((old-this-command this-command))
|
|
|
676 (setq this-command t)
|
|
|
677 @r{@dots{}do the work@dots{}}
|
|
|
678 (setq this-command old-this-command)))
|
|
|
679 @end example
|
|
|
680
|
|
|
681 @defun this-command-keys
|
|
|
682 This function returns a vector containing the key and mouse events that
|
|
|
683 invoked the present command, plus any previous commands that generated
|
|
|
684 the prefix argument for this command. (Note: this is not the same as in
|
|
|
685 FSF Emacs, which can return a string.) @xref{Events}.
|
|
|
686
|
|
|
687 This function copies the vector and the events; it is safe to keep and
|
|
|
688 modify them.
|
|
|
689
|
|
|
690 @example
|
|
|
691 @group
|
|
|
692 (this-command-keys)
|
|
|
693 ;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
|
|
|
694 @result{} [#<keypress-event control-U> #<keypress-event control-X> #<keypress-event control-E>]
|
|
|
695 @end group
|
|
|
696 @end example
|
|
|
697 @end defun
|
|
|
698
|
|
|
699 @ignore Not in XEmacs
|
|
|
700 @defvar last-nonmenu-event
|
|
|
701 This variable holds the last input event read as part of a key
|
|
|
702 sequence, not counting events resulting from mouse menus.
|
|
|
703
|
|
|
704 One use of this variable is to figure out a good default location to
|
|
|
705 pop up another menu.
|
|
|
706 @end defvar
|
|
|
707 @end ignore
|
|
|
708
|
|
|
709 @defvar last-command-event
|
|
|
710 This variable is set to the last input event that was read by the
|
|
|
711 command loop as part of a command. The principal use of this variable
|
|
|
712 is in @code{self-insert-command}, which uses it to decide which
|
|
|
713 character to insert.
|
|
|
714
|
|
|
715 This variable is off limits: you may not set its value or modify the
|
|
|
716 event that is its value, as it is destructively modified by
|
|
|
717 @code{read-key-sequence}. If you want to keep a pointer to this value,
|
|
|
718 you must use @code{copy-event}.
|
|
|
719
|
|
|
720 Note that this variable is an alias for @code{last-command-char} in
|
|
|
721 FSF Emacs.
|
|
|
722
|
|
|
723 @example
|
|
|
724 @group
|
|
|
725 last-command-event
|
|
|
726 ;; @r{Now type @kbd{C-u C-x C-e}.}
|
|
|
727 @result{} #<keypress-event control-E>
|
|
|
728 @end group
|
|
|
729 @end example
|
|
|
730 @end defvar
|
|
|
731
|
|
|
732 @defvar last-command-char
|
|
149
|
733
|
|
70
|
734 If the value of @code{last-command-event} is a keyboard event, then this
|
|
149
|
735 is the nearest character equivalent to it (or @code{nil} if there is no
|
|
|
736 character equivalent). @code{last-command-char} is the character that
|
|
|
737 @code{self-insert-command} will insert in the buffer. Remember that
|
|
|
738 there is @emph{not} a one-to-one mapping between keyboard events and
|
|
|
739 XEmacs characters: many keyboard events have no corresponding character,
|
|
|
740 and when the Mule feature is available, most characters can not be input
|
|
|
741 on standard keyboards, except possibly with help from an input method.
|
|
|
742 So writing code that examines this variable to determine what key has
|
|
|
743 been typed is bad practice, unless you are certain that it will be one
|
|
|
744 of a small set of characters.
|
|
54
|
745
|
|
149
|
746 This variable exists for compatibility with Emacs version 18.
|
|
0
|
747
|
|
|
748 @example
|
|
|
749 @group
|
|
149
|
750 last-command-char
|
|
0
|
751 ;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
|
|
149
|
752 @result{} ?\^E
|
|
0
|
753 @end group
|
|
|
754 @end example
|
|
|
755
|
|
|
756 @end defvar
|
|
|
757
|
|
|
758 @defvar current-mouse-event
|
|
|
759 This variable holds the mouse-button event which invoked this command,
|
|
|
760 or @code{nil}. This is what @code{(interactive "e")} returns.
|
|
|
761 @end defvar
|
|
|
762
|
|
|
763 @defvar echo-keystrokes
|
|
|
764 This variable determines how much time should elapse before command
|
|
|
765 characters echo. Its value must be an integer, which specifies the
|
|
|
766 number of seconds to wait before echoing. If the user types a prefix
|
|
|
767 key (say @kbd{C-x}) and then delays this many seconds before continuing,
|
|
|
768 the key @kbd{C-x} is echoed in the echo area. Any subsequent characters
|
|
|
769 in the same command will be echoed as well.
|
|
|
770
|
|
|
771 If the value is zero, then command input is not echoed.
|
|
|
772 @end defvar
|
|
|
773
|
|
|
774 @node Events
|
|
|
775 @section Events
|
|
|
776 @cindex events
|
|
|
777 @cindex input events
|
|
|
778
|
|
|
779 The XEmacs command loop reads a sequence of @dfn{events} that
|
|
|
780 represent keyboard or mouse activity. Unlike in Emacs 18 and in FSF
|
|
|
781 Emacs, events are a primitive Lisp type that must be manipulated
|
|
|
782 using their own accessor and settor primitives. This section describes
|
|
|
783 the representation and meaning of input events in detail.
|
|
|
784
|
|
|
785 A key sequence that starts with a mouse event is read using the keymaps
|
|
|
786 of the buffer in the window that the mouse was in, not the current
|
|
|
787 buffer. This does not imply that clicking in a window selects that
|
|
|
788 window or its buffer---that is entirely under the control of the command
|
|
|
789 binding of the key sequence.
|
|
|
790
|
|
|
791 For information about how exactly the XEmacs command loop works,
|
|
|
792 @xref{Reading Input}.
|
|
|
793
|
|
|
794 @defun eventp object
|
|
|
795 This function returns non-@code{nil} if @var{event} is an input event.
|
|
|
796 @end defun
|
|
|
797
|
|
|
798 @menu
|
|
|
799 * Event Types:: Events come in different types.
|
|
|
800 * Event Contents:: What the contents of each event type are.
|
|
|
801 * Event Predicates:: Querying whether an event is of a
|
|
|
802 particular type.
|
|
|
803 * Accessing Mouse Event Positions::
|
|
|
804 Determining where a mouse event occurred,
|
|
|
805 and over what.
|
|
|
806 * Accessing Other Event Info:: Accessing non-positional event info.
|
|
|
807 * Working With Events:: Creating, copying, and destroying events.
|
|
|
808 * Converting Events:: Converting between events, keys, and
|
|
|
809 characters.
|
|
|
810 @end menu
|
|
|
811
|
|
|
812 @node Event Types
|
|
|
813 @subsection Event Types
|
|
|
814
|
|
|
815 Events represent keyboard or mouse activity or status changes of various
|
|
|
816 sorts, such as process input being available or a timeout being triggered.
|
|
|
817 The different event types are as follows:
|
|
|
818
|
|
|
819 @table @asis
|
|
|
820 @item key-press event
|
|
|
821 A key was pressed. Note that modifier keys such as ``control'', ``shift'',
|
|
|
822 and ``alt'' do not generate events; instead, they are tracked internally
|
|
|
823 by XEmacs, and non-modifier key presses generate events that specify both
|
|
|
824 the key pressed and the modifiers that were held down at the time.
|
|
|
825
|
|
|
826 @item button-press event
|
|
|
827 @itemx button-release event
|
|
|
828 A button was pressed or released. Along with the button that was pressed
|
|
|
829 or released, button events specify the modifier keys that were held down
|
|
|
830 at the time and the position of the pointer at the time.
|
|
|
831
|
|
207
|
832 @item dnd-drop event
|
|
|
833 Some dragged data was released. The event provides the button that was used
|
|
|
834 to drag the data, the modifier keys that were hold down, the position where
|
|
|
835 the drop took place, and a lisp object containing the type and the data
|
|
|
836 dropped (Note: until now only the OffiX protocol supports dnd-drop).
|
|
|
837
|
|
149
|
838 @item motion event
|
|
0
|
839 The pointer was moved. Along with the position of the pointer, these events
|
|
|
840 also specify the modifier keys that were held down at the time.
|
|
|
841
|
|
|
842 @item misc-user event
|
|
|
843 A menu item was selected, or the scrollbar was used.
|
|
|
844
|
|
|
845 @item process event
|
|
|
846 Input is available on a process.
|
|
|
847
|
|
|
848 @item timeout event
|
|
|
849 A timeout has triggered.
|
|
|
850
|
|
|
851 @item magic event
|
|
|
852 Some window-system-specific action (such as a frame being resized or
|
|
|
853 a portion of a frame needing to be redrawn) has occurred. The contents
|
|
|
854 of this event are not accessible at the E-Lisp level, but
|
|
|
855 @code{dispatch-event} knows what to do with an event of this type.
|
|
|
856
|
|
|
857 @item eval event
|
|
|
858 This is a special kind of event specifying that a particular function
|
|
|
859 needs to be called when this event is dispatched. An event of this type
|
|
|
860 is sometimes placed in the event queue when a magic event is processed.
|
|
|
861 This kind of event should generally just be passed off to
|
|
|
862 @code{dispatch-event}. @xref{Dispatching an Event}.
|
|
|
863 @end table
|
|
|
864
|
|
|
865 @node Event Contents
|
|
|
866 @subsection Contents of the Different Types of Events
|
|
|
867
|
|
|
868 Every event, no matter what type it is, contains a timestamp (which is
|
|
|
869 typically an offset in milliseconds from when the X server was started)
|
|
|
870 indicating when the event occurred. In addition, many events contain
|
|
|
871 a @dfn{channel}, which specifies which frame the event occurred on,
|
|
|
872 and/or a value indicating which modifier keys (shift, control, etc.)
|
|
|
873 were held down at the time of the event.
|
|
|
874
|
|
|
875 The contents of each event are as follows:
|
|
|
876
|
|
|
877 @table @asis
|
|
|
878 @item key-press event
|
|
|
879 @table @asis
|
|
|
880 @item channel
|
|
|
881 @item timestamp
|
|
|
882 @item key
|
|
|
883 Which key was pressed. This is an integer (in the printing @sc{ASCII}
|
|
|
884 range: >32 and <127) or a symbol such as @code{left} or @code{right}.
|
|
|
885 Note that many physical keys are actually treated as two separate keys,
|
|
|
886 depending on whether the shift key is pressed; for example, the ``a''
|
|
|
887 key is treated as either ``a'' or ``A'' depending on the state of the
|
|
|
888 shift key, and the ``1'' key is similarly treated as either ``1'' or
|
|
|
889 ``!'' on most keyboards. In such cases, the shift key does not show up
|
|
|
890 in the modifier list. For other keys, such as @code{backspace}, the
|
|
|
891 shift key shows up as a regular modifier.
|
|
|
892 @item modifiers
|
|
|
893 Which modifier keys were pressed. As mentioned above, the shift key
|
|
|
894 is not treated as a modifier for many keys and will not show up in this list
|
|
|
895 in such cases.
|
|
|
896 @end table
|
|
|
897
|
|
|
898 @item button-press event
|
|
|
899 @itemx button-release event
|
|
|
900 @table @asis
|
|
|
901 @item channel
|
|
|
902 @item timestamp
|
|
|
903 @item button
|
|
|
904 What button went down or up. Buttons are numbered starting at 1.
|
|
|
905 @item modifiers
|
|
|
906 Which modifier keys were pressed. The special business mentioned above
|
|
|
907 for the shift key does @emph{not} apply to mouse events.
|
|
|
908 @item x
|
|
|
909 @itemx y
|
|
|
910 The position of the pointer (in pixels) at the time of the event.
|
|
|
911 @end table
|
|
|
912
|
|
207
|
913 @item dnd-drop event
|
|
|
914 @table @asis
|
|
|
915 @item channel
|
|
|
916 @item timestamp
|
|
|
917 @item button
|
|
|
918 What button was used to drag. Buttons are numbered starting at 1.
|
|
|
919 @item modifiers
|
|
|
920 Which modifier keys were pressed to do the drag.
|
|
|
921 @item x
|
|
|
922 @itemx y
|
|
|
923 The position of the pointer (in pixels) at the time of the event.
|
|
|
924 @item data
|
|
|
925 A lisp object containing the dropped type and data.
|
|
|
926 @end table
|
|
|
927
|
|
0
|
928 @item pointer-motion event
|
|
|
929 @table @asis
|
|
|
930 @item channel
|
|
|
931 @item timestamp
|
|
|
932 @item x
|
|
|
933 @itemx y
|
|
|
934 The position of the pointer (in pixels) after it moved.
|
|
|
935 @item modifiers
|
|
|
936 Which modifier keys were pressed. The special business mentioned above
|
|
|
937 for the shift key does @emph{not} apply to mouse events.
|
|
|
938 @end table
|
|
|
939
|
|
|
940 @item misc-user event
|
|
|
941 @table @asis
|
|
|
942 @item timestamp
|
|
|
943 @item function
|
|
|
944 The E-Lisp function to call for this event. This is normally either
|
|
|
945 @code{eval} or @code{call-interactively}.
|
|
|
946 @item object
|
|
|
947 The object to pass to the function. This is normally the callback that
|
|
|
948 was specified in the menu description.
|
|
|
949 @end table
|
|
|
950
|
|
|
951 @item process_event
|
|
|
952 @table @asis
|
|
|
953 @item timestamp
|
|
|
954 @item process
|
|
|
955 The Emacs ``process'' object in question.
|
|
|
956 @end table
|
|
|
957
|
|
|
958 @item timeout event
|
|
|
959 @table @asis
|
|
|
960 @item timestamp
|
|
|
961 @item function
|
|
|
962 The E-Lisp function to call for this timeout. It is called with one
|
|
|
963 argument, the event.
|
|
|
964 @item object
|
|
|
965 Some Lisp object associated with this timeout, to make it easier to tell
|
|
|
966 them apart. The function and object for this event were specified when
|
|
|
967 the timeout was set.
|
|
|
968 @end table
|
|
|
969
|
|
|
970 @item magic event
|
|
|
971 @table @asis
|
|
|
972 @item timestamp
|
|
|
973 @end table
|
|
|
974 (The rest of the information in this event is not user-accessible.)
|
|
|
975
|
|
|
976 @item eval event
|
|
|
977 @table @asis
|
|
|
978 @item timestamp
|
|
|
979 @item function
|
|
|
980 An E-Lisp function to call when this event is dispatched.
|
|
|
981 @item object
|
|
|
982 The object to pass to the function. The function and object are set
|
|
|
983 when the event is created.
|
|
|
984 @end table
|
|
|
985 @end table
|
|
|
986
|
|
149
|
987 @defun event-type event
|
|
|
988 Return the type of @var{event}.
|
|
|
989
|
|
|
990 This will be a symbol; one of
|
|
|
991
|
|
|
992 @table @code
|
|
|
993 @item key-press
|
|
|
994 A key was pressed.
|
|
|
995 @item button-press
|
|
|
996 A mouse button was pressed.
|
|
|
997 @item button-release
|
|
|
998 A mouse button was released.
|
|
207
|
999 @item dnd-drop
|
|
|
1000 A drop occured.
|
|
149
|
1001 @item motion
|
|
|
1002 The mouse moved.
|
|
|
1003 @item misc-user
|
|
|
1004 Some other user action happened; typically, this is
|
|
|
1005 a menu selection or scrollbar action.
|
|
|
1006 @item process
|
|
|
1007 Input is available from a subprocess.
|
|
|
1008 @item timeout
|
|
|
1009 A timeout has expired.
|
|
|
1010 @item eval
|
|
|
1011 This causes a specified action to occur when dispatched.
|
|
|
1012 @item magic
|
|
|
1013 Some window-system-specific event has occurred.
|
|
|
1014 @end table
|
|
|
1015 @end defun
|
|
|
1016
|
|
0
|
1017 @node Event Predicates
|
|
|
1018 @subsection Event Predicates
|
|
|
1019
|
|
149
|
1020 The following predicates return whether an object is an event of a
|
|
|
1021 particular type.
|
|
0
|
1022
|
|
|
1023 @defun key-press-event-p object
|
|
|
1024 This is true if @var{object} is a key-press event.
|
|
|
1025 @end defun
|
|
|
1026
|
|
149
|
1027 @defun button-event-p object object
|
|
|
1028 This is true if @var{object} is a mouse button-press or button-release
|
|
|
1029 event.
|
|
|
1030 @end defun
|
|
|
1031
|
|
|
1032 @defun button-press-event-p object
|
|
|
1033 This is true if @var{object} is a mouse button-press event.
|
|
|
1034 @end defun
|
|
|
1035
|
|
|
1036 @defun button-release-event-p object
|
|
|
1037 This is true if @var{object} is a mouse button-release event.
|
|
0
|
1038 @end defun
|
|
|
1039
|
|
207
|
1040 @defun dnd-drop-event-p object
|
|
|
1041 This is true if @var{object} is a mouse dnd-drop event.
|
|
|
1042 @end defun
|
|
|
1043
|
|
0
|
1044 @defun motion-event-p object
|
|
149
|
1045 This is true if @var{object} is a mouse motion event.
|
|
|
1046 @end defun
|
|
|
1047
|
|
|
1048 @defun mouse-event-p object
|
|
|
1049 This is true if @var{object} is a mouse button-press, button-release
|
|
|
1050 or motion event.
|
|
|
1051 @end defun
|
|
|
1052
|
|
|
1053 @defun eval-event-p object
|
|
|
1054 This is true if @var{object} is an eval event.
|
|
|
1055 @end defun
|
|
|
1056
|
|
|
1057 @defun misc-user-event-p object
|
|
|
1058 This is true if @var{object} is a misc-user event.
|
|
0
|
1059 @end defun
|
|
|
1060
|
|
|
1061 @defun process-event-p object
|
|
|
1062 This is true if @var{object} is a process event.
|
|
|
1063 @end defun
|
|
|
1064
|
|
|
1065 @defun timeout-event-p object
|
|
|
1066 This is true if @var{object} is a timeout event.
|
|
|
1067 @end defun
|
|
|
1068
|
|
|
1069 @defun event-live-p object
|
|
|
1070 This is true if @var{object} is any event that has not been deallocated.
|
|
|
1071 @end defun
|
|
|
1072
|
|
|
1073 @node Accessing Mouse Event Positions
|
|
|
1074 @subsection Accessing the Position of a Mouse Event
|
|
|
1075
|
|
207
|
1076 Unlike other events, mouse events (i.e. motion, button-press,
|
|
|
1077 button-release, and dnd-drop events) occur in a particular location
|
|
|
1078 on the screen. Many primitives are provided for determining exactly
|
|
|
1079 where the event occurred and what is under that location.
|
|
0
|
1080
|
|
|
1081 @menu
|
|
|
1082 * Frame-Level Event Position Info::
|
|
|
1083 * Window-Level Event Position Info::
|
|
|
1084 * Event Text Position Info::
|
|
|
1085 * Event Glyph Position Info::
|
|
|
1086 * Event Toolbar Position Info::
|
|
|
1087 * Other Event Position Info::
|
|
|
1088 @end menu
|
|
|
1089
|
|
|
1090 @node Frame-Level Event Position Info
|
|
|
1091 @subsubsection Frame-Level Event Position Info
|
|
|
1092
|
|
|
1093 The following functions return frame-level information about where
|
|
|
1094 a mouse event occurred.
|
|
|
1095
|
|
|
1096 @defun event-frame event
|
|
|
1097 This function returns the ``channel'' or frame that the given mouse
|
|
207
|
1098 motion, button press, button release, or dnd drop event occurred in.
|
|
|
1099 This will be @code{nil} for non-mouse events.
|
|
0
|
1100 @end defun
|
|
|
1101
|
|
|
1102 @defun event-x-pixel event
|
|
|
1103 This function returns the X position in pixels of the given mouse event.
|
|
|
1104 The value returned is relative to the frame the event occurred in.
|
|
149
|
1105 This will signal an error if the event is not a mouse event.
|
|
0
|
1106 @end defun
|
|
|
1107
|
|
|
1108 @defun event-y-pixel event
|
|
|
1109 This function returns the Y position in pixels of the given mouse event.
|
|
|
1110 The value returned is relative to the frame the event occurred in.
|
|
149
|
1111 This will signal an error if the event is not a mouse event.
|
|
0
|
1112 @end defun
|
|
|
1113
|
|
|
1114 @node Window-Level Event Position Info
|
|
|
1115 @subsubsection Window-Level Event Position Info
|
|
|
1116
|
|
|
1117 The following functions return window-level information about where
|
|
|
1118 a mouse event occurred.
|
|
|
1119
|
|
|
1120 @defun event-window event
|
|
207
|
1121 Given a mouse motion, button press, button release, or dnd drop event, compute and
|
|
0
|
1122 return the window on which that event occurred. This may be @code{nil}
|
|
|
1123 if the event occurred in the border or over a toolbar. The modeline is
|
|
149
|
1124 considered to be within the window it describes.
|
|
0
|
1125 @end defun
|
|
|
1126
|
|
|
1127 @defun event-buffer event
|
|
207
|
1128 Given a mouse motion, button press, button release, or dnd drop event, compute and
|
|
0
|
1129 return the buffer of the window on which that event occurred. This may
|
|
|
1130 be @code{nil} if the event occurred in the border or over a toolbar.
|
|
149
|
1131 The modeline is considered to be within the window it describes. This is
|
|
0
|
1132 equivalent to calling @code{event-window} and then calling
|
|
149
|
1133 @code{window-buffer} on the result if it is a window.
|
|
0
|
1134 @end defun
|
|
|
1135
|
|
|
1136 @defun event-window-x-pixel event
|
|
|
1137 This function returns the X position in pixels of the given mouse event.
|
|
|
1138 The value returned is relative to the window the event occurred in.
|
|
|
1139 This will signal an error if the event is not a mouse-motion, button-press,
|
|
207
|
1140 button-release, or dnd-drop event.
|
|
0
|
1141 @end defun
|
|
|
1142
|
|
|
1143 @defun event-window-y-pixel event
|
|
|
1144 This function returns the Y position in pixels of the given mouse event.
|
|
|
1145 The value returned is relative to the window the event occurred in.
|
|
|
1146 This will signal an error if the event is not a mouse-motion, button-press,
|
|
|
1147 or button-release event.
|
|
|
1148 @end defun
|
|
|
1149
|
|
|
1150 @node Event Text Position Info
|
|
|
1151 @subsubsection Event Text Position Info
|
|
|
1152
|
|
|
1153 The following functions return information about the text (including the
|
|
|
1154 modeline) that a mouse event occurred over or near.
|
|
|
1155
|
|
|
1156 @defun event-over-text-area-p event
|
|
207
|
1157 Given a mouse-motion, button-press, button-release, or dnd-drop event, this
|
|
2
|
1158 function returns @code{t} if the event is over the text area of a
|
|
0
|
1159 window. Otherwise, @code{nil} is returned. The modeline is not
|
|
|
1160 considered to be part of the text area.
|
|
|
1161 @end defun
|
|
|
1162
|
|
|
1163 @defun event-over-modeline-p event
|
|
207
|
1164 Given a mouse-motion, button-press, button-release, or dnd-drop event, this
|
|
0
|
1165 function returns @code{t} if the event is over the modeline of a window.
|
|
|
1166 Otherwise, @code{nil} is returned.
|
|
|
1167 @end defun
|
|
|
1168
|
|
|
1169 @defun event-x event
|
|
|
1170 This function returns the X position of the given mouse-motion,
|
|
207
|
1171 button-press, button-release, or dnd-drop event in characters. This is relative
|
|
0
|
1172 to the window the event occurred over.
|
|
|
1173 @end defun
|
|
|
1174
|
|
|
1175 @defun event-y event
|
|
|
1176 This function returns the Y position of the given mouse-motion,
|
|
207
|
1177 button-press, button-release, or dnd-drop event in characters. This is relative
|
|
0
|
1178 to the window the event occurred over.
|
|
|
1179 @end defun
|
|
|
1180
|
|
|
1181 @defun event-point event
|
|
|
1182 This function returns the character position of the given mouse-motion,
|
|
207
|
1183 button-press, button-release, or dnd-drop event. If the event did not occur over
|
|
0
|
1184 a window, or did not occur over text, then this returns @code{nil}.
|
|
|
1185 Otherwise, it returns an index into the buffer visible in the event's
|
|
|
1186 window.
|
|
|
1187 @end defun
|
|
|
1188
|
|
|
1189 @defun event-closest-point event
|
|
|
1190 This function returns the character position of the given mouse-motion,
|
|
207
|
1191 button-press, button-release, or dnd-drop event. If the event did not occur over
|
|
0
|
1192 a window or over text, it returns the closest point to the location of
|
|
|
1193 the event. If the Y pixel position overlaps a window and the X pixel
|
|
|
1194 position is to the left of that window, the closest point is the
|
|
|
1195 beginning of the line containing the Y position. If the Y pixel
|
|
|
1196 position overlaps a window and the X pixel position is to the right of
|
|
|
1197 that window, the closest point is the end of the line containing the Y
|
|
|
1198 position. If the Y pixel position is above a window, 0 is returned. If
|
|
|
1199 it is below a window, the value of @code{(window-end)} is returned.
|
|
|
1200 @end defun
|
|
|
1201
|
|
|
1202 @node Event Glyph Position Info
|
|
|
1203 @subsubsection Event Glyph Position Info
|
|
|
1204
|
|
|
1205 The following functions return information about the glyph (if any) that
|
|
|
1206 a mouse event occurred over.
|
|
|
1207
|
|
|
1208 @defun event-over-glyph-p event
|
|
207
|
1209 Given a mouse-motion, button-press, button-release, or dnd-drop event, this
|
|
0
|
1210 function returns @code{t} if the event is over a glyph. Otherwise,
|
|
|
1211 @code{nil} is returned.
|
|
|
1212 @end defun
|
|
|
1213
|
|
|
1214 @defun event-glyph-extent event
|
|
207
|
1215 If the given mouse-motion, button-press, button-release, or dnd-drop event happened
|
|
0
|
1216 on top of a glyph, this returns its extent; else @code{nil} is returned.
|
|
|
1217 @end defun
|
|
|
1218
|
|
|
1219 @defun event-glyph-x-pixel event
|
|
207
|
1220 Given a mouse-motion, button-press, button-release, or dnd-drop event over a
|
|
0
|
1221 glyph, this function returns the X position of the pointer relative to
|
|
|
1222 the upper left of the glyph. If the event is not over a glyph, it returns
|
|
|
1223 @code{nil}.
|
|
|
1224 @end defun
|
|
|
1225
|
|
|
1226 @defun event-glyph-y-pixel event
|
|
207
|
1227 Given a mouse-motion, button-press, button-release, or dnd-drop event over a
|
|
0
|
1228 glyph, this function returns the Y position of the pointer relative to
|
|
|
1229 the upper left of the glyph. If the event is not over a glyph, it returns
|
|
|
1230 @code{nil}.
|
|
|
1231 @end defun
|
|
|
1232
|
|
|
1233 @node Event Toolbar Position Info
|
|
|
1234 @subsubsection Event Toolbar Position Info
|
|
|
1235
|
|
|
1236 @defun event-over-toolbar-p event
|
|
207
|
1237 Given a mouse-motion, button-press, button-release, or dnd-drop event, this
|
|
0
|
1238 function returns @code{t} if the event is over a toolbar. Otherwise,
|
|
|
1239 @code{nil} is returned.
|
|
|
1240 @end defun
|
|
|
1241
|
|
|
1242 @defun event-toolbar-button event
|
|
207
|
1243 If the given mouse-motion, button-press, button-release, or dnd-drop event
|
|
0
|
1244 happened on top of a toolbar button, this function returns the button.
|
|
|
1245 Otherwise, @code{nil} is returned.
|
|
|
1246 @end defun
|
|
|
1247
|
|
|
1248 @node Other Event Position Info
|
|
|
1249 @subsubsection Other Event Position Info
|
|
|
1250
|
|
|
1251 @defun event-over-border-p event
|
|
207
|
1252 Given a mouse-motion, button-press, button-release, or dnd-drop event, this
|
|
0
|
1253 function returns @code{t} if the event is over an internal toolbar.
|
|
|
1254 Otherwise, @code{nil} is returned.
|
|
|
1255 @end defun
|
|
|
1256
|
|
|
1257 @node Accessing Other Event Info
|
|
|
1258 @subsection Accessing the Other Contents of Events
|
|
|
1259
|
|
|
1260 The following functions allow access to the contents of events other than
|
|
|
1261 the position info described in the previous section.
|
|
|
1262
|
|
|
1263 @defun event-timestamp event
|
|
|
1264 This function returns the timestamp of the given event object.
|
|
|
1265 @end defun
|
|
|
1266
|
|
|
1267 @defun event-device event
|
|
|
1268 This function returns the device that the given event occurred on.
|
|
|
1269 @end defun
|
|
|
1270
|
|
|
1271 @defun event-key event
|
|
|
1272 This function returns the Keysym of the given key-press event.
|
|
|
1273 This will be the @sc{ASCII} code of a printing character, or a symbol.
|
|
|
1274 @end defun
|
|
|
1275
|
|
|
1276 @defun event-button event
|
|
149
|
1277 This function returns the button-number of the given button-press or
|
|
|
1278 button-release event.
|
|
0
|
1279 @end defun
|
|
|
1280
|
|
|
1281 @defun event-modifiers event
|
|
|
1282 This function returns a list of symbols, the names of the modifier keys
|
|
|
1283 which were down when the given mouse or keyboard event was produced.
|
|
|
1284 @end defun
|
|
|
1285
|
|
|
1286 @defun event-modifier-bits event
|
|
|
1287 This function returns a number representing the modifier keys which were down
|
|
|
1288 when the given mouse or keyboard event was produced.
|
|
|
1289 @end defun
|
|
|
1290
|
|
|
1291 @defun event-function event
|
|
|
1292 This function returns the callback function of the given timeout, misc-user,
|
|
|
1293 or eval event.
|
|
|
1294 @end defun
|
|
|
1295
|
|
|
1296 @defun event-object event
|
|
|
1297 This function returns the callback function argument of the given timeout,
|
|
|
1298 misc-user, or eval event.
|
|
|
1299 @end defun
|
|
|
1300
|
|
|
1301 @defun event-process event
|
|
|
1302 This function returns the process of the given process event.
|
|
|
1303 @end defun
|
|
|
1304
|
|
207
|
1305 @defun event-drag-and-drop-data event
|
|
|
1306 This function returns a list containing the type of the drop as first element
|
|
|
1307 and the data of the drop as second element.
|
|
|
1308 @end defun
|
|
|
1309
|
|
0
|
1310 @node Working With Events
|
|
|
1311 @subsection Working With Events
|
|
|
1312
|
|
|
1313 XEmacs provides primitives for creating, copying, and destroying event
|
|
|
1314 objects. Many functions that return events take an event object as an
|
|
|
1315 argument and fill in the fields of this event; or they make accept
|
|
|
1316 either an event object or @code{nil}, creating the event object first in
|
|
|
1317 the latter case.
|
|
|
1318
|
|
213
|
1319 @defun make-event &optional type plist
|
|
|
1320 This function creates a new event structure. If no arguments are
|
|
|
1321 specified, the created event will be empty. To specify the event type,
|
|
|
1322 use the @var{type} argument. The allowed types are @code{empty},
|
|
280
|
1323 @code{key-press}, @code{button-press}, @code{button-release},
|
|
|
1324 @code{motion}, or @code{misc-user}.
|
|
213
|
1325
|
|
|
1326 @var{plist} is a property list, the properties being compatible to those
|
|
|
1327 returned by @code{event-properties}. For events other than
|
|
|
1328 @code{empty}, it is mandatory to specify certain properties. For
|
|
|
1329 @code{empty} events, @var{plist} must be @code{nil}. The list is
|
|
|
1330 @dfn{canonicalized}, which means that if a property keyword is present
|
|
|
1331 more than once, only the first instance is taken into account.
|
|
|
1332 Specifying an unknown or illegal property signals an error.
|
|
|
1333
|
|
|
1334 The following properties are allowed:
|
|
|
1335
|
|
|
1336 @table @b
|
|
|
1337 @item @code{channel}
|
|
|
1338 The event channel. This is a frame or a console. For mouse events (of
|
|
|
1339 type @code{button-press}, @code{button-release} and @code{motion}), this
|
|
|
1340 must be a frame. For key-press events, it must be a console. If
|
|
|
1341 channel is unspecified by @var{plist}, it will be set to the selected
|
|
|
1342 frame or selected console, as appropriate.
|
|
|
1343
|
|
|
1344 @item @code{key}
|
|
|
1345 The event key. This is either a symbol or a character. It is allowed
|
|
|
1346 (and required) only for key-press events.
|
|
|
1347
|
|
|
1348 @item @code{button}
|
|
|
1349 The event button. This an integer, either 1, 2 or 3. It is allowed
|
|
|
1350 only for button-press and button-release events.
|
|
|
1351
|
|
|
1352 @item @code{modifiers}
|
|
|
1353 The event modifiers. This is a list of modifier symbols. It is allowed
|
|
|
1354 for key-press, button-press, button-release and motion events.
|
|
|
1355
|
|
|
1356 @item @code{x}
|
|
|
1357 The event X coordinate. This is an integer. It is relative to the
|
|
|
1358 channel's root window, and is allowed for button-press, button-release
|
|
|
1359 and motion events.
|
|
|
1360
|
|
|
1361 @item @code{y}
|
|
|
1362 The event Y coordinate. This is an integer. It is relative to the
|
|
|
1363 channel's root window, and is allowed for button-press, button-release
|
|
|
1364 and motion events. This means that, for instance, to access the
|
|
|
1365 toolbar, the @code{y} property will have to be negative.
|
|
|
1366
|
|
|
1367 @item @code{timestamp}
|
|
|
1368 The event timestamp, a non-negative integer. Allowed for all types of
|
|
|
1369 events.
|
|
|
1370 @end table
|
|
|
1371
|
|
|
1372 @emph{WARNING}: the event object returned by this function may be a
|
|
|
1373 reused one; see the function @code{deallocate-event}.
|
|
|
1374
|
|
|
1375 The events created by @code{make-event} can be used as non-interactive
|
|
|
1376 arguments to the functions with an @code{(interactive "e")}
|
|
|
1377 specification.
|
|
|
1378
|
|
|
1379 Here are some basic examples of usage:
|
|
|
1380
|
|
|
1381 @lisp
|
|
|
1382 @group
|
|
|
1383 ;; @r{Create an empty event.}
|
|
|
1384 (make-event)
|
|
|
1385 @result{} #<empty-event>
|
|
|
1386 @end group
|
|
|
1387
|
|
|
1388 @group
|
|
|
1389 ;; @r{Try creating a key-press event.}
|
|
|
1390 (make-event 'key-press)
|
|
|
1391 @error{} Undefined key for keypress event
|
|
|
1392 @end group
|
|
|
1393
|
|
|
1394 @group
|
|
280
|
1395 ;; @r{Creating a key-press event, try 2}
|
|
213
|
1396 (make-event 'key-press '(key home))
|
|
|
1397 @result{} #<keypress-event home>
|
|
|
1398 @end group
|
|
|
1399
|
|
|
1400 @group
|
|
|
1401 ;; @r{Create a key-press event of dubious fame.}
|
|
|
1402 (make-event 'key-press '(key escape modifiers (meta alt control shift)))
|
|
|
1403 @result{} #<keypress-event control-meta-alt-shift-escape>
|
|
|
1404 @end group
|
|
|
1405
|
|
|
1406 @group
|
|
280
|
1407 ;; @r{Create a M-button1 event at coordinates defined by variables}
|
|
|
1408 ;; @r{@var{x} and @var{y}.}
|
|
213
|
1409 (make-event 'button-press `(button 1 modifiers (meta) x ,x y ,y))
|
|
|
1410 @result{} #<buttondown-event meta-button1>
|
|
|
1411 @end group
|
|
|
1412
|
|
|
1413 @group
|
|
|
1414 ;; @r{Create a simmilar button-release event.}
|
|
|
1415 (make-event 'button-release `(button 1 modifiers (meta) x ,x y ,x))
|
|
|
1416 @result{} #<buttonup-event meta-button1up>
|
|
|
1417 @end group
|
|
|
1418
|
|
|
1419 @group
|
|
|
1420 ;; @r{Create a mouse-motion event.}
|
|
|
1421 (make-event 'motion '(x 20 y 30))
|
|
280
|
1422 @result{} #<motion-event 20, 30>
|
|
|
1423
|
|
213
|
1424 (event-properties (make-event 'motion '(x 20 y 30)))
|
|
280
|
1425 @result{} (channel #<x-frame "emacs" 0x8e2> x 20 y 30
|
|
|
1426 modifiers nil timestamp 0)
|
|
213
|
1427 @end group
|
|
|
1428 @end lisp
|
|
|
1429
|
|
|
1430 In conjunction with @code{event-properties}, you can use
|
|
|
1431 @code{make-event} to create modified copies of existing events. For
|
|
|
1432 instance, the following code will return an @code{equal} copy of
|
|
|
1433 @var{event}:
|
|
|
1434
|
|
|
1435 @lisp
|
|
|
1436 (make-event (event-type @var{event})
|
|
|
1437 (event-properties @var{event}))
|
|
|
1438 @end lisp
|
|
|
1439
|
|
|
1440 Note, however, that you cannot use @code{make-event} as the generic
|
|
|
1441 replacement for @code{copy-event}, because it does not allow creating
|
|
|
1442 all of the event types.
|
|
|
1443
|
|
280
|
1444 To create a modified copy of an event, you can use the canonicalization
|
|
213
|
1445 feature of @var{plist}. The following example creates a copy of
|
|
|
1446 @var{event}, but with @code{modifiers} reset to @code{nil}.
|
|
|
1447
|
|
|
1448 @lisp
|
|
|
1449 (make-event (event-type @var{event})
|
|
|
1450 (append '(modifiers nil)
|
|
|
1451 (event-properties @var{event})))
|
|
|
1452 @end lisp
|
|
0
|
1453 @end defun
|
|
|
1454
|
|
|
1455 @defun copy-event event1 &optional event2
|
|
|
1456 This function makes a copy of the given event object. If a second
|
|
|
1457 argument is given, the first event is copied into the second and the
|
|
|
1458 second is returned. If the second argument is not supplied (or is
|
|
213
|
1459 @code{nil}) then a new event will be made.
|
|
0
|
1460 @end defun
|
|
|
1461
|
|
|
1462 @defun deallocate-event event
|
|
|
1463 This function allows the given event structure to be reused. You
|
|
|
1464 @strong{MUST NOT} use this event object after calling this function with
|
|
|
1465 it. You will lose. It is not necessary to call this function, as event
|
|
|
1466 objects are garbage-collected like all other objects; however, it may be
|
|
|
1467 more efficient to explicitly deallocate events when you are sure that
|
|
|
1468 that is safe.
|
|
|
1469 @end defun
|
|
|
1470
|
|
|
1471 @node Converting Events
|
|
|
1472 @subsection Converting Events
|
|
|
1473
|
|
|
1474 XEmacs provides some auxiliary functions for converting between events
|
|
|
1475 and other ways of representing keys. These are useful when working with
|
|
|
1476 @sc{ASCII} strings and with keymaps.
|
|
|
1477
|
|
|
1478 @defun character-to-event ch &optional event device
|
|
|
1479 This function converts a numeric @sc{ASCII} value to an event structure,
|
|
|
1480 replete with modifier bits. @var{ch} is the character to convert, and
|
|
|
1481 @var{event} is the event object to fill in. This function contains
|
|
|
1482 knowledge about what the codes ``mean'' -- for example, the number 9 is
|
|
|
1483 converted to the character @key{Tab}, not the distinct character
|
|
|
1484 @key{Control-I}.
|
|
|
1485
|
|
|
1486 Note that @var{ch} does not have to be a numeric value, but can be a
|
|
|
1487 symbol such as @code{clear} or a list such as @code{(control
|
|
|
1488 backspace)}.
|
|
|
1489
|
|
|
1490 If @code{event} is not @code{nil}, it is modified; otherwise, a
|
|
|
1491 new event object is created. In both cases, the event is returned.
|
|
|
1492
|
|
|
1493 Optional third arg @var{device} is the device to store in the event;
|
|
|
1494 this also affects whether the high bit is interpreted as a meta key. A
|
|
|
1495 value of @code{nil} means use the selected device but always treat the
|
|
|
1496 high bit as meta.
|
|
|
1497
|
|
|
1498 Beware that @code{character-to-event} and @code{event-to-character} are
|
|
|
1499 not strictly inverse functions, since events contain much more
|
|
|
1500 information than the @sc{ASCII} character set can encode.
|
|
|
1501 @end defun
|
|
|
1502
|
|
|
1503 @defun event-to-character event &optional allow-extra-modifiers allow-meta allow-non-ascii
|
|
|
1504 This function returns the closest @sc{ASCII} approximation to
|
|
|
1505 @var{event}. If the event isn't a keypress, this returns @code{nil}.
|
|
|
1506
|
|
|
1507 If @var{allow-extra-modifiers} is non-@code{nil}, then this is lenient
|
|
|
1508 in its translation; it will ignore modifier keys other than
|
|
|
1509 @key{control} and @key{meta}, and will ignore the @key{shift} modifier
|
|
|
1510 on those characters which have no shifted @sc{ASCII} equivalent
|
|
|
1511 (@key{Control-Shift-A} for example, will be mapped to the same
|
|
|
1512 @sc{ASCII} code as @key{Control-A}).
|
|
|
1513
|
|
|
1514 If @var{allow-meta} is non-@code{nil}, then the @key{Meta} modifier will
|
|
|
1515 be represented by turning on the high bit of the byte returned;
|
|
|
1516 otherwise, @code{nil} will be returned for events containing the
|
|
|
1517 @key{Meta} modifier.
|
|
|
1518
|
|
|
1519 If @var{allow-non-ascii} is non-@code{nil}, then characters which are
|
|
|
1520 present in the prevailing character set (@pxref{Keymaps, variable
|
|
|
1521 @code{character-set-property}}) will be returned as their code in that
|
|
|
1522 character set, instead of the return value being restricted to
|
|
|
1523 @sc{ASCII}.
|
|
|
1524
|
|
|
1525 Note that specifying both @var{allow-meta} and @var{allow-non-ascii} is
|
|
|
1526 ambiguous, as both use the high bit; @key{M-x} and @key{oslash} will be
|
|
|
1527 indistinguishable.
|
|
|
1528 @end defun
|
|
|
1529
|
|
|
1530 @defun events-to-keys events &optional no-mice
|
|
|
1531 Given a vector of event objects, this function returns a vector of key
|
|
|
1532 descriptors, or a string (if they all fit in the @sc{ASCII} range).
|
|
|
1533 Optional arg @var{no-mice} means that button events are not allowed.
|
|
|
1534 @end defun
|
|
|
1535
|
|
|
1536 @node Reading Input
|
|
|
1537 @section Reading Input
|
|
|
1538
|
|
|
1539 The editor command loop reads keyboard input using the function
|
|
|
1540 @code{next-event} and constructs key sequences out of the events using
|
|
|
1541 @code{dispatch-event}. Lisp programs can also use the function
|
|
|
1542 @code{read-key-sequence}, which reads input a key sequence at a time.
|
|
|
1543 See also @code{momentary-string-display} in @ref{Temporary Displays},
|
|
|
1544 and @code{sit-for} in @ref{Waiting}. @xref{Terminal Input}, for
|
|
|
1545 functions and variables for controlling terminal input modes and
|
|
|
1546 debugging terminal input.
|
|
|
1547
|
|
|
1548 For higher-level input facilities, see @ref{Minibuffers}.
|
|
|
1549
|
|
|
1550 @menu
|
|
|
1551 * Key Sequence Input:: How to read one key sequence.
|
|
|
1552 * Reading One Event:: How to read just one event.
|
|
|
1553 * Dispatching an Event:: What to do with an event once it has been read.
|
|
|
1554 * Quoted Character Input:: Asking the user to specify a character.
|
|
|
1555 * Peeking and Discarding:: How to reread or throw away input events.
|
|
|
1556 @end menu
|
|
|
1557
|
|
|
1558 @node Key Sequence Input
|
|
|
1559 @subsection Key Sequence Input
|
|
|
1560 @cindex key sequence input
|
|
|
1561
|
|
|
1562 Lisp programs can read input a key sequence at a time by calling
|
|
|
1563 @code{read-key-sequence}; for example, @code{describe-key} uses it to
|
|
|
1564 read the key to describe.
|
|
|
1565
|
|
|
1566 @defun read-key-sequence prompt
|
|
|
1567 @cindex key sequence
|
|
|
1568 This function reads a sequence of keystrokes or mouse clicks and returns
|
|
|
1569 it as a vector of events. It keeps reading events until it has
|
|
|
1570 accumulated a full key sequence; that is, enough to specify a non-prefix
|
|
|
1571 command using the currently active keymaps.
|
|
|
1572
|
|
|
1573 The vector and the event objects it contains are freshly created, and
|
|
|
1574 will not be side-effected by subsequent calls to this function.
|
|
|
1575
|
|
|
1576 The function @code{read-key-sequence} suppresses quitting: @kbd{C-g}
|
|
|
1577 typed while reading with this function works like any other character,
|
|
|
1578 and does not set @code{quit-flag}. @xref{Quitting}.
|
|
|
1579
|
|
|
1580 The argument @var{prompt} is either a string to be displayed in the echo
|
|
|
1581 area as a prompt, or @code{nil}, meaning not to display a prompt.
|
|
|
1582
|
|
|
1583 @c XEmacs feature
|
|
|
1584 If the user selects a menu item while we are prompting for a key
|
|
|
1585 sequence, the returned value will be a vector of a single menu-selection
|
|
|
1586 event (a misc-user event). An error will be signalled if you pass this
|
|
|
1587 value to @code{lookup-key} or a related function.
|
|
|
1588
|
|
|
1589 In the example below, the prompt @samp{?} is displayed in the echo area,
|
|
|
1590 and the user types @kbd{C-x C-f}.
|
|
|
1591
|
|
|
1592 @example
|
|
|
1593 (read-key-sequence "?")
|
|
|
1594
|
|
|
1595 @group
|
|
|
1596 ---------- Echo Area ----------
|
|
|
1597 ?@kbd{C-x C-f}
|
|
|
1598 ---------- Echo Area ----------
|
|
|
1599
|
|
|
1600 @result{} [#<keypress-event control-X> #<keypress-event control-F>]
|
|
|
1601 @end group
|
|
|
1602 @end example
|
|
|
1603 @end defun
|
|
|
1604
|
|
|
1605 @ignore @c Not in XEmacs
|
|
|
1606 @defvar num-input-keys
|
|
|
1607 @c Emacs 19 feature
|
|
|
1608 This variable's value is the number of key sequences processed so far in
|
|
|
1609 this XEmacs session. This includes key sequences read from the terminal
|
|
|
1610 and key sequences read from keyboard macros being executed.
|
|
|
1611 @end defvar
|
|
|
1612 @end ignore
|
|
|
1613
|
|
|
1614 @cindex upper case key sequence
|
|
|
1615 @cindex downcasing in @code{lookup-key}
|
|
|
1616 If an input character is an upper-case letter and has no key binding,
|
|
|
1617 but its lower-case equivalent has one, then @code{read-key-sequence}
|
|
|
1618 converts the character to lower case. Note that @code{lookup-key} does
|
|
|
1619 not perform case conversion in this way.
|
|
|
1620
|
|
|
1621 @node Reading One Event
|
|
|
1622 @subsection Reading One Event
|
|
|
1623
|
|
|
1624 The lowest level functions for command input are those which read a
|
|
|
1625 single event. These functions often make a distinction between
|
|
|
1626 @dfn{command events}, which are user actions (keystrokes and mouse
|
|
|
1627 actions), and other events, which serve as communication between
|
|
|
1628 XEmacs and the window system.
|
|
|
1629
|
|
|
1630 @defun next-event &optional event prompt
|
|
|
1631 This function reads and returns the next available event from the window
|
|
|
1632 system or terminal driver, waiting if necessary until an event is
|
|
|
1633 available. Pass this object to @code{dispatch-event} to handle it. If
|
|
|
1634 an event object is supplied, it is filled in and returned; otherwise a
|
|
|
1635 new event object will be created.
|
|
|
1636
|
|
|
1637 Events can come directly from the user, from a keyboard macro, or from
|
|
|
1638 @code{unread-command-events}.
|
|
|
1639
|
|
|
1640 In most cases, the function @code{next-command-event} is more
|
|
|
1641 appropriate.
|
|
|
1642 @end defun
|
|
|
1643
|
|
|
1644 @defun next-command-event &optional event
|
|
|
1645 This function returns the next available ``user'' event from the window
|
|
|
1646 system or terminal driver. Pass this object to @code{dispatch-event} to
|
|
|
1647 handle it. If an event object is supplied, it is filled in and
|
|
|
1648 returned, otherwise a new event object will be created.
|
|
|
1649
|
|
|
1650 The event returned will be a keyboard, mouse press, or mouse release
|
|
|
1651 event. If there are non-command events available (mouse motion,
|
|
|
1652 sub-process output, etc) then these will be executed (with
|
|
|
1653 @code{dispatch-event}) and discarded. This function is provided as a
|
|
|
1654 convenience; it is equivalent to the Lisp code
|
|
|
1655
|
|
|
1656 @lisp
|
|
|
1657 @group
|
|
|
1658 (while (progn
|
|
|
1659 (next-event event)
|
|
|
1660 (not (or (key-press-event-p event)
|
|
|
1661 (button-press-event-p event)
|
|
|
1662 (button-release-event-p event)
|
|
|
1663 (menu-event-p event))))
|
|
|
1664 (dispatch-event event))
|
|
|
1665 @end group
|
|
|
1666 @end lisp
|
|
|
1667
|
|
|
1668 Here is what happens if you call @code{next-command-event} and then
|
|
|
1669 press the right-arrow function key:
|
|
|
1670
|
|
|
1671 @example
|
|
|
1672 @group
|
|
|
1673 (next-command-event)
|
|
|
1674 @result{} #<keypress-event right>
|
|
|
1675 @end group
|
|
|
1676 @end example
|
|
|
1677 @end defun
|
|
|
1678
|
|
|
1679 @defun read-char
|
|
|
1680 This function reads and returns a character of command input. If a
|
|
|
1681 mouse click is detected, an error is signalled. The character typed is
|
|
|
1682 returned as an @sc{ASCII} value. This function is retained for
|
|
|
1683 compatibility with Emacs 18, and is most likely the wrong thing for you
|
|
|
1684 to be using: consider using @code{next-command-event} instead.
|
|
|
1685 @end defun
|
|
|
1686
|
|
|
1687 @defun enqueue-eval-event function object
|
|
|
1688 This function adds an eval event to the back of the queue. The
|
|
|
1689 eval event will be the next event read after all pending events.
|
|
|
1690 @end defun
|
|
|
1691
|
|
|
1692 @node Dispatching an Event
|
|
|
1693 @subsection Dispatching an Event
|
|
|
1694 @cindex dispatching an event
|
|
|
1695
|
|
|
1696 @defun dispatch-event event
|
|
|
1697 Given an event object returned by @code{next-event}, this function
|
|
|
1698 executes it. This is the basic function that makes XEmacs respond to
|
|
|
1699 user input; it also deals with notifications from the window system
|
|
|
1700 (such as Expose events).
|
|
|
1701 @end defun
|
|
|
1702
|
|
|
1703 @node Quoted Character Input
|
|
|
1704 @subsection Quoted Character Input
|
|
|
1705 @cindex quoted character input
|
|
|
1706
|
|
|
1707 You can use the function @code{read-quoted-char} to ask the user to
|
|
|
1708 specify a character, and allow the user to specify a control or meta
|
|
|
1709 character conveniently, either literally or as an octal character code.
|
|
|
1710 The command @code{quoted-insert} uses this function.
|
|
|
1711
|
|
|
1712 @defun read-quoted-char &optional prompt
|
|
|
1713 @cindex octal character input
|
|
|
1714 @cindex control characters, reading
|
|
|
1715 @cindex nonprinting characters, reading
|
|
|
1716 This function is like @code{read-char}, except that if the first
|
|
|
1717 character read is an octal digit (0-7), it reads up to two more octal digits
|
|
|
1718 (but stopping if a non-octal digit is found) and returns the
|
|
|
1719 character represented by those digits in octal.
|
|
|
1720
|
|
|
1721 Quitting is suppressed when the first character is read, so that the
|
|
|
1722 user can enter a @kbd{C-g}. @xref{Quitting}.
|
|
|
1723
|
|
|
1724 If @var{prompt} is supplied, it specifies a string for prompting the
|
|
|
1725 user. The prompt string is always displayed in the echo area, followed
|
|
|
1726 by a single @samp{-}.
|
|
|
1727
|
|
|
1728 In the following example, the user types in the octal number 177 (which
|
|
|
1729 is 127 in decimal).
|
|
|
1730
|
|
|
1731 @example
|
|
|
1732 (read-quoted-char "What character")
|
|
|
1733
|
|
|
1734 @group
|
|
|
1735 ---------- Echo Area ----------
|
|
|
1736 What character-@kbd{177}
|
|
|
1737 ---------- Echo Area ----------
|
|
|
1738
|
|
|
1739 @result{} 127
|
|
|
1740 @end group
|
|
|
1741 @end example
|
|
|
1742 @end defun
|
|
|
1743
|
|
|
1744 @need 2000
|
|
|
1745 @node Peeking and Discarding
|
|
|
1746 @subsection Miscellaneous Event Input Features
|
|
|
1747
|
|
|
1748 This section describes how to ``peek ahead'' at events without using
|
|
|
1749 them up, how to check for pending input, and how to discard pending
|
|
|
1750 input.
|
|
|
1751
|
|
|
1752 See also the variables @code{last-command-event} and @code{last-command-char}
|
|
|
1753 (@ref{Command Loop Info}).
|
|
|
1754
|
|
|
1755 @defvar unread-command-events
|
|
|
1756 @cindex next input
|
|
|
1757 @cindex peeking at input
|
|
|
1758 This variable holds a list of events waiting to be read as command
|
|
|
1759 input. The events are used in the order they appear in the list, and
|
|
|
1760 removed one by one as they are used.
|
|
|
1761
|
|
|
1762 The variable is needed because in some cases a function reads a event
|
|
|
1763 and then decides not to use it. Storing the event in this variable
|
|
|
1764 causes it to be processed normally, by the command loop or by the
|
|
|
1765 functions to read command input.
|
|
|
1766
|
|
|
1767 @cindex prefix argument unreading
|
|
|
1768 For example, the function that implements numeric prefix arguments reads
|
|
|
1769 any number of digits. When it finds a non-digit event, it must unread
|
|
|
1770 the event so that it can be read normally by the command loop.
|
|
|
1771 Likewise, incremental search uses this feature to unread events with no
|
|
|
1772 special meaning in a search, because these events should exit the search
|
|
|
1773 and then execute normally.
|
|
|
1774
|
|
|
1775 @ignore FSF Emacs stuff
|
|
|
1776 The reliable and easy way to extract events from a key sequence so as to
|
|
|
1777 put them in @code{unread-command-events} is to use
|
|
|
1778 @code{listify-key-sequence} (@pxref{Strings of Events}).
|
|
|
1779 @end ignore
|
|
|
1780 @end defvar
|
|
|
1781
|
|
|
1782 @defvar unread-command-event
|
|
|
1783 This variable holds a single event to be read as command input.
|
|
|
1784
|
|
|
1785 This variable is mostly obsolete now that you can use
|
|
|
1786 @code{unread-command-events} instead; it exists only to support programs
|
|
|
1787 written for versions of XEmacs prior to 19.12.
|
|
|
1788 @end defvar
|
|
|
1789
|
|
|
1790 @defun input-pending-p
|
|
|
1791 @cindex waiting for command key input
|
|
|
1792 This function determines whether any command input is currently
|
|
|
1793 available to be read. It returns immediately, with value @code{t} if
|
|
|
1794 there is available input, @code{nil} otherwise. On rare occasions it
|
|
|
1795 may return @code{t} when no input is available.
|
|
|
1796 @end defun
|
|
|
1797
|
|
|
1798 @defvar last-input-event
|
|
|
1799 This variable is set to the last keyboard or mouse button event received.
|
|
|
1800
|
|
|
1801 This variable is off limits: you may not set its value or modify the
|
|
|
1802 event that is its value, as it is destructively modified by
|
|
|
1803 @code{read-key-sequence}. If you want to keep a pointer to this value,
|
|
|
1804 you must use @code{copy-event}.
|
|
|
1805
|
|
|
1806 Note that this variable is an alias for @code{last-input-char} in
|
|
|
1807 FSF Emacs.
|
|
|
1808
|
|
|
1809 In the example below, a character is read (the character @kbd{1}). It
|
|
|
1810 becomes the value of @code{last-input-event}, while @kbd{C-e} (from the
|
|
|
1811 @kbd{C-x C-e} command used to evaluate this expression) remains the
|
|
|
1812 value of @code{last-command-event}.
|
|
|
1813
|
|
|
1814 @example
|
|
|
1815 @group
|
|
|
1816 (progn (print (next-command-event))
|
|
|
1817 (print last-command-event)
|
|
|
1818 last-input-event)
|
|
|
1819 @print{} #<keypress-event 1>
|
|
|
1820 @print{} #<keypress-event control-E>
|
|
|
1821 @result{} #<keypress-event 1>
|
|
|
1822
|
|
|
1823 @end group
|
|
|
1824 @end example
|
|
|
1825 @end defvar
|
|
|
1826
|
|
|
1827 @defvar last-input-char
|
|
|
1828 If the value of @code{last-input-event} is a keyboard event, then this
|
|
|
1829 is the nearest @sc{ASCII} equivalent to it. Remember that there is
|
|
|
1830 @emph{not} a 1:1 mapping between keyboard events and @sc{ASCII}
|
|
|
1831 characters: the set of keyboard events is much larger, so writing code
|
|
|
1832 that examines this variable to determine what key has been typed is bad
|
|
|
1833 practice, unless you are certain that it will be one of a small set of
|
|
|
1834 characters.
|
|
|
1835
|
|
|
1836 This function exists for compatibility with Emacs version 18.
|
|
|
1837 @end defvar
|
|
|
1838
|
|
|
1839 @defun discard-input
|
|
|
1840 @cindex flush input
|
|
|
1841 @cindex discard input
|
|
|
1842 @cindex terminate keyboard macro
|
|
|
1843 This function discards the contents of the terminal input buffer and
|
|
|
1844 cancels any keyboard macro that might be in the process of definition.
|
|
|
1845 It returns @code{nil}.
|
|
|
1846
|
|
|
1847 In the following example, the user may type a number of characters right
|
|
|
1848 after starting the evaluation of the form. After the @code{sleep-for}
|
|
|
1849 finishes sleeping, @code{discard-input} discards any characters typed
|
|
|
1850 during the sleep.
|
|
|
1851
|
|
|
1852 @example
|
|
|
1853 (progn (sleep-for 2)
|
|
|
1854 (discard-input))
|
|
|
1855 @result{} nil
|
|
|
1856 @end example
|
|
|
1857 @end defun
|
|
|
1858
|
|
|
1859 @node Waiting
|
|
|
1860 @section Waiting for Elapsed Time or Input
|
|
|
1861 @cindex pausing
|
|
|
1862 @cindex waiting
|
|
|
1863
|
|
|
1864 The wait functions are designed to wait for a certain amount of time
|
|
|
1865 to pass or until there is input. For example, you may wish to pause in
|
|
|
1866 the middle of a computation to allow the user time to view the display.
|
|
|
1867 @code{sit-for} pauses and updates the screen, and returns immediately if
|
|
|
1868 input comes in, while @code{sleep-for} pauses without updating the
|
|
|
1869 screen.
|
|
|
1870
|
|
|
1871 Note that in FSF Emacs, the commands @code{sit-for} and @code{sleep-for}
|
|
|
1872 take two arguments to specify the time (one integer and one float
|
|
|
1873 value), instead of a single argument that can be either an integer or a
|
|
|
1874 float.
|
|
|
1875
|
|
|
1876 @defun sit-for seconds &optional nodisp
|
|
|
1877 This function performs redisplay (provided there is no pending input
|
|
|
1878 from the user), then waits @var{seconds} seconds, or until input is
|
|
|
1879 available. The result is @code{t} if @code{sit-for} waited the full
|
|
|
1880 time with no input arriving (see @code{input-pending-p} in @ref{Peeking
|
|
|
1881 and Discarding}). Otherwise, the value is @code{nil}.
|
|
|
1882
|
|
|
1883 The argument @var{seconds} need not be an integer. If it is a floating
|
|
|
1884 point number, @code{sit-for} waits for a fractional number of seconds.
|
|
|
1885 @ignore FSF Emacs stuff
|
|
|
1886 Some systems support only a whole number of seconds; on these systems,
|
|
|
1887 @var{seconds} is rounded down.
|
|
|
1888
|
|
|
1889 The optional argument @var{millisec} specifies an additional waiting
|
|
|
1890 period measured in milliseconds. This adds to the period specified by
|
|
|
1891 @var{seconds}. If the system doesn't support waiting fractions of a
|
|
|
1892 second, you get an error if you specify nonzero @var{millisec}.
|
|
|
1893 @end ignore
|
|
|
1894
|
|
|
1895 @cindex forcing redisplay
|
|
|
1896 Redisplay is normally preempted if input arrives, and does not happen at
|
|
|
1897 all if input is available before it starts. (You can force screen
|
|
|
1898 updating in such a case by using @code{force-redisplay}. @xref{Refresh
|
|
|
1899 Screen}.) If there is no input pending, you can force an update with no
|
|
|
1900 delay by using @code{(sit-for 0)}.
|
|
|
1901
|
|
|
1902 If @var{nodisp} is non-@code{nil}, then @code{sit-for} does not
|
|
|
1903 redisplay, but it still returns as soon as input is available (or when
|
|
|
1904 the timeout elapses).
|
|
|
1905
|
|
|
1906 @ignore
|
|
|
1907 Iconifying or deiconifying a frame makes @code{sit-for} return, because
|
|
|
1908 that generates an event. @xref{Misc Events}.
|
|
|
1909 @end ignore
|
|
|
1910
|
|
|
1911 The usual purpose of @code{sit-for} is to give the user time to read
|
|
|
1912 text that you display.
|
|
|
1913 @end defun
|
|
|
1914
|
|
|
1915 @defun sleep-for seconds
|
|
|
1916 This function simply pauses for @var{seconds} seconds without updating
|
|
|
1917 the display. This function pays no attention to available input. It
|
|
|
1918 returns @code{nil}.
|
|
|
1919
|
|
|
1920 The argument @var{seconds} need not be an integer. If it is a floating
|
|
|
1921 point number, @code{sleep-for} waits for a fractional number of seconds.
|
|
|
1922 @ignore FSF Emacs stuff
|
|
|
1923 Some systems support only a whole number of seconds; on these systems,
|
|
|
1924 @var{seconds} is rounded down.
|
|
|
1925
|
|
|
1926 The optional argument @var{millisec} specifies an additional waiting
|
|
|
1927 period measured in milliseconds. This adds to the period specified by
|
|
|
1928 @var{seconds}. If the system doesn't support waiting fractions of a
|
|
|
1929 second, you get an error if you specify nonzero @var{millisec}.
|
|
|
1930 @end ignore
|
|
|
1931
|
|
|
1932 Use @code{sleep-for} when you wish to guarantee a delay.
|
|
|
1933 @end defun
|
|
|
1934
|
|
|
1935 @xref{Time of Day}, for functions to get the current time.
|
|
|
1936
|
|
|
1937 @node Quitting
|
|
|
1938 @section Quitting
|
|
|
1939 @cindex @kbd{C-g}
|
|
|
1940 @cindex quitting
|
|
|
1941
|
|
|
1942 Typing @kbd{C-g} while a Lisp function is running causes XEmacs to
|
|
|
1943 @dfn{quit} whatever it is doing. This means that control returns to the
|
|
|
1944 innermost active command loop.
|
|
|
1945
|
|
|
1946 Typing @kbd{C-g} while the command loop is waiting for keyboard input
|
|
|
1947 does not cause a quit; it acts as an ordinary input character. In the
|
|
|
1948 simplest case, you cannot tell the difference, because @kbd{C-g}
|
|
|
1949 normally runs the command @code{keyboard-quit}, whose effect is to quit.
|
|
|
1950 However, when @kbd{C-g} follows a prefix key, the result is an undefined
|
|
|
1951 key. The effect is to cancel the prefix key as well as any prefix
|
|
|
1952 argument.
|
|
|
1953
|
|
|
1954 In the minibuffer, @kbd{C-g} has a different definition: it aborts out
|
|
|
1955 of the minibuffer. This means, in effect, that it exits the minibuffer
|
|
|
1956 and then quits. (Simply quitting would return to the command loop
|
|
|
1957 @emph{within} the minibuffer.) The reason why @kbd{C-g} does not quit
|
|
|
1958 directly when the command reader is reading input is so that its meaning
|
|
|
1959 can be redefined in the minibuffer in this way. @kbd{C-g} following a
|
|
|
1960 prefix key is not redefined in the minibuffer, and it has its normal
|
|
|
1961 effect of canceling the prefix key and prefix argument. This too
|
|
|
1962 would not be possible if @kbd{C-g} always quit directly.
|
|
|
1963
|
|
|
1964 When @kbd{C-g} does directly quit, it does so by setting the variable
|
|
|
1965 @code{quit-flag} to @code{t}. XEmacs checks this variable at appropriate
|
|
|
1966 times and quits if it is not @code{nil}. Setting @code{quit-flag}
|
|
|
1967 non-@code{nil} in any way thus causes a quit.
|
|
|
1968
|
|
|
1969 At the level of C code, quitting cannot happen just anywhere; only at the
|
|
|
1970 special places that check @code{quit-flag}. The reason for this is
|
|
|
1971 that quitting at other places might leave an inconsistency in XEmacs's
|
|
|
1972 internal state. Because quitting is delayed until a safe place, quitting
|
|
|
1973 cannot make XEmacs crash.
|
|
|
1974
|
|
|
1975 Certain functions such as @code{read-key-sequence} or
|
|
|
1976 @code{read-quoted-char} prevent quitting entirely even though they wait
|
|
|
1977 for input. Instead of quitting, @kbd{C-g} serves as the requested
|
|
|
1978 input. In the case of @code{read-key-sequence}, this serves to bring
|
|
|
1979 about the special behavior of @kbd{C-g} in the command loop. In the
|
|
|
1980 case of @code{read-quoted-char}, this is so that @kbd{C-q} can be used
|
|
|
1981 to quote a @kbd{C-g}.
|
|
|
1982
|
|
|
1983 You can prevent quitting for a portion of a Lisp function by binding
|
|
|
1984 the variable @code{inhibit-quit} to a non-@code{nil} value. Then,
|
|
|
1985 although @kbd{C-g} still sets @code{quit-flag} to @code{t} as usual, the
|
|
|
1986 usual result of this---a quit---is prevented. Eventually,
|
|
|
1987 @code{inhibit-quit} will become @code{nil} again, such as when its
|
|
|
1988 binding is unwound at the end of a @code{let} form. At that time, if
|
|
|
1989 @code{quit-flag} is still non-@code{nil}, the requested quit happens
|
|
|
1990 immediately. This behavior is ideal when you wish to make sure that
|
|
|
1991 quitting does not happen within a ``critical section'' of the program.
|
|
|
1992
|
|
|
1993 @cindex @code{read-quoted-char} quitting
|
|
|
1994 In some functions (such as @code{read-quoted-char}), @kbd{C-g} is
|
|
|
1995 handled in a special way that does not involve quitting. This is done
|
|
|
1996 by reading the input with @code{inhibit-quit} bound to @code{t}, and
|
|
|
1997 setting @code{quit-flag} to @code{nil} before @code{inhibit-quit}
|
|
|
1998 becomes @code{nil} again. This excerpt from the definition of
|
|
|
1999 @code{read-quoted-char} shows how this is done; it also shows that
|
|
|
2000 normal quitting is permitted after the first character of input.
|
|
|
2001
|
|
|
2002 @example
|
|
|
2003 (defun read-quoted-char (&optional prompt)
|
|
|
2004 "@dots{}@var{documentation}@dots{}"
|
|
|
2005 (let ((count 0) (code 0) char)
|
|
|
2006 (while (< count 3)
|
|
|
2007 (let ((inhibit-quit (zerop count))
|
|
|
2008 (help-form nil))
|
|
|
2009 (and prompt (message "%s-" prompt))
|
|
|
2010 (setq char (read-char))
|
|
|
2011 (if inhibit-quit (setq quit-flag nil)))
|
|
|
2012 @dots{})
|
|
|
2013 (logand 255 code)))
|
|
|
2014 @end example
|
|
|
2015
|
|
|
2016 @defvar quit-flag
|
|
|
2017 If this variable is non-@code{nil}, then XEmacs quits immediately, unless
|
|
|
2018 @code{inhibit-quit} is non-@code{nil}. Typing @kbd{C-g} ordinarily sets
|
|
|
2019 @code{quit-flag} non-@code{nil}, regardless of @code{inhibit-quit}.
|
|
|
2020 @end defvar
|
|
|
2021
|
|
|
2022 @defvar inhibit-quit
|
|
|
2023 This variable determines whether XEmacs should quit when @code{quit-flag}
|
|
|
2024 is set to a value other than @code{nil}. If @code{inhibit-quit} is
|
|
|
2025 non-@code{nil}, then @code{quit-flag} has no special effect.
|
|
|
2026 @end defvar
|
|
|
2027
|
|
|
2028 @deffn Command keyboard-quit
|
|
|
2029 This function signals the @code{quit} condition with @code{(signal 'quit
|
|
|
2030 nil)}. This is the same thing that quitting does. (See @code{signal}
|
|
|
2031 in @ref{Errors}.)
|
|
|
2032 @end deffn
|
|
|
2033
|
|
|
2034 You can specify a character other than @kbd{C-g} to use for quitting.
|
|
|
2035 See the function @code{set-input-mode} in @ref{Terminal Input}.
|
|
|
2036
|
|
|
2037 @node Prefix Command Arguments
|
|
|
2038 @section Prefix Command Arguments
|
|
|
2039 @cindex prefix argument
|
|
|
2040 @cindex raw prefix argument
|
|
|
2041 @cindex numeric prefix argument
|
|
|
2042
|
|
|
2043 Most XEmacs commands can use a @dfn{prefix argument}, a number
|
|
|
2044 specified before the command itself. (Don't confuse prefix arguments
|
|
|
2045 with prefix keys.) The prefix argument is at all times represented by a
|
|
|
2046 value, which may be @code{nil}, meaning there is currently no prefix
|
|
|
2047 argument. Each command may use the prefix argument or ignore it.
|
|
|
2048
|
|
|
2049 There are two representations of the prefix argument: @dfn{raw} and
|
|
|
2050 @dfn{numeric}. The editor command loop uses the raw representation
|
|
|
2051 internally, and so do the Lisp variables that store the information, but
|
|
|
2052 commands can request either representation.
|
|
|
2053
|
|
|
2054 Here are the possible values of a raw prefix argument:
|
|
|
2055
|
|
|
2056 @itemize @bullet
|
|
|
2057 @item
|
|
|
2058 @code{nil}, meaning there is no prefix argument. Its numeric value is
|
|
|
2059 1, but numerous commands make a distinction between @code{nil} and the
|
|
|
2060 integer 1.
|
|
|
2061
|
|
|
2062 @item
|
|
|
2063 An integer, which stands for itself.
|
|
|
2064
|
|
|
2065 @item
|
|
|
2066 A list of one element, which is an integer. This form of prefix
|
|
|
2067 argument results from one or a succession of @kbd{C-u}'s with no
|
|
|
2068 digits. The numeric value is the integer in the list, but some
|
|
|
2069 commands make a distinction between such a list and an integer alone.
|
|
|
2070
|
|
|
2071 @item
|
|
|
2072 The symbol @code{-}. This indicates that @kbd{M--} or @kbd{C-u -} was
|
|
|
2073 typed, without following digits. The equivalent numeric value is
|
|
|
2074 @minus{}1, but some commands make a distinction between the integer
|
|
|
2075 @minus{}1 and the symbol @code{-}.
|
|
|
2076 @end itemize
|
|
|
2077
|
|
|
2078 We illustrate these possibilities by calling the following function with
|
|
|
2079 various prefixes:
|
|
|
2080
|
|
|
2081 @example
|
|
|
2082 @group
|
|
|
2083 (defun display-prefix (arg)
|
|
|
2084 "Display the value of the raw prefix arg."
|
|
|
2085 (interactive "P")
|
|
|
2086 (message "%s" arg))
|
|
|
2087 @end group
|
|
|
2088 @end example
|
|
|
2089
|
|
|
2090 @noindent
|
|
|
2091 Here are the results of calling @code{display-prefix} with various
|
|
|
2092 raw prefix arguments:
|
|
|
2093
|
|
|
2094 @example
|
|
|
2095 M-x display-prefix @print{} nil
|
|
|
2096
|
|
|
2097 C-u M-x display-prefix @print{} (4)
|
|
|
2098
|
|
|
2099 C-u C-u M-x display-prefix @print{} (16)
|
|
|
2100
|
|
|
2101 C-u 3 M-x display-prefix @print{} 3
|
|
|
2102
|
|
|
2103 M-3 M-x display-prefix @print{} 3 ; @r{(Same as @code{C-u 3}.)}
|
|
|
2104
|
|
|
2105 C-3 M-x display-prefix @print{} 3 ; @r{(Same as @code{C-u 3}.)}
|
|
|
2106
|
|
|
2107 C-u - M-x display-prefix @print{} -
|
|
|
2108
|
|
|
2109 M-- M-x display-prefix @print{} - ; @r{(Same as @code{C-u -}.)}
|
|
|
2110
|
|
|
2111 C-- M-x display-prefix @print{} - ; @r{(Same as @code{C-u -}.)}
|
|
|
2112
|
|
|
2113 C-u - 7 M-x display-prefix @print{} -7
|
|
|
2114
|
|
|
2115 M-- 7 M-x display-prefix @print{} -7 ; @r{(Same as @code{C-u -7}.)}
|
|
|
2116
|
|
|
2117 C-- 7 M-x display-prefix @print{} -7 ; @r{(Same as @code{C-u -7}.)}
|
|
|
2118 @end example
|
|
|
2119
|
|
|
2120 XEmacs uses two variables to store the prefix argument:
|
|
|
2121 @code{prefix-arg} and @code{current-prefix-arg}. Commands such as
|
|
|
2122 @code{universal-argument} that set up prefix arguments for other
|
|
|
2123 commands store them in @code{prefix-arg}. In contrast,
|
|
|
2124 @code{current-prefix-arg} conveys the prefix argument to the current
|
|
|
2125 command, so setting it has no effect on the prefix arguments for future
|
|
|
2126 commands.
|
|
|
2127
|
|
|
2128 Normally, commands specify which representation to use for the prefix
|
|
|
2129 argument, either numeric or raw, in the @code{interactive} declaration.
|
|
|
2130 (@xref{Using Interactive}.) Alternatively, functions may look at the
|
|
|
2131 value of the prefix argument directly in the variable
|
|
|
2132 @code{current-prefix-arg}, but this is less clean.
|
|
|
2133
|
|
|
2134 @defun prefix-numeric-value arg
|
|
|
2135 This function returns the numeric meaning of a valid raw prefix argument
|
|
|
2136 value, @var{arg}. The argument may be a symbol, a number, or a list.
|
|
|
2137 If it is @code{nil}, the value 1 is returned; if it is @code{-}, the
|
|
|
2138 value @minus{}1 is returned; if it is a number, that number is returned;
|
|
|
2139 if it is a list, the @sc{car} of that list (which should be a number) is
|
|
|
2140 returned.
|
|
|
2141 @end defun
|
|
|
2142
|
|
|
2143 @defvar current-prefix-arg
|
|
|
2144 This variable holds the raw prefix argument for the @emph{current}
|
|
|
2145 command. Commands may examine it directly, but the usual way to access
|
|
|
2146 it is with @code{(interactive "P")}.
|
|
|
2147 @end defvar
|
|
|
2148
|
|
|
2149 @defvar prefix-arg
|
|
|
2150 The value of this variable is the raw prefix argument for the
|
|
|
2151 @emph{next} editing command. Commands that specify prefix arguments for
|
|
|
2152 the following command work by setting this variable.
|
|
|
2153 @end defvar
|
|
|
2154
|
|
|
2155 Do not call the functions @code{universal-argument},
|
|
|
2156 @code{digit-argument}, or @code{negative-argument} unless you intend to
|
|
|
2157 let the user enter the prefix argument for the @emph{next} command.
|
|
|
2158
|
|
|
2159 @deffn Command universal-argument
|
|
|
2160 This command reads input and specifies a prefix argument for the
|
|
|
2161 following command. Don't call this command yourself unless you know
|
|
|
2162 what you are doing.
|
|
|
2163 @end deffn
|
|
|
2164
|
|
|
2165 @deffn Command digit-argument arg
|
|
|
2166 This command adds to the prefix argument for the following command. The
|
|
|
2167 argument @var{arg} is the raw prefix argument as it was before this
|
|
|
2168 command; it is used to compute the updated prefix argument. Don't call
|
|
|
2169 this command yourself unless you know what you are doing.
|
|
|
2170 @end deffn
|
|
|
2171
|
|
|
2172 @deffn Command negative-argument arg
|
|
|
2173 This command adds to the numeric argument for the next command. The
|
|
|
2174 argument @var{arg} is the raw prefix argument as it was before this
|
|
|
2175 command; its value is negated to form the new prefix argument. Don't
|
|
|
2176 call this command yourself unless you know what you are doing.
|
|
|
2177 @end deffn
|
|
|
2178
|
|
|
2179 @node Recursive Editing
|
|
|
2180 @section Recursive Editing
|
|
|
2181 @cindex recursive command loop
|
|
|
2182 @cindex recursive editing level
|
|
|
2183 @cindex command loop, recursive
|
|
|
2184
|
|
|
2185 The XEmacs command loop is entered automatically when XEmacs starts up.
|
|
|
2186 This top-level invocation of the command loop never exits; it keeps
|
|
|
2187 running as long as XEmacs does. Lisp programs can also invoke the
|
|
|
2188 command loop. Since this makes more than one activation of the command
|
|
|
2189 loop, we call it @dfn{recursive editing}. A recursive editing level has
|
|
|
2190 the effect of suspending whatever command invoked it and permitting the
|
|
|
2191 user to do arbitrary editing before resuming that command.
|
|
|
2192
|
|
|
2193 The commands available during recursive editing are the same ones
|
|
|
2194 available in the top-level editing loop and defined in the keymaps.
|
|
|
2195 Only a few special commands exit the recursive editing level; the others
|
|
|
2196 return to the recursive editing level when they finish. (The special
|
|
|
2197 commands for exiting are always available, but they do nothing when
|
|
|
2198 recursive editing is not in progress.)
|
|
|
2199
|
|
|
2200 All command loops, including recursive ones, set up all-purpose error
|
|
|
2201 handlers so that an error in a command run from the command loop will
|
|
|
2202 not exit the loop.
|
|
|
2203
|
|
|
2204 @cindex minibuffer input
|
|
|
2205 Minibuffer input is a special kind of recursive editing. It has a few
|
|
|
2206 special wrinkles, such as enabling display of the minibuffer and the
|
|
|
2207 minibuffer window, but fewer than you might suppose. Certain keys
|
|
|
2208 behave differently in the minibuffer, but that is only because of the
|
|
|
2209 minibuffer's local map; if you switch windows, you get the usual XEmacs
|
|
|
2210 commands.
|
|
|
2211
|
|
|
2212 @cindex @code{throw} example
|
|
|
2213 @kindex exit
|
|
|
2214 @cindex exit recursive editing
|
|
|
2215 @cindex aborting
|
|
|
2216 To invoke a recursive editing level, call the function
|
|
|
2217 @code{recursive-edit}. This function contains the command loop; it also
|
|
|
2218 contains a call to @code{catch} with tag @code{exit}, which makes it
|
|
|
2219 possible to exit the recursive editing level by throwing to @code{exit}
|
|
|
2220 (@pxref{Catch and Throw}). If you throw a value other than @code{t},
|
|
|
2221 then @code{recursive-edit} returns normally to the function that called
|
|
|
2222 it. The command @kbd{C-M-c} (@code{exit-recursive-edit}) does this.
|
|
|
2223 Throwing a @code{t} value causes @code{recursive-edit} to quit, so that
|
|
|
2224 control returns to the command loop one level up. This is called
|
|
|
2225 @dfn{aborting}, and is done by @kbd{C-]} (@code{abort-recursive-edit}).
|
|
|
2226
|
|
|
2227 Most applications should not use recursive editing, except as part of
|
|
|
2228 using the minibuffer. Usually it is more convenient for the user if you
|
|
|
2229 change the major mode of the current buffer temporarily to a special
|
|
|
2230 major mode, which should have a command to go back to the previous mode.
|
|
|
2231 (The @kbd{e} command in Rmail uses this technique.) Or, if you wish to
|
|
|
2232 give the user different text to edit ``recursively'', create and select
|
|
|
2233 a new buffer in a special mode. In this mode, define a command to
|
|
|
2234 complete the processing and go back to the previous buffer. (The
|
|
|
2235 @kbd{m} command in Rmail does this.)
|
|
|
2236
|
|
|
2237 Recursive edits are useful in debugging. You can insert a call to
|
|
|
2238 @code{debug} into a function definition as a sort of breakpoint, so that
|
|
|
2239 you can look around when the function gets there. @code{debug} invokes
|
|
|
2240 a recursive edit but also provides the other features of the debugger.
|
|
|
2241
|
|
|
2242 Recursive editing levels are also used when you type @kbd{C-r} in
|
|
|
2243 @code{query-replace} or use @kbd{C-x q} (@code{kbd-macro-query}).
|
|
|
2244
|
|
|
2245 @defun recursive-edit
|
|
|
2246 @cindex suspend evaluation
|
|
|
2247 This function invokes the editor command loop. It is called
|
|
|
2248 automatically by the initialization of XEmacs, to let the user begin
|
|
|
2249 editing. When called from a Lisp program, it enters a recursive editing
|
|
|
2250 level.
|
|
|
2251
|
|
|
2252 In the following example, the function @code{simple-rec} first
|
|
|
2253 advances point one word, then enters a recursive edit, printing out a
|
|
|
2254 message in the echo area. The user can then do any editing desired, and
|
|
|
2255 then type @kbd{C-M-c} to exit and continue executing @code{simple-rec}.
|
|
|
2256
|
|
|
2257 @example
|
|
|
2258 (defun simple-rec ()
|
|
|
2259 (forward-word 1)
|
|
|
2260 (message "Recursive edit in progress")
|
|
|
2261 (recursive-edit)
|
|
|
2262 (forward-word 1))
|
|
|
2263 @result{} simple-rec
|
|
|
2264 (simple-rec)
|
|
|
2265 @result{} nil
|
|
|
2266 @end example
|
|
|
2267 @end defun
|
|
|
2268
|
|
|
2269 @deffn Command exit-recursive-edit
|
|
|
2270 This function exits from the innermost recursive edit (including
|
|
|
2271 minibuffer input). Its definition is effectively @code{(throw 'exit
|
|
|
2272 nil)}.
|
|
|
2273 @end deffn
|
|
|
2274
|
|
|
2275 @deffn Command abort-recursive-edit
|
|
|
2276 This function aborts the command that requested the innermost recursive
|
|
|
2277 edit (including minibuffer input), by signaling @code{quit}
|
|
|
2278 after exiting the recursive edit. Its definition is effectively
|
|
|
2279 @code{(throw 'exit t)}. @xref{Quitting}.
|
|
|
2280 @end deffn
|
|
|
2281
|
|
|
2282 @deffn Command top-level
|
|
|
2283 This function exits all recursive editing levels; it does not return a
|
|
|
2284 value, as it jumps completely out of any computation directly back to
|
|
|
2285 the main command loop.
|
|
|
2286 @end deffn
|
|
|
2287
|
|
|
2288 @defun recursion-depth
|
|
|
2289 This function returns the current depth of recursive edits. When no
|
|
|
2290 recursive edit is active, it returns 0.
|
|
|
2291 @end defun
|
|
|
2292
|
|
|
2293 @node Disabling Commands
|
|
|
2294 @section Disabling Commands
|
|
|
2295 @cindex disabled command
|
|
|
2296
|
|
|
2297 @dfn{Disabling a command} marks the command as requiring user
|
|
|
2298 confirmation before it can be executed. Disabling is used for commands
|
|
|
2299 which might be confusing to beginning users, to prevent them from using
|
|
|
2300 the commands by accident.
|
|
|
2301
|
|
|
2302 @kindex disabled
|
|
|
2303 The low-level mechanism for disabling a command is to put a
|
|
|
2304 non-@code{nil} @code{disabled} property on the Lisp symbol for the
|
|
|
2305 command. These properties are normally set up by the user's
|
|
|
2306 @file{.emacs} file with Lisp expressions such as this:
|
|
|
2307
|
|
|
2308 @example
|
|
|
2309 (put 'upcase-region 'disabled t)
|
|
|
2310 @end example
|
|
|
2311
|
|
|
2312 @noindent
|
|
|
2313 For a few commands, these properties are present by default and may be
|
|
|
2314 removed by the @file{.emacs} file.
|
|
|
2315
|
|
|
2316 If the value of the @code{disabled} property is a string, the message
|
|
|
2317 saying the command is disabled includes that string. For example:
|
|
|
2318
|
|
|
2319 @example
|
|
|
2320 (put 'delete-region 'disabled
|
|
|
2321 "Text deleted this way cannot be yanked back!\n")
|
|
|
2322 @end example
|
|
|
2323
|
|
|
2324 @xref{Disabling,,, emacs, The XEmacs Reference Manual}, for the details on
|
|
|
2325 what happens when a disabled command is invoked interactively.
|
|
|
2326 Disabling a command has no effect on calling it as a function from Lisp
|
|
|
2327 programs.
|
|
|
2328
|
|
|
2329 @deffn Command enable-command command
|
|
|
2330 Allow @var{command} to be executed without special confirmation from now
|
|
|
2331 on, and (if the user confirms) alter the user's @file{.emacs} file so
|
|
|
2332 that this will apply to future sessions.
|
|
|
2333 @end deffn
|
|
|
2334
|
|
|
2335 @deffn Command disable-command command
|
|
|
2336 Require special confirmation to execute @var{command} from now on, and
|
|
|
2337 (if the user confirms) alter the user's @file{.emacs} file so that this
|
|
|
2338 will apply to future sessions.
|
|
|
2339 @end deffn
|
|
|
2340
|
|
|
2341 @defvar disabled-command-hook
|
|
|
2342 This normal hook is run instead of a disabled command, when the user
|
|
|
2343 invokes the disabled command interactively. The hook functions can use
|
|
|
2344 @code{this-command-keys} to determine what the user typed to run the
|
|
|
2345 command, and thus find the command itself. @xref{Hooks}.
|
|
|
2346
|
|
|
2347 By default, @code{disabled-command-hook} contains a function that asks
|
|
|
2348 the user whether to proceed.
|
|
|
2349 @end defvar
|
|
|
2350
|
|
|
2351 @node Command History
|
|
|
2352 @section Command History
|
|
|
2353 @cindex command history
|
|
|
2354 @cindex complex command
|
|
|
2355 @cindex history of commands
|
|
|
2356
|
|
|
2357 The command loop keeps a history of the complex commands that have
|
|
|
2358 been executed, to make it convenient to repeat these commands. A
|
|
|
2359 @dfn{complex command} is one for which the interactive argument reading
|
|
|
2360 uses the minibuffer. This includes any @kbd{M-x} command, any
|
|
|
2361 @kbd{M-:} command, and any command whose @code{interactive}
|
|
|
2362 specification reads an argument from the minibuffer. Explicit use of
|
|
|
2363 the minibuffer during the execution of the command itself does not cause
|
|
|
2364 the command to be considered complex.
|
|
|
2365
|
|
|
2366 @defvar command-history
|
|
|
2367 This variable's value is a list of recent complex commands, each
|
|
|
2368 represented as a form to evaluate. It continues to accumulate all
|
|
|
2369 complex commands for the duration of the editing session, but all but
|
|
|
2370 the first (most recent) thirty elements are deleted when a garbage
|
|
|
2371 collection takes place (@pxref{Garbage Collection}).
|
|
|
2372
|
|
|
2373 @example
|
|
|
2374 @group
|
|
|
2375 command-history
|
|
|
2376 @result{} ((switch-to-buffer "chistory.texi")
|
|
|
2377 (describe-key "^X^[")
|
|
|
2378 (visit-tags-table "~/emacs/src/")
|
|
|
2379 (find-tag "repeat-complex-command"))
|
|
|
2380 @end group
|
|
|
2381 @end example
|
|
|
2382 @end defvar
|
|
|
2383
|
|
|
2384 This history list is actually a special case of minibuffer history
|
|
|
2385 (@pxref{Minibuffer History}), with one special twist: the elements are
|
|
|
2386 expressions rather than strings.
|
|
|
2387
|
|
|
2388 There are a number of commands devoted to the editing and recall of
|
|
|
2389 previous commands. The commands @code{repeat-complex-command}, and
|
|
|
2390 @code{list-command-history} are described in the user manual
|
|
|
2391 (@pxref{Repetition,,, emacs, The XEmacs Reference Manual}). Within the
|
|
|
2392 minibuffer, the history commands used are the same ones available in any
|
|
|
2393 minibuffer.
|
|
|
2394
|
|
|
2395 @node Keyboard Macros
|
|
|
2396 @section Keyboard Macros
|
|
|
2397 @cindex keyboard macros
|
|
|
2398
|
|
|
2399 A @dfn{keyboard macro} is a canned sequence of input events that can
|
|
|
2400 be considered a command and made the definition of a key. The Lisp
|
|
|
2401 representation of a keyboard macro is a string or vector containing the
|
|
|
2402 events. Don't confuse keyboard macros with Lisp macros
|
|
|
2403 (@pxref{Macros}).
|
|
|
2404
|
|
|
2405 @defun execute-kbd-macro macro &optional count
|
|
|
2406 This function executes @var{macro} as a sequence of events. If
|
|
|
2407 @var{macro} is a string or vector, then the events in it are executed
|
|
|
2408 exactly as if they had been input by the user. The sequence is
|
|
|
2409 @emph{not} expected to be a single key sequence; normally a keyboard
|
|
|
2410 macro definition consists of several key sequences concatenated.
|
|
|
2411
|
|
|
2412 If @var{macro} is a symbol, then its function definition is used in
|
|
|
2413 place of @var{macro}. If that is another symbol, this process repeats.
|
|
|
2414 Eventually the result should be a string or vector. If the result is
|
|
|
2415 not a symbol, string, or vector, an error is signaled.
|
|
|
2416
|
|
|
2417 The argument @var{count} is a repeat count; @var{macro} is executed that
|
|
|
2418 many times. If @var{count} is omitted or @code{nil}, @var{macro} is
|
|
|
2419 executed once. If it is 0, @var{macro} is executed over and over until it
|
|
|
2420 encounters an error or a failing search.
|
|
|
2421 @end defun
|
|
|
2422
|
|
|
2423 @defvar executing-macro
|
|
|
2424 This variable contains the string or vector that defines the keyboard
|
|
|
2425 macro that is currently executing. It is @code{nil} if no macro is
|
|
|
2426 currently executing. A command can test this variable to behave
|
|
|
2427 differently when run from an executing macro. Do not set this variable
|
|
|
2428 yourself.
|
|
|
2429 @end defvar
|
|
|
2430
|
|
|
2431 @defvar defining-kbd-macro
|
|
|
2432 This variable indicates whether a keyboard macro is being defined. A
|
|
|
2433 command can test this variable to behave differently while a macro is
|
|
|
2434 being defined. The commands @code{start-kbd-macro} and
|
|
|
2435 @code{end-kbd-macro} set this variable---do not set it yourself.
|
|
|
2436 @end defvar
|
|
|
2437
|
|
|
2438 @defvar last-kbd-macro
|
|
|
2439 This variable is the definition of the most recently defined keyboard
|
|
|
2440 macro. Its value is a string or vector, or @code{nil}.
|
|
|
2441 @end defvar
|
|
|
2442
|
|
|
2443 @c Broke paragraph to prevent overfull hbox. --rjc 15mar92
|
|
|
2444 The commands are described in the user's manual (@pxref{Keyboard
|
|
199
|
2445 Macros,,, xemacs, The XEmacs Reference Manual}).
|
