Mercurial > emacs
annotate lispref/display.texi @ 12067:73dc8205d259
*** empty log message ***
author | Karl Heuer <kwzh@gnu.org> |
---|---|
date | Mon, 05 Jun 1995 12:23:13 +0000 |
parents | 0a84a40f16d5 |
children | a6eb5f12b0f3 |
rev | line source |
---|---|
6598 | 1 @c -*-texinfo-*- |
2 @c This is part of the GNU Emacs Lisp Reference Manual. | |
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. | |
4 @c See the file elisp.texi for copying conditions. | |
5 @setfilename ../info/display | |
6 @node Display, Calendar, System Interface, Top | |
7 @chapter Emacs Display | |
8 | |
9 This chapter describes a number of features related to the display | |
10 that Emacs presents to the user. | |
11 | |
12 @menu | |
13 * Refresh Screen:: Clearing the screen and redrawing everything on it. | |
14 * Screen Size:: How big is the Emacs screen. | |
15 * Truncation:: Folding or wrapping long text lines. | |
16 * The Echo Area:: Where messages are displayed. | |
12067 | 17 * Invisible Text:: Hiding part of the buffer text. |
18 * Selective Display:: Hiding part of the buffer text (the old way). | |
6598 | 19 * Overlay Arrow:: Display of an arrow to indicate position. |
20 * Temporary Displays:: Displays that go away automatically. | |
21 * Overlays:: Use overlays to highlight parts of the buffer. | |
22 * Faces:: A face defines a graphics appearance: font, color, etc. | |
23 * Blinking:: How Emacs shows the matching open parenthesis. | |
24 * Inverse Video:: Specifying how the screen looks. | |
25 * Usual Display:: The usual conventions for displaying nonprinting chars. | |
26 * Display Tables:: How to specify other conventions. | |
27 * Beeping:: Audible signal to the user. | |
28 * Window Systems:: Which window system is being used. | |
29 @end menu | |
30 | |
31 @node Refresh Screen | |
32 @section Refreshing the Screen | |
33 | |
34 The function @code{redraw-frame} redisplays the entire contents of a | |
35 given frame. @xref{Frames}. | |
36 | |
37 @c Emacs 19 feature | |
38 @defun redraw-frame frame | |
39 This function clears and redisplays frame @var{frame}. | |
40 @end defun | |
41 | |
42 Even more powerful is @code{redraw-display}: | |
43 | |
44 @deffn Command redraw-display | |
45 This function clears and redisplays all visible frames. | |
46 @end deffn | |
47 | |
48 Normally, suspending and resuming Emacs also refreshes the screen. | |
49 Some terminal emulators record separate contents for display-oriented | |
50 programs such as Emacs and for ordinary sequential display. If you are | |
51 using such a terminal, you might want to inhibit the redisplay on | |
9009 | 52 resumption. |
6598 | 53 |
54 @defvar no-redraw-on-reenter | |
55 @cindex suspend (cf. @code{no-redraw-on-reenter}) | |
56 @cindex resume (cf. @code{no-redraw-on-reenter}) | |
57 This variable controls whether Emacs redraws the entire screen after it | |
58 has been suspended and resumed. Non-@code{nil} means yes, @code{nil} | |
59 means no. | |
60 @end defvar | |
61 | |
62 Processing user input takes absolute priority over redisplay. If you | |
63 call these functions when input is available, they do nothing | |
64 immediately, but a full redisplay does happen eventually---after all the | |
65 input has been processed. | |
66 | |
67 @node Screen Size | |
68 @section Screen Size | |
69 @cindex size of screen | |
70 @cindex screen size | |
71 @cindex display lines | |
72 @cindex display columns | |
73 @cindex resize redisplay | |
74 | |
9009 | 75 The screen size functions access or specify the height or width of |
6598 | 76 the terminal. When you are using multiple frames, they apply to the |
77 selected frame (@pxref{Frames}). | |
78 | |
79 @defun screen-height | |
80 This function returns the number of lines on the screen that are | |
81 available for display. | |
82 | |
83 @example | |
84 @group | |
85 (screen-height) | |
86 @result{} 50 | |
87 @end group | |
88 @end example | |
89 @end defun | |
90 | |
91 @defun screen-width | |
92 This function returns the number of columns on the screen that are | |
93 available for display. | |
94 | |
95 @example | |
96 @group | |
97 (screen-width) | |
98 @result{} 80 | |
99 @end group | |
100 @end example | |
101 @end defun | |
102 | |
103 @defun set-screen-height lines &optional not-actual-size | |
104 This function declares that the terminal can display @var{lines} lines. | |
105 The sizes of existing windows are altered proportionally to fit. | |
106 | |
107 If @var{not-actual-size} is non-@code{nil}, then Emacs displays | |
108 @var{lines} lines of output, but does not change its value for the | |
109 actual height of the screen. (Knowing the correct actual size may be | |
110 necessary for correct cursor positioning.) Using a smaller height than | |
111 the terminal actually implements may be useful to reproduce behavior | |
112 observed on a smaller screen, or if the terminal malfunctions when using | |
113 its whole screen. | |
114 | |
115 If @var{lines} is different from what it was previously, then the | |
116 entire screen is cleared and redisplayed using the new size. | |
117 | |
118 This function returns @code{nil}. | |
119 @end defun | |
120 | |
121 @defun set-screen-width columns &optional not-actual-size | |
122 This function declares that the terminal can display @var{columns} | |
123 columns. The details are as in @code{set-screen-height}. | |
124 @end defun | |
125 | |
126 @node Truncation | |
127 @section Truncation | |
128 @cindex line wrapping | |
129 @cindex continuation lines | |
130 @cindex @samp{$} in display | |
131 @cindex @samp{\} in display | |
132 | |
133 When a line of text extends beyond the right edge of a window, the | |
134 line can either be continued on the next screen line, or truncated to | |
135 one screen line. The additional screen lines used to display a long | |
136 text line are called @dfn{continuation} lines. Normally, a @samp{$} in | |
137 the rightmost column of the window indicates truncation; a @samp{\} on | |
138 the rightmost column indicates a line that ``wraps'' or is continued | |
139 onto the next line. (The display table can specify alternative | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6598
diff
changeset
|
140 indicators; see @ref{Display Tables}.) |
6598 | 141 |
142 Note that continuation is different from filling; continuation happens | |
143 on the screen only, not in the buffer contents, and it breaks a line | |
144 precisely at the right margin, not at a word boundary. @xref{Filling}. | |
145 | |
146 @defopt truncate-lines | |
147 This buffer-local variable controls how Emacs displays lines that extend | |
148 beyond the right edge of the window. The default is @code{nil}, which | |
149 specifies continuation. If the value is non-@code{nil}, then these | |
150 lines are truncated. | |
151 | |
152 If the variable @code{truncate-partial-width-windows} is non-@code{nil}, | |
153 then truncation is always used for side-by-side windows (within one | |
154 frame) regardless of the value of @code{truncate-lines}. | |
155 @end defopt | |
156 | |
157 @defvar default-truncate-lines | |
158 This variable is the default value for @code{truncate-lines}, for | |
159 buffers that do not have local values for it. | |
160 @end defvar | |
161 | |
162 @defopt truncate-partial-width-windows | |
163 This variable controls display of lines that extend beyond the right | |
164 edge of the window, in side-by-side windows (@pxref{Splitting Windows}). | |
165 If it is non-@code{nil}, these lines are truncated; otherwise, | |
166 @code{truncate-lines} says what to do with them. | |
167 @end defopt | |
168 | |
169 You can override the images that indicate continuation or truncation | |
170 with the display table; see @ref{Display Tables}. | |
171 | |
12067 | 172 If your buffer contains @strong{very} long lines, and you use |
173 continuation to display them, just thinking about them can make Emacs | |
174 redisplay slow. | |
175 | |
176 @defvar cache-long-line-scans | |
177 If this variable is non-@code{nil}, various indentation and motion | |
178 functions, and Emacs redisplay, cache the results of their scans for | |
179 newlines, and consult the cache to avoid rescanning regions of the | |
180 buffer unless they are modified. | |
181 | |
182 Turning on the newline cache slows down processing of short lines. | |
183 | |
184 This variable is automatically local in every buffer. | |
185 @end defvar | |
186 | |
6598 | 187 @node The Echo Area |
188 @section The Echo Area | |
189 @cindex error display | |
190 @cindex echo area | |
191 | |
12067 | 192 The @dfn{echo area} is used for displaying messages made with the |
6598 | 193 @code{message} primitive, and for echoing keystrokes. It is not the |
194 same as the minibuffer, despite the fact that the minibuffer appears | |
195 (when active) in the same place on the screen as the echo area. The | |
196 @cite{GNU Emacs Manual} specifies the rules for resolving conflicts | |
197 between the echo area and the minibuffer for use of that screen space | |
198 (@pxref{Minibuffer,, The Minibuffer, emacs, The GNU Emacs Manual}). | |
199 Error messages appear in the echo area; see @ref{Errors}. | |
200 | |
201 You can write output in the echo area by using the Lisp printing | |
202 functions with @code{t} as the stream (@pxref{Output Functions}), or as | |
203 follows: | |
204 | |
205 @defun message string &rest arguments | |
12067 | 206 This function displays a one-line message in the echo area. The |
6598 | 207 argument @var{string} is similar to a C language @code{printf} control |
208 string. See @code{format} in @ref{String Conversion}, for the details | |
209 on the conversion specifications. @code{message} returns the | |
210 constructed string. | |
211 | |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
212 In batch mode, @code{message} prints the message text on the standard |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
213 error stream, followed by a newline. |
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
214 |
6598 | 215 @c Emacs 19 feature |
216 If @var{string} is @code{nil}, @code{message} clears the echo area. If | |
217 the minibuffer is active, this brings the minibuffer contents back onto | |
218 the screen immediately. | |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
219 |
6598 | 220 @example |
221 @group | |
222 (message "Minibuffer depth is %d." | |
223 (minibuffer-depth)) | |
224 @print{} Minibuffer depth is 0. | |
225 @result{} "Minibuffer depth is 0." | |
226 @end group | |
227 | |
228 @group | |
229 ---------- Echo Area ---------- | |
230 Minibuffer depth is 0. | |
231 ---------- Echo Area ---------- | |
232 @end group | |
233 @end example | |
234 @end defun | |
235 | |
12067 | 236 Almost all the messages displayed in the echo area are also recorded |
237 in the @samp{*Messages*} buffer. | |
238 | |
239 @defopt message-log-max | |
240 This variable specifies how many lines to keep in the @samp{*Messages*} | |
241 buffer. The value @code{t} means there is no limit on how many lines to | |
242 keep. The value @code{nil} disables message logging entirely. Here's | |
243 how to display a message and prevent it from being logged: | |
244 | |
245 @example | |
246 (let (message-log-max) | |
247 (message @dots{})) | |
248 @end example | |
249 @end defopt | |
250 | |
6598 | 251 @defvar cursor-in-echo-area |
252 This variable controls where the cursor appears when a message is | |
253 displayed in the echo area. If it is non-@code{nil}, then the cursor | |
254 appears at the end of the message. Otherwise, the cursor appears at | |
255 point---not in the echo area at all. | |
256 | |
257 The value is normally @code{nil}; Lisp programs bind it to @code{t} | |
258 for brief periods of time. | |
259 @end defvar | |
260 | |
12067 | 261 @node Invisible Text |
262 @section Invisible Text | |
263 | |
264 @cindex invisible text | |
265 You can make characters @dfn{invisible}, so that they do not appear on | |
266 the screen, with the @code{invisible} property. This can be either a | |
267 text property or a property of an overlay. | |
268 | |
269 In the simplest case, any non-@code{nil} @code{invisible} property makes | |
270 a character invisible. This is the default case---if you don't alter | |
271 the default value of @code{buffer-invisibility-spec}, this is how the | |
272 @code{invisibility} property works. This feature is much like selective | |
273 display (@pxref{Selective Display}), but more general and cleaner. | |
274 | |
275 More generally, you can use the variable @code{buffer-invisibility-spec} | |
276 to control which values of the @code{invisible} property make text | |
277 invisible. This permits you to classify the text into different subsets | |
278 in advance, by giving them different @code{invisible} values, and | |
279 subsequently make various subsets visible or invisible by changing the | |
280 value of @code{buffer-invisibility-spec}. | |
281 | |
282 Controlling visibility with @code{buffer-invisibility-spec} is | |
283 especially useful in a program to display the list of entries in a data | |
284 base. It permits the implementation of convenient filtering commands to | |
285 view just a part of the entries in the data base. Setting this variable | |
286 is very fast, much faster than scanning all the text in the buffer | |
287 looking for things to change. | |
288 | |
289 @defvar buffer-invisibility-spec | |
290 This variable specifies which kinds of @code{invisible} properties | |
291 actually make a character invisible. | |
292 | |
293 @table @asis | |
294 @item @code{t} | |
295 A character is invisible if its @code{invisible} property is | |
296 non-@code{nil}. This is the default. | |
297 | |
298 @item a list | |
299 Each element of the list makes certain characters invisible. | |
300 Ultimately, a character is invisible if any of the elements of this list | |
301 applies to it. The list can have two kinds of elements: | |
302 | |
303 @table @code | |
304 @item @var{atom} | |
305 A character is invisible if its @code{invisible} propery value | |
306 is @var{atom} or if it is a list with @var{atom} as a member. | |
307 | |
308 @item (@var{atom} . t) | |
309 A character is invisible if its @code{invisible} propery value | |
310 is @var{atom} or if it is a list with @var{atom} as a member. | |
311 Moreover, if this character is at the end of a line and is followed | |
312 by a visible newline, it displays an ellipsis. | |
313 @end table | |
314 @end table | |
315 @end defvar | |
316 | |
6598 | 317 @node Selective Display |
318 @section Selective Display | |
319 @cindex selective display | |
320 | |
321 @dfn{Selective display} is a class of minor modes in which specially | |
322 marked lines do not appear on the screen, or in which highly indented | |
323 lines do not appear. | |
324 | |
325 The first variant, explicit selective display, is designed for use in | |
326 a Lisp program. The program controls which lines are hidden by altering | |
12067 | 327 the text. Outline mode has traditionally used this variant. It has |
328 been partially replaced by the invisible text feature (@pxref{Invisible | |
329 Text}); there is a new version of Outline mode which uses that instead. | |
330 | |
331 In the second variant, the choice of lines to hide is made | |
332 automatically based on indentation. This variant is designed as a | |
333 user-level feature. | |
6598 | 334 |
335 The way you control explicit selective display is by replacing a | |
9009 | 336 newline (control-j) with a carriage return (control-m). The text that |
6598 | 337 was formerly a line following that newline is now invisible. Strictly |
338 speaking, it is temporarily no longer a line at all, since only newlines | |
339 can separate lines; it is now part of the previous line. | |
340 | |
341 Selective display does not directly affect editing commands. For | |
342 example, @kbd{C-f} (@code{forward-char}) moves point unhesitatingly into | |
343 invisible text. However, the replacement of newline characters with | |
344 carriage return characters affects some editing commands. For example, | |
345 @code{next-line} skips invisible lines, since it searches only for | |
346 newlines. Modes that use selective display can also define commands | |
347 that take account of the newlines, or that make parts of the text | |
348 visible or invisible. | |
349 | |
350 When you write a selectively displayed buffer into a file, all the | |
351 control-m's are output as newlines. This means that when you next read | |
352 in the file, it looks OK, with nothing invisible. The selective display | |
353 effect is seen only within Emacs. | |
354 | |
355 @defvar selective-display | |
356 This buffer-local variable enables selective display. This means that | |
357 lines, or portions of lines, may be made invisible. | |
358 | |
359 @itemize @bullet | |
360 @item | |
361 If the value of @code{selective-display} is @code{t}, then any portion | |
362 of a line that follows a control-m is not displayed. | |
363 | |
364 @item | |
365 If the value of @code{selective-display} is a positive integer, then | |
366 lines that start with more than that many columns of indentation are not | |
367 displayed. | |
368 @end itemize | |
369 | |
370 When some portion of a buffer is invisible, the vertical movement | |
371 commands operate as if that portion did not exist, allowing a single | |
372 @code{next-line} command to skip any number of invisible lines. | |
373 However, character movement commands (such as @code{forward-char}) do | |
374 not skip the invisible portion, and it is possible (if tricky) to insert | |
375 or delete text in an invisible portion. | |
376 | |
377 In the examples below, we show the @emph{display appearance} of the | |
378 buffer @code{foo}, which changes with the value of | |
379 @code{selective-display}. The @emph{contents} of the buffer do not | |
380 change. | |
381 | |
382 @example | |
383 @group | |
384 (setq selective-display nil) | |
385 @result{} nil | |
386 | |
387 ---------- Buffer: foo ---------- | |
388 1 on this column | |
389 2on this column | |
390 3n this column | |
391 3n this column | |
392 2on this column | |
393 1 on this column | |
394 ---------- Buffer: foo ---------- | |
395 @end group | |
396 | |
397 @group | |
398 (setq selective-display 2) | |
399 @result{} 2 | |
400 | |
401 ---------- Buffer: foo ---------- | |
402 1 on this column | |
403 2on this column | |
404 2on this column | |
405 1 on this column | |
406 ---------- Buffer: foo ---------- | |
407 @end group | |
408 @end example | |
409 @end defvar | |
410 | |
411 @defvar selective-display-ellipses | |
412 If this buffer-local variable is non-@code{nil}, then Emacs displays | |
413 @samp{@dots{}} at the end of a line that is followed by invisible text. | |
414 This example is a continuation of the previous one. | |
415 | |
416 @example | |
417 @group | |
418 (setq selective-display-ellipses t) | |
419 @result{} t | |
420 | |
421 ---------- Buffer: foo ---------- | |
422 1 on this column | |
423 2on this column ... | |
424 2on this column | |
425 1 on this column | |
426 ---------- Buffer: foo ---------- | |
427 @end group | |
428 @end example | |
429 | |
430 You can use a display table to substitute other text for the ellipsis | |
431 (@samp{@dots{}}). @xref{Display Tables}. | |
432 @end defvar | |
433 | |
434 @node Overlay Arrow | |
435 @section The Overlay Arrow | |
436 @cindex overlay arrow | |
437 | |
438 The @dfn{overlay arrow} is useful for directing the user's attention | |
439 to a particular line in a buffer. For example, in the modes used for | |
440 interface to debuggers, the overlay arrow indicates the line of code | |
441 about to be executed. | |
442 | |
443 @defvar overlay-arrow-string | |
9009 | 444 This variable holds the string to display to call attention to a |
445 particular line, or @code{nil} if the arrow feature is not in use. | |
6598 | 446 @end defvar |
447 | |
448 @defvar overlay-arrow-position | |
9009 | 449 This variable holds a marker that indicates where to display the overlay |
450 arrow. It should point at the beginning of a line. The arrow text | |
451 appears at the beginning of that line, overlaying any text that would | |
452 otherwise appear. Since the arrow is usually short, and the line | |
453 usually begins with indentation, normally nothing significant is | |
454 overwritten. | |
6598 | 455 |
9009 | 456 The overlay string is displayed only in the buffer that this marker |
6598 | 457 points into. Thus, only one buffer can have an overlay arrow at any |
458 given time. | |
459 @c !!! overlay-arrow-position: but the overlay string may remain in the display | |
460 @c of some other buffer until an update is required. This should be fixed | |
461 @c now. Is it? | |
462 @end defvar | |
463 | |
12067 | 464 You can do the same job by creating an overlay with a |
465 @code{before-string} property. @xref{Overlay Properties}. | |
466 | |
6598 | 467 @node Temporary Displays |
468 @section Temporary Displays | |
469 | |
470 Temporary displays are used by commands to put output into a buffer | |
471 and then present it to the user for perusal rather than for editing. | |
12067 | 472 Many of the help commands use this feature. Nowadays you can do the |
473 same job by creating an overlay with a @code{before-string} property. | |
474 @xref{Overlay Properties}. | |
6598 | 475 |
476 @defspec with-output-to-temp-buffer buffer-name forms@dots{} | |
477 This function executes @var{forms} while arranging to insert any | |
478 output they print into the buffer named @var{buffer-name}. The buffer | |
479 is then shown in some window for viewing, displayed but not selected. | |
480 | |
481 The string @var{buffer-name} specifies the temporary buffer, which | |
482 need not already exist. The argument must be a string, not a buffer. | |
483 The buffer is erased initially (with no questions asked), and it is | |
484 marked as unmodified after @code{with-output-to-temp-buffer} exits. | |
485 | |
486 @code{with-output-to-temp-buffer} binds @code{standard-output} to the | |
487 temporary buffer, then it evaluates the forms in @var{forms}. Output | |
488 using the Lisp output functions within @var{forms} goes by default to | |
489 that buffer (but screen display and messages in the echo area, although | |
490 they are ``output'' in the general sense of the word, are not affected). | |
491 @xref{Output Functions}. | |
492 | |
493 The value of the last form in @var{forms} is returned. | |
494 | |
495 @example | |
496 @group | |
497 ---------- Buffer: foo ---------- | |
498 This is the contents of foo. | |
499 ---------- Buffer: foo ---------- | |
500 @end group | |
501 | |
502 @group | |
503 (with-output-to-temp-buffer "foo" | |
504 (print 20) | |
505 (print standard-output)) | |
506 @result{} #<buffer foo> | |
507 | |
508 ---------- Buffer: foo ---------- | |
509 20 | |
510 | |
511 #<buffer foo> | |
512 | |
513 ---------- Buffer: foo ---------- | |
514 @end group | |
515 @end example | |
516 @end defspec | |
517 | |
518 @defvar temp-buffer-show-function | |
9009 | 519 If this variable is non-@code{nil}, @code{with-output-to-temp-buffer} |
6598 | 520 calls it as a function to do the job of displaying a help buffer. The |
521 function gets one argument, which is the buffer it should display. | |
522 | |
523 In Emacs versions 18 and earlier, this variable was called | |
524 @code{temp-buffer-show-hook}. | |
525 @end defvar | |
526 | |
527 @defun momentary-string-display string position &optional char message | |
528 This function momentarily displays @var{string} in the current buffer at | |
529 @var{position}. It has no effect on the undo list or on the buffer's | |
530 modification status. | |
531 | |
532 The momentary display remains until the next input event. If the next | |
533 input event is @var{char}, @code{momentary-string-display} ignores it | |
534 and returns. Otherwise, that event remains buffered for subsequent use | |
535 as input. Thus, typing @var{char} will simply remove the string from | |
536 the display, while typing (say) @kbd{C-f} will remove the string from | |
537 the display and later (presumably) move point forward. The argument | |
538 @var{char} is a space by default. | |
539 | |
540 The return value of @code{momentary-string-display} is not meaningful. | |
541 | |
542 If @var{message} is non-@code{nil}, it is displayed in the echo area | |
543 while @var{string} is displayed in the buffer. If it is @code{nil}, a | |
544 default message says to type @var{char} to continue. | |
545 | |
546 In this example, point is initially located at the beginning of the | |
547 second line: | |
548 | |
549 @example | |
550 @group | |
551 ---------- Buffer: foo ---------- | |
552 This is the contents of foo. | |
553 @point{}Second line. | |
554 ---------- Buffer: foo ---------- | |
555 @end group | |
556 | |
557 @group | |
558 (momentary-string-display | |
559 "**** Important Message! ****" | |
560 (point) ?\r | |
561 "Type RET when done reading") | |
562 @result{} t | |
563 @end group | |
564 | |
565 @group | |
566 ---------- Buffer: foo ---------- | |
567 This is the contents of foo. | |
568 **** Important Message! ****Second line. | |
569 ---------- Buffer: foo ---------- | |
570 | |
571 ---------- Echo Area ---------- | |
572 Type RET when done reading | |
573 ---------- Echo Area ---------- | |
574 @end group | |
575 @end example | |
576 @end defun | |
577 | |
578 @node Overlays | |
579 @section Overlays | |
580 @cindex overlays | |
581 | |
582 You can use @dfn{overlays} to alter the appearance of a buffer's text on | |
9009 | 583 the screen. An overlay is an object that belongs to a particular |
6598 | 584 buffer, and has a specified beginning and end. It also has properties |
585 that you can examine and set; these affect the display of the text | |
586 within the overlay. | |
587 | |
588 @menu | |
589 * Overlay Properties:: How to read and set properties. | |
590 What properties do to the screen display. | |
591 * Managing Overlays:: Creating, moving, finding overlays. | |
592 @end menu | |
593 | |
594 @node Overlay Properties | |
595 @subsection Overlay Properties | |
596 | |
597 Overlay properties are like text properties in some respects, but the | |
598 differences are more important than the similarities. Text properties | |
599 are considered a part of the text; overlays are specifically considered | |
600 not to be part of the text. Thus, copying text between various buffers | |
601 and strings preserves text properties, but does not try to preserve | |
602 overlays. Changing a buffer's text properties marks the buffer as | |
603 modified, while moving an overlay or changing its properties does not. | |
604 Unlike text propery changes, overlay changes are not recorded in the | |
605 buffer's undo list. | |
606 | |
607 @table @code | |
608 @item priority | |
609 @kindex priority @r{(overlay property)} | |
610 This property's value (which should be a nonnegative number) determines | |
611 the priority of the overlay. The priority matters when two or more | |
612 overlays cover the same character and both specify a face for display; | |
613 the one whose @code{priority} value is larger takes priority over the | |
614 other, and its face attributes override the face attributes of the lower | |
615 priority overlay. | |
616 | |
617 Currently, all overlays take priority over text properties. Please | |
618 avoid using negative priority values, as we have not yet decided just | |
619 what they should mean. | |
620 | |
621 @item window | |
622 @kindex window @r{(overlay property)} | |
623 If the @code{window} property is non-@code{nil}, then the overlay | |
624 applies only on that window. | |
625 | |
12067 | 626 @item category |
627 @kindex category @r{(overlay property)} | |
628 If an overlay has a @code{category} property, we call it the | |
629 @dfn{category} of the character. It should be a symbol. The properties | |
630 of the symbol serve as defaults for the properties of the overlay. | |
631 | |
6598 | 632 @item face |
633 @kindex face @r{(overlay property)} | |
12067 | 634 This property controls the font and color of text. Its value is a face |
635 name or a list of face names. @xref{Faces}, for more information. This | |
636 feature may be temporary; in the future, we may replace it with other | |
637 ways of specifying how to display text. | |
6598 | 638 |
639 @item mouse-face | |
640 @kindex mouse-face @r{(overlay property)} | |
641 This property is used instead of @code{face} when the mouse is within | |
642 the range of the overlay. This feature may be temporary, like | |
643 @code{face}. | |
644 | |
645 @item modification-hooks | |
646 @kindex modification-hooks @r{(overlay property)} | |
647 This property's value is a list of functions to be called if any | |
648 character within the overlay is changed or if text is inserted strictly | |
12067 | 649 within the overlay. |
650 | |
651 The hook functions are called both before and after each change. | |
652 If the functions save the information they receive, and compare notes | |
653 between calls, they can determine exactly what change has been made | |
654 in the buffer text. | |
655 | |
656 When called before a change, each function receives four arguments: the | |
657 overlay, @code{nil}, and the beginning and end of the text range to be | |
7086
075343a6b32b
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6598
diff
changeset
|
658 modified. |
6598 | 659 |
12067 | 660 When called after a change, each function receives five arguments: the |
661 overlay, @code{t}, the beginning and end of the text range just | |
662 modified, and the length of the pre-change text replaced by that range. | |
663 (For an insertion, the pre-change length is zero; for a deletion, that | |
664 length is the number of characters deleted, and the post-change | |
665 beginning and end are at the same place.) | |
666 | |
6598 | 667 @item insert-in-front-hooks |
668 @kindex insert-in-front-hooks @r{(overlay property)} | |
12067 | 669 This property's value is a list of functions to be called before and |
670 after inserting text right at the beginning of the overlay. The calling | |
671 conventions are the same as for the @code{modification-hooks} functions. | |
6598 | 672 |
673 @item insert-behind-hooks | |
674 @kindex insert-behind-hooks @r{(overlay property)} | |
12067 | 675 This property's value is a list of functions to be called before and |
676 after inserting text right at the end of the overlay. The calling | |
677 conventions are the same as for the @code{modification-hooks} functions. | |
6598 | 678 |
679 @item invisible | |
680 @kindex invisible @r{(overlay property)} | |
12067 | 681 The @code{invisible} property can make the text in the overlay |
682 invisible, which means that it does not appear on the screen. | |
683 @xref{Invisible Text}, for details. | |
684 | |
685 @item intangible | |
686 @kindex intangible @r{(overlay property)} | |
687 The @code{intangible} property on an overlay works just like the | |
688 @code{intangible} text propert. @xref{Special Properties}, for details. | |
6598 | 689 |
690 @item before-string | |
691 @kindex before-string @r{(overlay property)} | |
692 This property's value is a string to add to the display at the beginning | |
693 of the overlay. The string does not appear in the buffer in any | |
12067 | 694 sense---only on the screen. The string should contain only characters |
695 that display as a single column---control characters, including tabs or | |
696 newlines, will give strange results. | |
6598 | 697 |
698 @item after-string | |
699 @kindex after-string @r{(overlay property)} | |
700 This property's value is a string to add to the display at the end of | |
701 the overlay. The string does not appear in the buffer in any | |
12067 | 702 sense---only on the screen. The string should contain only characters |
703 that display as a single column---control characters, including tabs or | |
704 newlines, will give strange results. | |
705 | |
706 @item evaporate | |
707 @kindex evaporate @r{(overlay property)} | |
708 If this property is non-@code{nil}, the overlay is deleted automatically | |
709 if it ever becomes empty (i.e., if it spans no characters). | |
6598 | 710 @end table |
711 | |
712 These are the functions for reading and writing the properties of an | |
713 overlay. | |
714 | |
715 @defun overlay-get overlay prop | |
716 This function returns the value of property @var{prop} recorded in | |
12067 | 717 @var{overlay}, if any. If @var{overlay} does not record any value for |
718 that property, but it does have a @code{category} property which is a | |
719 symbol, that symbol's @var{prop} property is used. Otherwise, the value | |
720 is @code{nil}. | |
6598 | 721 @end defun |
722 | |
723 @defun overlay-put overlay prop value | |
724 This function sets the value of property @var{prop} recorded in | |
725 @var{overlay} to @var{value}. It returns @var{value}. | |
726 @end defun | |
727 | |
728 See also the function @code{get-char-property} which checks both | |
729 overlay properties and text properties for a given character. | |
730 @xref{Examining Properties}. | |
731 | |
732 @node Managing Overlays | |
733 @subsection Managing Overlays | |
734 | |
735 This section describes the functions to create, delete and move | |
736 overlays, and to examine their contents. | |
737 | |
738 @defun make-overlay start end &optional buffer | |
9009 | 739 This function creates and returns an overlay that belongs to |
6598 | 740 @var{buffer} and ranges from @var{start} to @var{end}. Both @var{start} |
741 and @var{end} must specify buffer positions; they may be integers or | |
742 markers. If @var{buffer} is omitted, the overlay is created in the | |
743 current buffer. | |
744 @end defun | |
745 | |
746 @defun overlay-start overlay | |
747 This function returns the position at which @var{overlay} starts. | |
748 @end defun | |
749 | |
750 @defun overlay-end overlay | |
751 This function returns the position at which @var{overlay} ends. | |
752 @end defun | |
753 | |
754 @defun overlay-buffer overlay | |
755 This function returns the buffer that @var{overlay} belongs to. | |
756 @end defun | |
757 | |
758 @defun delete-overlay overlay | |
759 This function deletes @var{overlay}. The overlay continues to exist as | |
760 a Lisp object, but ceases to be part of the buffer it belonged to, and | |
761 ceases to have any effect on display. | |
762 @end defun | |
763 | |
764 @defun move-overlay overlay start end &optional buffer | |
765 This function moves @var{overlay} to @var{buffer}, and places its bounds | |
766 at @var{start} and @var{end}. Both arguments @var{start} and @var{end} | |
767 must specify buffer positions; they may be integers or markers. If | |
768 @var{buffer} is omitted, the overlay stays in the same buffer. | |
769 | |
770 The return value is @var{overlay}. | |
771 | |
772 This is the only valid way to change the endpoints of an overlay. Do | |
773 not try modifying the markers in the overlay by hand, as that fails to | |
774 update other vital data structures and can cause some overlays to be | |
775 ``lost''. | |
776 @end defun | |
777 | |
778 @defun overlays-at pos | |
779 This function returns a list of all the overlays that contain position | |
780 @var{pos} in the current buffer. The list is in no particular order. | |
781 An overlay contains position @var{pos} if it begins at or before | |
782 @var{pos}, and ends after @var{pos}. | |
783 @end defun | |
784 | |
785 @defun next-overlay-change pos | |
786 This function returns the buffer position of the next beginning or end | |
787 of an overlay, after @var{pos}. | |
788 @end defun | |
789 | |
12067 | 790 @defun previous-overlay-change pos |
791 This function returns the buffer position of the previous beginning or | |
792 end of an overlay, before @var{pos}. | |
793 @end defun | |
794 | |
6598 | 795 @node Faces |
796 @section Faces | |
797 @cindex face | |
798 | |
799 A @dfn{face} is a named collection of graphical attributes: font, | |
800 foreground color, background color and optional underlining. Faces | |
801 control the display of text on the screen. | |
802 | |
803 @cindex face id | |
804 Each face has its own @dfn{face id number} which distinguishes faces at | |
805 low levels within Emacs. However, for most purposes, you can refer to | |
806 faces in Lisp programs by their names. | |
807 | |
12067 | 808 @defun facep object |
809 This function returns @code{t} if @var{object} is a face name symbol (or | |
810 if it is a vector of the kind used internally to record face data). It | |
811 returns @code{nil} otherwise. | |
812 @end defun | |
813 | |
6598 | 814 Each face name is meaningful for all frames, and by default it has the |
815 same meaning in all frames. But you can arrange to give a particular | |
816 face name a special meaning in one frame if you wish. | |
817 | |
818 @menu | |
819 * Standard Faces:: The faces Emacs normally comes with. | |
820 * Merging Faces:: How Emacs decides which face to use for a character. | |
821 * Face Functions:: How to define and examine faces. | |
822 @end menu | |
823 | |
824 @node Standard Faces | |
825 @subsection Standard Faces | |
826 | |
827 This table lists all the standard faces and their uses. | |
828 | |
829 @table @code | |
830 @item default | |
831 @kindex default @r{(face name)} | |
832 This face is used for ordinary text. | |
833 | |
834 @item modeline | |
835 @kindex modeline @r{(face name)} | |
836 This face is used for mode lines and menu bars. | |
837 | |
838 @item region | |
839 @kindex region @r{(face name)} | |
840 This face is used for highlighting the region in Transient Mark mode. | |
841 | |
842 @item secondary-selection | |
843 @kindex secondary-selection @r{(face name)} | |
844 This face is used to show any secondary selection you have made. | |
845 | |
846 @item highlight | |
847 @kindex highlight @r{(face name)} | |
848 This face is meant to be used for highlighting for various purposes. | |
849 | |
850 @item underline | |
851 @kindex underline @r{(face name)} | |
852 This face underlines text. | |
853 | |
854 @item bold | |
855 @kindex bold @r{(face name)} | |
856 This face uses a bold font, if possible. It uses the bold variant of | |
857 the frame's font, if it has one. It's up to you to choose a default | |
858 font that has a bold variant, if you want to use one. | |
859 | |
860 @item italic | |
861 @kindex italic @r{(face name)} | |
862 This face uses the italic variant of the frame's font, if it has one. | |
863 | |
864 @item bold-italic | |
865 @kindex bold-italic @r{(face name)} | |
866 This face uses the bold italic variant of the frame's font, if it has | |
867 one. | |
868 @end table | |
869 | |
870 @node Merging Faces | |
871 @subsection Merging Faces for Display | |
872 | |
873 Here are all the ways to specify which face to use for display of text: | |
874 | |
875 @itemize @bullet | |
876 @item | |
877 With defaults. Each frame has a @dfn{default face}, whose id number is | |
878 zero, which is used for all text that doesn't somehow specify another | |
879 face. | |
880 | |
881 @item | |
882 With text properties. A character may have a @code{face} property; if so, | |
9009 | 883 it is displayed with that face. @xref{Special Properties}. |
6598 | 884 |
885 If the character has a @code{mouse-face} property, that is used instead | |
886 of the @code{face} property when the mouse is ``near enough'' to the | |
887 character. | |
888 | |
889 @item | |
890 With overlays. An overlay may have @code{face} and @code{mouse-face} | |
891 properties too; they apply to all the text covered by the overlay. | |
892 | |
893 @item | |
894 With special glyphs. Each glyph can specify a particular face id | |
895 number. @xref{Glyphs}. | |
896 @end itemize | |
897 | |
898 If these various sources together specify more than one face for a | |
899 particular character, Emacs merges the attributes of the various faces | |
900 specified. The attributes of the faces of special glyphs come first; | |
901 then come attributes of faces from overlays, followed by those from text | |
902 properties, and last the default face. | |
903 | |
904 When multiple overlays cover one character, an overlay with higher | |
905 priority overrides those with lower priority. @xref{Overlays}. | |
906 | |
907 If an attribute such as the font or a color is not specified in any of | |
908 the above ways, the frame's own font or color is used. | |
909 | |
910 @node Face Functions | |
911 @subsection Functions for Working with Faces | |
912 | |
913 The attributes a face can specify include the font, the foreground | |
914 color, the background color, and underlining. The face can also leave | |
915 these unspecified by giving the value @code{nil} for them. | |
916 | |
917 Here are the primitives for creating and changing faces. | |
918 | |
919 @defun make-face name | |
920 This function defines a new face named @var{name}, initially with all | |
921 attributes @code{nil}. It does nothing if there is already a face named | |
922 @var{name}. | |
923 @end defun | |
924 | |
925 @defun face-list | |
926 This function returns a list of all defined face names. | |
927 @end defun | |
928 | |
929 @defun copy-face old-face new-name &optional frame new-frame | |
930 This function defines the face @var{new-name} as a copy of the existing | |
931 face named @var{old-face}. It creates the face @var{new-name} if that | |
932 doesn't already exist. | |
933 | |
934 If the optional argument @var{frame} is given, this function applies | |
935 only to that frame. Otherwise it applies to each frame individually, | |
936 copying attributes from @var{old-face} in each frame to @var{new-face} | |
937 in the same frame. | |
938 | |
939 If the optional argument @var{new-frame} is given, then @code{copy-face} | |
940 copies the attributes of @var{old-face} in @var{frame} to @var{new-name} | |
941 in @var{new-frame}. | |
942 @end defun | |
943 | |
944 You can modify the attributes of an existing face with the following | |
945 functions. If you specify @var{frame}, they affect just that frame; | |
946 otherwise, they affect all frames as well as the defaults that apply to | |
947 new frames. | |
948 | |
949 @defun set-face-foreground face color &optional frame | |
950 @defunx set-face-background face color &optional frame | |
9009 | 951 These functions set the foreground (or background, respectively) color |
952 of face @var{face} to @var{color}. The argument @var{color} should be a | |
6598 | 953 string, the name of a color. |
954 @end defun | |
955 | |
956 @defun set-face-font face font &optional frame | |
957 This function sets the font of face @var{face}. The argument @var{font} | |
958 should be a string. | |
959 @end defun | |
960 | |
961 @defun set-face-underline-p face underline-p &optional frame | |
962 This function sets the underline attribute of face @var{face}. | |
963 Non-@code{nil} means do underline; @code{nil} means don't. | |
964 @end defun | |
965 | |
966 @defun invert-face face &optional frame | |
967 Swap the foreground and background colors of face @var{face}. If the | |
968 face doesn't specify both foreground and background, then its foreground | |
9009 | 969 and background are set to the default background and foreground, |
970 respectively. | |
6598 | 971 @end defun |
972 | |
973 These functions examine the attributes of a face. If you don't | |
974 specify @var{frame}, they refer to the default data for new frames. | |
975 | |
976 @defun face-foreground face &optional frame | |
977 @defunx face-background face &optional frame | |
9009 | 978 These functions return the foreground color (or background color, |
979 respectively) of face @var{face}, as a string. | |
6598 | 980 @end defun |
981 | |
982 @defun face-font face &optional frame | |
983 This function returns the name of the font of face @var{face}. | |
984 @end defun | |
985 | |
986 @defun face-underline-p face &optional frame | |
987 This function returns the underline attribute of face @var{face}. | |
988 @end defun | |
989 | |
990 @defun face-id-number face | |
991 This function returns the face id number of face @var{face}. | |
992 @end defun | |
993 | |
994 @defun face-equal face1 face2 &optional frame | |
995 This returns @code{t} if the faces @var{face1} and @var{face2} have the | |
996 same attributes for display. | |
997 @end defun | |
998 | |
999 @defun face-differs-from-default-p face &optional frame | |
1000 This returns @code{t} if the face @var{face} displays differently from | |
1001 the default face. A face is considered to be ``the same'' as the normal | |
1002 face if each attribute is either the same as that of the default face or | |
1003 @code{nil} (meaning to inherit from the default). | |
1004 @end defun | |
1005 | |
1006 @defvar region-face | |
1007 This variable's value specifies the face id to use to display characters | |
1008 in the region when it is active (in Transient Mark mode only). The face | |
1009 thus specified takes precedence over all faces that come from text | |
1010 properties and overlays, for characters in the region. @xref{The Mark}, | |
1011 for more information about Transient Mark mode. | |
1012 | |
1013 Normally, the value is the id number of the face named @code{region}. | |
1014 @end defvar | |
1015 | |
1016 @node Blinking | |
1017 @section Blinking Parentheses | |
1018 @cindex parenthesis matching | |
1019 @cindex blinking | |
1020 @cindex balancing parentheses | |
1021 @cindex close parenthesis | |
1022 | |
1023 This section describes the mechanism by which Emacs shows a matching | |
1024 open parenthesis when the user inserts a close parenthesis. | |
1025 | |
1026 @vindex blink-paren-hook | |
1027 @defvar blink-paren-function | |
1028 The value of this variable should be a function (of no arguments) to | |
1029 be called whenever a character with close parenthesis syntax is inserted. | |
1030 The value of @code{blink-paren-function} may be @code{nil}, in which | |
1031 case nothing is done. | |
1032 | |
1033 @quotation | |
7735
7db892210924
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7086
diff
changeset
|
1034 @strong{Please note:} This variable was named @code{blink-paren-hook} in |
6598 | 1035 older Emacs versions, but since it is not called with the standard |
1036 convention for hooks, it was renamed to @code{blink-paren-function} in | |
1037 version 19. | |
1038 @end quotation | |
1039 @end defvar | |
1040 | |
1041 @defvar blink-matching-paren | |
1042 If this variable is @code{nil}, then @code{blink-matching-open} does | |
1043 nothing. | |
1044 @end defvar | |
1045 | |
1046 @defvar blink-matching-paren-distance | |
1047 This variable specifies the maximum distance to scan for a matching | |
1048 parenthesis before giving up. | |
1049 @end defvar | |
1050 | |
1051 @defun blink-matching-open | |
1052 This function is the default value of @code{blink-paren-function}. It | |
1053 assumes that point follows a character with close parenthesis syntax and | |
1054 moves the cursor momentarily to the matching opening character. If that | |
1055 character is not already on the screen, it displays the character's | |
1056 context in the echo area. To avoid long delays, this function does not | |
1057 search farther than @code{blink-matching-paren-distance} characters. | |
1058 | |
1059 Here is an example of calling this function explicitly. | |
1060 | |
1061 @smallexample | |
1062 @group | |
1063 (defun interactive-blink-matching-open () | |
1064 @c Do not break this line! -- rms. | |
1065 @c The first line of a doc string | |
1066 @c must stand alone. | |
1067 "Indicate momentarily the start of sexp before point." | |
1068 (interactive) | |
1069 @end group | |
1070 @group | |
1071 (let ((blink-matching-paren-distance | |
1072 (buffer-size)) | |
1073 (blink-matching-paren t)) | |
1074 (blink-matching-open))) | |
1075 @end group | |
1076 @end smallexample | |
1077 @end defun | |
1078 | |
1079 @node Inverse Video | |
1080 @section Inverse Video | |
1081 @cindex Inverse Video | |
1082 | |
1083 @defopt inverse-video | |
1084 @cindex highlighting | |
1085 This variable controls whether Emacs uses inverse video for all text | |
1086 on the screen. Non-@code{nil} means yes, @code{nil} means no. The | |
1087 default is @code{nil}. | |
1088 @end defopt | |
1089 | |
1090 @defopt mode-line-inverse-video | |
1091 This variable controls the use of inverse video for mode lines. If it | |
1092 is non-@code{nil}, then mode lines are displayed in inverse video (under | |
1093 X, this uses the face named @code{modeline}, which you can set as you | |
1094 wish). Otherwise, mode lines are displayed normally, just like text. | |
1095 The default is @code{t}. | |
1096 @end defopt | |
1097 | |
1098 @node Usual Display | |
1099 @section Usual Display Conventions | |
1100 | |
1101 The usual display conventions define how to display each character | |
1102 code. You can override these conventions by setting up a display table | |
1103 (@pxref{Display Tables}). Here are the usual display conventions: | |
1104 | |
1105 @itemize @bullet | |
1106 @item | |
1107 Character codes 32 through 126 map to glyph codes 32 through 126. | |
1108 Normally this means they display as themselves. | |
1109 | |
1110 @item | |
1111 Character code 9 is a horizontal tab. It displays as whitespace | |
1112 up to a position determined by @code{tab-width}. | |
1113 | |
1114 @item | |
1115 Character code 10 is a newline. | |
1116 | |
1117 @item | |
1118 All other codes in the range 0 through 31, and code 127, display in one | |
9009 | 1119 of two ways according to the value of @code{ctl-arrow}. If it is |
6598 | 1120 non-@code{nil}, these codes map to sequences of two glyphs, where the |
1121 first glyph is the @sc{ASCII} code for @samp{^}. (A display table can | |
1122 specify a glyph to use instead of @samp{^}.) Otherwise, these codes map | |
1123 just like the codes in the range 128 to 255. | |
1124 | |
1125 @item | |
1126 Character codes 128 through 255 map to sequences of four glyphs, where | |
1127 the first glyph is the @sc{ASCII} code for @samp{\}, and the others are | |
1128 digit characters representing the code in octal. (A display table can | |
1129 specify a glyph to use instead of @samp{\}.) | |
1130 @end itemize | |
1131 | |
1132 The usual display conventions apply even when there is a display | |
1133 table, for any character whose entry in the active display table is | |
1134 @code{nil}. Thus, when you set up a display table, you need only | |
1135 specify the the characters for which you want unusual behavior. | |
1136 | |
1137 These variables affect the way certain characters are displayed on the | |
1138 screen. Since they change the number of columns the characters occupy, | |
1139 they also affect the indentation functions. | |
1140 | |
1141 @defopt ctl-arrow | |
1142 @cindex control characters in display | |
1143 This buffer-local variable controls how control characters are | |
1144 displayed. If it is non-@code{nil}, they are displayed as a caret | |
1145 followed by the character: @samp{^A}. If it is @code{nil}, they are | |
1146 displayed as a backslash followed by three octal digits: @samp{\001}. | |
1147 @end defopt | |
1148 | |
1149 @c Following may have overfull hbox. | |
1150 @defvar default-ctl-arrow | |
1151 The value of this variable is the default value for @code{ctl-arrow} in | |
1152 buffers that do not override it. @xref{Default Value}. | |
1153 @end defvar | |
1154 | |
1155 @defopt tab-width | |
1156 The value of this variable is the spacing between tab stops used for | |
1157 displaying tab characters in Emacs buffers. The default is 8. Note | |
1158 that this feature is completely independent from the user-settable tab | |
1159 stops used by the command @code{tab-to-tab-stop}. @xref{Indent Tabs}. | |
1160 @end defopt | |
1161 | |
1162 @node Display Tables | |
1163 @section Display Tables | |
1164 | |
1165 @cindex display table | |
1166 You can use the @dfn{display table} feature to control how all 256 | |
1167 possible character codes display on the screen. This is useful for | |
1168 displaying European languages that have letters not in the @sc{ASCII} | |
1169 character set. | |
1170 | |
1171 The display table maps each character code into a sequence of | |
1172 @dfn{glyphs}, each glyph being an image that takes up one character | |
1173 position on the screen. You can also define how to display each glyph | |
1174 on your terminal, using the @dfn{glyph table}. | |
1175 | |
1176 @menu | |
1177 * Display Table Format:: What a display table consists of. | |
1178 * Active Display Table:: How Emacs selects a display table to use. | |
1179 * Glyphs:: How to define a glyph, and what glyphs mean. | |
1180 * ISO Latin 1:: How to use display tables | |
1181 to support the ISO Latin 1 character set. | |
1182 @end menu | |
1183 | |
1184 @node Display Table Format | |
1185 @subsection Display Table Format | |
1186 | |
8925 | 1187 A display table is actually an array of 262 elements. |
6598 | 1188 |
1189 @defun make-display-table | |
1190 This creates and returns a display table. The table initially has | |
1191 @code{nil} in all elements. | |
1192 @end defun | |
1193 | |
1194 The first 256 elements correspond to character codes; the @var{n}th | |
1195 element says how to display the character code @var{n}. The value | |
1196 should be @code{nil} or a vector of glyph values (@pxref{Glyphs}). If | |
1197 an element is @code{nil}, it says to display that character according to | |
12067 | 1198 the usual display conventions (@pxref{Usual Display}). |
1199 | |
1200 If you use the display table to change the display of newline | |
1201 characters, the whole buffer will be displayed as one long ``line.'' | |
6598 | 1202 |
8925 | 1203 The remaining six elements of a display table serve special purposes, |
6598 | 1204 and @code{nil} means use the default stated below. |
1205 | |
1206 @table @asis | |
1207 @item 256 | |
1208 The glyph for the end of a truncated screen line (the default for this | |
1209 is @samp{$}). @xref{Glyphs}. | |
1210 @item 257 | |
1211 The glyph for the end of a continued line (the default is @samp{\}). | |
1212 @item 258 | |
1213 The glyph for indicating a character displayed as an octal character | |
1214 code (the default is @samp{\}). | |
1215 @item 259 | |
1216 The glyph for indicating a control character (the default is @samp{^}). | |
1217 @item 260 | |
1218 A vector of glyphs for indicating the presence of invisible lines (the | |
1219 default is @samp{...}). @xref{Selective Display}. | |
8925 | 1220 @item 261 |
1221 The glyph used to draw the border between side-by-side windows (the | |
1222 default is @samp{|}). @xref{Splitting Windows}. | |
6598 | 1223 @end table |
1224 | |
1225 For example, here is how to construct a display table that mimics the | |
1226 effect of setting @code{ctl-arrow} to a non-@code{nil} value: | |
1227 | |
1228 @example | |
1229 (setq disptab (make-display-table)) | |
1230 (let ((i 0)) | |
1231 (while (< i 32) | |
1232 (or (= i ?\t) (= i ?\n) | |
1233 (aset disptab i (vector ?^ (+ i 64)))) | |
1234 (setq i (1+ i))) | |
1235 (aset disptab 127 (vector ?^ ??))) | |
1236 @end example | |
1237 | |
1238 @node Active Display Table | |
1239 @subsection Active Display Table | |
1240 @cindex active display table | |
1241 | |
1242 Each window can specify a display table, and so can each buffer. When | |
1243 a buffer @var{b} is displayed in window @var{w}, display uses the | |
1244 display table for window @var{w} if it has one; otherwise, the display | |
1245 table for buffer @var{b} if it has one; otherwise, the standard display | |
1246 table if any. The display table chosen is called the @dfn{active} | |
1247 display table. | |
1248 | |
1249 @defun window-display-table window | |
1250 This function returns @var{window}'s display table, or @code{nil} | |
1251 if @var{window} does not have an assigned display table. | |
1252 @end defun | |
1253 | |
1254 @defun set-window-display-table window table | |
1255 This function sets the display table of @var{window} to @var{table}. | |
1256 The argument @var{table} should be either a display table or | |
1257 @code{nil}. | |
1258 @end defun | |
1259 | |
1260 @defvar buffer-display-table | |
1261 This variable is automatically local in all buffers; its value in a | |
1262 particular buffer is the display table for that buffer, or @code{nil} if | |
1263 the buffer does not have an assigned display table. | |
1264 @end defvar | |
1265 | |
1266 @defvar standard-display-table | |
1267 This variable's value is the default display table, used whenever a | |
1268 window has no display table and neither does the buffer displayed in | |
1269 that window. This variable is @code{nil} by default. | |
1270 @end defvar | |
1271 | |
1272 If there is no display table to use for a particular window---that is, | |
1273 if the window has none, its buffer has none, and | |
1274 @code{standard-display-table} has none---then Emacs uses the usual | |
1275 display conventions for all character codes in that window. @xref{Usual | |
1276 Display}. | |
1277 | |
1278 @node Glyphs | |
1279 @subsection Glyphs | |
1280 | |
1281 @cindex glyph | |
1282 A @dfn{glyph} is a generalization of a character; it stands for an | |
1283 image that takes up a single character position on the screen. Glyphs | |
1284 are represented in Lisp as integers, just as characters are. | |
1285 | |
1286 @cindex glyph table | |
1287 The meaning of each integer, as a glyph, is defined by the glyph | |
1288 table, which is the value of the variable @code{glyph-table}. | |
1289 | |
1290 @defvar glyph-table | |
1291 The value of this variable is the current glyph table. It should be a | |
1292 vector; the @var{g}th element defines glyph code @var{g}. If the value | |
1293 is @code{nil} instead of a vector, then all glyphs are simple (see | |
1294 below). | |
1295 @end defvar | |
1296 | |
1297 Here are the possible types of elements in the glyph table: | |
1298 | |
1299 @table @var | |
1300 @item string | |
1301 Send the characters in @var{string} to the terminal to output | |
1302 this glyph. This alternative is available on character terminals, | |
1303 but not under X. | |
1304 | |
1305 @item integer | |
1306 Define this glyph code as an alias for code @var{integer}. You can use | |
1307 an alias to specify a face code for the glyph; see below. | |
1308 | |
1309 @item @code{nil} | |
1310 This glyph is simple. On an ordinary terminal, the glyph code mod 256 | |
1311 is the character to output. With X, the glyph code mod 256 is the | |
1312 character to output, and the glyph code divided by 256 specifies the | |
1313 @dfn{face id number} to use while outputting it. @xref{Faces}. | |
1314 @end table | |
1315 | |
1316 If a glyph code is greater than or equal to the length of the glyph | |
1317 table, that code is automatically simple. | |
1318 | |
1319 @node ISO Latin 1 | |
1320 @subsection ISO Latin 1 | |
1321 | |
1322 If you have a terminal that can handle the entire ISO Latin 1 character | |
1323 set, you can arrange to use that character set as follows: | |
1324 | |
1325 @example | |
1326 (require 'disp-table) | |
1327 ;; @r{Set char codes 160--255 to display as themselves.} | |
1328 ;; @r{(Codes 128--159 are the additional control characters.)} | |
1329 (standard-display-8bit 160 255) | |
1330 @end example | |
1331 | |
1332 If you are editing buffers written in the ISO Latin 1 character set and | |
9009 | 1333 your terminal doesn't handle anything but @sc{ASCII}, you can load the |
1334 file @file{iso-ascii} to set up a display table that displays the other | |
1335 ISO characters as explanatory sequences of @sc{ASCII} characters. For | |
1336 example, the character ``o with umlaut'' displays as @samp{@{"o@}}. | |
6598 | 1337 |
1338 Some European countries have terminals that don't support ISO Latin 1 | |
1339 but do support the special characters for that country's language. You | |
1340 can define a display table to work one language using such terminals. | |
1341 For an example, see @file{lisp/iso-swed.el}, which handles certain | |
1342 Swedish terminals. | |
1343 | |
1344 You can load the appropriate display table for your terminal | |
1345 automatically by writing a terminal-specific Lisp file for the terminal | |
1346 type. | |
1347 | |
1348 @node Beeping | |
1349 @section Beeping | |
1350 @cindex beeping | |
1351 @cindex bell | |
1352 | |
1353 You can make Emacs ring a bell (or blink the screen) to attract the | |
1354 user's attention. Be conservative about how often you do this; frequent | |
1355 bells can become irritating. Also be careful not to use beeping alone | |
1356 when signaling an error is appropriate. (@xref{Errors}.) | |
1357 | |
1358 @defun ding &optional dont-terminate | |
1359 @cindex keyboard macro termination | |
1360 This function beeps, or flashes the screen (see @code{visible-bell} below). | |
1361 It also terminates any keyboard macro currently executing unless | |
1362 @var{dont-terminate} is non-@code{nil}. | |
1363 @end defun | |
1364 | |
1365 @defun beep &optional dont-terminate | |
1366 This is a synonym for @code{ding}. | |
1367 @end defun | |
1368 | |
1369 @defvar visible-bell | |
1370 This variable determines whether Emacs should flash the screen to | |
1371 represent a bell. Non-@code{nil} means yes, @code{nil} means no. This | |
10211 | 1372 is effective under X windows, and on a character-only terminal provided |
1373 the terminal's Termcap entry defines the visible bell capability | |
1374 (@samp{vb}). | |
6598 | 1375 @end defvar |
1376 | |
1377 @node Window Systems | |
1378 @section Window Systems | |
1379 | |
1380 Emacs works with several window systems, most notably the X Window | |
1381 System. Both Emacs and X use the term ``window'', but use it | |
1382 differently. An Emacs frame is a single window as far as X is | |
1383 concerned; the individual Emacs windows are not known to X at all. | |
1384 | |
1385 @defvar window-system | |
1386 @cindex X Window System | |
1387 This variable tells Lisp programs what window system Emacs is running | |
1388 under. Its value should be a symbol such as @code{x} (if Emacs is | |
1389 running under X) or @code{nil} (if Emacs is running on an ordinary | |
1390 terminal). | |
1391 @end defvar | |
1392 | |
1393 @defvar window-system-version | |
1394 This variable distinguishes between different versions of the X Window | |
1395 System. Its value is 10 or 11 when using X; @code{nil} otherwise. | |
1396 @end defvar | |
1397 | |
1398 @defvar window-setup-hook | |
1399 This variable is a normal hook which Emacs runs after loading your | |
1400 @file{.emacs} file and the default initialization file (if any), after | |
1401 loading terminal-specific Lisp code, and after running the hook | |
1402 @code{term-setup-hook}. | |
1403 | |
1404 This hook is used for internal purposes: setting up communication with | |
1405 the window system, and creating the initial window. Users should not | |
1406 interfere with it. | |
1407 @end defvar |