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