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