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