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