|
0
|
1 This is Info file LNEWS, produced by Makeinfo-1.55 from the input file
|
|
|
2 news.texi.
|
|
|
3
|
|
|
4 This file describes the new Lisp features of Emacs version 19 as
|
|
|
5 first released to the public. For Lisp changes in subsequent Emacs 19
|
|
|
6 releases, see the file NEWS.
|
|
|
7
|
|
|
8 New Features in the Lisp Language
|
|
|
9 =================================
|
|
|
10
|
|
|
11 * The new function `delete' is a traditional Lisp function. It takes
|
|
|
12 two arguments, ELT and LIST, and deletes from LIST any elements
|
|
|
13 that are equal to ELT. It uses the function `equal' to compare
|
|
|
14 elements with ELT.
|
|
|
15
|
|
|
16 * The new function `member' is a traditional Lisp function. It takes
|
|
|
17 two arguments, ELT and LIST, and finds the first element of LIST
|
|
|
18 that is equal to ELT. It uses the function `equal' to compare
|
|
|
19 each list element with ELT.
|
|
|
20
|
|
|
21 The value is a sublist of LIST, whose first element is the one
|
|
|
22 that was found. If no matching element is found, the value is
|
|
|
23 `nil'.
|
|
|
24
|
|
|
25 * The new function `indirect-function' finds the effective function
|
|
|
26 definition of an object called as a function. If the object is a
|
|
|
27 symbol, `indirect-function' looks in the function definition of the
|
|
|
28 symbol. It keeps doing this until it finds something that is not a
|
|
|
29 symbol.
|
|
|
30
|
|
|
31 * There are new escape sequences for use in character and string
|
|
|
32 constants. The escape sequence `\a' is equivalent to `\C-g', the
|
|
|
33 ASCII BEL character (code 7). The escape sequence `\x' followed
|
|
|
34 by a hexidecimal number represents the character whose ASCII code
|
|
|
35 is that number. There is no limit on the number of digits in the
|
|
|
36 hexidecimal value.
|
|
|
37
|
|
|
38 * The function `read' when reading from a buffer now does not skip a
|
|
|
39 terminator character that terminates a symbol. It leaves that
|
|
|
40 character to be read (or just skipped, if it is whitespace) next
|
|
|
41 time.
|
|
|
42
|
|
|
43 * When you use a function FUNCTION as the input stream for `read',
|
|
|
44 it is usually called with no arguments, and should return the next
|
|
|
45 character. In Emacs 19, sometimes FUNCTION is called with one
|
|
|
46 argument (always a character). When that happens, FUNCTION should
|
|
|
47 save the argument and arrange to return it when called next time.
|
|
|
48
|
|
|
49 * `random' with integer argument N returns a random number between 0
|
|
|
50 and N-1.
|
|
|
51
|
|
|
52 * The functions `documentation' and `documentation-property' now
|
|
|
53 take an additional optional argument which, if non-`nil', says to
|
|
|
54 refrain from calling `substitute-command-keys'. This way, you get
|
|
|
55 the exact text of the documentation string as written, without the
|
|
|
56 usual substitutions. Make sure to call `substitute-command-keys'
|
|
|
57 yourself if you decide to display the string.
|
|
|
58
|
|
|
59 * The new function `invocation-name' returns as a string the program
|
|
|
60 name that was used to run Emacs, with any directory names
|
|
|
61 discarded.
|
|
|
62
|
|
|
63 * The new function `map-y-or-n-p' makes it convenient to ask a series
|
|
|
64 of similar questions. The arguments are PROMPTER, ACTOR, LIST,
|
|
|
65 and optional HELP.
|
|
|
66
|
|
|
67 The value of LIST is a list of objects, or a function of no
|
|
|
68 arguments to return either the next object or `nil' meaning there
|
|
|
69 are no more.
|
|
|
70
|
|
|
71 The argument PROMPTER specifies how to ask each question. If
|
|
|
72 PROMPTER is a string, the question text is computed like this:
|
|
|
73
|
|
|
74 (format PROMPTER OBJECT)
|
|
|
75
|
|
|
76 where OBJECT is the next object to ask about.
|
|
|
77
|
|
|
78 If not a string, PROMPTER should be a function of one argument
|
|
|
79 (the next object to ask about) and should return the question text.
|
|
|
80
|
|
|
81 The argument ACTOR should be a function of one argument, which is
|
|
|
82 called with each object that the user says yes for. Its argument
|
|
|
83 is always one object from LIST.
|
|
|
84
|
|
|
85 If HELP is given, it is a list `(OBJECT OBJECTS ACTION)', where
|
|
|
86 OBJECT is a string containing a singular noun that describes the
|
|
|
87 objects conceptually being acted on; OBJECTS is the corresponding
|
|
|
88 plural noun and ACTION is a transitive verb describing ACTOR. The
|
|
|
89 default is `("object" "objects" "act on")'.
|
|
|
90
|
|
|
91 Each time a question is asked, the user may enter `y', `Y', or SPC
|
|
|
92 to act on that object; `n', `N', or DEL to skip that object; `!'
|
|
|
93 to act on all following objects; ESC or `q' to exit (skip all
|
|
|
94 following objects); `.' (period) to act on the current object and
|
|
|
95 then exit; or `C-h' to get help.
|
|
|
96
|
|
|
97 `map-y-or-n-p' returns the number of objects acted on.
|
|
|
98
|
|
|
99 * You can now "set" environment variables with the `setenv' command.
|
|
|
100 This works by setting the variable `process-environment', which
|
|
|
101 `getenv' now examines in preference to the environment Emacs
|
|
|
102 received from its parent.
|
|
|
103
|
|
|
104 New Features for Loading Libraries
|
|
|
105 ==================================
|
|
|
106
|
|
|
107 You can now arrange to run a hook if a particular Lisp library is
|
|
|
108 loaded.
|
|
|
109
|
|
|
110 The variable `after-load-alist' is an alist of expressions to be
|
|
|
111 evalled when particular files are loaded. Each element looks like
|
|
|
112 `(FILENAME FORMS...)'.
|
|
|
113
|
|
|
114 When `load' is run and the file name argument equals FILENAME, the
|
|
|
115 FORMS in the corresponding element are executed at the end of loading.
|
|
|
116 fILENAME must match exactly! Normally FILENAME is the name of a
|
|
|
117 library, with no directory specified, since that is how `load' is
|
|
|
118 normally called.
|
|
|
119
|
|
|
120 An error in FORMS does not undo the load, but does prevent execution
|
|
|
121 of the rest of the FORMS.
|
|
|
122
|
|
|
123 The function `eval-after-load' provides a convenient way to add
|
|
|
124 entries to the alist. Call it with two arguments, FILE and a form to
|
|
|
125 execute.
|
|
|
126
|
|
|
127 The function `autoload' now supports autoloading a keymap. Use
|
|
|
128 `keymap' as the fourth argument if the autoloaded function will become
|
|
|
129 a keymap when loaded.
|
|
|
130
|
|
|
131 There is a new feature for specifying which functions in a library
|
|
|
132 should be autoloaded by writing special "magic" comments in that
|
|
|
133 library itself.
|
|
|
134
|
|
|
135 Write `;;;###autoload' on a line by itself before the real
|
|
|
136 definition of the function, in its autoloadable source file; then the
|
|
|
137 command `M-x update-file-autoloads' automatically puts the `autoload'
|
|
|
138 call into `loaddefs.el'.
|
|
|
139
|
|
|
140 You can also put other kinds of forms into `loaddefs.el', by writing
|
|
|
141 `;;;###autoload' followed on the same line by the form. `M-x
|
|
|
142 update-file-autoloads' copies the form from that line.
|
|
|
143
|
|
|
144 Compilation Features
|
|
|
145 ====================
|
|
|
146
|
|
|
147 * Inline functions.
|
|
|
148
|
|
|
149 You can define an "inline function" with `defsubst'. Use
|
|
|
150 `defsubst' just like `defun', and it defines a function which you
|
|
|
151 can call in all the usual ways. Whenever the function thus defined
|
|
|
152 is used in compiled code, the compiler will open code it.
|
|
|
153
|
|
|
154 You can get somewhat the same effects with a macro, but a macro
|
|
|
155 has the limitation that you can use it only explicitly; a macro
|
|
|
156 cannot be called with `apply', `mapcar' and so on. Also, it takes
|
|
|
157 some work to convert an ordinary function into a macro. To
|
|
|
158 convert it into an inline function, simply replace `defun' with
|
|
|
159 `defsubst'.
|
|
|
160
|
|
|
161 Making a function inline makes explicit calls run faster. But it
|
|
|
162 also has disadvantages. For one thing, it reduces flexibility; if
|
|
|
163 you change the definition of the function, calls already inlined
|
|
|
164 still use the old definition until you recompile them.
|
|
|
165
|
|
|
166 Another disadvantage is that making a large function inline can
|
|
|
167 increase the size of compiled code both in files and in memory.
|
|
|
168 Since the advantages of inline functions are greatest for small
|
|
|
169 functions, you generally should not make large functions inline.
|
|
|
170
|
|
|
171 Inline functions can be used and open coded later on in the same
|
|
|
172 file, following the definition, just like macros.
|
|
|
173
|
|
|
174 * The command `byte-compile-file' now offers to save any buffer
|
|
|
175 visiting the file you are compiling.
|
|
|
176
|
|
|
177 * The new command `compile-defun' reads, compiles and executes the
|
|
|
178 defun containing point. If you use this on a defun that is
|
|
|
179 actually a function definition, the effect is to install a
|
|
|
180 compiled version of that function.
|
|
|
181
|
|
|
182 * Whenever you load a Lisp file or library, you now receive a
|
|
|
183 warning if the directory contains both a `.el' file and a `.elc'
|
|
|
184 file, and the `.el' file is newer. This typically indicates that
|
|
|
185 someone has updated the Lisp code but forgotten to recompile it,
|
|
|
186 so the changes do not take effect. The warning is a reminder to
|
|
|
187 recompile.
|
|
|
188
|
|
|
189 * The special form `eval-when-compile' marks the forms it contains to
|
|
|
190 be evaluated at compile time *only*. At top-level, this is
|
|
|
191 analogous to the Common Lisp idiom `(eval-when (compile) ...)'.
|
|
|
192 Elsewhere, it is similar to the Common Lisp `#.' reader macro (but
|
|
|
193 not when interpreting).
|
|
|
194
|
|
|
195 If you're thinking of using this feature, we recommend you
|
|
|
196 consider whether `provide' and `require' might do the job as well.
|
|
|
197
|
|
|
198 * The special form `eval-and-compile' is similar to
|
|
|
199 `eval-when-compile', but the whole form is evaluated both at
|
|
|
200 compile time and at run time.
|
|
|
201
|
|
|
202 If you're thinking of using this feature, we recommend you consider
|
|
|
203 whether `provide' and `require' might do the job as well.
|
|
|
204
|
|
|
205 * Emacs Lisp has a new data type for byte-code functions. This makes
|
|
|
206 them faster to call, and also saves space. Internally, a byte-code
|
|
|
207 function object is much like a vector; however, the evaluator
|
|
|
208 handles this data type specially when it appears as a function to
|
|
|
209 be called.
|
|
|
210
|
|
|
211 The printed representation for a byte-code function object is like
|
|
|
212 that for a vector, except that it starts with `#' before the
|
|
|
213 opening `['. A byte-code function object must have at least four
|
|
|
214 elements; there is no maximum number, but only the first six
|
|
|
215 elements are actually used. They are:
|
|
|
216
|
|
|
217 ARGLIST
|
|
|
218 The list of argument symbols.
|
|
|
219
|
|
|
220 BYTE-CODE
|
|
|
221 The string containing the byte-code instructions.
|
|
|
222
|
|
|
223 CONSTANTS
|
|
|
224 The vector of constants referenced by the byte code.
|
|
|
225
|
|
|
226 STACKSIZE
|
|
|
227 The maximum stack size this function needs.
|
|
|
228
|
|
|
229 DOCSTRING
|
|
|
230 The documentation string (if any); otherwise, `nil'.
|
|
|
231
|
|
|
232 INTERACTIVE
|
|
|
233 The interactive spec (if any). This can be a string or a Lisp
|
|
|
234 expression. It is `nil' for a function that isn't
|
|
|
235 interactive.
|
|
|
236
|
|
|
237 The predicate `byte-code-function-p' tests whether a given object
|
|
|
238 is a byte-code function.
|
|
|
239
|
|
|
240 You can create a byte-code function object in a Lisp program with
|
|
|
241 the function `make-byte-code'. Its arguments are the elements to
|
|
|
242 put in the byte-code function object.
|
|
|
243
|
|
|
244 You should not try to come up with the elements for a byte-code
|
|
|
245 function yourself, because if they are inconsistent, Emacs may
|
|
|
246 crash when you call the function. Always leave it to the byte
|
|
|
247 compiler to create these objects; it, we hope, always makes the
|
|
|
248 elements consistent.
|
|
|
249
|
|
|
250 Floating Point Numbers
|
|
|
251 ======================
|
|
|
252
|
|
|
253 You can now use floating point numbers in Emacs, if you define the
|
|
|
254 macro `LISP_FLOAT_TYPE' when you compile Emacs.
|
|
|
255
|
|
|
256 The printed representation for floating point numbers requires
|
|
|
257 either a decimal point surrounded by digits, or an exponent, or both.
|
|
|
258 For example, `1500.0', `15e2', `15.0e2' and `1.5e3' are four ways of
|
|
|
259 writing a floating point number whose value is 1500.
|
|
|
260
|
|
|
261 The existing predicate `numberp' now returns `t' if the argument is
|
|
|
262 any kind of number--either integer or floating. The new predicates
|
|
|
263 `integerp' and `floatp' check for specific types of numbers.
|
|
|
264
|
|
|
265 You can do arithmetic on floating point numbers with the ordinary
|
|
|
266 arithmetic functions, `+', `-', `*' and `/'. If you call one of these
|
|
|
267 functions with both integers and floating point numbers among the
|
|
|
268 arguments, the arithmetic is done in floating point. The same applies
|
|
|
269 to the numeric comparison functions such as `=' and `<'. The remainder
|
|
|
270 function `%' does not accept floating point arguments, and neither do
|
|
|
271 the bitwise boolean operations such as `logand' or the shift functions
|
|
|
272 such as `ash'.
|
|
|
273
|
|
|
274 There is a new arithmetic function, `abs', which returns the absolute
|
|
|
275 value of its argument. It handles both integers and floating point
|
|
|
276 numbers.
|
|
|
277
|
|
|
278 To convert an integer to floating point, use the function `float'.
|
|
|
279 There are four functions to convert floating point numbers to integers;
|
|
|
280 they differ in how they round. `truncate' rounds toward 0, `floor'
|
|
|
281 rounds down, `ceil' rounds up, and `round' produces the nearest integer.
|
|
|
282
|
|
|
283 You can use `logb' to extract the binary exponent of a floating
|
|
|
284 point number. More precisely, it is the logarithm base 2, rounded down
|
|
|
285 to an integer.
|
|
|
286
|
|
|
287 Emacs has several new mathematical functions that accept any kind of
|
|
|
288 number as argument, but always return floating point numbers.
|
|
|
289
|
|
|
290 `cos'
|
|
|
291 `sin'
|
|
|
292 `tan'
|
|
|
293 Trigonometric functions.
|
|
|
294
|
|
|
295 `acos'
|
|
|
296 `asin'
|
|
|
297 `atan'
|
|
|
298 Inverse trigonometric functions.
|
|
|
299
|
|
|
300 `exp'
|
|
|
301 The exponential function (power of E).
|
|
|
302
|
|
|
303 `log'
|
|
|
304 Logarithm base E.
|
|
|
305
|
|
|
306 `log10'
|
|
|
307 Logarithm base 10
|
|
|
308
|
|
|
309 `expt'
|
|
|
310 Raise X to power Y.
|
|
|
311
|
|
|
312 `sqrt'
|
|
|
313 The square root function.
|
|
|
314
|
|
|
315 The new function `string-to-number' now parses a string containing
|
|
|
316 either an integer or a floating point number, returning the number.
|
|
|
317
|
|
|
318 The `format' function now handles the specifications `%e', `%f' and
|
|
|
319 `%g' for printing floating point numbers; likewise `message'.
|
|
|
320
|
|
|
321 The new variable `float-output-format' controls how Lisp prints
|
|
|
322 floating point numbers. Its value should be `nil' or a string.
|
|
|
323
|
|
|
324 If it is a string, it should contain a `%'-spec like those accepted
|
|
|
325 by `printf' in C, but with some restrictions. It must start with the
|
|
|
326 two characters `%.'. After that comes an integer which is the
|
|
|
327 precision specification, and then a letter which controls the format.
|
|
|
328
|
|
|
329 The letters allowed are `e', `f' and `g'. Use `e' for exponential
|
|
|
330 notation (`DIG.DIGITSeEXPT'). Use `f' for decimal point notation
|
|
|
331 (`DIGITS.DIGITS'). Use `g' to choose the shorter of those two formats
|
|
|
332 for the number at hand.
|
|
|
333
|
|
|
334 The precision in any of these cases is the number of digits following
|
|
|
335 the decimal point. With `e', a precision of 0 means to omit the
|
|
|
336 decimal point. 0 is not allowed with `f' or `g'.
|
|
|
337
|
|
|
338 A value of `nil' means to use the format `%.20g'.
|
|
|
339
|
|
|
340 No matter what the value of `float-output-format', printing ensures
|
|
|
341 that the result fits the syntax rules for a floating point number. If
|
|
|
342 it doesn't fit (for example, if it looks like an integer), it is
|
|
|
343 modified to fit. By contrast, the `format' function formats floating
|
|
|
344 point numbers without requiring the output to fit the syntax rules for
|
|
|
345 floating point number.
|
|
|
346
|
|
|
347 New Features for Printing And Formatting Output
|
|
|
348 ===============================================
|
|
|
349
|
|
|
350 * The `format' function has a new feature: `%S'. This print spec
|
|
|
351 prints any kind of Lisp object, even a string, using its Lisp
|
|
|
352 printed representation.
|
|
|
353
|
|
|
354 By contrast, `%s' prints everything without quotation.
|
|
|
355
|
|
|
356 * `prin1-to-string' now takes an optional second argument which says
|
|
|
357 not to print the Lisp quotation characters. (In other words, to
|
|
|
358 use `princ' instead of `prin1'.)
|
|
|
359
|
|
|
360 * The new variable `print-level' specifies the maximum depth of list
|
|
|
361 nesting to print before cutting off all deeper structure. A value
|
|
|
362 of `nil' means no limit.
|
|
|
363
|
|
|
364 Changes in Basic Editing Functions
|
|
|
365 ==================================
|
|
|
366
|
|
|
367 * There are two new primitives for putting text in the kill ring:
|
|
|
368 `kill-new' and `kill-append'.
|
|
|
369
|
|
|
370 The function `kill-new' adds a string to the front of the kill
|
|
|
371 ring.
|
|
|
372
|
|
|
373 Use `kill-append' to add a string to a previous kill. The second
|
|
|
374 argument BEFORE-P, if non-`nil', says to add the string at the
|
|
|
375 beginning; otherwise, it goes at the end.
|
|
|
376
|
|
|
377 Both of these functions apply `interprogram-cut-function' to the
|
|
|
378 entire string of killed text that ends up at the beginning of the
|
|
|
379 kill ring.
|
|
|
380
|
|
|
381 * The new function `current-kill' rotates the yanking pointer in the
|
|
|
382 kill ring by N places, and returns the text at that place in the
|
|
|
383 ring. If the optional second argument DO-NOT-MOVE is non-`nil',
|
|
|
384 it doesn't actually move the yanking point; it just returns the
|
|
|
385 Nth kill forward. If N is zero, indicating a request for the
|
|
|
386 latest kill, `current-kill' calls `interprogram-paste-function'
|
|
|
387 (documented below) before consulting the kill ring.
|
|
|
388
|
|
|
389 All Emacs Lisp programs should either use `current-kill',
|
|
|
390 `kill-new', and `kill-append' to manipulate the kill ring, or be
|
|
|
391 sure to call `interprogram-paste-function' and
|
|
|
392 `interprogram-cut-function' as appropriate.
|
|
|
393
|
|
|
394 * The variables `interprogram-paste-function' and
|
|
|
395 `interprogram-cut-function' exist so that you can provide functions
|
|
|
396 to transfer killed text to and from other programs.
|
|
|
397
|
|
|
398 * The `kill-region' function can now be used in read-only buffers.
|
|
|
399 It beeps, but adds the region to the kill ring without deleting it.
|
|
|
400
|
|
|
401 * The new function `compare-buffer-substrings' lets you compare two
|
|
|
402 substrings of the same buffer or two different buffers. Its
|
|
|
403 arguments look like this:
|
|
|
404
|
|
|
405 (compare-buffer-substrings BUF1 BEG1 END1 BUF2 BEG2 END2)
|
|
|
406
|
|
|
407 The first three arguments specify one substring, giving a buffer
|
|
|
408 and two positions within the buffer. The last three arguments
|
|
|
409 specify the other substring in the same way.
|
|
|
410
|
|
|
411 The value is negative if the first substring is less, positive if
|
|
|
412 the first is greater, and zero if they are equal. The absolute
|
|
|
413 value of the result is one plus the index of the first different
|
|
|
414 characters.
|
|
|
415
|
|
|
416 * Overwrite mode treats tab and newline characters specially. You
|
|
|
417 can now turn off this special treatment by setting
|
|
|
418 `overwrite-binary-mode' to `t'.
|
|
|
419
|
|
|
420 * Once the mark "exists" in a buffer, it normally never ceases to
|
|
|
421 exist. However, in Transient Mark mode, it may become "inactive".
|
|
|
422 The variable `mark-active', which is always local in all buffers,
|
|
|
423 indicates whether the mark is active: non-`nil' means yes.
|
|
|
424
|
|
|
425 When the mark is inactive, the function `mark' normally gets an
|
|
|
426 error. However, `(mark t)' returns the position of the inactive
|
|
|
427 mark.
|
|
|
428
|
|
|
429 The function `push-mark' normally does not activate the mark.
|
|
|
430 However, it accepts an optional third argument ACTIVATE which, if
|
|
|
431 non-`nil', says to activate.
|
|
|
432
|
|
|
433 A command can request deactivation of the mark upon return to the
|
|
|
434 editor command loop by setting `deactivate-mark' to a non-`nil'
|
|
|
435 value. Transient Mark mode works by causing the command loop to
|
|
|
436 take note of `deactivate-mark' and actually deactivate the mark.
|
|
|
437
|
|
|
438 Transient Mark mode enables highlighting of the region when the
|
|
|
439 mark is active. This is currently implemented only under the X
|
|
|
440 Window System. A few other commands vary their behavior slightly
|
|
|
441 in this case, by testing `transient-mark-mode'. More
|
|
|
442 specifically, they avoid special display actions such as moving
|
|
|
443 the cursor temporarily, which are not needed when the region is
|
|
|
444 shown by highlighting.
|
|
|
445
|
|
|
446 The variables `activate-mark-hook' and `deactivate-mark-hook' are
|
|
|
447 normal hooks run, respectively, when the mark becomes active and
|
|
|
448 when it becomes inactive. The hook `activate-mark-hook' is also
|
|
|
449 run at the end of a command if the mark is active and the region
|
|
|
450 may have changed.
|
|
|
451
|
|
|
452 * The function `move-to-column' now accepts a second optional
|
|
|
453 argument FORCE, in addition to COLUMN; if the requested column
|
|
|
454 COLUMN is in the middle of a tab character and FORCE is non-`nil',
|
|
|
455 `move-to-column' replaces the tab with the appropriate sequence of
|
|
|
456 spaces so that it can place point exactly at COLUMN.
|
|
|
457
|
|
|
458 * The search functions when successful now return the value of point
|
|
|
459 rather than just `t'. This affects the functions
|
|
|
460 `search-forward', `search-backward', `word-search-forward',
|
|
|
461 `word-search-backward', `re-search-forward', and
|
|
|
462 `re-search-backward'.
|
|
|
463
|
|
|
464 * When you do regular expression searching or matching, there is no
|
|
|
465 longer a limit to how many `\(...\)' pairs you can get information
|
|
|
466 about with `match-beginning' and `match-end'. Also, these
|
|
|
467 parenthetical groupings may now be nested to any degree.
|
|
|
468
|
|
|
469 * In a regular expression, when you use an asterisk after a
|
|
|
470 parenthetical grouping, and then ask about what range was matched
|
|
|
471 by the grouping, Emacs 19 reports just its last occurrence. Emacs
|
|
|
472 18 used to report the range of all the repetitions put together.
|
|
|
473
|
|
|
474 For example,
|
|
|
475
|
|
|
476 (progn
|
|
|
477 (string-match "f\\(o\\)*" "foo")
|
|
|
478 (list (match-beginning 1)
|
|
|
479 (match-end 1)))
|
|
|
480
|
|
|
481 returns `(2 3)' in Emacs 19, corresponding to just the last
|
|
|
482 repetition of `\(o\)'. In Emacs 18, that expression returns `(1
|
|
|
483 3)', encompassing both repetitions.
|
|
|
484
|
|
|
485 If you want the Emacs 18 behavior, use a grouping *containing* the
|
|
|
486 asterisk: `"f\\(o*\\)"'.
|
|
|
487
|
|
|
488 * The new special form `save-match-data' preserves the regular
|
|
|
489 expression match status. Usage: `(save-match-data BODY...)'.
|
|
|
490
|
|
|
491 * The function `translate-region' applies a translation table to the
|
|
|
492 characters in a part of the buffer. Invoke it as
|
|
|
493 `(translate-region START END TABLE)'; START and END bound the
|
|
|
494 region to translate.
|
|
|
495
|
|
|
496 The translation table TABLE is a string; `(aref TABLE OCHAR)'
|
|
|
497 gives the translated character corresponding to OCHAR. If the
|
|
|
498 length of TABLE is less than 256, any characters with codes larger
|
|
|
499 than the length of TABLE are not altered by the translation.
|
|
|
500
|
|
|
501 `translate-region' returns the number of characters which were
|
|
|
502 actually changed by the translation. This does not count
|
|
|
503 characters which were mapped into themselves in the translation
|
|
|
504 table.
|
|
|
505
|
|
|
506 * There are two new hook variables that let you notice all changes
|
|
|
507 in all buffers (or in a particular buffer, if you make them
|
|
|
508 buffer-local): `before-change-function' and
|
|
|
509 `after-change-function'.
|
|
|
510
|
|
|
511 If `before-change-function' is non-`nil', then it is called before
|
|
|
512 any buffer modification. Its arguments are the beginning and end
|
|
|
513 of the region that is going to change, represented as integers.
|
|
|
514 The buffer that's about to change is always the current buffer.
|
|
|
515
|
|
|
516 If `after-change-function' is non-`nil', then it is called after
|
|
|
517 any buffer modification. It takes three arguments: the beginning
|
|
|
518 and end of the region just changed, and the length of the text that
|
|
|
519 existed before the change. (To get the current length, subtract
|
|
|
520 the region beginning from the region end.) All three arguments are
|
|
|
521 integers. The buffer that has just changed is always the current
|
|
|
522 buffer.
|
|
|
523
|
|
|
524 Both of these variables are temporarily bound to `nil' during the
|
|
|
525 time that either of these hooks is running. This means that if
|
|
|
526 one of these functions changes the buffer, that change won't run
|
|
|
527 these functions. If you do want hooks to be run recursively,
|
|
|
528 write your hook functions to bind these variables back to their
|
|
|
529 usual values.
|
|
|
530
|
|
|
531 * The hook `first-change-hook' is run using `run-hooks' whenever a
|
|
|
532 buffer is changed that was previously in the unmodified state.
|
|
|
533
|
|
|
534 * The second argument to `insert-abbrev-table-description' is now
|
|
|
535 optional.
|
|
|
536
|
|
|
537 Text Properties
|
|
|
538 ===============
|
|
|
539
|
|
|
540 Each character in a buffer or a string can have a "text property
|
|
|
541 list", much like the property list of a symbol. The properties belong
|
|
|
542 to a particular character at a particular place, such as, the letter
|
|
|
543 `T' at the beginning of this sentence. Each property has a name, which
|
|
|
544 is usually a symbol, and an associated value, which can be any Lisp
|
|
|
545 object--just as for properties of symbols.
|
|
|
546
|
|
|
547 You can use the property `face' to control the font and color of
|
|
|
548 text. Several other property names have special meanings. You can
|
|
|
549 create properties of any name and examine them later for your own
|
|
|
550 purposes.
|
|
|
551
|
|
|
552 Copying text between strings and buffers preserves the properties
|
|
|
553 along with the characters; this includes such diverse functions as
|
|
|
554 `substring', `insert', and `buffer-substring'.
|
|
|
555
|
|
|
556 Since text properties are considered part of the buffer contents,
|
|
|
557 changing properties in a buffer "modifies" the buffer, and you can also
|
|
|
558 undo such changes.
|
|
|
559
|
|
|
560 Strings with text properties have a special printed representation
|
|
|
561 which describes all the properties. This representation is also the
|
|
|
562 read syntax for such a string. It looks like this:
|
|
|
563
|
|
|
564 #("CHARACTERS" PROPERTY-DATA...)
|
|
|
565
|
|
|
566 where PROPERTY-DATA is zero or more elements in groups of three as
|
|
|
567 follows:
|
|
|
568
|
|
|
569 BEG END PLIST
|
|
|
570
|
|
|
571 The elements BEG and END are integers, and together specify a portion
|
|
|
572 of the string; PLIST is the property list for that portion.
|
|
|
573
|
|
|
574 Examining Text Properties
|
|
|
575 -------------------------
|
|
|
576
|
|
|
577 The simplest way to examine text properties is to ask for the value
|
|
|
578 of a particular property of a particular character. For that, use
|
|
|
579 `get-text-property'. Use `text-properties-at' to get the entire
|
|
|
580 property list of a character.
|
|
|
581
|
|
|
582 `(get-text-property POS PROP OBJECT)' returns the PROP property of
|
|
|
583 the character after POS in OBJECT (a buffer or string). The argument
|
|
|
584 OBJECT is optional and defaults to the current buffer.
|
|
|
585
|
|
|
586 `(text-properties-at POS OBJECT)' returns the entire property list
|
|
|
587 of the character after POS in the string or buffer OBJECT (which
|
|
|
588 defaults to the current buffer).
|
|
|
589
|
|
|
590 Changing Text Properties
|
|
|
591 ------------------------
|
|
|
592
|
|
|
593 There are four primitives for changing properties of a specified
|
|
|
594 range of text:
|
|
|
595
|
|
|
596 `add-text-properties'
|
|
|
597 This function puts on specified properties, leaving other existing
|
|
|
598 properties unaltered.
|
|
|
599
|
|
|
600 `put-text-property'
|
|
|
601 This function puts on a single specified property, leaving others
|
|
|
602 unaltered.
|
|
|
603
|
|
|
604 `remove-text-properties'
|
|
|
605 This function removes specified properties, leaving other
|
|
|
606 properties unaltered.
|
|
|
607
|
|
|
608 `set-text-properties'
|
|
|
609 This function replaces the entire property list, leaving no
|
|
|
610 vestige of the properties that that text used to have.
|
|
|
611
|
|
|
612 All these functions take four arguments: START, END, PROPS, and
|
|
|
613 OBJECT. The last argument is optional and defaults to the current
|
|
|
614 buffer. The argument PROPS has the form of a property list.
|
|
|
615
|
|
|
616 Property Search Functions
|
|
|
617 -------------------------
|
|
|
618
|
|
|
619 In typical use of text properties, most of the time several or many
|
|
|
620 consecutive characters have the same value for a property. Rather than
|
|
|
621 writing your programs to examine characters one by one, it is much
|
|
|
622 faster to process chunks of text that have the same property value.
|
|
|
623
|
|
|
624 The functions `next-property-change' and `previous-property-change'
|
|
|
625 scan forward or backward from position POS in OBJECT, looking for a
|
|
|
626 change in any property between two characters scanned. They returns
|
|
|
627 the position between those two characters, or `nil' if no change is
|
|
|
628 found.
|
|
|
629
|
|
|
630 The functions `next-single-property-change' and
|
|
|
631 `previous-single-property-change' are similar except that you specify a
|
|
|
632 particular property and they look for changes in the value of that
|
|
|
633 property only. The property is the second argument, and OBJECT is
|
|
|
634 third.
|
|
|
635
|
|
|
636 Special Properties
|
|
|
637 ------------------
|
|
|
638
|
|
|
639 If a character has a `category' property, we call it the "category"
|
|
|
640 of the character. It should be a symbol. The properties of the symbol
|
|
|
641 serve as defaults for the properties of the character.
|
|
|
642
|
|
|
643 You can use the property `face' to control the font and color of
|
|
|
644 text.
|
|
|
645
|
|
|
646 You can specify a different keymap for a portion of the text by means
|
|
|
647 of a `local-map' property. The property's value, for the character
|
|
|
648 after point, replaces the buffer's local map.
|
|
|
649
|
|
|
650 If a character has the property `read-only', then modifying that
|
|
|
651 character is not allowed. Any command that would do so gets an error.
|
|
|
652
|
|
|
653 If a character has the property `modification-hooks', then its value
|
|
|
654 should be a list of functions; modifying that character calls all of
|
|
|
655 those functions. Each function receives two arguments: the beginning
|
|
|
656 and end of the part of the buffer being modified. Note that if a
|
|
|
657 particular modification hook function appears on several characters
|
|
|
658 being modified by a single primitive, you can't predict how many times
|
|
|
659 the function will be called.
|
|
|
660
|
|
|
661 Insertion of text does not, strictly speaking, change any existing
|
|
|
662 character, so there is a special rule for insertion. It compares the
|
|
|
663 `read-only' properties of the two surrounding characters; if they are
|
|
|
664 `eq', then the insertion is not allowed. Assuming insertion is
|
|
|
665 allowed, it then gets the `modification-hooks' properties of those
|
|
|
666 characters and calls all the functions in each of them. (If a function
|
|
|
667 appears on both characters, it may be called once or twice.)
|
|
|
668
|
|
|
669 The special properties `point-entered' and `point-left' record hook
|
|
|
670 functions that report motion of point. Each time point moves, Emacs
|
|
|
671 compares these two property values:
|
|
|
672
|
|
|
673 * the `point-left' property of the character after the old location,
|
|
|
674 and
|
|
|
675
|
|
|
676 * the `point-entered' property of the character after the new
|
|
|
677 location.
|
|
|
678
|
|
|
679 If these two values differ, each of them is called (if not `nil') with
|
|
|
680 two arguments: the old value of point, and the new one.
|
|
|
681
|
|
|
682 The same comparison is made for the characters before the old and new
|
|
|
683 locations. The result may be to execute two `point-left' functions
|
|
|
684 (which may be the same function) and/or two `point-entered' functions
|
|
|
685 (which may be the same function). The `point-left' functions are
|
|
|
686 always called before the `point-entered' functions.
|
|
|
687
|
|
|
688 A primitive function may examine characters at various positions
|
|
|
689 without moving point to those positions. Only an actual change in the
|
|
|
690 value of point runs these hook functions.
|
|
|
691
|
|
|
692 New Features for Files
|
|
|
693 ======================
|
|
|
694
|
|
|
695 * The new function `file-accessible-directory-p' tells you whether
|
|
|
696 you can open files in a particular directory. Specify as an
|
|
|
697 argument either a directory name or a file name which names a
|
|
|
698 directory file. The function returns `t' if you can open existing
|
|
|
699 files in that directory.
|
|
|
700
|
|
|
701 * The new function `file-executable-p' returns `t' if its argument
|
|
|
702 is the name of a file you have permission to execute.
|
|
|
703
|
|
|
704 * The function `file-truename' returns the "true name" of a
|
|
|
705 specified file. This is the name that you get by following
|
|
|
706 symbolic links until none remain. The argument must be an
|
|
|
707 absolute file name.
|
|
|
708
|
|
|
709 * New functions `make-directory' and `delete-directory' create and
|
|
|
710 delete directories. They both take one argument, which is the
|
|
|
711 name of the directory as a file.
|
|
|
712
|
|
|
713 * The function `read-file-name' now takes an additional argument
|
|
|
714 which specifies an initial file name. If you specify this
|
|
|
715 argument, `read-file-name' inserts it along with the directory
|
|
|
716 name. It puts the cursor between the directory and the initial
|
|
|
717 file name.
|
|
|
718
|
|
|
719 The user can then use the initial file name unchanged, modify it,
|
|
|
720 or simply kill it with `C-k'.
|
|
|
721
|
|
|
722 If the variable `insert-default-directory' is `nil', then the
|
|
|
723 default directory is not inserted, and the new argument is ignored.
|
|
|
724
|
|
|
725 * The function `file-relative-name' does the inverse of
|
|
|
726 expansion--it tries to return a relative name which is equivalent
|
|
|
727 to FILENAME when interpreted relative to DIRECTORY. (If such a
|
|
|
728 relative name would be longer than the absolute name, it returns
|
|
|
729 the absolute name instead.)
|
|
|
730
|
|
|
731 * The function `file-newest-backup' returns the name of the most
|
|
|
732 recent backup file for FILENAME, or `nil' that file has no backup
|
|
|
733 files.
|
|
|
734
|
|
|
735 * The list returned by `file-attributes' now has 12 elements. The
|
|
|
736 12th element is the file system number of the file system that the
|
|
|
737 file is in. This element together with the file's inode number,
|
|
|
738 which is the 11th element, give enough information to distinguish
|
|
|
739 any two files on the system--no two files can have the same values
|
|
|
740 for both of these numbers.
|
|
|
741
|
|
|
742 * The new function `set-visited-file-modtime' updates the current
|
|
|
743 buffer's recorded modification time from the visited file's time.
|
|
|
744
|
|
|
745 This is useful if the buffer was not read from the file normally,
|
|
|
746 or if the file itself has been changed for some known benign
|
|
|
747 reason.
|
|
|
748
|
|
|
749 If you give the function an argument, that argument specifies the
|
|
|
750 new value for the recorded modification time. The argument should
|
|
|
751 be a list of the form `(HIGH . LOW)' or `(HIGH LOW)' containing
|
|
|
752 two integers, each of which holds 16 bits of the time. (This is
|
|
|
753 the same format that `file-attributes' uses to return time values.)
|
|
|
754
|
|
|
755 The new function `visited-file-modtime' returns the recorded last
|
|
|
756 modification time, in that same format.
|
|
|
757
|
|
|
758 * The function `directory-files' now takes an optional fourth
|
|
|
759 argument which, if non-`nil', inhibits sorting the file names.
|
|
|
760 Use this if you want the utmost possible speed and don't care what
|
|
|
761 order the files are processed in.
|
|
|
762
|
|
|
763 If the order of processing is at all visible to the user, then the
|
|
|
764 user will probably be happier if you do sort the names.
|
|
|
765
|
|
|
766 * The variable `directory-abbrev-alist' contains an alist of
|
|
|
767 abbreviations to use for file directories. Each element has the
|
|
|
768 form `(FROM . TO)', and says to replace FROM with TO when it
|
|
|
769 appears in a directory name. This replacement is done when
|
|
|
770 setting up the default directory of a newly visited file. The
|
|
|
771 FROM string is actually a regular expression; it should always
|
|
|
772 start with `^'.
|
|
|
773
|
|
|
774 You can set this variable in `site-init.el' to describe the
|
|
|
775 abbreviations appropriate for your site.
|
|
|
776
|
|
|
777 * The function `abbreviate-file-name' applies abbreviations from
|
|
|
778 `directory-abbrev-alist' to its argument, and substitutes `~' for
|
|
|
779 the user's home directory.
|
|
|
780
|
|
|
781 Abbreviated directory names are useful for directories that are
|
|
|
782 normally accessed through symbolic links. If you think of the
|
|
|
783 link's name as "the name" of the directory, you can define it as
|
|
|
784 an abbreviation for the directory's official name; then ordinarily
|
|
|
785 Emacs will call that directory by the link name you normally use.
|
|
|
786
|
|
|
787 * `write-region' can write a given string instead of text from the
|
|
|
788 buffer. Use the string as the first argument (in place of the
|
|
|
789 starting character position).
|
|
|
790
|
|
|
791 You can supply a second file name as the fifth argument (VISIT).
|
|
|
792 Use this to write the data to one file (the first argument,
|
|
|
793 FILENAME) while nominally visiting a different file (the fifth
|
|
|
794 argument, VISIT). The argument VISIT is used in the echo area
|
|
|
795 message and also for file locking; VISIT is stored in
|
|
|
796 `buffer-file-name'.
|
|
|
797
|
|
|
798 * The value of `write-file-hooks' does not change when you switch to
|
|
|
799 a new major mode. The intention is that these hooks have to do
|
|
|
800 with where the file came from, and not with what it contains.
|
|
|
801
|
|
|
802 * There is a new hook variable for saving files:
|
|
|
803 `write-contents-hooks'. It works just like `write-file-hooks'
|
|
|
804 except that switching to a new major mode clears it back to `nil'.
|
|
|
805 Major modes should use this hook variable rather than
|
|
|
806 `write-file-hooks'.
|
|
|
807
|
|
|
808 * The hook `after-save-buffer-hook' runs just after a buffer has been
|
|
|
809 saved in its visited file.
|
|
|
810
|
|
|
811 * The new function `set-default-file-modes' sets the file protection
|
|
|
812 for new files created with Emacs. The argument must be an
|
|
|
813 integer. (It would be better to permit symbolic arguments like
|
|
|
814 the `chmod' program, but that would take more work than this
|
|
|
815 function merits.)
|
|
|
816
|
|
|
817 Use the new function `default-file-modes' to read the current
|
|
|
818 default file mode.
|
|
|
819
|
|
|
820 * Call the new function `unix-sync' to force all pending disk output
|
|
|
821 to happen as soon as possible.
|
|
|
822
|
|
|
823 Making Certain File Names "Magic"
|
|
|
824 =================================
|
|
|
825
|
|
|
826 You can implement special handling for a class of file names. You
|
|
|
827 must supply a regular expression to define the class of names (all those
|
|
|
828 which match the regular expression), plus a handler that implements all
|
|
|
829 the primitive Emacs file operations for file names that do match.
|
|
|
830
|
|
|
831 The value of `file-name-handler-alist' is a list of handlers,
|
|
|
832 together with regular expressions that decide when to apply each
|
|
|
833 handler. Each element has the form `(REGEXP . HANDLER)'. If a file
|
|
|
834 name matches REGEXP, then all work on that file is done by calling
|
|
|
835 HANDLER.
|
|
|
836
|
|
|
837 All the Emacs primitives for file access and file name transformation
|
|
|
838 check the given file name against `file-name-handler-alist', and call
|
|
|
839 HANDLER to do the work if appropriate. The first argument given to
|
|
|
840 HANDLER is the name of the primitive; the remaining arguments are the
|
|
|
841 arguments that were passed to that primitive. (The first of these
|
|
|
842 arguments is typically the file name itself.) For example, if you do
|
|
|
843 this:
|
|
|
844
|
|
|
845 (file-exists-p FILENAME)
|
|
|
846
|
|
|
847 and FILENAME has handler HANDLER, then HANDLER is called like this:
|
|
|
848
|
|
|
849 (funcall HANDLER 'file-exists-p FILENAME)
|
|
|
850
|
|
|
851 Here are the primitives that you can handle in this way:
|
|
|
852
|
|
|
853 `add-name-to-file', `copy-file', `delete-directory',
|
|
|
854 `delete-file', `directory-file-name', `directory-files',
|
|
|
855 `dired-compress-file', `dired-uncache', `expand-file-name',
|
|
|
856 `file-accessible-directory-p', `file-attributes',
|
|
|
857 `file-directory-p', `file-executable-p', `file-exists-p',
|
|
|
858 `file-local-copy', `file-modes', `file-name-all-completions',
|
|
|
859 `file-name-as-directory', `file-name-completion',
|
|
|
860 `file-name-directory', `file-name-nondirectory',
|
|
|
861 `file-name-sans-versions', `file-newer-than-file-p',
|
|
|
862 `file-readable-p', `file-symlink-p', `file-writable-p',
|
|
|
863 `insert-directory', `insert-file-contents', `load',
|
|
|
864 `make-directory', `make-symbolic-link', `rename-file',
|
|
|
865 `set-file-modes', `set-visited-file-modtime',
|
|
|
866 `unhandled-file-name-directory', `verify-visited-file-modtime',
|
|
|
867 `write-region'.
|
|
|
868
|
|
|
869 The handler function must handle all of the above operations, and
|
|
|
870 possibly others to be added in the future. Therefore, it should always
|
|
|
871 reinvoke the ordinary Lisp primitive when it receives an operation it
|
|
|
872 does not recognize. Here's one way to do this:
|
|
|
873
|
|
|
874 (defun my-file-handler (operation &rest args)
|
|
|
875 ;; First check for the specific operations
|
|
|
876 ;; that we have special handling for.
|
|
|
877 (cond ((eq operation 'insert-file-contents) ...)
|
|
|
878 ((eq operation 'write-region) ...)
|
|
|
879 ...
|
|
|
880 ;; Handle any operation we don't know about.
|
|
|
881 (t (let (file-name-handler-alist)
|
|
|
882 (apply operation args)))))
|
|
|
883
|
|
|
884 The function `file-local-copy' copies file FILENAME to the local
|
|
|
885 site, if it isn't there already. If FILENAME specifies a "magic" file
|
|
|
886 name which programs outside Emacs cannot directly read or write, this
|
|
|
887 copies the contents to an ordinary file and returns that file's name.
|
|
|
888
|
|
|
889 If FILENAME is an ordinary file name, not magic, then this function
|
|
|
890 does nothing and returns `nil'.
|
|
|
891
|
|
|
892 The function `unhandled-file-name-directory' is used to get a
|
|
|
893 non-magic directory name from an arbitrary file name. It uses the
|
|
|
894 directory part of the specified file name if that is not magic.
|
|
|
895 Otherwise, it asks the file name's handler what to do.
|
|
|
896
|
|
|
897 Frames
|
|
|
898 ======
|
|
|
899
|
|
|
900 Emacs now supports multiple X windows via a new data type known as a
|
|
|
901 "frame".
|
|
|
902
|
|
|
903 A frame is a rectangle on the screen that contains one or more Emacs
|
|
|
904 windows. Subdividing a frame works just like subdividing the screen in
|
|
|
905 earlier versions of Emacs.
|
|
|
906
|
|
|
907 There are two kinds of frames: terminal frames and X window frames.
|
|
|
908 Emacs creates one terminal frame when it starts up with no X display; it
|
|
|
909 uses Termcap or Terminfo to display using characters. There is no way
|
|
|
910 to create another terminal frame after startup. If Emacs has an X
|
|
|
911 display, it does not make a terminal frame, and there is none.
|
|
|
912
|
|
|
913 When you are using X windows, Emacs starts out with a single X window
|
|
|
914 frame. You can create any number of X window frames using `make-frame'.
|
|
|
915
|
|
|
916 Use the predicate `framep' to determine whether a given Lisp object
|
|
|
917 is a frame.
|
|
|
918
|
|
|
919 The function `redraw-frame' redisplays the entire contents of a
|
|
|
920 given frame.
|
|
|
921
|
|
|
922 Creating and Deleting Frames
|
|
|
923 ----------------------------
|
|
|
924
|
|
|
925 Use `make-frame' to create a new frame. This is the only primitive
|
|
|
926 for creating frames. In principle it could work under any window system
|
|
|
927 which Emacs understands; the only one we support is X.
|
|
|
928
|
|
|
929 `make-frame' takes just one argument, which is an alist specifying
|
|
|
930 frame parameters. Any parameters not mentioned in the argument alist
|
|
|
931 default based on the value of `default-frame-alist'; parameters not
|
|
|
932 specified there default from the standard X defaults file and X
|
|
|
933 resources.
|
|
|
934
|
|
|
935 When you invoke Emacs, if you specify arguments for window appearance
|
|
|
936 and so forth, these go into `default-frame-alist' and that is how they
|
|
|
937 have their effect.
|
|
|
938
|
|
|
939 You can specify the parameters for the initial startup X window
|
|
|
940 frame by setting `initial-frame-alist' in your `.emacs' file. If these
|
|
|
941 parameters specify a separate minibuffer-only frame, and you have not
|
|
|
942 created one, Emacs creates one for you, using the parameter values
|
|
|
943 specified in `minibuffer-frame-alist'.
|
|
|
944
|
|
|
945 You can specify the size and position of a frame using the frame
|
|
|
946 parameters `left', `top', `height' and `width'. You must specify
|
|
|
947 either both size parameters or neither. You must specify either both
|
|
|
948 position parameters or neither. The geometry parameters that you don't
|
|
|
949 specify are chosen by the window manager in its usual fashion.
|
|
|
950
|
|
|
951 The function `x-parse-geometry' converts a standard X-style geometry
|
|
|
952 string to an alist which you can use as part of the argument to
|
|
|
953 `make-frame'.
|
|
|
954
|
|
|
955 Use the function `delete-frame' to eliminate a frame. Frames are
|
|
|
956 like buffers where deletion is concerned; a frame actually continues to
|
|
|
957 exist as a Lisp object until it is deleted *and* there are no
|
|
|
958 references to it, but once it is deleted, it has no further effect on
|
|
|
959 the screen.
|
|
|
960
|
|
|
961 The function `frame-live-p' returns non-`nil' if the argument (a
|
|
|
962 frame) has not been deleted.
|
|
|
963
|
|
|
964 Finding All Frames
|
|
|
965 ------------------
|
|
|
966
|
|
|
967 The function `frame-list' returns a list of all the frames that have
|
|
|
968 not been deleted. It is analogous to `buffer-list'. The list that you
|
|
|
969 get is newly created, so modifying the list doesn't have any effect on
|
|
|
970 the internals of Emacs. The function `visible-frame-list' returns the
|
|
|
971 list of just the frames that are visible.
|
|
|
972
|
|
|
973 `next-frame' lets you cycle conveniently through all the frames from
|
|
|
974 an arbitrary starting point. Its first argument is a frame. Its second
|
|
|
975 argument MINIBUF says what to do about minibuffers:
|
|
|
976
|
|
|
977 `nil'
|
|
|
978 Exclude minibuffer-only frames.
|
|
|
979
|
|
|
980 a window
|
|
|
981 Consider only the frames using that particular window as their
|
|
|
982 minibuffer.
|
|
|
983
|
|
|
984 anything else
|
|
|
985 Consider all frames.
|
|
|
986
|
|
|
987 Frames and Windows
|
|
|
988 ------------------
|
|
|
989
|
|
|
990 All the non-minibuffer windows in a frame are arranged in a tree of
|
|
|
991 subdivisions; the root of this tree is available via the function
|
|
|
992 `frame-root-window'. Each window is part of one and only one frame;
|
|
|
993 you can get the frame with `window-frame'.
|
|
|
994
|
|
|
995 At any time, exactly one window on any frame is "selected within the
|
|
|
996 frame". You can get the frame's current selected window with
|
|
|
997 `frame-selected-window'. The significance of this designation is that
|
|
|
998 selecting the frame selects for Emacs as a whole the window currently
|
|
|
999 selected within that frame.
|
|
|
1000
|
|
|
1001 Conversely, selecting a window for Emacs with `select-window' also
|
|
|
1002 makes that window selected within its frame.
|
|
|
1003
|
|
|
1004 Frame Visibility
|
|
|
1005 ----------------
|
|
|
1006
|
|
|
1007 A frame may be "visible", "invisible", or "iconified". If it is
|
|
|
1008 invisible, it doesn't show in the screen, not even as an icon. You can
|
|
|
1009 set the visibility status of a frame with `make-frame-visible',
|
|
|
1010 `make-frame-invisible', and `iconify-frame'. You can examine the
|
|
|
1011 visibility status with `frame-visible-p'--it returns `t' for a visible
|
|
|
1012 frame, `nil' for an invisible frame, and `icon' for an iconified frame.
|
|
|
1013
|
|
|
1014 Selected Frame
|
|
|
1015 --------------
|
|
|
1016
|
|
|
1017 At any time, one frame in Emacs is the "selected frame". The
|
|
|
1018 selected window always resides on the selected frame.
|
|
|
1019
|
|
|
1020 - Function: selected-frame
|
|
|
1021 This function returns the selected frame.
|
|
|
1022
|
|
|
1023 The X server normally directs keyboard input to the X window that the
|
|
|
1024 mouse is in. Some window managers use mouse clicks or keyboard events
|
|
|
1025 to "shift the focus" to various X windows, overriding the normal
|
|
|
1026 behavior of the server.
|
|
|
1027
|
|
|
1028 Lisp programs can switch frames "temporarily" by calling the function
|
|
|
1029 `select-frame'. This does not override the window manager; rather, it
|
|
|
1030 escapes from the window manager's control until that control is somehow
|
|
|
1031 reasserted. The function takes one argument, a frame, and selects that
|
|
|
1032 frame. The selection lasts until the next time the user does something
|
|
|
1033 to select a different frame, or until the next time this function is
|
|
|
1034 called.
|
|
|
1035
|
|
|
1036 Emacs cooperates with the X server and the window managers by
|
|
|
1037 arranging to select frames according to what the server and window
|
|
|
1038 manager ask for. It does so by generating a special kind of input
|
|
|
1039 event, called a "focus" event. The command loop handles a focus event
|
|
|
1040 by calling `internal-select-frame'.
|
|
|
1041
|
|
|
1042 Frame Size and Position
|
|
|
1043 -----------------------
|
|
|
1044
|
|
|
1045 The new functions `frame-height' and `frame-width' return the height
|
|
|
1046 and width of a specified frame (or of the selected frame), measured in
|
|
|
1047 characters.
|
|
|
1048
|
|
|
1049 The new functions `frame-pixel-height' and `frame-pixel-width'
|
|
|
1050 return the height and width of a specified frame (or of the selected
|
|
|
1051 frame), measured in pixels.
|
|
|
1052
|
|
|
1053 The new functions `frame-char-height' and `frame-char-width' return
|
|
|
1054 the height and width of a character in a specified frame (or in the
|
|
|
1055 selected frame), measured in pixels.
|
|
|
1056
|
|
|
1057 `set-frame-size' sets the size of a frame, measured in characters;
|
|
|
1058 its arguments are FRAME, COLS and ROWS. To set the size with values
|
|
|
1059 measured in pixels, you can use `modify-frame-parameters'.
|
|
|
1060
|
|
|
1061 The function `set-frame-position' sets the position of the top left
|
|
|
1062 corner of a frame. Its arguments are FRAME, LEFT and TOP.
|
|
|
1063
|
|
|
1064 Frame Parameters
|
|
|
1065 ----------------
|
|
|
1066
|
|
|
1067 A frame has many parameters that affect how it displays. Use the
|
|
|
1068 function `frame-parameters' to get an alist of all the parameters of a
|
|
|
1069 given frame. To alter parameters, use `modify-frame-parameters', which
|
|
|
1070 takes two arguments: the frame to modify, and an alist of parameters to
|
|
|
1071 change and their new values. Each element of ALIST has the form `(PARM
|
|
|
1072 . VALUE)', where PARM is a symbol. Parameters that aren't meaningful
|
|
|
1073 are ignored. If you don't mention a parameter in ALIST, its value
|
|
|
1074 doesn't change.
|
|
|
1075
|
|
|
1076 Just what parameters a frame has depends on what display mechanism it
|
|
|
1077 uses. Here is a table of the parameters of an X window frame:
|
|
|
1078
|
|
|
1079 `name'
|
|
|
1080 The name of the frame.
|
|
|
1081
|
|
|
1082 `left'
|
|
|
1083 The screen position of the left edge.
|
|
|
1084
|
|
|
1085 `top'
|
|
|
1086 The screen position of the top edge.
|
|
|
1087
|
|
|
1088 `height'
|
|
|
1089 The height of the frame contents, in pixels.
|
|
|
1090
|
|
|
1091 `width'
|
|
|
1092 The width of the frame contents, in pixels.
|
|
|
1093
|
|
|
1094 `window-id'
|
|
|
1095 The number of the X window for the frame.
|
|
|
1096
|
|
|
1097 `minibuffer'
|
|
|
1098 Whether this frame has its own minibuffer. `t' means yes, `none'
|
|
|
1099 means no, `only' means this frame is just a minibuffer, a
|
|
|
1100 minibuffer window (in some other frame) means the new frame uses
|
|
|
1101 that minibuffer.
|
|
|
1102
|
|
|
1103 `font'
|
|
|
1104 The name of the font for the text.
|
|
|
1105
|
|
|
1106 `foreground-color'
|
|
|
1107 The color to use for the inside of a character. Use strings to
|
|
|
1108 designate colors; the X server defines the meaningful color names.
|
|
|
1109
|
|
|
1110 `background-color'
|
|
|
1111 The color to use for the background of text.
|
|
|
1112
|
|
|
1113 `mouse-color'
|
|
|
1114 The color for the mouse cursor.
|
|
|
1115
|
|
|
1116 `cursor-color'
|
|
|
1117 The color for the cursor that shows point.
|
|
|
1118
|
|
|
1119 `border-color'
|
|
|
1120 The color for the border of the frame.
|
|
|
1121
|
|
|
1122 `cursor-type'
|
|
|
1123 The way to display the cursor. There are two legitimate values:
|
|
|
1124 `bar' and `box'. The value `bar' specifies a vertical bar between
|
|
|
1125 characters as the cursor. The value `box' specifies an ordinary
|
|
|
1126 black box overlaying the character after point; that is the
|
|
|
1127 default.
|
|
|
1128
|
|
|
1129 `icon-type'
|
|
|
1130 Non-`nil' for a bitmap icon, `nil' for a text icon.
|
|
|
1131
|
|
|
1132 `border-width'
|
|
|
1133 The width in pixels of the window border.
|
|
|
1134
|
|
|
1135 `internal-border-width'
|
|
|
1136 The distance in pixels between text and border.
|
|
|
1137
|
|
|
1138 `auto-raise'
|
|
|
1139 Non-`nil' means selecting the frame raises it.
|
|
|
1140
|
|
|
1141 `auto-lower'
|
|
|
1142 Non-`nil' means deselecting the frame lowers it.
|
|
|
1143
|
|
|
1144 `vertical-scroll-bars'
|
|
|
1145 Non-`nil' gives the frame a scroll bar for vertical scrolling.
|
|
|
1146
|
|
|
1147 Minibufferless Frames
|
|
|
1148 ---------------------
|
|
|
1149
|
|
|
1150 Normally, each frame has its own minibuffer window at the bottom,
|
|
|
1151 which is used whenever that frame is selected. However, you can also
|
|
|
1152 create frames with no minibuffers. These frames must use the
|
|
|
1153 minibuffer window of some other frame.
|
|
|
1154
|
|
|
1155 The variable `default-minibuffer-frame' specifies where to find a
|
|
|
1156 minibuffer for frames created without minibuffers of their own. Its
|
|
|
1157 value should be a frame which does have a minibuffer.
|
|
|
1158
|
|
|
1159 You can also specify a minibuffer window explicitly when you create a
|
|
|
1160 frame; then `default-minibuffer-frame' is not used.
|
|
|
1161
|
|
|
1162 X Window System Features
|
|
|
1163 ========================
|
|
|
1164
|
|
|
1165 * The new functions `mouse-position' and `set-mouse-position' give
|
|
|
1166 access to the current position of the mouse.
|
|
|
1167
|
|
|
1168 `mouse-position' returns a description of the position of the
|
|
|
1169 mouse. The value looks like `(FRAME X . Y)', where X and Y are
|
|
|
1170 measured in pixels relative to the top left corner of the inside
|
|
|
1171 of FRAME.
|
|
|
1172
|
|
|
1173 `set-mouse-position' takes three arguments, FRAME, X and Y, and
|
|
|
1174 warps the mouse cursor to that location on the screen.
|
|
|
1175
|
|
|
1176 * `track-mouse' is a new special form for tracking mouse motion.
|
|
|
1177 Use it in definitions of mouse clicks that want pay to attention to
|
|
|
1178 the motion of the mouse, not just where the buttons are pressed and
|
|
|
1179 released. Here is how to use it:
|
|
|
1180
|
|
|
1181 (track-mouse BODY...)
|
|
|
1182
|
|
|
1183 While BODY executes, mouse motion generates input events just as
|
|
|
1184 mouse clicks do. BODY can read them with `read-event' or
|
|
|
1185 `read-key-sequence'.
|
|
|
1186
|
|
|
1187 `track-mouse' returns the value of the last form in BODY.
|
|
|
1188
|
|
|
1189 The format of these events is described under "New Input Event
|
|
|
1190 Formats."
|
|
|
1191
|
|
|
1192 * `x-set-selection' sets a "selection" in the X server. It takes
|
|
|
1193 two arguments: a selection type TYPE, and the value to assign to
|
|
|
1194 it, DATA. If DATA is `nil', it means to clear out the selection.
|
|
|
1195 Otherwise, DATA may be a string, a symbol, an integer (or a cons
|
|
|
1196 of two integers or list of two integers), or a cons of two markers
|
|
|
1197 pointing to the same buffer. In the last case, the selection is
|
|
|
1198 considered to be the text between the markers. The data may also
|
|
|
1199 be a vector of valid non-vector selection values.
|
|
|
1200
|
|
|
1201 Each possible TYPE has its own selection value, which changes
|
|
|
1202 independently. The usual values of TYPE are `PRIMARY' and
|
|
|
1203 `SECONDARY'; these are symbols with upper-case names, in accord
|
|
|
1204 with X protocol conventions. The default is `PRIMARY'.
|
|
|
1205
|
|
|
1206 To get the value of the selection, call `x-get-selection'. This
|
|
|
1207 function accesses selections set up by Emacs and those set up by
|
|
|
1208 other X clients. It takes two optional arguments, TYPE and
|
|
|
1209 DATA-TYPE. The default for TYPE is `PRIMARY'.
|
|
|
1210
|
|
|
1211 The DATA-TYPE argument specifies the form of data conversion to
|
|
|
1212 use; meaningful values include `TEXT', `STRING', `TARGETS',
|
|
|
1213 `LENGTH', `DELETE', `FILE_NAME', `CHARACTER_POSITION',
|
|
|
1214 `LINE_NUMBER', `COLUMN_NUMBER', `OWNER_OS', `HOST_NAME', `USER',
|
|
|
1215 `CLASS', `NAME', `ATOM', and `INTEGER'. (These are symbols with
|
|
|
1216 upper-case names in accord with X Windows conventions.) The
|
|
|
1217 default for DATA-TYPE is `STRING'.
|
|
|
1218
|
|
|
1219 * The X server has a set of numbered "cut buffers" which can store
|
|
|
1220 text or other data being moved between applications. Use
|
|
|
1221 `x-get-cut-buffer' to get the contents of a cut buffer; specify the
|
|
|
1222 cut buffer number as argument. Use `x-set-cut-buffer' with
|
|
|
1223 argument STRING to store a new string into the first cut buffer
|
|
|
1224 (moving the other values down through the series of cut buffers,
|
|
|
1225 kill-ring-style).
|
|
|
1226
|
|
|
1227 Cut buffers are considered obsolete, but Emacs supports them for
|
|
|
1228 the sake of X clients that still use them.
|
|
|
1229
|
|
|
1230 * You can close the connection with the X server with the function
|
|
|
1231 `x-close-current-connection'. This takes no arguments.
|
|
|
1232
|
|
|
1233 Then you can connect to a different X server with
|
|
|
1234 `x-open-connection'. The first argument, DISPLAY, is the name of
|
|
|
1235 the display to connect to.
|
|
|
1236
|
|
|
1237 The optional second argument XRM-STRING is a string of resource
|
|
|
1238 names and values, in the same format used in the `.Xresources'
|
|
|
1239 file. The values you specify override the resource values
|
|
|
1240 recorded in the X server itself. Here's an example of what this
|
|
|
1241 string might look like:
|
|
|
1242
|
|
|
1243 "*BorderWidth: 3\n*InternalBorder: 2\n"
|
|
|
1244
|
|
|
1245 * A series of new functions give you information about the X server
|
|
|
1246 and the screen you are using.
|
|
|
1247
|
|
|
1248 `x-display-screens'
|
|
|
1249 The number of screens associated with the current display.
|
|
|
1250
|
|
|
1251 `x-server-version'
|
|
|
1252 The version numbers of the X server in use.
|
|
|
1253
|
|
|
1254 `x-server-vendor'
|
|
|
1255 The vendor supporting the X server in use.
|
|
|
1256
|
|
|
1257 `x-display-pixel-height'
|
|
|
1258 The height of this X screen in pixels.
|
|
|
1259
|
|
|
1260 `x-display-mm-height'
|
|
|
1261 The height of this X screen in millimeters.
|
|
|
1262
|
|
|
1263 `x-display-pixel-width'
|
|
|
1264 The width of this X screen in pixels.
|
|
|
1265
|
|
|
1266 `x-display-mm-width'
|
|
|
1267 The width of this X screen in millimeters.
|
|
|
1268
|
|
|
1269 `x-display-backing-store'
|
|
|
1270 The backing store capability of this screen. Values can be
|
|
|
1271 the symbols `always', `when-mapped', or `not-useful'.
|
|
|
1272
|
|
|
1273 `x-display-save-under'
|
|
|
1274 Non-`nil' if this X screen supports the SaveUnder feature.
|
|
|
1275
|
|
|
1276 `x-display-planes'
|
|
|
1277 The number of planes this display supports.
|
|
|
1278
|
|
|
1279 `x-display-visual-class'
|
|
|
1280 The visual class for this X screen. The value is one of the
|
|
|
1281 symbols `static-gray', `gray-scale', `static-color',
|
|
|
1282 `pseudo-color', `true-color', and `direct-color'.
|
|
|
1283
|
|
|
1284 `x-display-color-p'
|
|
|
1285 `t' if the X screen in use is a color screen.
|
|
|
1286
|
|
|
1287 `x-display-color-cells'
|
|
|
1288 The number of color cells this X screen supports.
|
|
|
1289
|
|
|
1290 There is also a variable `x-no-window-manager', whose value is `t'
|
|
|
1291 if no X window manager is in use.
|
|
|
1292
|
|
|
1293 * The function `x-synchronize' enables or disables an X Windows
|
|
|
1294 debugging mode: synchronous communication. It takes one argument,
|
|
|
1295 non-`nil' to enable the mode and `nil' to disable.
|
|
|
1296
|
|
|
1297 In synchronous mode, Emacs waits for a response to each X protocol
|
|
|
1298 command before doing anything else. This means that errors are
|
|
|
1299 reported right away, and you can directly find the erroneous
|
|
|
1300 command. Synchronous mode is not the default because it is much
|
|
|
1301 slower.
|
|
|
1302
|
|
|
1303 * The function `x-get-resource' retrieves a resource value from the X
|
|
|
1304 Windows defaults database. Its three arguments are ATTRIBUTE,
|
|
|
1305 NAME and CLASS. It searches using a key of the form
|
|
|
1306 `INSTANCE.ATTRIBUTE', with class `Emacs', where INSTANCE is the
|
|
|
1307 name under which Emacs was invoked.
|
|
|
1308
|
|
|
1309 The optional arguments COMPONENT and SUBCLASS add to the key and
|
|
|
1310 the class, respectively. You must specify both of them or neither.
|
|
|
1311 If you specify them, the key is `INSTANCE.COMPONENT.ATTRIBUTE',
|
|
|
1312 and the class is `Emacs.SUBCLASS'.
|
|
|
1313
|
|
|
1314 * `x-display-color-p' returns `t' if you are using an X server with
|
|
|
1315 a color display, and `nil' otherwise.
|
|
|
1316
|
|
|
1317 `x-color-defined-p' takes as argument a string describing a color;
|
|
|
1318 it returns `t' if the display supports that color. (If the color
|
|
|
1319 is `"black"' or `"white"' then even black-and-white displays
|
|
|
1320 support it.)
|
|
|
1321
|
|
|
1322 * `x-popup-menu' has been generalized. It now accepts a keymap as
|
|
|
1323 the MENU argument. Then the menu items are the prompt strings of
|
|
|
1324 individual key bindings, and the item values are the keys which
|
|
|
1325 have those bindings.
|
|
|
1326
|
|
|
1327 You can also supply a list of keymaps as the first argument; then
|
|
|
1328 each keymap makes one menu pane (but keymaps that don't provide
|
|
|
1329 any menu items don't appear in the menu at all).
|
|
|
1330
|
|
|
1331 `x-popup-menu' also accepts a mouse button event as the POSITION
|
|
|
1332 argument. Then it displays the menu at the location at which the
|
|
|
1333 event took place. This is convenient for mouse-invoked commands
|
|
|
1334 that pop up menus.
|
|
|
1335
|
|
|
1336 * You can use the function `x-rebind-key' to change the sequence of
|
|
|
1337 characters generated by the X server for one of the keyboard keys.
|
|
|
1338
|
|
|
1339 The first two arguments, KEYCODE and SHIFT-MASK, should be numbers
|
|
|
1340 representing the keyboard code and shift mask respectively. They
|
|
|
1341 specify what key to change.
|
|
|
1342
|
|
|
1343 The third argument, NEWSTRING, is the new definition of the key.
|
|
|
1344 It is a sequence of characters that the key should produce as
|
|
|
1345 input.
|
|
|
1346
|
|
|
1347 The shift mask value is a combination of bits according to this
|
|
|
1348 table:
|
|
|
1349
|
|
|
1350 8
|
|
|
1351 Control
|
|
|
1352
|
|
|
1353 4
|
|
|
1354 Meta
|
|
|
1355
|
|
|
1356 2
|
|
|
1357 Shift
|
|
|
1358
|
|
|
1359 1
|
|
|
1360 Shift Lock
|
|
|
1361
|
|
|
1362 If you specify `nil' for SHIFT-MASK, then the key specified by
|
|
|
1363 KEYCODE is redefined for all possible shift combinations.
|
|
|
1364
|
|
|
1365 For the possible values of KEYCODE and their meanings, see the
|
|
|
1366 file `/usr/lib/Xkeymap.txt'. Keep in mind that the codes in that
|
|
|
1367 file are in octal!
|
|
|
1368
|
|
|
1369 The related function `x-rebind-keys' redefines a single keyboard
|
|
|
1370 key, specifying the behavior for each of the 16 shift masks
|
|
|
1371 independently. The first argument is KEYCODE, as in
|
|
|
1372 `x-rebind-key'. The second argument STRINGS is a list of 16
|
|
|
1373 elements, one for each possible shift mask value; each element
|
|
|
1374 says how to redefine the key KEYCODE with the corresponding shift
|
|
|
1375 mask value. If an element is a string, it is the new definition.
|
|
|
1376 If an element is `nil', the definition does not change for that
|
|
|
1377 shift mask.
|
|
|
1378
|
|
|
1379 * The function `x-parse-geometry' parses a string specifying window
|
|
|
1380 size and position in the usual X format. It returns an alist
|
|
|
1381 describing which parameters were specified, and the values that
|
|
|
1382 were given for them.
|
|
|
1383
|
|
|
1384 The elements of the alist look like `(PARAMETER . VALUE)'. The
|
|
|
1385 possible PARAMETER values are `left', `top', `width', and `height'.
|
|
|
1386
|
|
|
1387 New Window Features
|
|
|
1388 ===================
|
|
|
1389
|
|
|
1390 * The new function `window-at' tells you which window contains a
|
|
|
1391 given horizontal and vertical position on a specified frame. Call
|
|
|
1392 it with three arguments, like this:
|
|
|
1393
|
|
|
1394 (window-at X COLUMN FRAME)
|
|
|
1395
|
|
|
1396 The function returns the window which contains that cursor
|
|
|
1397 position in the frame FRAME. If you omit FRAME, the selected
|
|
|
1398 frame is used.
|
|
|
1399
|
|
|
1400 * The function `coordinates-in-window-p' takes two arguments and
|
|
|
1401 checks whether a particular frame position falls within a
|
|
|
1402 particular window.
|
|
|
1403
|
|
|
1404 (coordinates-in-window-p COORDINATES WINDOW)
|
|
|
1405
|
|
|
1406 The argument COORDINATES is a cons cell of this form:
|
|
|
1407
|
|
|
1408 (X . Y)
|
|
|
1409
|
|
|
1410 The two coordinates are measured in characters, and count from the
|
|
|
1411 top left corner of the screen or frame.
|
|
|
1412
|
|
|
1413 The value of the function tells you what part of the window the
|
|
|
1414 position is in. The possible values are:
|
|
|
1415
|
|
|
1416 `(RELX . RELY)'
|
|
|
1417 The coordinates are inside WINDOW. The numbers RELX and RELY
|
|
|
1418 are equivalent window-relative coordinates, counting from 0
|
|
|
1419 at the top left corner of the window.
|
|
|
1420
|
|
|
1421 `mode-line'
|
|
|
1422 The coordinates are in the mode line of WINDOW.
|
|
|
1423
|
|
|
1424 `vertical-split'
|
|
|
1425 The coordinates are in the vertical line between WINDOW and
|
|
|
1426 its neighbor to the right.
|
|
|
1427
|
|
|
1428 `nil'
|
|
|
1429 The coordinates are not in any sense within WINDOW.
|
|
|
1430
|
|
|
1431 You need not specify a frame when you call
|
|
|
1432 `coordinates-in-window-p', because it assumes you mean the frame
|
|
|
1433 which window WINDOW is on.
|
|
|
1434
|
|
|
1435 * The function `minibuffer-window' now accepts a frame as argument
|
|
|
1436 and returns the minibuffer window used for that frame. If you
|
|
|
1437 don't specify a frame, the currently selected frame is used. The
|
|
|
1438 minibuffer window may be on the frame in question, but if that
|
|
|
1439 frame has no minibuffer of its own, it uses the minibuffer window
|
|
|
1440 of some other frame, and `minibuffer-window' returns that window.
|
|
|
1441
|
|
|
1442 * Use `window-live-p' to test whether a window is still alive (that
|
|
|
1443 is, not deleted).
|
|
|
1444
|
|
|
1445 * Use `window-minibuffer-p' to determine whether a given window is a
|
|
|
1446 minibuffer or not. It no longer works to do this by comparing the
|
|
|
1447 window with the result of `(minibuffer-window)', because there can
|
|
|
1448 be more than one minibuffer window at a time (if you have multiple
|
|
|
1449 frames).
|
|
|
1450
|
|
|
1451 * If you set the variable `pop-up-frames' non-`nil', then the
|
|
|
1452 functions to show something "in another window" actually create a
|
|
|
1453 new frame for the new window. Thus, you will tend to have a frame
|
|
|
1454 for each window, and you can easily have a frame for each buffer.
|
|
|
1455
|
|
|
1456 The value of the variable `pop-up-frame-function' controls how new
|
|
|
1457 frames are made. The value should be a function which takes no
|
|
|
1458 arguments and returns a frame. The default value is a function
|
|
|
1459 which creates a frame using parameters from `pop-up-frame-alist'.
|
|
|
1460
|
|
|
1461 * `display-buffer' is the basic primitive for finding a way to show a
|
|
|
1462 buffer on the screen. You can customize its behavior by storing a
|
|
|
1463 function in the variable `display-buffer-function'. If this
|
|
|
1464 variable is non-`nil', then `display-buffer' calls it to do the
|
|
|
1465 work. Your function should accept two arguments, as follows:
|
|
|
1466
|
|
|
1467 BUFFER
|
|
|
1468 The buffer to be displayed.
|
|
|
1469
|
|
|
1470 FLAG
|
|
|
1471 A flag which, if non-`nil', means you should find another
|
|
|
1472 window to display BUFFER in, even if it is already visible in
|
|
|
1473 the selected window.
|
|
|
1474
|
|
|
1475 The function you supply will be used by commands such as
|
|
|
1476 `switch-to-buffer-other-window' and `find-file-other-window' as
|
|
|
1477 well as for your own calls to `display-buffer'.
|
|
|
1478
|
|
|
1479 * `delete-window' now gives all of the deleted window's screen space
|
|
|
1480 to a single neighboring window. Likewise, `enlarge-window' takes
|
|
|
1481 space from only one neighboring window until that window
|
|
|
1482 disappears; only then does it take from another window.
|
|
|
1483
|
|
|
1484 * `next-window' and `previous-window' accept another argument,
|
|
|
1485 ALL-FRAMES.
|
|
|
1486
|
|
|
1487 These functions now take three optional arguments: WINDOW, MINIBUF
|
|
|
1488 and ALL-FRAMES. WINDOW is the window to start from (`nil' means
|
|
|
1489 use the selected window). MINIBUF says whether to include the
|
|
|
1490 minibuffer in the windows to cycle through: `t' means yes, `nil'
|
|
|
1491 means yes if it is active, and anything else means no.
|
|
|
1492
|
|
|
1493 Normally, these functions cycle through all the windows in the
|
|
|
1494 selected frame, plus the minibuffer used by the selected frame
|
|
|
1495 even if it lies in some other frame.
|
|
|
1496
|
|
|
1497 If ALL-FRAMES is `t', then these functions cycle through all the
|
|
|
1498 windows in all the frames that currently exist. If ALL-FRAMES is
|
|
|
1499 neither `t' nor `nil', then they limit themselves strictly to the
|
|
|
1500 windows in the selected frame, excluding the minibuffer in use if
|
|
|
1501 it lies in some other frame.
|
|
|
1502
|
|
|
1503 * The functions `get-lru-window' and `get-largest-window' now take
|
|
|
1504 an optional argument ALL-FRAMES. If it is non-`nil', the
|
|
|
1505 functions consider all windows on all frames. Otherwise, they
|
|
|
1506 consider just the windows on the selected frame.
|
|
|
1507
|
|
|
1508 Likewise, `get-buffer-window' takes an optional second argument
|
|
|
1509 ALL-FRAMES.
|
|
|
1510
|
|
|
1511 * The variable `other-window-scroll-buffer' specifies which buffer
|
|
|
1512 `scroll-other-window' should scroll.
|
|
|
1513
|
|
|
1514 * You can now mark a window as "dedicated" to its buffer. Then
|
|
|
1515 Emacs will not try to use that window for any other buffer unless
|
|
|
1516 you explicitly request it.
|
|
|
1517
|
|
|
1518 Use the new function `set-window-dedicated-p' to set the dedication
|
|
|
1519 flag of a window WINDOW to the value FLAG. If FLAG is `t', this
|
|
|
1520 makes the window dedicated. If FLAG is `nil', this makes the
|
|
|
1521 window non-dedicated.
|
|
|
1522
|
|
|
1523 Use `window-dedicated-p' to examine the dedication flag of a
|
|
|
1524 specified window.
|
|
|
1525
|
|
|
1526 * The new function `walk-windows' cycles through all visible
|
|
|
1527 windows, calling `proc' once for each window with the window as
|
|
|
1528 its sole argument.
|
|
|
1529
|
|
|
1530 The optional second argument MINIBUF says whether to include
|
|
|
1531 minibuffer windows. A value of `t' means count the minibuffer
|
|
|
1532 window even if not active. A value of `nil' means count it only
|
|
|
1533 if active. Any other value means not to count the minibuffer even
|
|
|
1534 if it is active.
|
|
|
1535
|
|
|
1536 If the optional third argument ALL-FRAMES is `t', that means
|
|
|
1537 include all windows in all frames. If ALL-FRAMES is `nil', it
|
|
|
1538 means to cycle within the selected frame, but include the
|
|
|
1539 minibuffer window (if MINIBUF says so) that that frame uses, even
|
|
|
1540 if it is on another frame. If ALL-FRAMES is neither `nil' nor `t',
|
|
|
1541 `walk-windows' sticks strictly to the selected frame.
|
|
|
1542
|
|
|
1543 * The function `window-end' is a counterpart to `window-start': it
|
|
|
1544 returns the buffer position of the end of the display in a given
|
|
|
1545 window (or the selected window).
|
|
|
1546
|
|
|
1547 * The function `window-configuration-p' returns non-`nil' when given
|
|
|
1548 an object that is a window configuration (such as is returned by
|
|
|
1549 `current-window-configuration').
|
|
|
1550
|
|
|
1551 Display Features
|
|
|
1552 ================
|
|
|
1553
|
|
|
1554 * `baud-rate' is now a variable rather than a function. This is so
|
|
|
1555 you can set it to reflect the effective speed of your terminal,
|
|
|
1556 when the system doesn't accurately know the speed.
|
|
|
1557
|
|
|
1558 * You can now remove any echo area message and make the minibuffer
|
|
|
1559 visible. To do this, call `message' with `nil' as the only
|
|
|
1560 argument. This clears any existing message, and lets the current
|
|
|
1561 minibuffer contents show through. Previously, there was no
|
|
|
1562 reliable way to make sure that the minibuffer contents were
|
|
|
1563 visible.
|
|
|
1564
|
|
|
1565 * The variable `temp-buffer-show-hook' has been renamed
|
|
|
1566 `temp-buffer-show-function', because its value is a single function
|
|
|
1567 (of one argument), not a normal hook.
|
|
|
1568
|
|
|
1569 * The new function `force-mode-line-update' causes redisplay of the
|
|
|
1570 current buffer's mode line.
|
|
|
1571
|
|
|
1572 Display Tables
|
|
|
1573 ==============
|
|
|
1574
|
|
|
1575 You can use the "display table" feature to control how all 256
|
|
|
1576 possible character codes display on the screen. This is useful for
|
|
|
1577 displaying European languages that have letters not in the ASCII
|
|
|
1578 character set.
|
|
|
1579
|
|
|
1580 The display table maps each character code into a sequence of
|
|
|
1581 "glyphs", each glyph being an image that takes up one character
|
|
|
1582 position on the screen. You can also define how to display each glyph
|
|
|
1583 on your terminal, using the "glyph table".
|
|
|
1584
|
|
|
1585 Display Tables Proper
|
|
|
1586 ---------------------
|
|
|
1587
|
|
|
1588 Use `make-display-table' to create a display table. The table
|
|
|
1589 initially has `nil' in all elements.
|
|
|
1590
|
|
|
1591 A display table is actually an array of 261 elements. The first 256
|
|
|
1592 elements of a display table control how to display each possible text
|
|
|
1593 character. The value should be `nil' or a vector (which is a sequence
|
|
|
1594 of glyphs; see below). `nil' as an element means to display that
|
|
|
1595 character following the usual display conventions.
|
|
|
1596
|
|
|
1597 The remaining five elements of a display table serve special purposes
|
|
|
1598 (`nil' means use the default stated below):
|
|
|
1599
|
|
|
1600 256
|
|
|
1601 The glyph for the end of a truncated screen line (the default for
|
|
|
1602 this is `\').
|
|
|
1603
|
|
|
1604 257
|
|
|
1605 The glyph for the end of a continued line (the default is `$').
|
|
|
1606
|
|
|
1607 258
|
|
|
1608 The glyph for the indicating an octal character code (the default
|
|
|
1609 is `\').
|
|
|
1610
|
|
|
1611 259
|
|
|
1612 The glyph for indicating a control characters (the default is `^').
|
|
|
1613
|
|
|
1614 260
|
|
|
1615 The vector of glyphs for indicating the presence of invisible
|
|
|
1616 lines (the default is `...').
|
|
|
1617
|
|
|
1618 Each buffer typically has its own display table. The display table
|
|
|
1619 for the current buffer is stored in `buffer-display-table'. (This
|
|
|
1620 variable automatically becomes local if you set it.) If this variable
|
|
|
1621 is `nil', the value of `standard-display-table' is used in that buffer.
|
|
|
1622
|
|
|
1623 Each window can have its own display table, which overrides the
|
|
|
1624 display table of the buffer it is showing.
|
|
|
1625
|
|
|
1626 If neither the selected window nor the current buffer has a display
|
|
|
1627 table, and if `standard-display-table' is `nil', then Emacs uses the
|
|
|
1628 usual display conventions:
|
|
|
1629
|
|
|
1630 * Character codes 32 through 127 map to glyph codes 32 through 127.
|
|
|
1631
|
|
|
1632 * Codes 0 through 31 map to sequences of two glyphs, where the first
|
|
|
1633 glyph is the ASCII code for `^'.
|
|
|
1634
|
|
|
1635 * Character codes 128 through 255 map to sequences of four glyphs,
|
|
|
1636 where the first glyph is the ASCII code for `\', and the others
|
|
|
1637 represent digits.
|
|
|
1638
|
|
|
1639 The usual display conventions are also used for any character whose
|
|
|
1640 entry in the active display table is `nil'. This means that when you
|
|
|
1641 set up a display table, you need not specify explicitly what to do with
|
|
|
1642 each character, only the characters for which you want unusual behavior.
|
|
|
1643
|
|
|
1644 Glyphs
|
|
|
1645 ------
|
|
|
1646
|
|
|
1647 A glyph stands for an image that takes up a single character
|
|
|
1648 position on the screen. A glyph is represented in Lisp as an integer.
|
|
|
1649
|
|
|
1650 The meaning of each integer, as a glyph, is defined by the glyph
|
|
|
1651 table, which is the value of the variable `glyph-table'. It should be a
|
|
|
1652 vector; the Gth element defines glyph code G. The possible definitions
|
|
|
1653 of a glyph code are:
|
|
|
1654
|
|
|
1655 INTEGER
|
|
|
1656 Define this glyph code as an alias for code INTEGER. This is used
|
|
|
1657 with X Windows to specify a face code.
|
|
|
1658
|
|
|
1659 STRING
|
|
|
1660 Send the characters in STRING to the terminal to output this
|
|
|
1661 glyph. This alternative is available only for character
|
|
|
1662 terminals, not with X.
|
|
|
1663
|
|
|
1664 `NIL'
|
|
|
1665 This glyph is simple. On an ordinary terminal, the glyph code mod
|
|
|
1666 256 is the character to output. With X, the glyph code mod 256 is
|
|
|
1667 character to output, and the glyph code divided by 256 specifies
|
|
|
1668 the "face code" to use while outputting it.
|
|
|
1669
|
|
|
1670 Any glyph code beyond the length of the glyph table is automatically
|
|
|
1671 simple.
|
|
|
1672
|
|
|
1673 If `glyph-table' is `nil', then all possible glyph codes are simple.
|
|
|
1674
|
|
|
1675 A "face" is a named combination of a font and a pair of colors
|
|
|
1676 (foreground and background). A glyph code can specify a face id number
|
|
|
1677 to use for displaying that glyph.
|
|
|
1678
|
|
|
1679 ISO Latin 1
|
|
|
1680 -----------
|
|
|
1681
|
|
|
1682 If you have a terminal that can handle the entire ISO Latin 1
|
|
|
1683 character set, you can arrange to use that character set as follows:
|
|
|
1684
|
|
|
1685 (standard-display-european 1)
|
|
|
1686
|
|
|
1687 If you are editing buffers written in the ISO Latin 1 character set
|
|
|
1688 and your terminal doesn't handle anything but ASCII, you can load the
|
|
|
1689 file `iso-ascii' to set up a display table which makes the other ISO
|
|
|
1690 characters display as sequences of ASCII characters. For example, the
|
|
|
1691 character "o with umlaut" displays as `{"o}'.
|
|
|
1692
|
|
|
1693 Some European countries have terminals that don't support ISO Latin 1
|
|
|
1694 but do support the special characters for that country's language. You
|
|
|
1695 can define a display table to work one language using such terminals.
|
|
|
1696 For an example, see `lisp/iso-swed.el', which handles certain Swedish
|
|
|
1697 terminals.
|
|
|
1698
|
|
|
1699 You can load the appropriate display table for your terminal
|
|
|
1700 automatically by writing a terminal-specific Lisp file for the terminal
|
|
|
1701 type.
|
|
|
1702
|
|
|
1703 Overlays
|
|
|
1704 ========
|
|
|
1705
|
|
|
1706 You can use "overlays" to alter the appearance of a buffer's text on
|
|
|
1707 the screen. An overlay is an object which belongs to a particular
|
|
|
1708 buffer, and has a specified beginning and end. It also has properties
|
|
|
1709 which you can examine and set; these affect the display of the text
|
|
|
1710 within the overlay.
|
|
|
1711
|
|
|
1712 Overlay Properties
|
|
|
1713 ------------------
|
|
|
1714
|
|
|
1715 Overlay properties are like text properties in some respects, but the
|
|
|
1716 differences are more important than the similarities. Text properties
|
|
|
1717 are considered a part of the text; overlays are specifically considered
|
|
|
1718 not to be part of the text. Thus, copying text between various buffers
|
|
|
1719 and strings preserves text properties, but does not try to preserve
|
|
|
1720 overlays. Changing a buffer's text properties marks the buffer as
|
|
|
1721 modified, while moving an overlay or changing its properties does not.
|
|
|
1722
|
|
|
1723 `face'
|
|
|
1724 This property specifies a face for displaying the text within the
|
|
|
1725 overlay.
|
|
|
1726
|
|
|
1727 `priority'
|
|
|
1728 This property's value (which should be a nonnegative number)
|
|
|
1729 determines the priority of the overlay. The priority matters when
|
|
|
1730 two or more overlays cover the same character and both specify a
|
|
|
1731 face for display; the one whose `priority' value is larger takes
|
|
|
1732 priority over the other, and its face attributes override the face
|
|
|
1733 attributes of the lower priority overlay.
|
|
|
1734
|
|
|
1735 Currently, all overlays take priority over text properties. Please
|
|
|
1736 avoid using negative priority values, as we have not yet decided
|
|
|
1737 just what they should mean.
|
|
|
1738
|
|
|
1739 `window'
|
|
|
1740 If the `window' property is non-`nil', then the overlay applies
|
|
|
1741 only on that window.
|
|
|
1742
|
|
|
1743 Overlay Functions
|
|
|
1744 -----------------
|
|
|
1745
|
|
|
1746 Use the functions `overlay-get' and `overlay-put' to access and set
|
|
|
1747 the properties of an overlay. They take arguments like `get' and
|
|
|
1748 `put', except that the first argument is an overlay rather than a
|
|
|
1749 symbol.
|
|
|
1750
|
|
|
1751 To create an overlay, call `(make-overlay START END)'. You can
|
|
|
1752 specify the buffer as the third argument if you wish. To delete one,
|
|
|
1753 use `delete-overlay'.
|
|
|
1754
|
|
|
1755 Use `overlay-start', `overlay-end' and `overlay-buffer' to examine
|
|
|
1756 the location and range of an overlay. Use `move-overlay' to change
|
|
|
1757 them; its arguments are OVERLAY, START, END and (optionally) the buffer.
|
|
|
1758
|
|
|
1759 There are two functions to search for overlays: `overlays-at' and
|
|
|
1760 `next-overlay-change'. `overlays-at' returns a list of all the
|
|
|
1761 overlays containing a particular position. `(next-overlay-change POS)'
|
|
|
1762 returns the position of the next overlay beginning or end following POS.
|
|
|
1763
|
|
|
1764 Faces
|
|
|
1765 =====
|
|
|
1766
|
|
|
1767 A "face" is a named collection of graphical attributes: font,
|
|
|
1768 foreground color, background color and optional underlining. Faces
|
|
|
1769 control the display of text on the screen.
|
|
|
1770
|
|
|
1771 Each face has its own "face id number" which distinguishes faces at
|
|
|
1772 low levels within Emacs. However, for most purposes, you can refer to
|
|
|
1773 faces in Lisp programs by their names.
|
|
|
1774
|
|
|
1775 Each face name is meaningful for all frames, and by default it has
|
|
|
1776 the same meaning in all frames. But you can arrange to give a
|
|
|
1777 particular face name a special meaning in one frame if you wish.
|
|
|
1778
|
|
|
1779 Choosing a Face for Display
|
|
|
1780 ---------------------------
|
|
|
1781
|
|
|
1782 Here are all the ways to specify which face to use for display of
|
|
|
1783 text:
|
|
|
1784
|
|
|
1785 * With defaults. Each frame has a "default face", whose id number is
|
|
|
1786 zero, which is used for all text that doesn't somehow specify
|
|
|
1787 another face.
|
|
|
1788
|
|
|
1789 * With text properties. A character may have a `face' property; if
|
|
|
1790 so, it's displayed with that face. If the character has a
|
|
|
1791 `mouse-face' property, that is used instead of the `face' property
|
|
|
1792 when the mouse is "near enough" to the character.
|
|
|
1793
|
|
|
1794 * With overlays. An overlay may have `face' and `mouse-face'
|
|
|
1795 properties too; they apply to all the text covered by the overlay.
|
|
|
1796
|
|
|
1797 * With special glyphs. Each glyph can specify a particular face id
|
|
|
1798 number.
|
|
|
1799
|
|
|
1800 If these various sources together specify more than one face for a
|
|
|
1801 particular character, Emacs merges the attributes of the various faces
|
|
|
1802 specified. The attributes of the faces of special glyphs come first;
|
|
|
1803 then come attributes of faces from overlays, followed by those from text
|
|
|
1804 properties, and last the default face.
|
|
|
1805
|
|
|
1806 When multiple overlays cover one character, an overlay with higher
|
|
|
1807 priority overrides those with lower priority.
|
|
|
1808
|
|
|
1809 If an attribute such as the font or a color is not specified in any
|
|
|
1810 of the above ways, the frame's own font or color is used.
|
|
|
1811
|
|
|
1812 *Note Face Functions: (elisp)Face Functions, for functions to create
|
|
|
1813 and change faces.
|
|
|
1814
|
|
|
1815 New Input Event Formats
|
|
|
1816 =======================
|
|
|
1817
|
|
|
1818 Mouse clicks, mouse movements and function keys no longer appear in
|
|
|
1819 the input stream as characters; instead, other kinds of Lisp objects
|
|
|
1820 represent them as input.
|
|
|
1821
|
|
|
1822 * An ordinary input character event consists of a "basic code"
|
|
|
1823 between 0 and 255, plus any or all of these "modifier bits":
|
|
|
1824
|
|
|
1825 meta
|
|
|
1826 The 2**23 bit in the character code indicates a character
|
|
|
1827 typed with the meta key held down.
|
|
|
1828
|
|
|
1829 control
|
|
|
1830 The 2**22 bit in the character code indicates a non-ASCII
|
|
|
1831 control character.
|
|
|
1832
|
|
|
1833 ASCII control characters such as `C-a' have special basic
|
|
|
1834 codes of their own, so Emacs needs no special bit to indicate
|
|
|
1835 them. Thus, the code for `C-a' is just 1.
|
|
|
1836
|
|
|
1837 But if you type a control combination not in ASCII, such as
|
|
|
1838 `%' with the control key, the numeric value you get is the
|
|
|
1839 code for `%' plus 2**22 (assuming the terminal supports
|
|
|
1840 non-ASCII control characters).
|
|
|
1841
|
|
|
1842 shift
|
|
|
1843 The 2**21 bit in the character code indicates an ASCII control
|
|
|
1844 character typed with the shift key held down.
|
|
|
1845
|
|
|
1846 For letters, the basic code indicates upper versus lower
|
|
|
1847 case; for digits and punctuation, the shift key selects an
|
|
|
1848 entirely different character with a different basic code. In
|
|
|
1849 order to keep within the ASCII character set whenever
|
|
|
1850 possible, Emacs avoids using the 2**21 bit for those
|
|
|
1851 characters.
|
|
|
1852
|
|
|
1853 However, ASCII provides no way to distinguish `C-A' from
|
|
|
1854 `C-a', so Emacs uses the 2**21 bit in `C-A' and not in `C-a'.
|
|
|
1855
|
|
|
1856 hyper
|
|
|
1857 The 2**20 bit in the character code indicates a character
|
|
|
1858 typed with the hyper key held down.
|
|
|
1859
|
|
|
1860 super
|
|
|
1861 The 2**19 bit in the character code indicates a character
|
|
|
1862 typed with the super key held down.
|
|
|
1863
|
|
|
1864 alt
|
|
|
1865 The 2**18 bit in the character code indicates a character
|
|
|
1866 typed with the alt key held down. (On some terminals, the
|
|
|
1867 key labeled ALT is actually the meta key.)
|
|
|
1868
|
|
|
1869 In the future, Emacs may support a larger range of basic codes.
|
|
|
1870 We may also move the modifier bits to larger bit numbers.
|
|
|
1871 Therefore, you should avoid mentioning specific bit numbers in
|
|
|
1872 your program. Instead, the way to test the modifier bits of a
|
|
|
1873 character is with the function `event-modifiers' (see below).
|
|
|
1874
|
|
|
1875 * Function keys are represented as symbols. The symbol's name is
|
|
|
1876 the function key's label. For example, pressing a key labeled F1
|
|
|
1877 places the symbol `f1' in the input stream.
|
|
|
1878
|
|
|
1879 There are a few exceptions to the symbol naming convention:
|
|
|
1880
|
|
|
1881 `kp-add', `kp-decimal', `kp-divide', ...
|
|
|
1882 Keypad keys (to the right of the regular keyboard).
|
|
|
1883
|
|
|
1884 `kp-0', `kp-1', ...
|
|
|
1885 Keypad keys with digits.
|
|
|
1886
|
|
|
1887 `kp-f1', `kp-f2', `kp-f3', `kp-f4'
|
|
|
1888 Keypad PF keys.
|
|
|
1889
|
|
|
1890 `left', `up', `right', `down'
|
|
|
1891 Cursor arrow keys
|
|
|
1892
|
|
|
1893 You can use the modifier keys CTRL, META, HYPER, SUPER, ALT and
|
|
|
1894 SHIFT with function keys. The way to represent them is with
|
|
|
1895 prefixes in the symbol name:
|
|
|
1896
|
|
|
1897 `A-'
|
|
|
1898 The alt modifier.
|
|
|
1899
|
|
|
1900 `C-'
|
|
|
1901 The control modifier.
|
|
|
1902
|
|
|
1903 `H-'
|
|
|
1904 The hyper modifier.
|
|
|
1905
|
|
|
1906 `M-'
|
|
|
1907 The meta modifier.
|
|
|
1908
|
|
|
1909 `s-'
|
|
|
1910 The super modifier.
|
|
|
1911
|
|
|
1912 `S-'
|
|
|
1913 The shift modifier.
|
|
|
1914
|
|
|
1915 Thus, the symbol for the key F3 with META held down is `M-F3'.
|
|
|
1916 When you use more than one prefix, we recommend you write them in
|
|
|
1917 alphabetical order (though the order does not matter in arguments
|
|
|
1918 to the key-binding lookup and modification functions).
|
|
|
1919
|
|
|
1920 * Mouse events are represented as lists.
|
|
|
1921
|
|
|
1922 If you press a mouse button and release it at the same location,
|
|
|
1923 this generates a "click" event. Mouse click events have this form:
|
|
|
1924
|
|
|
1925 (BUTTON-SYMBOL
|
|
|
1926 (WINDOW (COLUMN . ROW)
|
|
|
1927 BUFFER-POS TIMESTAMP))
|
|
|
1928
|
|
|
1929 Here is what the elements normally mean:
|
|
|
1930
|
|
|
1931 BUTTON-SYMBOL
|
|
|
1932 indicates which mouse button was used. It is one of the
|
|
|
1933 symbols `mouse-1', `mouse-2', ..., where the buttons are
|
|
|
1934 normally numbered left to right.
|
|
|
1935
|
|
|
1936 You can also use prefixes `A-', `C-', `H-', `M-', `S-' and
|
|
|
1937 `s-' for modifiers alt, control, hyper, meta, shift and
|
|
|
1938 super, just as you would with function keys.
|
|
|
1939
|
|
|
1940 WINDOW
|
|
|
1941 is the window in which the click occurred.
|
|
|
1942
|
|
|
1943 COLUMN
|
|
|
1944 ROW
|
|
|
1945 are the column and row of the click, relative to the top left
|
|
|
1946 corner of WINDOW, which is `(0 . 0)'.
|
|
|
1947
|
|
|
1948 BUFFER-POS
|
|
|
1949 is the buffer position of the character clicked on.
|
|
|
1950
|
|
|
1951 TIMESTAMP
|
|
|
1952 is the time at which the event occurred, in milliseconds.
|
|
|
1953 (Since this value wraps around the entire range of Emacs Lisp
|
|
|
1954 integers in about five hours, it is useful only for relating
|
|
|
1955 the times of nearby events.)
|
|
|
1956
|
|
|
1957 The meanings of BUFFER-POS, ROW and COLUMN are somewhat different
|
|
|
1958 when the event location is in a special part of the screen, such
|
|
|
1959 as the mode line or a scroll bar.
|
|
|
1960
|
|
|
1961 If the position is in the window's scroll bar, then BUFFER-POS is
|
|
|
1962 the symbol `vertical-scroll-bar', and the pair `(COLUMN . ROW)' is
|
|
|
1963 replaced with a pair `(PORTION . WHOLE)', where PORTION is the
|
|
|
1964 distance of the click from the top or left end of the scroll bar,
|
|
|
1965 and WHOLE is the length of the entire scroll bar.
|
|
|
1966
|
|
|
1967 If the position is on a mode line or the vertical line separating
|
|
|
1968 WINDOW from its neighbor to the right, then BUFFER-POS is the
|
|
|
1969 symbol `mode-line' or `vertical-line'. In this case ROW and
|
|
|
1970 COLUMN do not have meaningful data.
|
|
|
1971
|
|
|
1972 * Releasing a mouse button above a different character position
|
|
|
1973 generates a "drag" event, which looks like this:
|
|
|
1974
|
|
|
1975 (BUTTON-SYMBOL
|
|
|
1976 (WINDOW1 (COLUMN1 . ROW1)
|
|
|
1977 BUFFER-POS1 TIMESTAMP1)
|
|
|
1978 (WINDOW2 (COLUMN2 . ROW2)
|
|
|
1979 BUFFER-POS2 TIMESTAMP2))
|
|
|
1980
|
|
|
1981 The name of BUTTON-SYMBOL contains the prefix `drag-'. The second
|
|
|
1982 and third elements of the event give the starting and ending
|
|
|
1983 position of the drag.
|
|
|
1984
|
|
|
1985 The `drag-' prefix follows the modifier key prefixes such as `C-'
|
|
|
1986 and `M-'.
|
|
|
1987
|
|
|
1988 If `read-key-sequence' receives a drag event which has no key
|
|
|
1989 binding, and the corresponding click event does have a binding, it
|
|
|
1990 changes the drag event into a click event at the drag's starting
|
|
|
1991 position. This means that you don't have to distinguish between
|
|
|
1992 click and drag events unless you want to.
|
|
|
1993
|
|
|
1994 * Click and drag events happen when you release a mouse button.
|
|
|
1995 Another kind of event happens when you press a button. It looks
|
|
|
1996 just like a click event, except that the name of BUTTON-SYMBOL
|
|
|
1997 contains the prefix `down-'. The `down-' prefix follows the
|
|
|
1998 modifier key prefixes such as `C-' and `M-'.
|
|
|
1999
|
|
|
2000 The function `read-key-sequence', and the Emacs command loop,
|
|
|
2001 ignore any down events that don't have command bindings. This
|
|
|
2002 means that you need not worry about defining down events unless
|
|
|
2003 you want them to do something. The usual reason to define a down
|
|
|
2004 event is so that you can track mouse motion until the button is
|
|
|
2005 released.
|
|
|
2006
|
|
|
2007 * For example, if the user presses and releases the left mouse
|
|
|
2008 button over the same location, Emacs generates a sequence of
|
|
|
2009 events like this:
|
|
|
2010
|
|
|
2011 (down-mouse-1 (#<window 18 on NEWS> 2613 (0 . 38) -864320))
|
|
|
2012 (mouse-1 (#<window 18 on NEWS> 2613 (0 . 38) -864180))
|
|
|
2013
|
|
|
2014 Or, while holding the control key down, the user might hold down
|
|
|
2015 the second mouse button, and drag the mouse from one line to the
|
|
|
2016 next. That produces two events, as shown here:
|
|
|
2017
|
|
|
2018 (C-down-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219))
|
|
|
2019 (C-drag-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219)
|
|
|
2020 (#<window 18 on NEWS> 3510 (0 . 28) -729648))
|
|
|
2021
|
|
|
2022 Or, while holding down the meta and shift keys, the user might
|
|
|
2023 press the second mouse button on the window's mode line, and then
|
|
|
2024 drag the mouse into another window. That produces an event like
|
|
|
2025 this:
|
|
|
2026
|
|
|
2027 (M-S-down-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844))
|
|
|
2028 (M-S-drag-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844)
|
|
|
2029 (#<window 20 on carlton-sanskrit.tex> 161 (33 . 3)
|
|
|
2030 -453816))
|
|
|
2031
|
|
|
2032 * A key sequence that starts with a mouse click is read using the
|
|
|
2033 keymaps of the buffer in the window clicked on, not the current
|
|
|
2034 buffer.
|
|
|
2035
|
|
|
2036 This does not imply that clicking in a window selects that window
|
|
|
2037 or its buffer. The execution of the command begins with no change
|
|
|
2038 in the selected window or current buffer. However, the command
|
|
|
2039 can switch windows or buffers if programmed to do so.
|
|
|
2040
|
|
|
2041 * Mouse motion events are represented by lists. During the
|
|
|
2042 execution of the body of a `track-mouse' form, moving the mouse
|
|
|
2043 generates events that look like this:
|
|
|
2044
|
|
|
2045 (mouse-movement (WINDOW (COLUMN . ROW)
|
|
|
2046 BUFFER-POS TIMESTAMP))
|
|
|
2047
|
|
|
2048 The second element of the list describes the current position of
|
|
|
2049 the mouse, just as in a mouse click event.
|
|
|
2050
|
|
|
2051 Outside of `track-mouse' forms, Emacs does not generate events for
|
|
|
2052 mere motion of the mouse, and these events do not appear.
|
|
|
2053
|
|
|
2054 * Focus shifts between frames are represented by lists.
|
|
|
2055
|
|
|
2056 When the mouse shifts temporary input focus from one frame to
|
|
|
2057 another, Emacs generates an event like this:
|
|
|
2058
|
|
|
2059 (switch-frame NEW-FRAME)
|
|
|
2060
|
|
|
2061 where NEW-FRAME is the frame switched to.
|
|
|
2062
|
|
|
2063 In X windows, most window managers are set up so that just moving
|
|
|
2064 the mouse into a window is enough to set the focus there. As far
|
|
|
2065 as the user is concerned, Emacs behaves consistently with this.
|
|
|
2066 However, there is no need for the Lisp program to know about the
|
|
|
2067 focus change until some other kind of input arrives. So Emacs
|
|
|
2068 generates the focus event only when the user actually types a
|
|
|
2069 keyboard key or presses a mouse button in the new frame; just
|
|
|
2070 moving the mouse between frames does not generate a focus event.
|
|
|
2071
|
|
|
2072 The global key map usually binds this event to the
|
|
|
2073 `internal-select-frame' function, so that characters typed at a
|
|
|
2074 frame apply to that frame's selected window.
|
|
|
2075
|
|
|
2076 If the user switches frames in the middle of a key sequence, then
|
|
|
2077 Emacs delays the `switch-frame' event until the key sequence is
|
|
|
2078 over. For example, suppose `C-c C-a' is a key sequence in the
|
|
|
2079 current buffer's keymaps. If the user types `C-c', moves the
|
|
|
2080 mouse to another frame, and then types `C-a', `read-key-sequence'
|
|
|
2081 returns the sequence `"\C-c\C-a"', and the next call to
|
|
|
2082 `read-event' or `read-key-sequence' will return the `switch-frame'
|
|
|
2083 event.
|
|
|
2084
|
|
|
2085 Working with Input Events
|
|
|
2086 =========================
|
|
|
2087
|
|
|
2088 * Functions which work with key sequences now handle non-character
|
|
|
2089 events. Functions like `define-key', `global-set-key', and
|
|
|
2090 `local-set-key' used to accept strings representing key sequences;
|
|
|
2091 now, since events may be arbitrary lisp objects, they also accept
|
|
|
2092 vectors. The function `read-key-sequence' may return a string or a
|
|
|
2093 vector, depending on whether or not the sequence read contains only
|
|
|
2094 characters.
|
|
|
2095
|
|
|
2096 List events may be represented by the symbols at their head; to
|
|
|
2097 bind clicks of the left mouse button, you need only present the
|
|
|
2098 symbol `mouse-1', not an entire mouse click event. If you do put
|
|
|
2099 an event which is a list in a key sequence, only the event's head
|
|
|
2100 symbol is used in key lookups.
|
|
|
2101
|
|
|
2102 For example, to globally bind the left mouse button to the function
|
|
|
2103 `mouse-set-point', you could evaluate this:
|
|
|
2104
|
|
|
2105 (global-set-key [mouse-1] 'mouse-set-point)
|
|
|
2106
|
|
|
2107 To bind the sequence `C-c F1' to the command `tex-view' in
|
|
|
2108 `tex-mode-map', you could evaluate this:
|
|
|
2109
|
|
|
2110 (define-key tex-mode-map [?\C-c f1] 'tex-view)
|
|
|
2111
|
|
|
2112 To find the binding for the function key labeled NEXT in
|
|
|
2113 `minibuffer-local-map', you could evaluate this:
|
|
|
2114
|
|
|
2115 (lookup-key minibuffer-local-map [next])
|
|
|
2116 => next-history-element
|
|
|
2117
|
|
|
2118 If you call the function `read-key-sequence' and then press `C-x
|
|
|
2119 C-F5', here is how it behaves:
|
|
|
2120
|
|
|
2121 (read-key-sequence "Press `C-x C-F5': ")
|
|
|
2122 => [24 C-f5]
|
|
|
2123
|
|
|
2124 Note that `24' is the character `C-x'.
|
|
|
2125
|
|
|
2126 * The documentation functions (`single-key-description',
|
|
|
2127 `key-description', etc.) now handle the new event types. Wherever
|
|
|
2128 a string of keyboard input characters was acceptable in previous
|
|
|
2129 versions of Emacs, a vector of events should now work.
|
|
|
2130
|
|
|
2131 * Special parts of a window can have their own bindings for mouse
|
|
|
2132 events.
|
|
|
2133
|
|
|
2134 When mouse events occur in special parts of a window, such as a
|
|
|
2135 mode line or a scroll bar, the event itself shows nothing
|
|
|
2136 special--only the symbol that would normally represent that mouse
|
|
|
2137 button and modifier keys. The information about the screen region
|
|
|
2138 is kept in other parts of the event list. But `read-key-sequence'
|
|
|
2139 translates this information into imaginary prefix keys, all of
|
|
|
2140 which are symbols: `mode-line', `vertical-line', and
|
|
|
2141 `vertical-scroll-bar'.
|
|
|
2142
|
|
|
2143 For example, if you call `read-key-sequence' and then click the
|
|
|
2144 mouse on the window's mode line, this is what happens:
|
|
|
2145
|
|
|
2146 (read-key-sequence "Click on the mode line: ")
|
|
|
2147 => [mode-line (mouse-1 (#<window 6 on NEWS> mode-line
|
|
|
2148 (40 . 63) 5959987))]
|
|
|
2149
|
|
|
2150 You can define meanings for mouse clicks in special window regions
|
|
|
2151 by defining key sequences using these imaginary prefix keys. For
|
|
|
2152 example, here is how to bind the third mouse button on a window's
|
|
|
2153 mode line delete the window:
|
|
|
2154
|
|
|
2155 (global-set-key [mode-line mouse-3] 'mouse-delete-window)
|
|
|
2156
|
|
|
2157 Here's how to bind the middle button (modified by META) on the
|
|
|
2158 vertical line at the right of a window to scroll the window to the
|
|
|
2159 left.
|
|
|
2160
|
|
|
2161 (global-set-key [vertical-line M-mouse-2] 'scroll-left)
|
|
|
2162
|
|
|
2163 * Decomposing an event symbol.
|
|
|
2164
|
|
|
2165 Each symbol used to identify a function key or mouse button has a
|
|
|
2166 property named `event-symbol-elements', which is a list containing
|
|
|
2167 an unmodified version of the symbol, followed by modifiers the
|
|
|
2168 symbol name contains. The modifiers are symbols; they include
|
|
|
2169 `shift', `control', and `meta'. In addition, a mouse event symbol
|
|
|
2170 has one of `click', `drag', and `down'. For example:
|
|
|
2171
|
|
|
2172 (get 'f5 'event-symbol-elements)
|
|
|
2173 => (f5)
|
|
|
2174 (get 'C-f5 'event-symbol-elements)
|
|
|
2175 => (f5 control)
|
|
|
2176 (get 'M-S-f5 'event-symbol-elements)
|
|
|
2177 => (f5 meta shift)
|
|
|
2178 (get 'mouse-1 'event-symbol-elements)
|
|
|
2179 => (mouse-1 click)
|
|
|
2180 (get 'down-mouse-1 'event-symbol-elements)
|
|
|
2181 => (mouse-1 down)
|
|
|
2182
|
|
|
2183 Note that the `event-symbol-elements' property for a mouse click
|
|
|
2184 explicitly contains `click', but the event symbol name itself does
|
|
|
2185 not contain `click'.
|
|
|
2186
|
|
|
2187 * Use `read-event' to read input if you want to accept any kind of
|
|
|
2188 event. The old function `read-char' now discards events other than
|
|
|
2189 keyboard characters.
|
|
|
2190
|
|
|
2191 * `last-command-char' and `last-input-char' can now hold any kind of
|
|
|
2192 event.
|
|
|
2193
|
|
|
2194 * The new variable `unread-command-events' is much like
|
|
|
2195 `unread-command-char'. Its value is a list of events of any type,
|
|
|
2196 to be processed as command input in order of appearance in the
|
|
|
2197 list.
|
|
|
2198
|
|
|
2199 * The function `this-command-keys' may return a string or a vector,
|
|
|
2200 depending on whether or not the sequence read contains only
|
|
|
2201 characters. You may need to upgrade code which uses this function.
|
|
|
2202
|
|
|
2203 The function `recent-keys' now returns a vector of events. You
|
|
|
2204 may need to upgrade code which uses this function.
|
|
|
2205
|
|
|
2206 * A keyboard macro's definition can now be either a string or a
|
|
|
2207 vector. All that really matters is what elements it has. If the
|
|
|
2208 elements are all characters, then the macro can be a string;
|
|
|
2209 otherwise, it has to be a vector.
|
|
|
2210
|
|
|
2211 * The variable `last-event-frame' records which frame the last input
|
|
|
2212 event was directed to. Usually this is the frame that was
|
|
|
2213 selected when the event was generated, but if that frame has
|
|
|
2214 redirected input focus to another frame, `last-event-frame' is the
|
|
|
2215 frame to which the event was redirected.
|
|
|
2216
|
|
|
2217 * The interactive specification now allows a new code letter `e' to
|
|
|
2218 simplify commands bound to events which are lists. This code
|
|
|
2219 supplies as an argument the complete event object.
|
|
|
2220
|
|
|
2221 You can use `e' more than once in a single command's interactive
|
|
|
2222 specification. If the key sequence which invoked the command has
|
|
|
2223 N events with parameters, the Nth `e' provides the Nth
|
|
|
2224 parameterized event. Events which are not lists, such as function
|
|
|
2225 keys and ASCII keystrokes, do not count where `e' is concerned.
|
|
|
2226
|
|
|
2227 * You can extract the starting and ending position values from a
|
|
|
2228 mouse button or motion event using the two functions `event-start'
|
|
|
2229 and `event-end'. These two functions return different values for
|
|
|
2230 drag and motion events; for click and button-down events, they
|
|
|
2231 both return the position of the event.
|
|
|
2232
|
|
|
2233 * The position, a returned by `event-start' and `event-end', is a
|
|
|
2234 list of this form:
|
|
|
2235
|
|
|
2236 (WINDOW BUFFER-POSITION (COL . ROW) TIMESTAMP)
|
|
|
2237
|
|
|
2238 You can extract parts of this list with the functions
|
|
|
2239 `posn-window', `posn-point', `posn-col-row', and `posn-timestamp'.
|
|
|
2240
|
|
|
2241 * The function `scroll-bar-scale' is useful for computing where to
|
|
|
2242 scroll to in response to a mouse button event from a scroll bar.
|
|
|
2243 It takes two arguments, RATIO and TOTAL, and in effect multiplies
|
|
|
2244 them. We say "in effect" because RATIO is not a number; rather a
|
|
|
2245 pair `(NUM . DENOM)'.
|
|
|
2246
|
|
|
2247 Here's the usual way to use `scroll-bar-scale':
|
|
|
2248
|
|
|
2249 (scroll-bar-scale (posn-col-row (event-start event))
|
|
|
2250 (buffer-size))
|
|
|
2251
|
|
|
2252 Putting Keyboard Events in Strings
|
|
|
2253 ==================================
|
|
|
2254
|
|
|
2255 In most of the places where strings are used, we conceptualize the
|
|
|
2256 string as containing text characters--the same kind of characters found
|
|
|
2257 in buffers or files. Occasionally Lisp programs use strings which
|
|
|
2258 conceptually contain keyboard characters; for example, they may be key
|
|
|
2259 sequences or keyboard macro definitions. There are special rules for
|
|
|
2260 how to put keyboard characters into a string, because they are not
|
|
|
2261 limited to the range of 0 to 255 as text characters are.
|
|
|
2262
|
|
|
2263 A keyboard character typed using the META key is called a "meta
|
|
|
2264 character". The numeric code for such an event includes the 2**23 bit;
|
|
|
2265 it does not even come close to fitting in a string. However, earlier
|
|
|
2266 Emacs versions used a different representation for these characters,
|
|
|
2267 which gave them codes in the range of 128 to 255. That did fit in a
|
|
|
2268 string, and many Lisp programs contain string constants that use `\M-'
|
|
|
2269 to express meta characters, especially as the argument to `define-key'
|
|
|
2270 and similar functions.
|
|
|
2271
|
|
|
2272 We provide backward compatibility to run those programs with special
|
|
|
2273 rules for how to put a keyboard character event in a string. Here are
|
|
|
2274 the rules:
|
|
|
2275
|
|
|
2276 * If the keyboard event value is in the range of 0 to 127, it can go
|
|
|
2277 in the string unchanged.
|
|
|
2278
|
|
|
2279 * The meta variants of those events, with codes in the range of
|
|
|
2280 2**23 to 2**23+127, can also go in the string, but you must change
|
|
|
2281 their numeric values. You must set the 2**7 bit instead of the
|
|
|
2282 2**23 bit, resulting in a value between 128 and 255.
|
|
|
2283
|
|
|
2284 * Other keyboard character events cannot fit in a string. This
|
|
|
2285 includes keyboard events in the range of 128 to 255.
|
|
|
2286
|
|
|
2287 Functions such as `read-key-sequence' that can construct strings
|
|
|
2288 containing events follow these rules.
|
|
|
2289
|
|
|
2290 When you use the read syntax `\M-' in a string, it produces a code
|
|
|
2291 in the range of 128 to 255--the same code that you get if you modify
|
|
|
2292 the corresponding keyboard event to put it in the string. Thus, meta
|
|
|
2293 events in strings work consistently regardless of how they get into the
|
|
|
2294 strings.
|
|
|
2295
|
|
|
2296 New programs can avoid dealing with these rules by using vectors
|
|
|
2297 instead of strings for key sequences when there is any possibility that
|
|
|
2298 these issues might arise.
|
|
|
2299
|
|
|
2300 The reason we changed the representation of meta characters as
|
|
|
2301 keyboard events is to make room for basic character codes beyond 127,
|
|
|
2302 and support meta variants of such larger character codes.
|
|
|
2303
|
|
|
2304 Menus
|
|
|
2305 =====
|
|
|
2306
|
|
|
2307 You can now define menus conveniently as keymaps. Menus are normally
|
|
|
2308 used with the mouse, but they can work with the keyboard also.
|
|
|
2309
|
|
|
2310 Defining Menus
|
|
|
2311 --------------
|
|
|
2312
|
|
|
2313 A keymap is suitable for menu use if it has an "overall prompt
|
|
|
2314 string", which is a string that appears as an element of the keymap. It
|
|
|
2315 should describes the purpose of the menu. The easiest way to construct
|
|
|
2316 a keymap with a prompt string is to specify the string as an argument
|
|
|
2317 when you run `make-keymap' or `make-sparse-keymap'.
|
|
|
2318
|
|
|
2319 The individual bindings in the menu keymap should also have prompt
|
|
|
2320 strings; these strings are the items in the menu. A binding with a
|
|
|
2321 prompt string looks like this:
|
|
|
2322
|
|
|
2323 (CHAR STRING . REAL-BINDING)
|
|
|
2324
|
|
|
2325 As far as `define-key' is concerned, the string is part of the
|
|
|
2326 character's binding--the binding looks like this:
|
|
|
2327
|
|
|
2328 (STRING . REAL-BINDING).
|
|
|
2329
|
|
|
2330 However, only REAL-BINDING is used for executing the key.
|
|
|
2331
|
|
|
2332 You can also supply a second string, called the help string, as
|
|
|
2333 follows:
|
|
|
2334
|
|
|
2335 (CHAR STRING HELP-STRING . REAL-BINDING)
|
|
|
2336
|
|
|
2337 Currently Emacs does not actually use HELP-STRING; it knows only how
|
|
|
2338 to ignore HELP-STRING in order to extract REAL-BINDING. In the future
|
|
|
2339 we hope to make HELP-STRING serve as longer documentation for the menu
|
|
|
2340 item, available on request.
|
|
|
2341
|
|
|
2342 The prompt string for a binding should be short--one or two words.
|
|
|
2343 Its meaning should describe the command it corresponds to.
|
|
|
2344
|
|
|
2345 If REAL-BINDING is `nil', then STRING appears in the menu but cannot
|
|
|
2346 be selected.
|
|
|
2347
|
|
|
2348 If REAL-BINDING is a symbol, and has a non-`nil' `menu-enable'
|
|
|
2349 property, that property is an expression which controls whether the
|
|
|
2350 menu item is enabled. Every time the keymap is used to display a menu,
|
|
|
2351 Emacs evaluates the expression, and it enables the menu item only if
|
|
|
2352 the expression's value is non-`nil'. When a menu item is disabled, it
|
|
|
2353 is displayed in a "fuzzy" fashion, and cannot be selected with the
|
|
|
2354 mouse.
|
|
|
2355
|
|
|
2356 Menus and the Mouse
|
|
|
2357 -------------------
|
|
|
2358
|
|
|
2359 The way to make a menu keymap produce a menu is to make it the
|
|
|
2360 definition of a prefix key.
|
|
|
2361
|
|
|
2362 When the prefix key ends with a mouse event, Emacs handles the menu
|
|
|
2363 keymap by popping up a visible menu that you can select from with the
|
|
|
2364 mouse. When you click on a menu item, the event generated is whatever
|
|
|
2365 character or symbol has the binding which brought about that menu item.
|
|
|
2366
|
|
|
2367 A single keymap can appear as multiple panes, if you explicitly
|
|
|
2368 arrange for this. The way to do this is to make a keymap for each
|
|
|
2369 pane, then create a binding for each of those maps in the main keymap
|
|
|
2370 of the menu. Give each of these bindings a prompt string that starts
|
|
|
2371 with `@'. The rest of the prompt string becomes the name of the pane.
|
|
|
2372 See the file `lisp/mouse.el' for an example of this. Any ordinary
|
|
|
2373 bindings with prompt strings are grouped into one pane, which appears
|
|
|
2374 along with the other panes explicitly created for the submaps.
|
|
|
2375
|
|
|
2376 You can also get multiple panes from separate keymaps. The full
|
|
|
2377 definition of a prefix key always comes from merging the definitions
|
|
|
2378 supplied by the various active keymaps (minor modes, local, and
|
|
|
2379 global). When more than one of these keymaps is a menu, each of them
|
|
|
2380 makes a separate pane or panes.
|
|
|
2381
|
|
|
2382 Menus and the Keyboard
|
|
|
2383 ----------------------
|
|
|
2384
|
|
|
2385 When a prefix key ending with a keyboard event (a character or
|
|
|
2386 function key) has a definition that is a menu keymap, you can use the
|
|
|
2387 keyboard to choose a menu item.
|
|
|
2388
|
|
|
2389 Emacs displays the menu alternatives in the echo area. If they don't
|
|
|
2390 all fit at once, type SPC to see the next line of alternatives. If you
|
|
|
2391 keep typing SPC, you eventually get to the end of the menu and then
|
|
|
2392 cycle around to the beginning again.
|
|
|
2393
|
|
|
2394 When you have found the alternative you want, type the corresponding
|
|
|
2395 character--the one whose binding is that alternative.
|
|
|
2396
|
|
|
2397 In a menu intended for keyboard use, each menu item must clearly
|
|
|
2398 indicate what character to type. The best convention to use is to make
|
|
|
2399 the character the first letter of the menu item prompt string. That is
|
|
|
2400 something users will understand without being told.
|
|
|
2401
|
|
|
2402 The Menu Bar
|
|
|
2403 ------------
|
|
|
2404
|
|
|
2405 Under X Windows, each frame can have a "menu bar"--a permanently
|
|
|
2406 displayed menu stretching horizontally across the top of the frame. The
|
|
|
2407 items of the menu bar are the subcommands of the fake "function key"
|
|
|
2408 `menu-bar', as defined by all the active keymaps.
|
|
|
2409
|
|
|
2410 To add an item to the menu bar, invent a fake "function key" of your
|
|
|
2411 own (let's call it KEY), and make a binding for the key sequence
|
|
|
2412 `[menu-bar KEY]'. Most often, the binding is a menu keymap, so that
|
|
|
2413 pressing a button on the menu bar item leads to another menu.
|
|
|
2414
|
|
|
2415 In order for a frame to display a menu bar, its `menu-bar-lines'
|
|
|
2416 property must be greater than zero. Emacs uses just one line for the
|
|
|
2417 menu bar itself; if you specify more than one line, the other lines
|
|
|
2418 serve to separate the menu bar from the windows in the frame. We
|
|
|
2419 recommend you try one or two as the `menu-bar-lines' value.
|
|
|
2420
|
|
|
2421 Keymaps
|
|
|
2422 =======
|
|
|
2423
|
|
|
2424 * The representation of keymaps has changed to support the new event
|
|
|
2425 types. All keymaps now have the form `(keymap ELEMENT ELEMENT
|
|
|
2426 ...)'. Each ELEMENT takes one of the following forms:
|
|
|
2427
|
|
|
2428 PROMPT-STRING
|
|
|
2429 A string as an element of the keymap marks the keymap as a
|
|
|
2430 menu, and serves as the overall prompt string for it.
|
|
|
2431
|
|
|
2432 `(KEY . BINDING)'
|
|
|
2433 A cons cell binds KEY to DEFINITION. Here KEY may be any
|
|
|
2434 sort of event head--a character, a function key symbol, or a
|
|
|
2435 mouse button symbol.
|
|
|
2436
|
|
|
2437 VECTOR
|
|
|
2438 A vector of 128 elements binds all the ASCII characters; the
|
|
|
2439 Nth element holds the binding for character number N.
|
|
|
2440
|
|
|
2441 `(t . BINDING)'
|
|
|
2442 A cons cell whose CAR is `t' is a default binding; anything
|
|
|
2443 not bound by previous keymap elements is given BINDING as its
|
|
|
2444 binding.
|
|
|
2445
|
|
|
2446 Default bindings are important because they allow a keymap to
|
|
|
2447 bind all possible events without having to enumerate all the
|
|
|
2448 possible function keys and mouse clicks, with all possible
|
|
|
2449 modifier prefixes.
|
|
|
2450
|
|
|
2451 The function `lookup-key' (and likewise other functions for
|
|
|
2452 examining a key binding) normally report only explicit
|
|
|
2453 bindings of the specified key sequence; if there is none,
|
|
|
2454 they return `nil', even if there is a default binding that
|
|
|
2455 would apply to that key sequence if it were actually typed
|
|
|
2456 in. However, these functions now take an optional argument
|
|
|
2457 ACCEPT-DEFAULTS which, if non-`nil', says to consider default
|
|
|
2458 bindings.
|
|
|
2459
|
|
|
2460 Note that if a vector in the keymap binds an ASCII character
|
|
|
2461 to `nil' (thus making it "unbound"), the default binding does
|
|
|
2462 not apply to the character. Think of the vector element as
|
|
|
2463 an explicit binding of `nil'.
|
|
|
2464
|
|
|
2465 Note also that if the keymap for a minor or major mode
|
|
|
2466 contains a default binding, it completely masks out any
|
|
|
2467 lower-priority keymaps.
|
|
|
2468
|
|
|
2469 * A keymap can now inherit from another keymap. To do this, make the
|
|
|
2470 latter keymap the "tail" of the new one. Such a keymap looks like
|
|
|
2471 this:
|
|
|
2472
|
|
|
2473 (keymap BINDINGS... . OTHER-KEYMAP)
|
|
|
2474
|
|
|
2475 The effect is that this keymap inherits all the bindings of
|
|
|
2476 OTHER-KEYMAP, but can add to them or override them with BINDINGS.
|
|
|
2477 Subsequent changes in the bindings of OTHER-KEYMAP *do* affect
|
|
|
2478 this keymap.
|
|
|
2479
|
|
|
2480 For example,
|
|
|
2481
|
|
|
2482 (setq my-mode-map (cons 'keymap text-mode-map))
|
|
|
2483
|
|
|
2484 makes a keymap that by default inherits all the bindings of Text
|
|
|
2485 mode--whatever they may be at the time a key is looked up. Any
|
|
|
2486 bindings made explicitly in `my-mode-map' override the bindings
|
|
|
2487 inherited from Text mode, however.
|
|
|
2488
|
|
|
2489 * Minor modes can now have local keymaps. Thus, a key can act a
|
|
|
2490 special way when a minor mode is in effect, and then revert to the
|
|
|
2491 major mode or global definition when the minor mode is no longer
|
|
|
2492 in effect. The precedence of keymaps is now: minor modes (in no
|
|
|
2493 particular order), then major mode, and lastly the global map.
|
|
|
2494
|
|
|
2495 The new `current-minor-mode-maps' function returns a list of all
|
|
|
2496 the keymaps of currently enabled minor modes, in the other that
|
|
|
2497 they apply.
|
|
|
2498
|
|
|
2499 To set up a keymap for a minor mode, add an element to the alist
|
|
|
2500 `minor-mode-map-alist'. Its elements look like this:
|
|
|
2501
|
|
|
2502 (SYMBOL . KEYMAP)
|
|
|
2503
|
|
|
2504 The keymap KEYMAP is active whenever SYMBOL has a non-`nil' value.
|
|
|
2505 Use for SYMBOL the variable which indicates whether the minor
|
|
|
2506 mode is enabled.
|
|
|
2507
|
|
|
2508 When more than one minor mode keymap is active, their order of
|
|
|
2509 precedence is the order of `minor-mode-map-alist'. But you should
|
|
|
2510 design minor modes so that they don't interfere with each other,
|
|
|
2511 and if you do this properly, the order will not matter.
|
|
|
2512
|
|
|
2513 The function `minor-mode-key-binding' returns a list of all the
|
|
|
2514 active minor mode bindings of KEY. More precisely, it returns an
|
|
2
|
2515 alist of pairs `(MODENAME . BINDING)', where MODENAME is the
|
|
0
|
2516 variable which enables the minor mode, and BINDING is KEY's
|
|
|
2517 definition in that mode. If KEY has no minor-mode bindings, the
|
|
|
2518 value is `nil'.
|
|
|
2519
|
|
|
2520 If the first binding is a non-prefix, all subsequent bindings from
|
|
|
2521 other minor modes are omitted, since they would be completely
|
|
|
2522 shadowed. Similarly, the list omits non-prefix bindings that
|
|
|
2523 follow prefix bindings.
|
|
|
2524
|
|
|
2525 * The new function `copy-keymap' copies a keymap, producing a new
|
|
|
2526 keymap with the same key bindings in it. If the keymap contains
|
|
|
2527 other keymaps directly, these subkeymaps are copied recursively.
|
|
|
2528
|
|
|
2529 If you want to, you can define a prefix key with a binding that is
|
|
|
2530 a symbol whose function definition is another keymap. In this
|
|
|
2531 case, `copy-keymap' does not look past the symbol; it doesn't copy
|
|
|
2532 the keymap inside the symbol.
|
|
|
2533
|
|
|
2534 * `substitute-key-definition' now accepts an optional fourth
|
|
|
2535 argument, which is a keymap to use as a template.
|
|
|
2536
|
|
|
2537 (substitute-key-definition olddef newdef keymap oldmap)
|
|
|
2538
|
|
|
2539 finds all characters defined in OLDMAP as OLDDEF, and defines them
|
|
|
2540 in KEYMAP as NEWDEF.
|
|
|
2541
|
|
|
2542 In addition, this function now operates recursively on the keymaps
|
|
|
2543 that define prefix keys within KEYMAP and OLDMAP.
|
|
|
2544
|
|
|
2545 Minibuffer Features
|
|
|
2546 ===================
|
|
|
2547
|
|
|
2548 The minibuffer input functions `read-from-minibuffer' and
|
|
|
2549 `completing-read' have new features.
|
|
|
2550
|
|
|
2551 Minibuffer History
|
|
|
2552 ------------------
|
|
|
2553
|
|
|
2554 A new optional argument HIST specifies which history list to use.
|
|
|
2555 If you specify a variable (a symbol), that variable is the history
|
|
|
2556 list. If you specify a cons cell `(VARIABLE . STARTPOS)', then
|
|
|
2557 VARIABLE is the history list variable, and STARTPOS specifies the
|
|
|
2558 initial history position (an integer, counting from zero which
|
|
|
2559 specifies the most recent element of the history).
|
|
|
2560
|
|
|
2561 If you specify STARTPOS, then you should also specify that element
|
|
|
2562 of the history as INITIAL-INPUT, for consistency.
|
|
|
2563
|
|
|
2564 If you don't specify HIST, then the default history list
|
|
|
2565 `minibuffer-history' is used. Other standard history lists that you
|
|
|
2566 can use when appropriate include `query-replace-history',
|
|
|
2567 `command-history', and `file-name-history'.
|
|
|
2568
|
|
|
2569 The value of the history list variable is a list of strings, most
|
|
|
2570 recent first. You should set a history list variable to `nil' before
|
|
|
2571 using it for the first time.
|
|
|
2572
|
|
|
2573 `read-from-minibuffer' and `completing-read' add new elements to the
|
|
|
2574 history list automatically, and provide commands to allow the user to
|
|
|
2575 reuse items on the list. The only thing your program needs to do to
|
|
|
2576 use a history list is to initialize it and to pass its name to the
|
|
|
2577 input functions when you wish. But it is safe to modify the list by
|
|
|
2578 hand when the minibuffer input functions are not using it.
|
|
|
2579
|
|
|
2580 Other Minibuffer Features
|
|
|
2581 -------------------------
|
|
|
2582
|
|
|
2583 The INITIAL argument to `read-from-minibuffer' and other minibuffer
|
|
|
2584 input functions can now be a cons cell `(STRING . POSITION)'. This
|
|
|
2585 means to start off with STRING in the minibuffer, but put the cursor
|
|
|
2586 POSITION characters from the beginning, rather than at the end.
|
|
|
2587
|
|
|
2588 In `read-no-blanks-input', the INITIAL argument is now optional; if
|
|
|
2589 it is omitted, the initial input string is the empty string.
|
|
|
2590
|
|
|
2591 New Features for Defining Commands
|
|
|
2592 ==================================
|
|
|
2593
|
|
|
2594 * If the interactive specification begins with `@', this means to
|
|
|
2595 select the window under the mouse. This selection takes place
|
|
|
2596 before doing anything else with the command.
|
|
|
2597
|
|
|
2598 You can use both `@' and `*' together in one command; they are
|
|
|
2599 processed in order of appearance.
|
|
|
2600
|
|
|
2601 * Prompts in an interactive specification can incorporate the values
|
|
|
2602 of the preceding arguments. Emacs replaces `%'-sequences (as used
|
|
|
2603 with the `format' function) in the prompt with the interactive
|
|
|
2604 arguments that have been read so far. For example, a command with
|
|
|
2605 this interactive specification
|
|
|
2606
|
|
|
2607 (interactive "sReplace: \nsReplace %s with: ")
|
|
|
2608
|
|
|
2609 prompts for the first argument with `Replace: ', and then prompts
|
|
|
2610 for the second argument with `Replace FOO with: ', where FOO is
|
|
|
2611 the string read as the first argument.
|
|
|
2612
|
|
|
2613 * If a command name has a property `enable-recursive-minibuffers'
|
|
|
2614 which is non-`nil', then the command can use the minibuffer to read
|
|
|
2615 arguments even if it is invoked from the minibuffer. The
|
|
|
2616 minibuffer command `next-matching-history-element' (normally bound
|
|
|
2617 to `M-s' in the minibuffer) uses this feature.
|
|
|
2618
|
|
|
2619 New Features for Reading Input
|
|
|
2620 ==============================
|
|
|
2621
|
|
|
2622 * The function `set-input-mode' now takes four arguments. The last
|
|
|
2623 argument is optional. Their names are INTERRUPT, FLOW, META and
|
|
|
2624 QUIT.
|
|
|
2625
|
|
|
2626 The argument INTERRUPT says whether to use interrupt-driven input.
|
|
|
2627 Non-`nil' means yes, and `nil' means no (use CBREAK mode).
|
|
|
2628
|
|
|
2629 The argument FLOW says whether to enable terminal flow control.
|
|
|
2630 Non-`nil' means yes.
|
|
|
2631
|
|
|
2632 The argument META controls support for input character codes above
|
|
|
2633 127. If META is `t', Emacs converts characters with the 8th bit
|
|
|
2634 set into Meta characters. If META is `nil', Emacs disregards the
|
|
|
2635 8th bit; this is necessary when the terminal uses it as a parity
|
|
|
2636 bit. If META is neither `t' nor `nil', Emacs uses all 8 bits of
|
|
|
2637 input unchanged. This is good for terminals using European 8-bit
|
|
|
2638 character sets.
|
|
|
2639
|
|
|
2640 If QUIT non-`nil', it is the character to use for quitting.
|
|
|
2641 (Normally this is `C-g'.)
|
|
|
2642
|
|
|
2643 * The variable `meta-flag' has been deleted; use `set-input-mode' to
|
|
|
2644 enable or disable support for a META key. This change was made
|
|
|
2645 because `set-input-mode' can send the terminal the appropriate
|
|
|
2646 commands to enable or disable operation of the META key.
|
|
|
2647
|
|
|
2648 * The new variable `extra-keyboard-modifiers' lets Lisp programs
|
|
|
2649 "press" the modifier keys on the keyboard. The value is a bit
|
|
|
2650 mask:
|
|
|
2651
|
|
|
2652 1
|
|
|
2653 The SHIFT key.
|
|
|
2654
|
|
|
2655 2
|
|
|
2656 The LOCK key.
|
|
|
2657
|
|
|
2658 4
|
|
|
2659 The CTL key.
|
|
|
2660
|
|
|
2661 8
|
|
|
2662 The META key.
|
|
|
2663
|
|
|
2664 When you use X windows, the program can press any of the modifier
|
|
|
2665 keys in this way. Otherwise, only the CTL and META keys can be
|
|
|
2666 virtually pressed.
|
|
|
2667
|
|
|
2668 * You can use the new function `keyboard-translate' to set up
|
|
|
2669 `keyboard-translate-table' conveniently.
|
|
|
2670
|
|
|
2671 * Y-or-n questions using the `y-or-n-p' function now accept `C-]'
|
|
|
2672 (usually mapped to `abort-recursive-edit') as well as `C-g' to
|
|
|
2673 quit.
|
|
|
2674
|
|
|
2675 * The variable `num-input-keys' is the total number of key sequences
|
|
|
2676 that the user has typed during this Emacs session.
|
|
|
2677
|
|
|
2678 * A new Lisp variable, `function-key-map', holds a keymap which
|
|
|
2679 describes the character sequences sent by function keys on an
|
|
|
2680 ordinary character terminal. This uses the same keymap data
|
|
|
2681 structure that is used to hold bindings of key sequences, but it
|
|
|
2682 has a different meaning: it specifies translations to make while
|
|
|
2683 reading a key sequence.
|
|
|
2684
|
|
|
2685 If `function-key-map' "binds" a key sequence K to a vector V, then
|
|
|
2686 when K appears as a subsequence *anywhere* in a key sequence, it
|
|
|
2687 is replaced with V.
|
|
|
2688
|
|
|
2689 For example, VT100 terminals send `ESC O P' when the "keypad" PF1
|
|
|
2690 key is pressed. Thus, on a VT100, `function-key-map' should
|
|
|
2691 "bind" that sequence to `[pf1]'. This specifies translation of
|
|
|
2692 `ESC O P' into PF1 anywhere in a key sequence.
|
|
|
2693
|
|
|
2694 Thus, typing `C-c PF1' sends the character sequence `C-c ESC O P',
|
|
|
2695 but `read-key-sequence' translates this back into `C-c PF1', which
|
|
|
2696 it returns as the vector `[?\C-c PF1]'.
|
|
|
2697
|
|
|
2698 Entries in `function-key-map' are ignored if they conflict with
|
|
|
2699 bindings made in the minor mode, local, or global keymaps.
|
|
|
2700
|
|
|
2701 The value of `function-key-map' is usually set up automatically
|
|
|
2702 according to the terminal's Terminfo or Termcap entry, and the
|
|
|
2703 terminal-specific Lisp files. Emacs comes with a number of
|
|
|
2704 terminal-specific files for many common terminals; their main
|
|
|
2705 purpose is to make entries in `function-key-map' beyond those that
|
|
|
2706 can be deduced from Termcap and Terminfo.
|
|
|
2707
|
|
|
2708 * The variable `key-translation-map' works like `function-key-map'
|
|
|
2709 except for two things:
|
|
|
2710
|
|
|
2711 * `key-translation-map' goes to work after `function-key-map' is
|
|
|
2712 finished; it receives the results of translation by
|
|
|
2713 `function-key-map'.
|
|
|
2714
|
|
|
2715 * `key-translation-map' overrides actual key bindings.
|
|
|
2716
|
|
|
2717 The intent of `key-translation-map' is for users to map one
|
|
|
2718 character set to another, including ordinary characters normally
|
|
|
2719 bound to `self-insert-command'.
|
|
|
2720
|
|
|
2721 New Syntax Table Features
|
|
|
2722 =========================
|
|
|
2723
|
|
|
2724 * You can use two new functions to move across characters in certain
|
|
|
2725 syntax classes.
|
|
|
2726
|
|
|
2727 `skip-syntax-forward' moves point forward across characters whose
|
|
|
2728 syntax classes are mentioned in its first argument, a string. It
|
|
|
2729 stops when it encounters the end of the buffer, or position LIM
|
|
|
2730 (the optional second argument), or a character it is not supposed
|
|
|
2731 to skip. The function `skip-syntax-backward' is similar but moves
|
|
|
2732 backward.
|
|
|
2733
|
|
|
2734 * The new function `forward-comment' moves point by comments. It
|
|
|
2735 takes one argument, COUNT; it moves point forward across COUNT
|
|
|
2736 comments (backward, if COUNT is negative). If it finds anything
|
|
|
2737 other than a comment or whitespace, it stops, leaving point at the
|
|
|
2738 far side of the last comment found. It also stops after
|
|
|
2739 satisfying COUNT.
|
|
|
2740
|
|
|
2741 * The new variable `words-include-escapes' affects the behavior of
|
|
|
2742 `forward-word' and everything that uses it. If it is non-`nil',
|
|
|
2743 then characters in the "escape" and "character quote" syntax
|
|
|
2744 classes count as part of words.
|
|
|
2745
|
|
|
2746 * There are two new syntax flags for use in syntax tables.
|
|
|
2747
|
|
|
2748 - The prefix flag.
|
|
|
2749
|
|
|
2750 The `p' flag identifies additional "prefix characters" in Lisp
|
|
|
2751 syntax. You can set this flag with `modify-syntax-entry' by
|
|
|
2752 including the letter `p' in the syntax specification.
|
|
|
2753
|
|
|
2754 These characters are treated as whitespace when they appear
|
|
|
2755 between expressions. When they appear withing an expression,
|
|
|
2756 they are handled according to their usual syntax codes.
|
|
|
2757
|
|
|
2758 The function `backward-prefix-chars' moves back over these
|
|
|
2759 characters, as well as over characters whose primary syntax
|
|
|
2760 class is prefix (`'').
|
|
|
2761
|
|
|
2762 - The `b' comment style flag.
|
|
|
2763
|
|
|
2764 Emacs can now supports two comment styles simultaneously.
|
|
|
2765 (This is for the sake of C++.) More specifically, it can
|
|
|
2766 recognize two different comment-start sequences. Both must
|
|
|
2767 share the same first character; only the second character may
|
|
|
2768 differ. Mark the second character of the `b'-style comment
|
|
|
2769 start sequence with the `b' flag. You can set this flag with
|
|
|
2770 `modify-syntax-entry' by including the letter `b' in the
|
|
|
2771 syntax specification.
|
|
|
2772
|
|
|
2773 The two styles of comment can have different comment-end
|
|
|
2774 sequences. A comment-end sequence (one or two characters)
|
|
|
2775 applies to the `b' style if its first character has the `b'
|
|
|
2776 flag set; otherwise, it applies to the `a' style.
|
|
|
2777
|
|
|
2778 The appropriate comment syntax settings for C++ are as
|
|
|
2779 follows:
|
|
|
2780
|
|
|
2781 `/'
|
|
|
2782 `124b'
|
|
|
2783
|
|
|
2784 `*'
|
|
|
2785 `23'
|
|
|
2786
|
|
|
2787 newline
|
|
|
2788 `>b'
|
|
|
2789
|
|
|
2790 Thus `/*' is a comment-start sequence for `a' style, `//' is
|
|
|
2791 a comment-start sequence for `b' style, `*/' is a comment-end
|
|
|
2792 sequence for `a' style, and newline is a comment-end sequence
|
|
|
2793 for `b' style.
|
|
|
2794
|
|
|
2795 The Case Table
|
|
|
2796 ==============
|
|
|
2797
|
|
|
2798 You can customize case conversion using the new case table feature.
|
|
|
2799 A case table is a collection of strings that specifies the mapping
|
|
|
2800 between upper case and lower case letters. Each buffer has its own
|
|
|
2801 case table. You need a case table if you are using a language which
|
|
|
2802 has letters that are not standard ASCII letters.
|
|
|
2803
|
|
|
2804 A case table is a list of this form:
|
|
|
2805
|
|
|
2806 (DOWNCASE UPCASE CANONICALIZE EQUIVALENCES)
|
|
|
2807
|
|
|
2808 where each element is either `nil' or a string of length 256. The
|
|
|
2809 element DOWNCASE says how to map each character to its lower-case
|
|
|
2810 equivalent. The element UPCASE maps each character to its upper-case
|
|
|
2811 equivalent. If lower and upper case characters are in 1-1
|
|
|
2812 correspondence, use `nil' for UPCASE; then Emacs deduces the upcase
|
|
|
2813 table from DOWNCASE.
|
|
|
2814
|
|
|
2815 For some languages, upper and lower case letters are not in 1-1
|
|
|
2816 correspondence. There may be two different lower case letters with the
|
|
|
2817 same upper case equivalent. In these cases, you need to specify the
|
|
|
2818 maps for both directions.
|
|
|
2819
|
|
|
2820 The element CANONICALIZE maps each character to a canonical
|
|
|
2821 equivalent; any two characters that are related by case-conversion have
|
|
|
2822 the same canonical equivalent character.
|
|
|
2823
|
|
|
2824 The element EQUIVALENCES is a map that cyclicly permutes each
|
|
|
2825 equivalence class (of characters with the same canonical equivalent).
|
|
|
2826
|
|
|
2827 You can provide `nil' for both CANONICALIZE and EQUIVALENCES, in
|
|
|
2828 which case both are deduced from DOWNCASE and UPCASE.
|
|
|
2829
|
|
|
2830 Here are the functions for working with case tables:
|
|
|
2831
|
|
|
2832 `case-table-p' is a predicate that says whether a Lisp object is a
|
|
|
2833 valid case table.
|
|
|
2834
|
|
|
2835 `set-standard-case-table' takes one argument and makes that argument
|
|
|
2836 the case table for new buffers created subsequently.
|
|
|
2837 `standard-case-table' returns the current value of the new buffer case
|
|
|
2838 table.
|
|
|
2839
|
|
|
2840 `current-case-table' returns the case table of the current buffer.
|
|
|
2841 `set-case-table' sets the current buffer's case table to the argument.
|
|
|
2842
|
|
|
2843 `set-case-syntax-pair' is a convenient function for specifying a
|
|
|
2844 pair of letters, upper case and lower case. Call it with two arguments,
|
|
|
2845 the upper case letter and the lower case letter. It modifies the
|
|
|
2846 standard case table and a few syntax tables that are predefined in
|
|
|
2847 Emacs. This function is intended as a subroutine for packages that
|
|
|
2848 define non-ASCII character sets.
|
|
|
2849
|
|
|
2850 Load the library `iso-syntax' to set up the syntax and case table for
|
|
|
2851 the 256 bit ISO Latin 1 character set.
|
|
|
2852
|
|
|
2853 New Features for Dealing with Buffers
|
|
|
2854 =====================================
|
|
|
2855
|
|
|
2856 * The new function `buffer-modified-tick' returns a buffer's
|
|
|
2857 modification-count that ticks every time the buffer is modified.
|
|
|
2858 It takes one optional argument, which is the buffer you want to
|
|
|
2859 examine. If the argument is `nil' (or omitted), the current
|
|
|
2860 buffer is used.
|
|
|
2861
|
|
|
2862 * `buffer-disable-undo' is a new name for the function formerly
|
|
|
2863 known as `buffer-flush-undo'. This turns off recording of undo
|
|
|
2864 information in the buffer given as argument.
|
|
|
2865
|
|
|
2866 * The new function `generate-new-buffer-name' chooses a name that
|
|
|
2867 would be unique for a new buffer--but does not create the buffer.
|
|
|
2868 Give it one argument, a starting name. It produces a name not in
|
|
|
2869 use for a buffer by appending a number inside of `<...>'.
|
|
|
2870
|
|
|
2871 * The function `rename-buffer' now takes an optional second argument
|
|
|
2872 which tells it that if the specified new name corresponds to an
|
|
|
2873 existing buffer, it should use `generate-new-buffer-name' to
|
|
|
2874 modify the name to be unique, rather than signaling an error.
|
|
|
2875
|
|
|
2876 `rename-buffer' now returns the name to which the buffer was
|
|
|
2877 renamed.
|
|
|
2878
|
|
|
2879 * The function `list-buffers' now looks at the local variable
|
|
|
2880 `list-buffers-directory' in each non-file-visiting buffer, and
|
|
|
2881 shows its value where the file would normally go. Dired sets this
|
|
|
2882 variable in each Dired buffer, so the buffer list now shows which
|
|
|
2883 directory each Dired buffer is editing.
|
|
|
2884
|
|
|
2885 * The function `other-buffer' now takes an optional second argument
|
|
|
2886 VISIBLE-OK which, if non-`nil', indicates that buffers currently
|
|
|
2887 being displayed in windows may be returned even if there are other
|
|
|
2888 buffers not visible. Normally, `other-buffer' returns a currently
|
|
|
2889 visible buffer only as a last resort, if there are no suitable
|
|
|
2890 nonvisible buffers.
|
|
|
2891
|
|
|
2892 * The hook `kill-buffer-hook' now runs whenever a buffer is killed.
|
|
|
2893
|
|
|
2894 Local Variables Features
|
|
|
2895 ========================
|
|
|
2896
|
|
|
2897 * If a local variable name has a non-`nil' `permanent-local'
|
|
|
2898 property, then `kill-all-local-variables' does not kill it. Such
|
|
|
2899 local variables are "permanent"--they remain unchanged even if you
|
|
|
2900 select a different major mode.
|
|
|
2901
|
|
|
2902 Permanent locals are useful when they have to do with where the
|
|
|
2903 file came from or how to save it, rather than with how to edit the
|
|
|
2904 contents.
|
|
|
2905
|
|
|
2906 * The function `make-local-variable' now never changes the value of
|
|
|
2907 the variable that it makes local. If the variable had no value
|
|
|
2908 before, it still has no value after becoming local.
|
|
|
2909
|
|
|
2910 * The new function `default-boundp' tells you whether a variable has
|
|
|
2911 a default value (as opposed to being unbound in its default
|
|
|
2912 value). If `(default-boundp 'foo)' returns `nil', then
|
|
|
2913 `(default-value 'foo)' would get an error.
|
|
|
2914
|
|
|
2915 `default-boundp' is to `default-value' as `boundp' is to
|
|
|
2916 `symbol-value'.
|
|
|
2917
|
|
|
2918 * The special forms `defconst' and `defvar', when the variable is
|
|
|
2919 local in the current buffer, now set the variable's default value
|
|
|
2920 rather than its local value.
|
|
|
2921
|
|
|
2922 New Features for Subprocesses
|
|
|
2923 =============================
|
|
|
2924
|
|
|
2925 * `call-process' and `call-process-region' now return a value that
|
|
|
2926 indicates how the synchronous subprocess terminated. It is either
|
|
|
2927 a number, which is the exit status of a process, or a signal name
|
|
|
2928 represented as a string.
|
|
|
2929
|
|
|
2930 * `process-status' now returns `open' and `closed' as the status
|
|
|
2931 values for network connections.
|
|
|
2932
|
|
|
2933 * The standard asynchronous subprocess features work on VMS now, and
|
|
|
2934 the special VMS asynchronous subprocess functions have been
|
|
|
2935 deleted.
|
|
|
2936
|
|
|
2937 * You can use the transaction queue feature for more convenient
|
|
|
2938 communication with subprocesses using transactions.
|
|
|
2939
|
|
|
2940 Call `tq-create' to create a transaction queue communicating with a
|
|
|
2941 specified process. Then you can call `tq-enqueue' to send a
|
|
|
2942 transaction. `tq-enqueue' takes these five arguments:
|
|
|
2943
|
|
|
2944 (tq-enqueue TQ QUESTION REGEXP CLOSURE FN)
|
|
|
2945
|
|
|
2946 TQ is the queue to use. (Specifying the queue has the effect of
|
|
|
2947 specifying the process to talk to.) The argument QUESTION is the
|
|
|
2948 outgoing message which starts the transaction. The argument FN is
|
|
|
2949 the function to call when the corresponding answer comes back; it
|
|
|
2950 is called with two arguments: CLOSURE, and the answer received.
|
|
|
2951
|
|
|
2952 The argument REGEXP is a regular expression to match the entire
|
|
|
2953 answer; that's how `tq-enqueue' tells where the answer ends.
|
|
|
2954
|
|
|
2955 Call `tq-close' to shut down a transaction queue and terminate its
|
|
|
2956 subprocess.
|
|
|
2957
|
|
|
2958 * The function `signal-process' sends a signal to process PID, which
|
|
|
2959 need not be a child of Emacs. The second argument SIGNAL
|
|
|
2960 specifies which signal to send; it should be an integer.
|
|
|
2961
|
|
|
2962 New Features for Dealing with Times And Time Delays
|
|
|
2963 ===================================================
|
|
|
2964
|
|
|
2965 * The new function `current-time' returns the system's time value as
|
|
|
2966 a list of three integers: `(HIGH LOW MICROSEC)'. The integers
|
|
|
2967 HIGH and LOW combine to give the number of seconds since 0:00
|
|
|
2968 January 1, 1970, which is HIGH * 2**16 + LOW.
|
|
|
2969
|
|
|
2970 MICROSEC gives the microseconds since the start of the current
|
|
|
2971 second (or 0 for systems that return time only on the resolution
|
|
|
2972 of a second).
|
|
|
2973
|
|
|
2974 * The function `current-time-string' accepts an optional argument
|
|
|
2975 TIME-VALUE. If given, this specifies a time to format instead of
|
|
|
2976 the current time. The argument should be a cons cell containing
|
|
|
2977 two integers, or a list whose first two elements are integers.
|
|
|
2978 Thus, you can use times obtained from `current-time' (see above)
|
|
|
2979 and from `file-attributes'.
|
|
|
2980
|
|
|
2981 * You can now find out the user's time zone using
|
|
|
2982 `current-time-zone'.
|
|
|
2983
|
|
|
2984 The value has the form `(OFFSET NAME)'. Here OFFSET is an integer
|
|
|
2985 giving the number of seconds ahead of UTC (east of Greenwich). A
|
|
|
2986 negative value means west of Greenwich. The second element, NAME
|
|
|
2987 is a string giving the name of the time zone. Both elements
|
|
|
2988 change when daylight savings time begins or ends; if the user has
|
|
|
2989 specified a time zone that does not use a seasonal time
|
|
|
2990 adjustment, then the value is constant through time.
|
|
|
2991
|
|
|
2992 If the operating system doesn't supply all the information
|
|
|
2993 necessary to compute the value, both elements of the list are
|
|
|
2994 `nil'.
|
|
|
2995
|
|
|
2996 The optional argument TIME-VALUE, if given, specifies a time to
|
|
|
2997 analyze instead of the current time. The argument should be a
|
|
|
2998 cons cell containing two integers, or a list whose first two
|
|
|
2999 elements are integers. Thus, you can use times obtained from
|
|
|
3000 `current-time' and from `file-attributes'.
|
|
|
3001
|
|
|
3002 * `sit-for', `sleep-for' now let you specify the time period in
|
|
|
3003 milliseconds as well as in seconds. The first argument gives the
|
|
|
3004 number of seconds, as before, and the optional second argument
|
|
|
3005 gives additional milliseconds. The time periods specified by
|
|
|
3006 these two arguments are added together.
|
|
|
3007
|
|
|
3008 Not all systems support this; you get an error if you specify
|
|
|
3009 nonzero milliseconds and it isn't supported.
|
|
|
3010
|
|
|
3011 `sit-for' also accepts an optional third argument NODISP. If this
|
|
|
3012 is non-`nil', `sit-for' does not redisplay. It still waits for
|
|
|
3013 the specified time or until input is available.
|
|
|
3014
|
|
|
3015 * `accept-process-output' now accepts a timeout specified by optional
|
|
|
3016 second and third arguments. The second argument specifies the
|
|
|
3017 number of seconds, while the third specifies the number of
|
|
|
3018 milliseconds. The time periods specified by these two arguments
|
|
|
3019 are added together.
|
|
|
3020
|
|
|
3021 Not all systems support this; you get an error if you specify
|
|
|
3022 nonzero milliseconds and it isn't supported.
|
|
|
3023
|
|
|
3024 The function returns `nil' if the timeout expired before output
|
|
|
3025 arrived, or non-`nil' if it did get some output.
|
|
|
3026
|
|
|
3027 * You can set up a timer to call a function at a specified future
|
|
|
3028 time. To do so, call `run-at-time', like this:
|
|
|
3029
|
|
|
3030 (run-at-time TIME REPEAT FUNCTION ARGS...)
|
|
|
3031
|
|
|
3032 Here, TIME is a string saying when to call the function. The
|
|
|
3033 argument FUNCTION is the function to call later, and ARGS are the
|
|
|
3034 arguments to give it when it is called.
|
|
|
3035
|
|
|
3036 The argument REPEAT specifies how often to repeat the call. If
|
|
|
3037 REPEAT is `nil', there are no repetitions; FUNCTION is called just
|
|
|
3038 once, at TIME. If REPEAT is an integer, it specifies a repetition
|
|
|
3039 period measured in seconds.
|
|
|
3040
|
|
|
3041 Absolute times may be specified in a wide variety of formats; The
|
|
|
3042 form `HOUR:MIN:SEC TIMEZONE MONTH/DAY/YEAR', where all fields are
|
|
|
3043 numbers, works; the format that `current-time-string' returns is
|
|
|
3044 also allowed.
|
|
|
3045
|
|
|
3046 To specify a relative time, use numbers followed by units. For
|
|
|
3047 example:
|
|
|
3048
|
|
|
3049 `1 min'
|
|
|
3050 denotes 1 minute from now.
|
|
|
3051
|
|
|
3052 `1 min 5 sec'
|
|
|
3053 denotes 65 seconds from now.
|
|
|
3054
|
|
|
3055 `1 min 2 sec 3 hour 4 day 5 week 6 fortnight 7 month 8 year'
|
|
|
3056 denotes exactly 103 months, 123 days, and 10862 seconds from
|
|
|
3057 now.
|
|
|
3058
|
|
|
3059 If TIME is an integer, that specifies a relative time measured in
|
|
|
3060 seconds.
|
|
|
3061
|
|
|
3062 To cancel the requested future action, pass the value that
|
|
|
3063 `run-at-time' returned to the function `cancel-timer'.
|
|
|
3064
|
|
|
3065 Profiling Lisp Programs
|
|
|
3066 =======================
|
|
|
3067
|
|
|
3068 You can now make execution-time profiles of Emacs Lisp programs using
|
|
|
3069 the `profile' library. See the file `profile.el' for instructions; if
|
|
|
3070 you have written a Lisp program big enough to be worth profiling, you
|
|
|
3071 can surely understand them.
|
|
|
3072
|
|
|
3073 New Features for Lisp Debuggers
|
|
|
3074 ===============================
|
|
|
3075
|
|
|
3076 * You can now specify which kinds of errors should invoke the Lisp
|
|
|
3077 debugger by setting the variable `debug-on-error' to a list of
|
|
|
3078 error conditions. For example, if you set it to the list
|
|
|
3079 `(void-variable)', then only errors about a variable that has no
|
|
|
3080 value invoke the debugger.
|
|
|
3081
|
|
|
3082 * The variable `command-debug-status' is used by Lisp debuggers. It
|
|
|
3083 records the debugging status of current interactive command. Each
|
|
|
3084 time a command is called interactively, this variable is bound to
|
|
|
3085 `nil'. The debugger can set this variable to leave information for
|
|
|
3086 future debugger invocations during the same command.
|
|
|
3087
|
|
|
3088 The advantage of this variable over some other variable in the
|
|
|
3089 debugger itself is that the data will not be visible for any other
|
|
|
3090 command invocation.
|
|
|
3091
|
|
|
3092 * The function `backtrace-frame' is intended for use in Lisp
|
|
|
3093 debuggers. It returns information about what a frame on the Lisp
|
|
|
3094 call stack is doing. You specify one argument, which is the
|
|
|
3095 number of stack frames to count up from the current execution
|
|
|
3096 point.
|
|
|
3097
|
|
|
3098 If that stack frame has not evaluated the arguments yet (or is a
|
|
|
3099 special form), the value is `(nil FUNCTION ARG-FORMS...)'.
|
|
|
3100
|
|
|
3101 If that stack frame has evaluated its arguments and called its
|
|
|
3102 function already, the value is `(t FUNCTION ARG-VALUES...)'.
|
|
|
3103
|
|
|
3104 In the return value, FUNCTION is whatever was supplied as CAR of
|
|
|
3105 evaluated list, or a `lambda' expression in the case of a macro
|
|
|
3106 call. If the function has a `&rest' argument, that is represented
|
|
|
3107 as the tail of the list ARG-VALUES.
|
|
|
3108
|
|
|
3109 If the argument is out of range, `backtrace-frame' returns `nil'.
|
|
|
3110
|
|
|
3111 Memory Allocation Changes
|
|
|
3112 =========================
|
|
|
3113
|
|
|
3114 The list that `garbage-collect' returns now has one additional
|
|
|
3115 element. This is a cons cell containing two numbers. It gives
|
|
|
3116 information about the number of used and free floating point numbers,
|
|
|
3117 much as the first element gives such information about the number of
|
|
|
3118 used and free cons cells.
|
|
|
3119
|
|
|
3120 The new function `memory-limit' returns an indication of the last
|
|
|
3121 address allocated by Emacs. More precisely, it returns that address
|
|
|
3122 divided by 1024. You can use this to get a general idea of how your
|
|
|
3123 actions affect the memory usage.
|
|
|
3124
|
|
|
3125 Hook Changes
|
|
|
3126 ============
|
|
|
3127
|
|
|
3128 * Expanding an abbrev first runs the new hook
|
|
|
3129 `pre-abbrev-expand-hook'.
|
|
|
3130
|
|
|
3131 * The editor command loop runs the normal hook `pre-command-hook'
|
|
|
3132 before each command, and runs `post-command-hook' after each
|
|
|
3133 command.
|
|
|
3134
|
|
|
3135 * Auto-saving runs the new hook `auto-save-hook' before actually
|
|
|
3136 starting to save any files.
|
|
|
3137
|
|
|
3138 * The new variable `revert-buffer-insert-file-contents-function'
|
|
|
3139 holds a function that `revert-buffer' now uses to read in the
|
|
|
3140 contents of the reverted buffer--instead of calling
|
|
|
3141 `insert-file-contents'.
|
|
|
3142
|
|
|
3143 * The variable `lisp-indent-hook' has been renamed to
|
|
|
3144 `lisp-indent-function'.
|
|
|
3145
|
|
|
3146 * The variable `auto-fill-hook' has been renamed to
|
|
|
3147 `auto-fill-function'.
|
|
|
3148
|
|
|
3149 * The variable `blink-paren-hook' has been renamed to
|
|
|
3150 `blink-paren-function'.
|
|
|
3151
|
|
|
3152 * The variable `temp-buffer-show-hook' has been renamed to
|
|
|
3153 `temp-buffer-show-function'.
|
|
|
3154
|
|
|
3155 * The variable `suspend-hook' is now a normal hook. It used to be a
|
|
|
3156 special kind of hook; its value had to be a single function, and
|
|
|
3157 if the function returned a non-`nil' value, then suspension was
|
|
|
3158 inhibited.
|
|
|
3159
|
|
|
3160 * The new function `add-hook' provides a handy way to add a function
|
|
|
3161 to a hook variable. For example,
|
|
|
3162
|
|
|
3163 (add-hook 'text-mode-hook 'my-text-hook-function)
|
|
|
3164
|
|
|
3165 arranges to call `my-text-hook-function' when entering Text mode
|
|
|
3166 or related modes.
|
|
|
3167
|
|
|
3168 `add-hook' takes an optional third argument which says to add the
|
|
|
3169 new hook function at the end of the list (normally, it goes at the
|
|
|
3170 beginning).
|
|
|
3171
|
