|
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
|
|
54
|
726
|
|
0
|
727 If the value of @code{last-command-event} is a keyboard event, then this
|
|
54
|
728 is the nearest character equivalent to it (or @code{nil} if there is no
|
|
|
729 character equivalent). @code{last-command-char} is the character that
|
|
|
730 @code{self-insert-command} will insert in the buffer. Remember that
|
|
|
731 there is @emph{not} a one-to-one mapping between keyboard events and
|
|
|
732 XEmacs characters: many keyboard events have no corresponding character,
|
|
|
733 and when the Mule feature is available, most characters can not be input
|
|
|
734 on standard keyboards, except possibly with help from an input method.
|
|
|
735 So writing code that examines this variable to determine what key has
|
|
|
736 been typed is bad practice, unless you are certain that it will be one
|
|
|
737 of a small set of characters.
|
|
0
|
738
|
|
54
|
739 This variable exists for compatibility with Emacs version 18.
|
|
0
|
740
|
|
|
741 @example
|
|
|
742 @group
|
|
54
|
743 last-command-char
|
|
0
|
744 ;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
|
|
54
|
745 @result{} ?\^E
|
|
0
|
746 @end group
|
|
|
747 @end example
|
|
|
748
|
|
|
749 @end defvar
|
|
|
750
|
|
|
751 @defvar current-mouse-event
|
|
|
752 This variable holds the mouse-button event which invoked this command,
|
|
|
753 or @code{nil}. This is what @code{(interactive "e")} returns.
|
|
|
754 @end defvar
|
|
|
755
|
|
|
756 @defvar echo-keystrokes
|
|
|
757 This variable determines how much time should elapse before command
|
|
|
758 characters echo. Its value must be an integer, which specifies the
|
|
|
759 number of seconds to wait before echoing. If the user types a prefix
|
|
|
760 key (say @kbd{C-x}) and then delays this many seconds before continuing,
|
|
|
761 the key @kbd{C-x} is echoed in the echo area. Any subsequent characters
|
|
|
762 in the same command will be echoed as well.
|
|
|
763
|
|
|
764 If the value is zero, then command input is not echoed.
|
|
|
765 @end defvar
|
|
|
766
|
|
|
767 @node Events
|
|
|
768 @section Events
|
|
|
769 @cindex events
|
|
|
770 @cindex input events
|
|
|
771
|
|
|
772 The XEmacs command loop reads a sequence of @dfn{events} that
|
|
|
773 represent keyboard or mouse activity. Unlike in Emacs 18 and in FSF
|
|
|
774 Emacs, events are a primitive Lisp type that must be manipulated
|
|
|
775 using their own accessor and settor primitives. This section describes
|
|
|
776 the representation and meaning of input events in detail.
|
|
|
777
|
|
|
778 A key sequence that starts with a mouse event is read using the keymaps
|
|
|
779 of the buffer in the window that the mouse was in, not the current
|
|
|
780 buffer. This does not imply that clicking in a window selects that
|
|
|
781 window or its buffer---that is entirely under the control of the command
|
|
|
782 binding of the key sequence.
|
|
|
783
|
|
|
784 For information about how exactly the XEmacs command loop works,
|
|
|
785 @xref{Reading Input}.
|
|
|
786
|
|
|
787 @defun eventp object
|
|
|
788 This function returns non-@code{nil} if @var{event} is an input event.
|
|
|
789 @end defun
|
|
|
790
|
|
|
791 @menu
|
|
|
792 * Event Types:: Events come in different types.
|
|
|
793 * Event Contents:: What the contents of each event type are.
|
|
|
794 * Event Predicates:: Querying whether an event is of a
|
|
|
795 particular type.
|
|
|
796 * Accessing Mouse Event Positions::
|
|
|
797 Determining where a mouse event occurred,
|
|
|
798 and over what.
|
|
|
799 * Accessing Other Event Info:: Accessing non-positional event info.
|
|
|
800 * Working With Events:: Creating, copying, and destroying events.
|
|
|
801 * Converting Events:: Converting between events, keys, and
|
|
|
802 characters.
|
|
|
803 @end menu
|
|
|
804
|
|
|
805 @node Event Types
|
|
|
806 @subsection Event Types
|
|
|
807
|
|
|
808 Events represent keyboard or mouse activity or status changes of various
|
|
|
809 sorts, such as process input being available or a timeout being triggered.
|
|
|
810 The different event types are as follows:
|
|
|
811
|
|
|
812 @table @asis
|
|
|
813 @item key-press event
|
|
|
814 A key was pressed. Note that modifier keys such as ``control'', ``shift'',
|
|
|
815 and ``alt'' do not generate events; instead, they are tracked internally
|
|
|
816 by XEmacs, and non-modifier key presses generate events that specify both
|
|
|
817 the key pressed and the modifiers that were held down at the time.
|
|
|
818
|
|
|
819 @item button-press event
|
|
|
820 @itemx button-release event
|
|
|
821 A button was pressed or released. Along with the button that was pressed
|
|
|
822 or released, button events specify the modifier keys that were held down
|
|
|
823 at the time and the position of the pointer at the time.
|
|
|
824
|
|
54
|
825 @item motion event
|
|
0
|
826 The pointer was moved. Along with the position of the pointer, these events
|
|
|
827 also specify the modifier keys that were held down at the time.
|
|
|
828
|
|
|
829 @item misc-user event
|
|
|
830 A menu item was selected, or the scrollbar was used.
|
|
|
831
|
|
|
832 @item process event
|
|
|
833 Input is available on a process.
|
|
|
834
|
|
|
835 @item timeout event
|
|
|
836 A timeout has triggered.
|
|
|
837
|
|
|
838 @item magic event
|
|
|
839 Some window-system-specific action (such as a frame being resized or
|
|
|
840 a portion of a frame needing to be redrawn) has occurred. The contents
|
|
|
841 of this event are not accessible at the E-Lisp level, but
|
|
|
842 @code{dispatch-event} knows what to do with an event of this type.
|
|
|
843
|
|
|
844 @item eval event
|
|
|
845 This is a special kind of event specifying that a particular function
|
|
|
846 needs to be called when this event is dispatched. An event of this type
|
|
|
847 is sometimes placed in the event queue when a magic event is processed.
|
|
|
848 This kind of event should generally just be passed off to
|
|
|
849 @code{dispatch-event}. @xref{Dispatching an Event}.
|
|
|
850 @end table
|
|
|
851
|
|
|
852 @node Event Contents
|
|
|
853 @subsection Contents of the Different Types of Events
|
|
|
854
|
|
|
855 Every event, no matter what type it is, contains a timestamp (which is
|
|
|
856 typically an offset in milliseconds from when the X server was started)
|
|
|
857 indicating when the event occurred. In addition, many events contain
|
|
|
858 a @dfn{channel}, which specifies which frame the event occurred on,
|
|
|
859 and/or a value indicating which modifier keys (shift, control, etc.)
|
|
|
860 were held down at the time of the event.
|
|
|
861
|
|
|
862 The contents of each event are as follows:
|
|
|
863
|
|
|
864 @table @asis
|
|
|
865 @item key-press event
|
|
|
866 @table @asis
|
|
|
867 @item channel
|
|
|
868 @item timestamp
|
|
|
869 @item key
|
|
|
870 Which key was pressed. This is an integer (in the printing @sc{ASCII}
|
|
|
871 range: >32 and <127) or a symbol such as @code{left} or @code{right}.
|
|
|
872 Note that many physical keys are actually treated as two separate keys,
|
|
|
873 depending on whether the shift key is pressed; for example, the ``a''
|
|
|
874 key is treated as either ``a'' or ``A'' depending on the state of the
|
|
|
875 shift key, and the ``1'' key is similarly treated as either ``1'' or
|
|
|
876 ``!'' on most keyboards. In such cases, the shift key does not show up
|
|
|
877 in the modifier list. For other keys, such as @code{backspace}, the
|
|
|
878 shift key shows up as a regular modifier.
|
|
|
879 @item modifiers
|
|
|
880 Which modifier keys were pressed. As mentioned above, the shift key
|
|
|
881 is not treated as a modifier for many keys and will not show up in this list
|
|
|
882 in such cases.
|
|
|
883 @end table
|
|
|
884
|
|
|
885 @item button-press event
|
|
|
886 @itemx button-release event
|
|
|
887 @table @asis
|
|
|
888 @item channel
|
|
|
889 @item timestamp
|
|
|
890 @item button
|
|
|
891 What button went down or up. Buttons are numbered starting at 1.
|
|
|
892 @item modifiers
|
|
|
893 Which modifier keys were pressed. The special business mentioned above
|
|
|
894 for the shift key does @emph{not} apply to mouse events.
|
|
|
895 @item x
|
|
|
896 @itemx y
|
|
|
897 The position of the pointer (in pixels) at the time of the event.
|
|
|
898 @end table
|
|
|
899
|
|
|
900 @item pointer-motion event
|
|
|
901 @table @asis
|
|
|
902 @item channel
|
|
|
903 @item timestamp
|
|
|
904 @item x
|
|
|
905 @itemx y
|
|
|
906 The position of the pointer (in pixels) after it moved.
|
|
|
907 @item modifiers
|
|
|
908 Which modifier keys were pressed. The special business mentioned above
|
|
|
909 for the shift key does @emph{not} apply to mouse events.
|
|
|
910 @end table
|
|
|
911
|
|
|
912 @item misc-user event
|
|
|
913 @table @asis
|
|
|
914 @item timestamp
|
|
|
915 @item function
|
|
|
916 The E-Lisp function to call for this event. This is normally either
|
|
|
917 @code{eval} or @code{call-interactively}.
|
|
|
918 @item object
|
|
|
919 The object to pass to the function. This is normally the callback that
|
|
|
920 was specified in the menu description.
|
|
|
921 @end table
|
|
|
922
|
|
|
923 @item process_event
|
|
|
924 @table @asis
|
|
|
925 @item timestamp
|
|
|
926 @item process
|
|
|
927 The Emacs ``process'' object in question.
|
|
|
928 @end table
|
|
|
929
|
|
|
930 @item timeout event
|
|
|
931 @table @asis
|
|
|
932 @item timestamp
|
|
|
933 @item function
|
|
|
934 The E-Lisp function to call for this timeout. It is called with one
|
|
|
935 argument, the event.
|
|
|
936 @item object
|
|
|
937 Some Lisp object associated with this timeout, to make it easier to tell
|
|
|
938 them apart. The function and object for this event were specified when
|
|
|
939 the timeout was set.
|
|
|
940 @end table
|
|
|
941
|
|
|
942 @item magic event
|
|
|
943 @table @asis
|
|
|
944 @item timestamp
|
|
|
945 @end table
|
|
|
946 (The rest of the information in this event is not user-accessible.)
|
|
|
947
|
|
|
948 @item eval event
|
|
|
949 @table @asis
|
|
|
950 @item timestamp
|
|
|
951 @item function
|
|
|
952 An E-Lisp function to call when this event is dispatched.
|
|
|
953 @item object
|
|
|
954 The object to pass to the function. The function and object are set
|
|
|
955 when the event is created.
|
|
|
956 @end table
|
|
|
957 @end table
|
|
|
958
|
|
54
|
959 @defun event-type event
|
|
|
960 Return the type of @var{event}.
|
|
|
961
|
|
|
962 This will be a symbol; one of
|
|
|
963
|
|
|
964 @table @code
|
|
|
965 @item key-press
|
|
|
966 A key was pressed.
|
|
|
967 @item button-press
|
|
|
968 A mouse button was pressed.
|
|
|
969 @item button-release
|
|
|
970 A mouse button was released.
|
|
|
971 @item motion
|
|
|
972 The mouse moved.
|
|
|
973 @item misc-user
|
|
|
974 Some other user action happened; typically, this is
|
|
|
975 a menu selection or scrollbar action.
|
|
|
976 @item process
|
|
|
977 Input is available from a subprocess.
|
|
|
978 @item timeout
|
|
|
979 A timeout has expired.
|
|
|
980 @item eval
|
|
|
981 This causes a specified action to occur when dispatched.
|
|
|
982 @item magic
|
|
|
983 Some window-system-specific event has occurred.
|
|
|
984 @end table
|
|
|
985 @end defun
|
|
|
986
|
|
0
|
987 @node Event Predicates
|
|
|
988 @subsection Event Predicates
|
|
|
989
|
|
54
|
990 The following predicates return whether an object is an event of a
|
|
|
991 particular type.
|
|
0
|
992
|
|
|
993 @defun key-press-event-p object
|
|
|
994 This is true if @var{object} is a key-press event.
|
|
|
995 @end defun
|
|
|
996
|
|
54
|
997 @defun button-event-p object object
|
|
|
998 This is true if @var{object} is a mouse button-press or button-release
|
|
|
999 event.
|
|
|
1000 @end defun
|
|
|
1001
|
|
|
1002 @defun button-press-event-p object
|
|
|
1003 This is true if @var{object} is a mouse button-press event.
|
|
|
1004 @end defun
|
|
|
1005
|
|
|
1006 @defun button-release-event-p object
|
|
|
1007 This is true if @var{object} is a mouse button-release event.
|
|
0
|
1008 @end defun
|
|
|
1009
|
|
|
1010 @defun motion-event-p object
|
|
54
|
1011 This is true if @var{object} is a mouse motion event.
|
|
|
1012 @end defun
|
|
|
1013
|
|
|
1014 @defun mouse-event-p object
|
|
|
1015 This is true if @var{object} is a mouse button-press, button-release
|
|
|
1016 or motion event.
|
|
|
1017 @end defun
|
|
|
1018
|
|
|
1019 @defun eval-event-p object
|
|
|
1020 This is true if @var{object} is an eval event.
|
|
|
1021 @end defun
|
|
|
1022
|
|
|
1023 @defun misc-user-event-p object
|
|
|
1024 This is true if @var{object} is a misc-user event.
|
|
0
|
1025 @end defun
|
|
|
1026
|
|
|
1027 @defun process-event-p object
|
|
|
1028 This is true if @var{object} is a process event.
|
|
|
1029 @end defun
|
|
|
1030
|
|
|
1031 @defun timeout-event-p object
|
|
|
1032 This is true if @var{object} is a timeout event.
|
|
|
1033 @end defun
|
|
|
1034
|
|
|
1035 @defun event-live-p object
|
|
|
1036 This is true if @var{object} is any event that has not been deallocated.
|
|
|
1037 @end defun
|
|
|
1038
|
|
|
1039 @node Accessing Mouse Event Positions
|
|
|
1040 @subsection Accessing the Position of a Mouse Event
|
|
|
1041
|
|
54
|
1042 Unlike other events, mouse events (i.e. motion, button-press, and
|
|
0
|
1043 button-release events) occur in a particular location on the screen.
|
|
|
1044 Many primitives are provided for determining exactly where the event
|
|
|
1045 occurred and what is under that location.
|
|
|
1046
|
|
|
1047 @menu
|
|
|
1048 * Frame-Level Event Position Info::
|
|
|
1049 * Window-Level Event Position Info::
|
|
|
1050 * Event Text Position Info::
|
|
|
1051 * Event Glyph Position Info::
|
|
|
1052 * Event Toolbar Position Info::
|
|
|
1053 * Other Event Position Info::
|
|
|
1054 @end menu
|
|
|
1055
|
|
|
1056 @node Frame-Level Event Position Info
|
|
|
1057 @subsubsection Frame-Level Event Position Info
|
|
|
1058
|
|
|
1059 The following functions return frame-level information about where
|
|
|
1060 a mouse event occurred.
|
|
|
1061
|
|
|
1062 @defun event-frame event
|
|
|
1063 This function returns the ``channel'' or frame that the given mouse
|
|
|
1064 motion, button press, or button release event occurred in. This will be
|
|
|
1065 @code{nil} for non-mouse events.
|
|
|
1066 @end defun
|
|
|
1067
|
|
|
1068 @defun event-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 frame the event occurred in.
|
|
54
|
1071 This will signal an error if the event is not a mouse event.
|
|
0
|
1072 @end defun
|
|
|
1073
|
|
|
1074 @defun event-y-pixel event
|
|
|
1075 This function returns the Y position in pixels of the given mouse event.
|
|
|
1076 The value returned is relative to the frame the event occurred in.
|
|
54
|
1077 This will signal an error if the event is not a mouse event.
|
|
0
|
1078 @end defun
|
|
|
1079
|
|
|
1080 @node Window-Level Event Position Info
|
|
|
1081 @subsubsection Window-Level Event Position Info
|
|
|
1082
|
|
|
1083 The following functions return window-level information about where
|
|
|
1084 a mouse event occurred.
|
|
|
1085
|
|
|
1086 @defun event-window event
|
|
|
1087 Given a mouse motion, button press, or button release event, compute and
|
|
|
1088 return the window on which that event occurred. This may be @code{nil}
|
|
|
1089 if the event occurred in the border or over a toolbar. The modeline is
|
|
54
|
1090 considered to be within the window it describes.
|
|
0
|
1091 @end defun
|
|
|
1092
|
|
|
1093 @defun event-buffer event
|
|
|
1094 Given a mouse motion, button press, or button release event, compute and
|
|
|
1095 return the buffer of the window on which that event occurred. This may
|
|
|
1096 be @code{nil} if the event occurred in the border or over a toolbar.
|
|
54
|
1097 The modeline is considered to be within the window it describes. This is
|
|
0
|
1098 equivalent to calling @code{event-window} and then calling
|
|
54
|
1099 @code{window-buffer} on the result if it is a window.
|
|
0
|
1100 @end defun
|
|
|
1101
|
|
|
1102 @defun event-window-x-pixel event
|
|
|
1103 This function returns the X position in pixels of the given mouse event.
|
|
|
1104 The value returned is relative to the window the event occurred in.
|
|
|
1105 This will signal an error if the event is not a mouse-motion, button-press,
|
|
|
1106 or button-release event.
|
|
|
1107 @end defun
|
|
|
1108
|
|
|
1109 @defun event-window-y-pixel event
|
|
|
1110 This function returns the Y position in pixels of the given mouse event.
|
|
|
1111 The value returned is relative to the window the event occurred in.
|
|
|
1112 This will signal an error if the event is not a mouse-motion, button-press,
|
|
|
1113 or button-release event.
|
|
|
1114 @end defun
|
|
|
1115
|
|
|
1116 @node Event Text Position Info
|
|
|
1117 @subsubsection Event Text Position Info
|
|
|
1118
|
|
|
1119 The following functions return information about the text (including the
|
|
|
1120 modeline) that a mouse event occurred over or near.
|
|
|
1121
|
|
|
1122 @defun event-over-text-area-p event
|
|
|
1123 Given a mouse-motion, button-press, or button-release event, this
|
|
2
|
1124 function returns @code{t} if the event is over the text area of a
|
|
0
|
1125 window. Otherwise, @code{nil} is returned. The modeline is not
|
|
|
1126 considered to be part of the text area.
|
|
|
1127 @end defun
|
|
|
1128
|
|
|
1129 @defun event-over-modeline-p event
|
|
|
1130 Given a mouse-motion, button-press, or button-release event, this
|
|
|
1131 function returns @code{t} if the event is over the modeline of a window.
|
|
|
1132 Otherwise, @code{nil} is returned.
|
|
|
1133 @end defun
|
|
|
1134
|
|
|
1135 @defun event-x event
|
|
|
1136 This function returns the X position of the given mouse-motion,
|
|
|
1137 button-press, or button-release event in characters. This is relative
|
|
|
1138 to the window the event occurred over.
|
|
|
1139 @end defun
|
|
|
1140
|
|
|
1141 @defun event-y event
|
|
|
1142 This function returns the Y position of the given mouse-motion,
|
|
|
1143 button-press, or button-release event in characters. This is relative
|
|
|
1144 to the window the event occurred over.
|
|
|
1145 @end defun
|
|
|
1146
|
|
|
1147 @defun event-point event
|
|
|
1148 This function returns the character position of the given mouse-motion,
|
|
|
1149 button-press, or button-release event. If the event did not occur over
|
|
|
1150 a window, or did not occur over text, then this returns @code{nil}.
|
|
|
1151 Otherwise, it returns an index into the buffer visible in the event's
|
|
|
1152 window.
|
|
|
1153 @end defun
|
|
|
1154
|
|
|
1155 @defun event-closest-point event
|
|
|
1156 This function returns the character position of the given mouse-motion,
|
|
|
1157 button-press, or button-release event. If the event did not occur over
|
|
|
1158 a window or over text, it returns the closest point to the location of
|
|
|
1159 the event. If the Y pixel position overlaps a window and the X pixel
|
|
|
1160 position is to the left of that window, the closest point is the
|
|
|
1161 beginning of the line containing the Y position. If the Y pixel
|
|
|
1162 position overlaps a window and the X pixel position is to the right of
|
|
|
1163 that window, the closest point is the end of the line containing the Y
|
|
|
1164 position. If the Y pixel position is above a window, 0 is returned. If
|
|
|
1165 it is below a window, the value of @code{(window-end)} is returned.
|
|
|
1166 @end defun
|
|
|
1167
|
|
|
1168 @node Event Glyph Position Info
|
|
|
1169 @subsubsection Event Glyph Position Info
|
|
|
1170
|
|
|
1171 The following functions return information about the glyph (if any) that
|
|
|
1172 a mouse event occurred over.
|
|
|
1173
|
|
|
1174 @defun event-over-glyph-p event
|
|
|
1175 Given a mouse-motion, button-press, or button-release event, this
|
|
|
1176 function returns @code{t} if the event is over a glyph. Otherwise,
|
|
|
1177 @code{nil} is returned.
|
|
|
1178 @end defun
|
|
|
1179
|
|
|
1180 @defun event-glyph-extent event
|
|
|
1181 If the given mouse-motion, button-press, or button-release event happened
|
|
|
1182 on top of a glyph, this returns its extent; else @code{nil} is returned.
|
|
|
1183 @end defun
|
|
|
1184
|
|
|
1185 @defun event-glyph-x-pixel event
|
|
|
1186 Given a mouse-motion, button-press, or button-release event over a
|
|
|
1187 glyph, this function returns the X position of the pointer relative to
|
|
|
1188 the upper left of the glyph. If the event is not over a glyph, it returns
|
|
|
1189 @code{nil}.
|
|
|
1190 @end defun
|
|
|
1191
|
|
|
1192 @defun event-glyph-y-pixel event
|
|
|
1193 Given a mouse-motion, button-press, or button-release event over a
|
|
|
1194 glyph, this function returns the Y position of the pointer relative to
|
|
|
1195 the upper left of the glyph. If the event is not over a glyph, it returns
|
|
|
1196 @code{nil}.
|
|
|
1197 @end defun
|
|
|
1198
|
|
|
1199 @node Event Toolbar Position Info
|
|
|
1200 @subsubsection Event Toolbar Position Info
|
|
|
1201
|
|
|
1202 @defun event-over-toolbar-p event
|
|
|
1203 Given a mouse-motion, button-press, or button-release event, this
|
|
|
1204 function returns @code{t} if the event is over a toolbar. Otherwise,
|
|
|
1205 @code{nil} is returned.
|
|
|
1206 @end defun
|
|
|
1207
|
|
|
1208 @defun event-toolbar-button event
|
|
|
1209 If the given mouse-motion, button-press, or button-release event
|
|
|
1210 happened on top of a toolbar button, this function returns the button.
|
|
|
1211 Otherwise, @code{nil} is returned.
|
|
|
1212 @end defun
|
|
|
1213
|
|
|
1214 @node Other Event Position Info
|
|
|
1215 @subsubsection Other Event Position Info
|
|
|
1216
|
|
|
1217 @defun event-over-border-p event
|
|
|
1218 Given a mouse-motion, button-press, or button-release event, this
|
|
|
1219 function returns @code{t} if the event is over an internal toolbar.
|
|
|
1220 Otherwise, @code{nil} is returned.
|
|
|
1221 @end defun
|
|
|
1222
|
|
|
1223 @node Accessing Other Event Info
|
|
|
1224 @subsection Accessing the Other Contents of Events
|
|
|
1225
|
|
|
1226 The following functions allow access to the contents of events other than
|
|
|
1227 the position info described in the previous section.
|
|
|
1228
|
|
|
1229 @defun event-timestamp event
|
|
|
1230 This function returns the timestamp of the given event object.
|
|
|
1231 @end defun
|
|
|
1232
|
|
|
1233 @defun event-device event
|
|
|
1234 This function returns the device that the given event occurred on.
|
|
|
1235 @end defun
|
|
|
1236
|
|
|
1237 @defun event-key event
|
|
|
1238 This function returns the Keysym of the given key-press event.
|
|
|
1239 This will be the @sc{ASCII} code of a printing character, or a symbol.
|
|
|
1240 @end defun
|
|
|
1241
|
|
|
1242 @defun event-button event
|
|
54
|
1243 This function returns the button-number of the given button-press or
|
|
|
1244 button-release event.
|
|
0
|
1245 @end defun
|
|
|
1246
|
|
|
1247 @defun event-modifiers event
|
|
|
1248 This function returns a list of symbols, the names of the modifier keys
|
|
|
1249 which were down when the given mouse or keyboard event was produced.
|
|
|
1250 @end defun
|
|
|
1251
|
|
|
1252 @defun event-modifier-bits event
|
|
|
1253 This function returns a number representing the modifier keys which were down
|
|
|
1254 when the given mouse or keyboard event was produced.
|
|
|
1255 @end defun
|
|
|
1256
|
|
|
1257 @defun event-function event
|
|
|
1258 This function returns the callback function of the given timeout, misc-user,
|
|
|
1259 or eval event.
|
|
|
1260 @end defun
|
|
|
1261
|
|
|
1262 @defun event-object event
|
|
|
1263 This function returns the callback function argument of the given timeout,
|
|
|
1264 misc-user, or eval event.
|
|
|
1265 @end defun
|
|
|
1266
|
|
|
1267 @defun event-process event
|
|
|
1268 This function returns the process of the given process event.
|
|
|
1269 @end defun
|
|
|
1270
|
|
|
1271 @node Working With Events
|
|
|
1272 @subsection Working With Events
|
|
|
1273
|
|
|
1274 XEmacs provides primitives for creating, copying, and destroying event
|
|
|
1275 objects. Many functions that return events take an event object as an
|
|
|
1276 argument and fill in the fields of this event; or they make accept
|
|
|
1277 either an event object or @code{nil}, creating the event object first in
|
|
|
1278 the latter case.
|
|
|
1279
|
|
|
1280 @defun allocate-event
|
|
|
1281 This function returns an empty event structure. WARNING: The event
|
|
|
1282 object returned may be a reused one; see the function
|
|
|
1283 @code{deallocate-event}.
|
|
|
1284 @end defun
|
|
|
1285
|
|
|
1286 @defun copy-event event1 &optional event2
|
|
|
1287 This function makes a copy of the given event object. If a second
|
|
|
1288 argument is given, the first event is copied into the second and the
|
|
|
1289 second is returned. If the second argument is not supplied (or is
|
|
|
1290 @code{nil}) then a new event will be made as with @code{allocate-event}.
|
|
|
1291 @end defun
|
|
|
1292
|
|
|
1293 @defun deallocate-event event
|
|
|
1294 This function allows the given event structure to be reused. You
|
|
|
1295 @strong{MUST NOT} use this event object after calling this function with
|
|
|
1296 it. You will lose. It is not necessary to call this function, as event
|
|
|
1297 objects are garbage-collected like all other objects; however, it may be
|
|
|
1298 more efficient to explicitly deallocate events when you are sure that
|
|
|
1299 that is safe.
|
|
|
1300 @end defun
|
|
|
1301
|
|
|
1302 @node Converting Events
|
|
|
1303 @subsection Converting Events
|
|
|
1304
|
|
|
1305 XEmacs provides some auxiliary functions for converting between events
|
|
|
1306 and other ways of representing keys. These are useful when working with
|
|
|
1307 @sc{ASCII} strings and with keymaps.
|
|
|
1308
|
|
|
1309 @defun character-to-event ch &optional event device
|
|
|
1310 This function converts a numeric @sc{ASCII} value to an event structure,
|
|
|
1311 replete with modifier bits. @var{ch} is the character to convert, and
|
|
|
1312 @var{event} is the event object to fill in. This function contains
|
|
|
1313 knowledge about what the codes ``mean'' -- for example, the number 9 is
|
|
|
1314 converted to the character @key{Tab}, not the distinct character
|
|
|
1315 @key{Control-I}.
|
|
|
1316
|
|
|
1317 Note that @var{ch} does not have to be a numeric value, but can be a
|
|
|
1318 symbol such as @code{clear} or a list such as @code{(control
|
|
|
1319 backspace)}.
|
|
|
1320
|
|
|
1321 If @code{event} is not @code{nil}, it is modified; otherwise, a
|
|
|
1322 new event object is created. In both cases, the event is returned.
|
|
|
1323
|
|
|
1324 Optional third arg @var{device} is the device to store in the event;
|
|
|
1325 this also affects whether the high bit is interpreted as a meta key. A
|
|
|
1326 value of @code{nil} means use the selected device but always treat the
|
|
|
1327 high bit as meta.
|
|
|
1328
|
|
|
1329 Beware that @code{character-to-event} and @code{event-to-character} are
|
|
|
1330 not strictly inverse functions, since events contain much more
|
|
|
1331 information than the @sc{ASCII} character set can encode.
|
|
|
1332 @end defun
|
|
|
1333
|
|
|
1334 @defun event-to-character event &optional allow-extra-modifiers allow-meta allow-non-ascii
|
|
|
1335 This function returns the closest @sc{ASCII} approximation to
|
|
|
1336 @var{event}. If the event isn't a keypress, this returns @code{nil}.
|
|
|
1337
|
|
|
1338 If @var{allow-extra-modifiers} is non-@code{nil}, then this is lenient
|
|
|
1339 in its translation; it will ignore modifier keys other than
|
|
|
1340 @key{control} and @key{meta}, and will ignore the @key{shift} modifier
|
|
|
1341 on those characters which have no shifted @sc{ASCII} equivalent
|
|
|
1342 (@key{Control-Shift-A} for example, will be mapped to the same
|
|
|
1343 @sc{ASCII} code as @key{Control-A}).
|
|
|
1344
|
|
|
1345 If @var{allow-meta} is non-@code{nil}, then the @key{Meta} modifier will
|
|
|
1346 be represented by turning on the high bit of the byte returned;
|
|
|
1347 otherwise, @code{nil} will be returned for events containing the
|
|
|
1348 @key{Meta} modifier.
|
|
|
1349
|
|
|
1350 If @var{allow-non-ascii} is non-@code{nil}, then characters which are
|
|
|
1351 present in the prevailing character set (@pxref{Keymaps, variable
|
|
|
1352 @code{character-set-property}}) will be returned as their code in that
|
|
|
1353 character set, instead of the return value being restricted to
|
|
|
1354 @sc{ASCII}.
|
|
|
1355
|
|
|
1356 Note that specifying both @var{allow-meta} and @var{allow-non-ascii} is
|
|
|
1357 ambiguous, as both use the high bit; @key{M-x} and @key{oslash} will be
|
|
|
1358 indistinguishable.
|
|
|
1359 @end defun
|
|
|
1360
|
|
|
1361 @defun events-to-keys events &optional no-mice
|
|
|
1362 Given a vector of event objects, this function returns a vector of key
|
|
|
1363 descriptors, or a string (if they all fit in the @sc{ASCII} range).
|
|
|
1364 Optional arg @var{no-mice} means that button events are not allowed.
|
|
|
1365 @end defun
|
|
|
1366
|
|
|
1367 @node Reading Input
|
|
|
1368 @section Reading Input
|
|
|
1369
|
|
|
1370 The editor command loop reads keyboard input using the function
|
|
|
1371 @code{next-event} and constructs key sequences out of the events using
|
|
|
1372 @code{dispatch-event}. Lisp programs can also use the function
|
|
|
1373 @code{read-key-sequence}, which reads input a key sequence at a time.
|
|
|
1374 See also @code{momentary-string-display} in @ref{Temporary Displays},
|
|
|
1375 and @code{sit-for} in @ref{Waiting}. @xref{Terminal Input}, for
|
|
|
1376 functions and variables for controlling terminal input modes and
|
|
|
1377 debugging terminal input.
|
|
|
1378
|
|
|
1379 For higher-level input facilities, see @ref{Minibuffers}.
|
|
|
1380
|
|
|
1381 @menu
|
|
|
1382 * Key Sequence Input:: How to read one key sequence.
|
|
|
1383 * Reading One Event:: How to read just one event.
|
|
|
1384 * Dispatching an Event:: What to do with an event once it has been read.
|
|
|
1385 * Quoted Character Input:: Asking the user to specify a character.
|
|
|
1386 * Peeking and Discarding:: How to reread or throw away input events.
|
|
|
1387 @end menu
|
|
|
1388
|
|
|
1389 @node Key Sequence Input
|
|
|
1390 @subsection Key Sequence Input
|
|
|
1391 @cindex key sequence input
|
|
|
1392
|
|
|
1393 Lisp programs can read input a key sequence at a time by calling
|
|
|
1394 @code{read-key-sequence}; for example, @code{describe-key} uses it to
|
|
|
1395 read the key to describe.
|
|
|
1396
|
|
|
1397 @defun read-key-sequence prompt
|
|
|
1398 @cindex key sequence
|
|
|
1399 This function reads a sequence of keystrokes or mouse clicks and returns
|
|
|
1400 it as a vector of events. It keeps reading events until it has
|
|
|
1401 accumulated a full key sequence; that is, enough to specify a non-prefix
|
|
|
1402 command using the currently active keymaps.
|
|
|
1403
|
|
|
1404 The vector and the event objects it contains are freshly created, and
|
|
|
1405 will not be side-effected by subsequent calls to this function.
|
|
|
1406
|
|
|
1407 The function @code{read-key-sequence} suppresses quitting: @kbd{C-g}
|
|
|
1408 typed while reading with this function works like any other character,
|
|
|
1409 and does not set @code{quit-flag}. @xref{Quitting}.
|
|
|
1410
|
|
|
1411 The argument @var{prompt} is either a string to be displayed in the echo
|
|
|
1412 area as a prompt, or @code{nil}, meaning not to display a prompt.
|
|
|
1413
|
|
|
1414 @c XEmacs feature
|
|
|
1415 If the user selects a menu item while we are prompting for a key
|
|
|
1416 sequence, the returned value will be a vector of a single menu-selection
|
|
|
1417 event (a misc-user event). An error will be signalled if you pass this
|
|
|
1418 value to @code{lookup-key} or a related function.
|
|
|
1419
|
|
|
1420 In the example below, the prompt @samp{?} is displayed in the echo area,
|
|
|
1421 and the user types @kbd{C-x C-f}.
|
|
|
1422
|
|
|
1423 @example
|
|
|
1424 (read-key-sequence "?")
|
|
|
1425
|
|
|
1426 @group
|
|
|
1427 ---------- Echo Area ----------
|
|
|
1428 ?@kbd{C-x C-f}
|
|
|
1429 ---------- Echo Area ----------
|
|
|
1430
|
|
|
1431 @result{} [#<keypress-event control-X> #<keypress-event control-F>]
|
|
|
1432 @end group
|
|
|
1433 @end example
|
|
|
1434 @end defun
|
|
|
1435
|
|
|
1436 @ignore @c Not in XEmacs
|
|
|
1437 @defvar num-input-keys
|
|
|
1438 @c Emacs 19 feature
|
|
|
1439 This variable's value is the number of key sequences processed so far in
|
|
|
1440 this XEmacs session. This includes key sequences read from the terminal
|
|
|
1441 and key sequences read from keyboard macros being executed.
|
|
|
1442 @end defvar
|
|
|
1443 @end ignore
|
|
|
1444
|
|
|
1445 @cindex upper case key sequence
|
|
|
1446 @cindex downcasing in @code{lookup-key}
|
|
|
1447 If an input character is an upper-case letter and has no key binding,
|
|
|
1448 but its lower-case equivalent has one, then @code{read-key-sequence}
|
|
|
1449 converts the character to lower case. Note that @code{lookup-key} does
|
|
|
1450 not perform case conversion in this way.
|
|
|
1451
|
|
|
1452 @node Reading One Event
|
|
|
1453 @subsection Reading One Event
|
|
|
1454
|
|
|
1455 The lowest level functions for command input are those which read a
|
|
|
1456 single event. These functions often make a distinction between
|
|
|
1457 @dfn{command events}, which are user actions (keystrokes and mouse
|
|
|
1458 actions), and other events, which serve as communication between
|
|
|
1459 XEmacs and the window system.
|
|
|
1460
|
|
|
1461 @defun next-event &optional event prompt
|
|
|
1462 This function reads and returns the next available event from the window
|
|
|
1463 system or terminal driver, waiting if necessary until an event is
|
|
|
1464 available. Pass this object to @code{dispatch-event} to handle it. If
|
|
|
1465 an event object is supplied, it is filled in and returned; otherwise a
|
|
|
1466 new event object will be created.
|
|
|
1467
|
|
|
1468 Events can come directly from the user, from a keyboard macro, or from
|
|
|
1469 @code{unread-command-events}.
|
|
|
1470
|
|
|
1471 In most cases, the function @code{next-command-event} is more
|
|
|
1472 appropriate.
|
|
|
1473 @end defun
|
|
|
1474
|
|
|
1475 @defun next-command-event &optional event
|
|
|
1476 This function returns the next available ``user'' event from the window
|
|
|
1477 system or terminal driver. Pass this object to @code{dispatch-event} to
|
|
|
1478 handle it. If an event object is supplied, it is filled in and
|
|
|
1479 returned, otherwise a new event object will be created.
|
|
|
1480
|
|
|
1481 The event returned will be a keyboard, mouse press, or mouse release
|
|
|
1482 event. If there are non-command events available (mouse motion,
|
|
|
1483 sub-process output, etc) then these will be executed (with
|
|
|
1484 @code{dispatch-event}) and discarded. This function is provided as a
|
|
|
1485 convenience; it is equivalent to the Lisp code
|
|
|
1486
|
|
|
1487 @lisp
|
|
|
1488 @group
|
|
|
1489 (while (progn
|
|
|
1490 (next-event event)
|
|
|
1491 (not (or (key-press-event-p event)
|
|
|
1492 (button-press-event-p event)
|
|
|
1493 (button-release-event-p event)
|
|
|
1494 (menu-event-p event))))
|
|
|
1495 (dispatch-event event))
|
|
|
1496 @end group
|
|
|
1497 @end lisp
|
|
|
1498
|
|
|
1499 Here is what happens if you call @code{next-command-event} and then
|
|
|
1500 press the right-arrow function key:
|
|
|
1501
|
|
|
1502 @example
|
|
|
1503 @group
|
|
|
1504 (next-command-event)
|
|
|
1505 @result{} #<keypress-event right>
|
|
|
1506 @end group
|
|
|
1507 @end example
|
|
|
1508 @end defun
|
|
|
1509
|
|
|
1510 @defun read-char
|
|
|
1511 This function reads and returns a character of command input. If a
|
|
|
1512 mouse click is detected, an error is signalled. The character typed is
|
|
|
1513 returned as an @sc{ASCII} value. This function is retained for
|
|
|
1514 compatibility with Emacs 18, and is most likely the wrong thing for you
|
|
|
1515 to be using: consider using @code{next-command-event} instead.
|
|
|
1516 @end defun
|
|
|
1517
|
|
|
1518 @defun enqueue-eval-event function object
|
|
|
1519 This function adds an eval event to the back of the queue. The
|
|
|
1520 eval event will be the next event read after all pending events.
|
|
|
1521 @end defun
|
|
|
1522
|
|
|
1523 @node Dispatching an Event
|
|
|
1524 @subsection Dispatching an Event
|
|
|
1525 @cindex dispatching an event
|
|
|
1526
|
|
|
1527 @defun dispatch-event event
|
|
|
1528 Given an event object returned by @code{next-event}, this function
|
|
|
1529 executes it. This is the basic function that makes XEmacs respond to
|
|
|
1530 user input; it also deals with notifications from the window system
|
|
|
1531 (such as Expose events).
|
|
|
1532 @end defun
|
|
|
1533
|
|
|
1534 @node Quoted Character Input
|
|
|
1535 @subsection Quoted Character Input
|
|
|
1536 @cindex quoted character input
|
|
|
1537
|
|
|
1538 You can use the function @code{read-quoted-char} to ask the user to
|
|
|
1539 specify a character, and allow the user to specify a control or meta
|
|
|
1540 character conveniently, either literally or as an octal character code.
|
|
|
1541 The command @code{quoted-insert} uses this function.
|
|
|
1542
|
|
|
1543 @defun read-quoted-char &optional prompt
|
|
|
1544 @cindex octal character input
|
|
|
1545 @cindex control characters, reading
|
|
|
1546 @cindex nonprinting characters, reading
|
|
|
1547 This function is like @code{read-char}, except that if the first
|
|
|
1548 character read is an octal digit (0-7), it reads up to two more octal digits
|
|
|
1549 (but stopping if a non-octal digit is found) and returns the
|
|
|
1550 character represented by those digits in octal.
|
|
|
1551
|
|
|
1552 Quitting is suppressed when the first character is read, so that the
|
|
|
1553 user can enter a @kbd{C-g}. @xref{Quitting}.
|
|
|
1554
|
|
|
1555 If @var{prompt} is supplied, it specifies a string for prompting the
|
|
|
1556 user. The prompt string is always displayed in the echo area, followed
|
|
|
1557 by a single @samp{-}.
|
|
|
1558
|
|
|
1559 In the following example, the user types in the octal number 177 (which
|
|
|
1560 is 127 in decimal).
|
|
|
1561
|
|
|
1562 @example
|
|
|
1563 (read-quoted-char "What character")
|
|
|
1564
|
|
|
1565 @group
|
|
|
1566 ---------- Echo Area ----------
|
|
|
1567 What character-@kbd{177}
|
|
|
1568 ---------- Echo Area ----------
|
|
|
1569
|
|
|
1570 @result{} 127
|
|
|
1571 @end group
|
|
|
1572 @end example
|
|
|
1573 @end defun
|
|
|
1574
|
|
|
1575 @need 2000
|
|
|
1576 @node Peeking and Discarding
|
|
|
1577 @subsection Miscellaneous Event Input Features
|
|
|
1578
|
|
|
1579 This section describes how to ``peek ahead'' at events without using
|
|
|
1580 them up, how to check for pending input, and how to discard pending
|
|
|
1581 input.
|
|
|
1582
|
|
|
1583 See also the variables @code{last-command-event} and @code{last-command-char}
|
|
|
1584 (@ref{Command Loop Info}).
|
|
|
1585
|
|
|
1586 @defvar unread-command-events
|
|
|
1587 @cindex next input
|
|
|
1588 @cindex peeking at input
|
|
|
1589 This variable holds a list of events waiting to be read as command
|
|
|
1590 input. The events are used in the order they appear in the list, and
|
|
|
1591 removed one by one as they are used.
|
|
|
1592
|
|
|
1593 The variable is needed because in some cases a function reads a event
|
|
|
1594 and then decides not to use it. Storing the event in this variable
|
|
|
1595 causes it to be processed normally, by the command loop or by the
|
|
|
1596 functions to read command input.
|
|
|
1597
|
|
|
1598 @cindex prefix argument unreading
|
|
|
1599 For example, the function that implements numeric prefix arguments reads
|
|
|
1600 any number of digits. When it finds a non-digit event, it must unread
|
|
|
1601 the event so that it can be read normally by the command loop.
|
|
|
1602 Likewise, incremental search uses this feature to unread events with no
|
|
|
1603 special meaning in a search, because these events should exit the search
|
|
|
1604 and then execute normally.
|
|
|
1605
|
|
|
1606 @ignore FSF Emacs stuff
|
|
|
1607 The reliable and easy way to extract events from a key sequence so as to
|
|
|
1608 put them in @code{unread-command-events} is to use
|
|
|
1609 @code{listify-key-sequence} (@pxref{Strings of Events}).
|
|
|
1610 @end ignore
|
|
|
1611 @end defvar
|
|
|
1612
|
|
|
1613 @defvar unread-command-event
|
|
|
1614 This variable holds a single event to be read as command input.
|
|
|
1615
|
|
|
1616 This variable is mostly obsolete now that you can use
|
|
|
1617 @code{unread-command-events} instead; it exists only to support programs
|
|
|
1618 written for versions of XEmacs prior to 19.12.
|
|
|
1619 @end defvar
|
|
|
1620
|
|
|
1621 @defun input-pending-p
|
|
|
1622 @cindex waiting for command key input
|
|
|
1623 This function determines whether any command input is currently
|
|
|
1624 available to be read. It returns immediately, with value @code{t} if
|
|
|
1625 there is available input, @code{nil} otherwise. On rare occasions it
|
|
|
1626 may return @code{t} when no input is available.
|
|
|
1627 @end defun
|
|
|
1628
|
|
|
1629 @defvar last-input-event
|
|
|
1630 This variable is set to the last keyboard or mouse button event received.
|
|
|
1631
|
|
|
1632 This variable is off limits: you may not set its value or modify the
|
|
|
1633 event that is its value, as it is destructively modified by
|
|
|
1634 @code{read-key-sequence}. If you want to keep a pointer to this value,
|
|
|
1635 you must use @code{copy-event}.
|
|
|
1636
|
|
|
1637 Note that this variable is an alias for @code{last-input-char} in
|
|
|
1638 FSF Emacs.
|
|
|
1639
|
|
|
1640 In the example below, a character is read (the character @kbd{1}). It
|
|
|
1641 becomes the value of @code{last-input-event}, while @kbd{C-e} (from the
|
|
|
1642 @kbd{C-x C-e} command used to evaluate this expression) remains the
|
|
|
1643 value of @code{last-command-event}.
|
|
|
1644
|
|
|
1645 @example
|
|
|
1646 @group
|
|
|
1647 (progn (print (next-command-event))
|
|
|
1648 (print last-command-event)
|
|
|
1649 last-input-event)
|
|
|
1650 @print{} #<keypress-event 1>
|
|
|
1651 @print{} #<keypress-event control-E>
|
|
|
1652 @result{} #<keypress-event 1>
|
|
|
1653
|
|
|
1654 @end group
|
|
|
1655 @end example
|
|
|
1656 @end defvar
|
|
|
1657
|
|
|
1658 @defvar last-input-char
|
|
|
1659 If the value of @code{last-input-event} is a keyboard event, then this
|
|
|
1660 is the nearest @sc{ASCII} equivalent to it. Remember that there is
|
|
|
1661 @emph{not} a 1:1 mapping between keyboard events and @sc{ASCII}
|
|
|
1662 characters: the set of keyboard events is much larger, so writing code
|
|
|
1663 that examines this variable to determine what key has been typed is bad
|
|
|
1664 practice, unless you are certain that it will be one of a small set of
|
|
|
1665 characters.
|
|
|
1666
|
|
|
1667 This function exists for compatibility with Emacs version 18.
|
|
|
1668 @end defvar
|
|
|
1669
|
|
|
1670 @defun discard-input
|
|
|
1671 @cindex flush input
|
|
|
1672 @cindex discard input
|
|
|
1673 @cindex terminate keyboard macro
|
|
|
1674 This function discards the contents of the terminal input buffer and
|
|
|
1675 cancels any keyboard macro that might be in the process of definition.
|
|
|
1676 It returns @code{nil}.
|
|
|
1677
|
|
|
1678 In the following example, the user may type a number of characters right
|
|
|
1679 after starting the evaluation of the form. After the @code{sleep-for}
|
|
|
1680 finishes sleeping, @code{discard-input} discards any characters typed
|
|
|
1681 during the sleep.
|
|
|
1682
|
|
|
1683 @example
|
|
|
1684 (progn (sleep-for 2)
|
|
|
1685 (discard-input))
|
|
|
1686 @result{} nil
|
|
|
1687 @end example
|
|
|
1688 @end defun
|
|
|
1689
|
|
|
1690 @node Waiting
|
|
|
1691 @section Waiting for Elapsed Time or Input
|
|
|
1692 @cindex pausing
|
|
|
1693 @cindex waiting
|
|
|
1694
|
|
|
1695 The wait functions are designed to wait for a certain amount of time
|
|
|
1696 to pass or until there is input. For example, you may wish to pause in
|
|
|
1697 the middle of a computation to allow the user time to view the display.
|
|
|
1698 @code{sit-for} pauses and updates the screen, and returns immediately if
|
|
|
1699 input comes in, while @code{sleep-for} pauses without updating the
|
|
|
1700 screen.
|
|
|
1701
|
|
|
1702 Note that in FSF Emacs, the commands @code{sit-for} and @code{sleep-for}
|
|
|
1703 take two arguments to specify the time (one integer and one float
|
|
|
1704 value), instead of a single argument that can be either an integer or a
|
|
|
1705 float.
|
|
|
1706
|
|
|
1707 @defun sit-for seconds &optional nodisp
|
|
|
1708 This function performs redisplay (provided there is no pending input
|
|
|
1709 from the user), then waits @var{seconds} seconds, or until input is
|
|
|
1710 available. The result is @code{t} if @code{sit-for} waited the full
|
|
|
1711 time with no input arriving (see @code{input-pending-p} in @ref{Peeking
|
|
|
1712 and Discarding}). Otherwise, the value is @code{nil}.
|
|
|
1713
|
|
|
1714 The argument @var{seconds} need not be an integer. If it is a floating
|
|
|
1715 point number, @code{sit-for} waits for a fractional number of seconds.
|
|
|
1716 @ignore FSF Emacs stuff
|
|
|
1717 Some systems support only a whole number of seconds; on these systems,
|
|
|
1718 @var{seconds} is rounded down.
|
|
|
1719
|
|
|
1720 The optional argument @var{millisec} specifies an additional waiting
|
|
|
1721 period measured in milliseconds. This adds to the period specified by
|
|
|
1722 @var{seconds}. If the system doesn't support waiting fractions of a
|
|
|
1723 second, you get an error if you specify nonzero @var{millisec}.
|
|
|
1724 @end ignore
|
|
|
1725
|
|
|
1726 @cindex forcing redisplay
|
|
|
1727 Redisplay is normally preempted if input arrives, and does not happen at
|
|
|
1728 all if input is available before it starts. (You can force screen
|
|
|
1729 updating in such a case by using @code{force-redisplay}. @xref{Refresh
|
|
|
1730 Screen}.) If there is no input pending, you can force an update with no
|
|
|
1731 delay by using @code{(sit-for 0)}.
|
|
|
1732
|
|
|
1733 If @var{nodisp} is non-@code{nil}, then @code{sit-for} does not
|
|
|
1734 redisplay, but it still returns as soon as input is available (or when
|
|
|
1735 the timeout elapses).
|
|
|
1736
|
|
|
1737 @ignore
|
|
|
1738 Iconifying or deiconifying a frame makes @code{sit-for} return, because
|
|
|
1739 that generates an event. @xref{Misc Events}.
|
|
|
1740 @end ignore
|
|
|
1741
|
|
|
1742 The usual purpose of @code{sit-for} is to give the user time to read
|
|
|
1743 text that you display.
|
|
|
1744 @end defun
|
|
|
1745
|
|
|
1746 @defun sleep-for seconds
|
|
|
1747 This function simply pauses for @var{seconds} seconds without updating
|
|
|
1748 the display. This function pays no attention to available input. It
|
|
|
1749 returns @code{nil}.
|
|
|
1750
|
|
|
1751 The argument @var{seconds} need not be an integer. If it is a floating
|
|
|
1752 point number, @code{sleep-for} waits for a fractional number of seconds.
|
|
|
1753 @ignore FSF Emacs stuff
|
|
|
1754 Some systems support only a whole number of seconds; on these systems,
|
|
|
1755 @var{seconds} is rounded down.
|
|
|
1756
|
|
|
1757 The optional argument @var{millisec} specifies an additional waiting
|
|
|
1758 period measured in milliseconds. This adds to the period specified by
|
|
|
1759 @var{seconds}. If the system doesn't support waiting fractions of a
|
|
|
1760 second, you get an error if you specify nonzero @var{millisec}.
|
|
|
1761 @end ignore
|
|
|
1762
|
|
|
1763 Use @code{sleep-for} when you wish to guarantee a delay.
|
|
|
1764 @end defun
|
|
|
1765
|
|
|
1766 @xref{Time of Day}, for functions to get the current time.
|
|
|
1767
|
|
|
1768 @node Quitting
|
|
|
1769 @section Quitting
|
|
|
1770 @cindex @kbd{C-g}
|
|
|
1771 @cindex quitting
|
|
|
1772
|
|
|
1773 Typing @kbd{C-g} while a Lisp function is running causes XEmacs to
|
|
|
1774 @dfn{quit} whatever it is doing. This means that control returns to the
|
|
|
1775 innermost active command loop.
|
|
|
1776
|
|
|
1777 Typing @kbd{C-g} while the command loop is waiting for keyboard input
|
|
|
1778 does not cause a quit; it acts as an ordinary input character. In the
|
|
|
1779 simplest case, you cannot tell the difference, because @kbd{C-g}
|
|
|
1780 normally runs the command @code{keyboard-quit}, whose effect is to quit.
|
|
|
1781 However, when @kbd{C-g} follows a prefix key, the result is an undefined
|
|
|
1782 key. The effect is to cancel the prefix key as well as any prefix
|
|
|
1783 argument.
|
|
|
1784
|
|
|
1785 In the minibuffer, @kbd{C-g} has a different definition: it aborts out
|
|
|
1786 of the minibuffer. This means, in effect, that it exits the minibuffer
|
|
|
1787 and then quits. (Simply quitting would return to the command loop
|
|
|
1788 @emph{within} the minibuffer.) The reason why @kbd{C-g} does not quit
|
|
|
1789 directly when the command reader is reading input is so that its meaning
|
|
|
1790 can be redefined in the minibuffer in this way. @kbd{C-g} following a
|
|
|
1791 prefix key is not redefined in the minibuffer, and it has its normal
|
|
|
1792 effect of canceling the prefix key and prefix argument. This too
|
|
|
1793 would not be possible if @kbd{C-g} always quit directly.
|
|
|
1794
|
|
|
1795 When @kbd{C-g} does directly quit, it does so by setting the variable
|
|
|
1796 @code{quit-flag} to @code{t}. XEmacs checks this variable at appropriate
|
|
|
1797 times and quits if it is not @code{nil}. Setting @code{quit-flag}
|
|
|
1798 non-@code{nil} in any way thus causes a quit.
|
|
|
1799
|
|
|
1800 At the level of C code, quitting cannot happen just anywhere; only at the
|
|
|
1801 special places that check @code{quit-flag}. The reason for this is
|
|
|
1802 that quitting at other places might leave an inconsistency in XEmacs's
|
|
|
1803 internal state. Because quitting is delayed until a safe place, quitting
|
|
|
1804 cannot make XEmacs crash.
|
|
|
1805
|
|
|
1806 Certain functions such as @code{read-key-sequence} or
|
|
|
1807 @code{read-quoted-char} prevent quitting entirely even though they wait
|
|
|
1808 for input. Instead of quitting, @kbd{C-g} serves as the requested
|
|
|
1809 input. In the case of @code{read-key-sequence}, this serves to bring
|
|
|
1810 about the special behavior of @kbd{C-g} in the command loop. In the
|
|
|
1811 case of @code{read-quoted-char}, this is so that @kbd{C-q} can be used
|
|
|
1812 to quote a @kbd{C-g}.
|
|
|
1813
|
|
|
1814 You can prevent quitting for a portion of a Lisp function by binding
|
|
|
1815 the variable @code{inhibit-quit} to a non-@code{nil} value. Then,
|
|
|
1816 although @kbd{C-g} still sets @code{quit-flag} to @code{t} as usual, the
|
|
|
1817 usual result of this---a quit---is prevented. Eventually,
|
|
|
1818 @code{inhibit-quit} will become @code{nil} again, such as when its
|
|
|
1819 binding is unwound at the end of a @code{let} form. At that time, if
|
|
|
1820 @code{quit-flag} is still non-@code{nil}, the requested quit happens
|
|
|
1821 immediately. This behavior is ideal when you wish to make sure that
|
|
|
1822 quitting does not happen within a ``critical section'' of the program.
|
|
|
1823
|
|
|
1824 @cindex @code{read-quoted-char} quitting
|
|
|
1825 In some functions (such as @code{read-quoted-char}), @kbd{C-g} is
|
|
|
1826 handled in a special way that does not involve quitting. This is done
|
|
|
1827 by reading the input with @code{inhibit-quit} bound to @code{t}, and
|
|
|
1828 setting @code{quit-flag} to @code{nil} before @code{inhibit-quit}
|
|
|
1829 becomes @code{nil} again. This excerpt from the definition of
|
|
|
1830 @code{read-quoted-char} shows how this is done; it also shows that
|
|
|
1831 normal quitting is permitted after the first character of input.
|
|
|
1832
|
|
|
1833 @example
|
|
|
1834 (defun read-quoted-char (&optional prompt)
|
|
|
1835 "@dots{}@var{documentation}@dots{}"
|
|
|
1836 (let ((count 0) (code 0) char)
|
|
|
1837 (while (< count 3)
|
|
|
1838 (let ((inhibit-quit (zerop count))
|
|
|
1839 (help-form nil))
|
|
|
1840 (and prompt (message "%s-" prompt))
|
|
|
1841 (setq char (read-char))
|
|
|
1842 (if inhibit-quit (setq quit-flag nil)))
|
|
|
1843 @dots{})
|
|
|
1844 (logand 255 code)))
|
|
|
1845 @end example
|
|
|
1846
|
|
|
1847 @defvar quit-flag
|
|
|
1848 If this variable is non-@code{nil}, then XEmacs quits immediately, unless
|
|
|
1849 @code{inhibit-quit} is non-@code{nil}. Typing @kbd{C-g} ordinarily sets
|
|
|
1850 @code{quit-flag} non-@code{nil}, regardless of @code{inhibit-quit}.
|
|
|
1851 @end defvar
|
|
|
1852
|
|
|
1853 @defvar inhibit-quit
|
|
|
1854 This variable determines whether XEmacs should quit when @code{quit-flag}
|
|
|
1855 is set to a value other than @code{nil}. If @code{inhibit-quit} is
|
|
|
1856 non-@code{nil}, then @code{quit-flag} has no special effect.
|
|
|
1857 @end defvar
|
|
|
1858
|
|
|
1859 @deffn Command keyboard-quit
|
|
|
1860 This function signals the @code{quit} condition with @code{(signal 'quit
|
|
|
1861 nil)}. This is the same thing that quitting does. (See @code{signal}
|
|
|
1862 in @ref{Errors}.)
|
|
|
1863 @end deffn
|
|
|
1864
|
|
|
1865 You can specify a character other than @kbd{C-g} to use for quitting.
|
|
|
1866 See the function @code{set-input-mode} in @ref{Terminal Input}.
|
|
|
1867
|
|
|
1868 @node Prefix Command Arguments
|
|
|
1869 @section Prefix Command Arguments
|
|
|
1870 @cindex prefix argument
|
|
|
1871 @cindex raw prefix argument
|
|
|
1872 @cindex numeric prefix argument
|
|
|
1873
|
|
|
1874 Most XEmacs commands can use a @dfn{prefix argument}, a number
|
|
|
1875 specified before the command itself. (Don't confuse prefix arguments
|
|
|
1876 with prefix keys.) The prefix argument is at all times represented by a
|
|
|
1877 value, which may be @code{nil}, meaning there is currently no prefix
|
|
|
1878 argument. Each command may use the prefix argument or ignore it.
|
|
|
1879
|
|
|
1880 There are two representations of the prefix argument: @dfn{raw} and
|
|
|
1881 @dfn{numeric}. The editor command loop uses the raw representation
|
|
|
1882 internally, and so do the Lisp variables that store the information, but
|
|
|
1883 commands can request either representation.
|
|
|
1884
|
|
|
1885 Here are the possible values of a raw prefix argument:
|
|
|
1886
|
|
|
1887 @itemize @bullet
|
|
|
1888 @item
|
|
|
1889 @code{nil}, meaning there is no prefix argument. Its numeric value is
|
|
|
1890 1, but numerous commands make a distinction between @code{nil} and the
|
|
|
1891 integer 1.
|
|
|
1892
|
|
|
1893 @item
|
|
|
1894 An integer, which stands for itself.
|
|
|
1895
|
|
|
1896 @item
|
|
|
1897 A list of one element, which is an integer. This form of prefix
|
|
|
1898 argument results from one or a succession of @kbd{C-u}'s with no
|
|
|
1899 digits. The numeric value is the integer in the list, but some
|
|
|
1900 commands make a distinction between such a list and an integer alone.
|
|
|
1901
|
|
|
1902 @item
|
|
|
1903 The symbol @code{-}. This indicates that @kbd{M--} or @kbd{C-u -} was
|
|
|
1904 typed, without following digits. The equivalent numeric value is
|
|
|
1905 @minus{}1, but some commands make a distinction between the integer
|
|
|
1906 @minus{}1 and the symbol @code{-}.
|
|
|
1907 @end itemize
|
|
|
1908
|
|
|
1909 We illustrate these possibilities by calling the following function with
|
|
|
1910 various prefixes:
|
|
|
1911
|
|
|
1912 @example
|
|
|
1913 @group
|
|
|
1914 (defun display-prefix (arg)
|
|
|
1915 "Display the value of the raw prefix arg."
|
|
|
1916 (interactive "P")
|
|
|
1917 (message "%s" arg))
|
|
|
1918 @end group
|
|
|
1919 @end example
|
|
|
1920
|
|
|
1921 @noindent
|
|
|
1922 Here are the results of calling @code{display-prefix} with various
|
|
|
1923 raw prefix arguments:
|
|
|
1924
|
|
|
1925 @example
|
|
|
1926 M-x display-prefix @print{} nil
|
|
|
1927
|
|
|
1928 C-u M-x display-prefix @print{} (4)
|
|
|
1929
|
|
|
1930 C-u C-u M-x display-prefix @print{} (16)
|
|
|
1931
|
|
|
1932 C-u 3 M-x display-prefix @print{} 3
|
|
|
1933
|
|
|
1934 M-3 M-x display-prefix @print{} 3 ; @r{(Same as @code{C-u 3}.)}
|
|
|
1935
|
|
|
1936 C-3 M-x display-prefix @print{} 3 ; @r{(Same as @code{C-u 3}.)}
|
|
|
1937
|
|
|
1938 C-u - M-x display-prefix @print{} -
|
|
|
1939
|
|
|
1940 M-- M-x display-prefix @print{} - ; @r{(Same as @code{C-u -}.)}
|
|
|
1941
|
|
|
1942 C-- M-x display-prefix @print{} - ; @r{(Same as @code{C-u -}.)}
|
|
|
1943
|
|
|
1944 C-u - 7 M-x display-prefix @print{} -7
|
|
|
1945
|
|
|
1946 M-- 7 M-x display-prefix @print{} -7 ; @r{(Same as @code{C-u -7}.)}
|
|
|
1947
|
|
|
1948 C-- 7 M-x display-prefix @print{} -7 ; @r{(Same as @code{C-u -7}.)}
|
|
|
1949 @end example
|
|
|
1950
|
|
|
1951 XEmacs uses two variables to store the prefix argument:
|
|
|
1952 @code{prefix-arg} and @code{current-prefix-arg}. Commands such as
|
|
|
1953 @code{universal-argument} that set up prefix arguments for other
|
|
|
1954 commands store them in @code{prefix-arg}. In contrast,
|
|
|
1955 @code{current-prefix-arg} conveys the prefix argument to the current
|
|
|
1956 command, so setting it has no effect on the prefix arguments for future
|
|
|
1957 commands.
|
|
|
1958
|
|
|
1959 Normally, commands specify which representation to use for the prefix
|
|
|
1960 argument, either numeric or raw, in the @code{interactive} declaration.
|
|
|
1961 (@xref{Using Interactive}.) Alternatively, functions may look at the
|
|
|
1962 value of the prefix argument directly in the variable
|
|
|
1963 @code{current-prefix-arg}, but this is less clean.
|
|
|
1964
|
|
|
1965 @defun prefix-numeric-value arg
|
|
|
1966 This function returns the numeric meaning of a valid raw prefix argument
|
|
|
1967 value, @var{arg}. The argument may be a symbol, a number, or a list.
|
|
|
1968 If it is @code{nil}, the value 1 is returned; if it is @code{-}, the
|
|
|
1969 value @minus{}1 is returned; if it is a number, that number is returned;
|
|
|
1970 if it is a list, the @sc{car} of that list (which should be a number) is
|
|
|
1971 returned.
|
|
|
1972 @end defun
|
|
|
1973
|
|
|
1974 @defvar current-prefix-arg
|
|
|
1975 This variable holds the raw prefix argument for the @emph{current}
|
|
|
1976 command. Commands may examine it directly, but the usual way to access
|
|
|
1977 it is with @code{(interactive "P")}.
|
|
|
1978 @end defvar
|
|
|
1979
|
|
|
1980 @defvar prefix-arg
|
|
|
1981 The value of this variable is the raw prefix argument for the
|
|
|
1982 @emph{next} editing command. Commands that specify prefix arguments for
|
|
|
1983 the following command work by setting this variable.
|
|
|
1984 @end defvar
|
|
|
1985
|
|
|
1986 Do not call the functions @code{universal-argument},
|
|
|
1987 @code{digit-argument}, or @code{negative-argument} unless you intend to
|
|
|
1988 let the user enter the prefix argument for the @emph{next} command.
|
|
|
1989
|
|
|
1990 @deffn Command universal-argument
|
|
|
1991 This command reads input and specifies a prefix argument for the
|
|
|
1992 following command. Don't call this command yourself unless you know
|
|
|
1993 what you are doing.
|
|
|
1994 @end deffn
|
|
|
1995
|
|
|
1996 @deffn Command digit-argument arg
|
|
|
1997 This command adds to the prefix argument for the following command. The
|
|
|
1998 argument @var{arg} is the raw prefix argument as it was before this
|
|
|
1999 command; it is used to compute the updated prefix argument. Don't call
|
|
|
2000 this command yourself unless you know what you are doing.
|
|
|
2001 @end deffn
|
|
|
2002
|
|
|
2003 @deffn Command negative-argument arg
|
|
|
2004 This command adds to the numeric argument for the next command. The
|
|
|
2005 argument @var{arg} is the raw prefix argument as it was before this
|
|
|
2006 command; its value is negated to form the new prefix argument. Don't
|
|
|
2007 call this command yourself unless you know what you are doing.
|
|
|
2008 @end deffn
|
|
|
2009
|
|
|
2010 @node Recursive Editing
|
|
|
2011 @section Recursive Editing
|
|
|
2012 @cindex recursive command loop
|
|
|
2013 @cindex recursive editing level
|
|
|
2014 @cindex command loop, recursive
|
|
|
2015
|
|
|
2016 The XEmacs command loop is entered automatically when XEmacs starts up.
|
|
|
2017 This top-level invocation of the command loop never exits; it keeps
|
|
|
2018 running as long as XEmacs does. Lisp programs can also invoke the
|
|
|
2019 command loop. Since this makes more than one activation of the command
|
|
|
2020 loop, we call it @dfn{recursive editing}. A recursive editing level has
|
|
|
2021 the effect of suspending whatever command invoked it and permitting the
|
|
|
2022 user to do arbitrary editing before resuming that command.
|
|
|
2023
|
|
|
2024 The commands available during recursive editing are the same ones
|
|
|
2025 available in the top-level editing loop and defined in the keymaps.
|
|
|
2026 Only a few special commands exit the recursive editing level; the others
|
|
|
2027 return to the recursive editing level when they finish. (The special
|
|
|
2028 commands for exiting are always available, but they do nothing when
|
|
|
2029 recursive editing is not in progress.)
|
|
|
2030
|
|
|
2031 All command loops, including recursive ones, set up all-purpose error
|
|
|
2032 handlers so that an error in a command run from the command loop will
|
|
|
2033 not exit the loop.
|
|
|
2034
|
|
|
2035 @cindex minibuffer input
|
|
|
2036 Minibuffer input is a special kind of recursive editing. It has a few
|
|
|
2037 special wrinkles, such as enabling display of the minibuffer and the
|
|
|
2038 minibuffer window, but fewer than you might suppose. Certain keys
|
|
|
2039 behave differently in the minibuffer, but that is only because of the
|
|
|
2040 minibuffer's local map; if you switch windows, you get the usual XEmacs
|
|
|
2041 commands.
|
|
|
2042
|
|
|
2043 @cindex @code{throw} example
|
|
|
2044 @kindex exit
|
|
|
2045 @cindex exit recursive editing
|
|
|
2046 @cindex aborting
|
|
|
2047 To invoke a recursive editing level, call the function
|
|
|
2048 @code{recursive-edit}. This function contains the command loop; it also
|
|
|
2049 contains a call to @code{catch} with tag @code{exit}, which makes it
|
|
|
2050 possible to exit the recursive editing level by throwing to @code{exit}
|
|
|
2051 (@pxref{Catch and Throw}). If you throw a value other than @code{t},
|
|
|
2052 then @code{recursive-edit} returns normally to the function that called
|
|
|
2053 it. The command @kbd{C-M-c} (@code{exit-recursive-edit}) does this.
|
|
|
2054 Throwing a @code{t} value causes @code{recursive-edit} to quit, so that
|
|
|
2055 control returns to the command loop one level up. This is called
|
|
|
2056 @dfn{aborting}, and is done by @kbd{C-]} (@code{abort-recursive-edit}).
|
|
|
2057
|
|
|
2058 Most applications should not use recursive editing, except as part of
|
|
|
2059 using the minibuffer. Usually it is more convenient for the user if you
|
|
|
2060 change the major mode of the current buffer temporarily to a special
|
|
|
2061 major mode, which should have a command to go back to the previous mode.
|
|
|
2062 (The @kbd{e} command in Rmail uses this technique.) Or, if you wish to
|
|
|
2063 give the user different text to edit ``recursively'', create and select
|
|
|
2064 a new buffer in a special mode. In this mode, define a command to
|
|
|
2065 complete the processing and go back to the previous buffer. (The
|
|
|
2066 @kbd{m} command in Rmail does this.)
|
|
|
2067
|
|
|
2068 Recursive edits are useful in debugging. You can insert a call to
|
|
|
2069 @code{debug} into a function definition as a sort of breakpoint, so that
|
|
|
2070 you can look around when the function gets there. @code{debug} invokes
|
|
|
2071 a recursive edit but also provides the other features of the debugger.
|
|
|
2072
|
|
|
2073 Recursive editing levels are also used when you type @kbd{C-r} in
|
|
|
2074 @code{query-replace} or use @kbd{C-x q} (@code{kbd-macro-query}).
|
|
|
2075
|
|
|
2076 @defun recursive-edit
|
|
|
2077 @cindex suspend evaluation
|
|
|
2078 This function invokes the editor command loop. It is called
|
|
|
2079 automatically by the initialization of XEmacs, to let the user begin
|
|
|
2080 editing. When called from a Lisp program, it enters a recursive editing
|
|
|
2081 level.
|
|
|
2082
|
|
|
2083 In the following example, the function @code{simple-rec} first
|
|
|
2084 advances point one word, then enters a recursive edit, printing out a
|
|
|
2085 message in the echo area. The user can then do any editing desired, and
|
|
|
2086 then type @kbd{C-M-c} to exit and continue executing @code{simple-rec}.
|
|
|
2087
|
|
|
2088 @example
|
|
|
2089 (defun simple-rec ()
|
|
|
2090 (forward-word 1)
|
|
|
2091 (message "Recursive edit in progress")
|
|
|
2092 (recursive-edit)
|
|
|
2093 (forward-word 1))
|
|
|
2094 @result{} simple-rec
|
|
|
2095 (simple-rec)
|
|
|
2096 @result{} nil
|
|
|
2097 @end example
|
|
|
2098 @end defun
|
|
|
2099
|
|
|
2100 @deffn Command exit-recursive-edit
|
|
|
2101 This function exits from the innermost recursive edit (including
|
|
|
2102 minibuffer input). Its definition is effectively @code{(throw 'exit
|
|
|
2103 nil)}.
|
|
|
2104 @end deffn
|
|
|
2105
|
|
|
2106 @deffn Command abort-recursive-edit
|
|
|
2107 This function aborts the command that requested the innermost recursive
|
|
|
2108 edit (including minibuffer input), by signaling @code{quit}
|
|
|
2109 after exiting the recursive edit. Its definition is effectively
|
|
|
2110 @code{(throw 'exit t)}. @xref{Quitting}.
|
|
|
2111 @end deffn
|
|
|
2112
|
|
|
2113 @deffn Command top-level
|
|
|
2114 This function exits all recursive editing levels; it does not return a
|
|
|
2115 value, as it jumps completely out of any computation directly back to
|
|
|
2116 the main command loop.
|
|
|
2117 @end deffn
|
|
|
2118
|
|
|
2119 @defun recursion-depth
|
|
|
2120 This function returns the current depth of recursive edits. When no
|
|
|
2121 recursive edit is active, it returns 0.
|
|
|
2122 @end defun
|
|
|
2123
|
|
|
2124 @node Disabling Commands
|
|
|
2125 @section Disabling Commands
|
|
|
2126 @cindex disabled command
|
|
|
2127
|
|
|
2128 @dfn{Disabling a command} marks the command as requiring user
|
|
|
2129 confirmation before it can be executed. Disabling is used for commands
|
|
|
2130 which might be confusing to beginning users, to prevent them from using
|
|
|
2131 the commands by accident.
|
|
|
2132
|
|
|
2133 @kindex disabled
|
|
|
2134 The low-level mechanism for disabling a command is to put a
|
|
|
2135 non-@code{nil} @code{disabled} property on the Lisp symbol for the
|
|
|
2136 command. These properties are normally set up by the user's
|
|
|
2137 @file{.emacs} file with Lisp expressions such as this:
|
|
|
2138
|
|
|
2139 @example
|
|
|
2140 (put 'upcase-region 'disabled t)
|
|
|
2141 @end example
|
|
|
2142
|
|
|
2143 @noindent
|
|
|
2144 For a few commands, these properties are present by default and may be
|
|
|
2145 removed by the @file{.emacs} file.
|
|
|
2146
|
|
|
2147 If the value of the @code{disabled} property is a string, the message
|
|
|
2148 saying the command is disabled includes that string. For example:
|
|
|
2149
|
|
|
2150 @example
|
|
|
2151 (put 'delete-region 'disabled
|
|
|
2152 "Text deleted this way cannot be yanked back!\n")
|
|
|
2153 @end example
|
|
|
2154
|
|
|
2155 @xref{Disabling,,, emacs, The XEmacs Reference Manual}, for the details on
|
|
|
2156 what happens when a disabled command is invoked interactively.
|
|
|
2157 Disabling a command has no effect on calling it as a function from Lisp
|
|
|
2158 programs.
|
|
|
2159
|
|
|
2160 @deffn Command enable-command command
|
|
|
2161 Allow @var{command} to be executed without special confirmation from now
|
|
|
2162 on, and (if the user confirms) alter the user's @file{.emacs} file so
|
|
|
2163 that this will apply to future sessions.
|
|
|
2164 @end deffn
|
|
|
2165
|
|
|
2166 @deffn Command disable-command command
|
|
|
2167 Require special confirmation to execute @var{command} from now on, and
|
|
|
2168 (if the user confirms) alter the user's @file{.emacs} file so that this
|
|
|
2169 will apply to future sessions.
|
|
|
2170 @end deffn
|
|
|
2171
|
|
|
2172 @defvar disabled-command-hook
|
|
|
2173 This normal hook is run instead of a disabled command, when the user
|
|
|
2174 invokes the disabled command interactively. The hook functions can use
|
|
|
2175 @code{this-command-keys} to determine what the user typed to run the
|
|
|
2176 command, and thus find the command itself. @xref{Hooks}.
|
|
|
2177
|
|
|
2178 By default, @code{disabled-command-hook} contains a function that asks
|
|
|
2179 the user whether to proceed.
|
|
|
2180 @end defvar
|
|
|
2181
|
|
|
2182 @node Command History
|
|
|
2183 @section Command History
|
|
|
2184 @cindex command history
|
|
|
2185 @cindex complex command
|
|
|
2186 @cindex history of commands
|
|
|
2187
|
|
|
2188 The command loop keeps a history of the complex commands that have
|
|
|
2189 been executed, to make it convenient to repeat these commands. A
|
|
|
2190 @dfn{complex command} is one for which the interactive argument reading
|
|
|
2191 uses the minibuffer. This includes any @kbd{M-x} command, any
|
|
|
2192 @kbd{M-:} command, and any command whose @code{interactive}
|
|
|
2193 specification reads an argument from the minibuffer. Explicit use of
|
|
|
2194 the minibuffer during the execution of the command itself does not cause
|
|
|
2195 the command to be considered complex.
|
|
|
2196
|
|
|
2197 @defvar command-history
|
|
|
2198 This variable's value is a list of recent complex commands, each
|
|
|
2199 represented as a form to evaluate. It continues to accumulate all
|
|
|
2200 complex commands for the duration of the editing session, but all but
|
|
|
2201 the first (most recent) thirty elements are deleted when a garbage
|
|
|
2202 collection takes place (@pxref{Garbage Collection}).
|
|
|
2203
|
|
|
2204 @example
|
|
|
2205 @group
|
|
|
2206 command-history
|
|
|
2207 @result{} ((switch-to-buffer "chistory.texi")
|
|
|
2208 (describe-key "^X^[")
|
|
|
2209 (visit-tags-table "~/emacs/src/")
|
|
|
2210 (find-tag "repeat-complex-command"))
|
|
|
2211 @end group
|
|
|
2212 @end example
|
|
|
2213 @end defvar
|
|
|
2214
|
|
|
2215 This history list is actually a special case of minibuffer history
|
|
|
2216 (@pxref{Minibuffer History}), with one special twist: the elements are
|
|
|
2217 expressions rather than strings.
|
|
|
2218
|
|
|
2219 There are a number of commands devoted to the editing and recall of
|
|
|
2220 previous commands. The commands @code{repeat-complex-command}, and
|
|
|
2221 @code{list-command-history} are described in the user manual
|
|
|
2222 (@pxref{Repetition,,, emacs, The XEmacs Reference Manual}). Within the
|
|
|
2223 minibuffer, the history commands used are the same ones available in any
|
|
|
2224 minibuffer.
|
|
|
2225
|
|
|
2226 @node Keyboard Macros
|
|
|
2227 @section Keyboard Macros
|
|
|
2228 @cindex keyboard macros
|
|
|
2229
|
|
|
2230 A @dfn{keyboard macro} is a canned sequence of input events that can
|
|
|
2231 be considered a command and made the definition of a key. The Lisp
|
|
|
2232 representation of a keyboard macro is a string or vector containing the
|
|
|
2233 events. Don't confuse keyboard macros with Lisp macros
|
|
|
2234 (@pxref{Macros}).
|
|
|
2235
|
|
|
2236 @defun execute-kbd-macro macro &optional count
|
|
|
2237 This function executes @var{macro} as a sequence of events. If
|
|
|
2238 @var{macro} is a string or vector, then the events in it are executed
|
|
|
2239 exactly as if they had been input by the user. The sequence is
|
|
|
2240 @emph{not} expected to be a single key sequence; normally a keyboard
|
|
|
2241 macro definition consists of several key sequences concatenated.
|
|
|
2242
|
|
|
2243 If @var{macro} is a symbol, then its function definition is used in
|
|
|
2244 place of @var{macro}. If that is another symbol, this process repeats.
|
|
|
2245 Eventually the result should be a string or vector. If the result is
|
|
|
2246 not a symbol, string, or vector, an error is signaled.
|
|
|
2247
|
|
|
2248 The argument @var{count} is a repeat count; @var{macro} is executed that
|
|
|
2249 many times. If @var{count} is omitted or @code{nil}, @var{macro} is
|
|
|
2250 executed once. If it is 0, @var{macro} is executed over and over until it
|
|
|
2251 encounters an error or a failing search.
|
|
|
2252 @end defun
|
|
|
2253
|
|
|
2254 @defvar executing-macro
|
|
|
2255 This variable contains the string or vector that defines the keyboard
|
|
|
2256 macro that is currently executing. It is @code{nil} if no macro is
|
|
|
2257 currently executing. A command can test this variable to behave
|
|
|
2258 differently when run from an executing macro. Do not set this variable
|
|
|
2259 yourself.
|
|
|
2260 @end defvar
|
|
|
2261
|
|
|
2262 @defvar defining-kbd-macro
|
|
|
2263 This variable indicates whether a keyboard macro is being defined. A
|
|
|
2264 command can test this variable to behave differently while a macro is
|
|
|
2265 being defined. The commands @code{start-kbd-macro} and
|
|
|
2266 @code{end-kbd-macro} set this variable---do not set it yourself.
|
|
|
2267 @end defvar
|
|
|
2268
|
|
|
2269 @defvar last-kbd-macro
|
|
|
2270 This variable is the definition of the most recently defined keyboard
|
|
|
2271 macro. Its value is a string or vector, or @code{nil}.
|
|
|
2272 @end defvar
|
|
|
2273
|
|
|
2274 @c Broke paragraph to prevent overfull hbox. --rjc 15mar92
|
|
|
2275 The commands are described in the user's manual (@pxref{Keyboard
|
|
|
2276 Macros,,, emacs, The XEmacs Reference Manual}).
|
