Mercurial > hg > xemacs-beta
annotate man/lispref/commands.texi @ 5044:e84a30b0e4a2
remove duplicative code in change_frame_size()
-------------------- ChangeLog entries follow: --------------------
src/ChangeLog addition:
2010-02-15 Ben Wing <ben@xemacs.org>
* frame.c (change_frame_size_1):
Simplify the logic in this function.
(1) Don't allow 0 as the value of height or width. The old code
that tried to allow this was totally broken, anyway, so obviously
this never happens any more.
(2) Don't duplicate the code in frame_conversion_internal() that
converts displayable pixel size to total pixel size -- just call
that function.
| author | Ben Wing <ben@xemacs.org> |
|---|---|
| date | Mon, 15 Feb 2010 22:58:10 -0600 |
| parents | 755ae5b97edb |
| children | 62b9ef1ed4ac |
| rev | line source |
|---|---|
| 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 | |
|
4905
755ae5b97edb
Change "special form" to "special operator" in our sources.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4885
diff
changeset
|
105 level, a form that calls the special operator @code{interactive}. This |
|
755ae5b97edb
Change "special form" to "special operator" in our sources.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4885
diff
changeset
|
106 operator does nothing when actually executed, but its presence serves as a |
| 428 | 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 | |
|
4905
755ae5b97edb
Change "special form" to "special operator" in our sources.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4885
diff
changeset
|
125 This special operator declares that the function in which it appears is a |
| 428 | 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 | |
|
4885
6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents:
2862
diff
changeset
|
765 characters echo. Its value must be a float or a fixnum, which specifies the |
| 428 | 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 | |
|
4885
6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents:
2862
diff
changeset
|
1327 for button-press, button-release and misc-user events. |
| 428 | 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}). |