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