Commit | Line | Data |
---|---|---|
42b85554 RS |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Emacs Lisp Reference Manual. | |
f9f59935 | 3 | @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc. |
42b85554 RS |
4 | @c See the file elisp.texi for copying conditions. |
5 | @setfilename ../info/display | |
969fe9b5 | 6 | @node Display, Calendar, Processes, Top |
42b85554 RS |
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. | |
42b85554 RS |
14 | * Truncation:: Folding or wrapping long text lines. |
15 | * The Echo Area:: Where messages are displayed. | |
22697dac KH |
16 | * Invisible Text:: Hiding part of the buffer text. |
17 | * Selective Display:: Hiding part of the buffer text (the old way). | |
42b85554 RS |
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. | |
f9f59935 | 21 | * Width:: How wide is a character or string. |
42b85554 RS |
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 | |
1911e6e5 | 35 | given frame (@pxref{Frames}). |
42b85554 RS |
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 | ||
bfe721d1 KH |
48 | Processing user input takes absolute priority over redisplay. If you |
49 | call these functions when input is available, they do nothing | |
50 | immediately, but a full redisplay does happen eventually---after all the | |
51 | input has been processed. | |
52 | ||
42b85554 RS |
53 | Normally, suspending and resuming Emacs also refreshes the screen. |
54 | Some terminal emulators record separate contents for display-oriented | |
55 | programs such as Emacs and for ordinary sequential display. If you are | |
56 | using such a terminal, you might want to inhibit the redisplay on | |
78608595 | 57 | resumption. |
42b85554 RS |
58 | |
59 | @defvar no-redraw-on-reenter | |
60 | @cindex suspend (cf. @code{no-redraw-on-reenter}) | |
61 | @cindex resume (cf. @code{no-redraw-on-reenter}) | |
62 | This variable controls whether Emacs redraws the entire screen after it | |
f9f59935 | 63 | has been suspended and resumed. Non-@code{nil} means there is no need |
969fe9b5 | 64 | to redraw, @code{nil} means redrawing is needed. The default is @code{nil}. |
42b85554 RS |
65 | @end defvar |
66 | ||
42b85554 RS |
67 | @node Truncation |
68 | @section Truncation | |
69 | @cindex line wrapping | |
70 | @cindex continuation lines | |
71 | @cindex @samp{$} in display | |
72 | @cindex @samp{\} in display | |
73 | ||
74 | When a line of text extends beyond the right edge of a window, the | |
75 | line can either be continued on the next screen line, or truncated to | |
76 | one screen line. The additional screen lines used to display a long | |
77 | text line are called @dfn{continuation} lines. Normally, a @samp{$} in | |
78 | the rightmost column of the window indicates truncation; a @samp{\} on | |
969fe9b5 RS |
79 | the rightmost column indicates a line that ``wraps'' onto the next line, |
80 | which is also called @dfn{continuing} the line. (The display table can | |
81 | specify alternative indicators; see @ref{Display Tables}.) | |
42b85554 RS |
82 | |
83 | Note that continuation is different from filling; continuation happens | |
84 | on the screen only, not in the buffer contents, and it breaks a line | |
85 | precisely at the right margin, not at a word boundary. @xref{Filling}. | |
86 | ||
87 | @defopt truncate-lines | |
88 | This buffer-local variable controls how Emacs displays lines that extend | |
89 | beyond the right edge of the window. The default is @code{nil}, which | |
90 | specifies continuation. If the value is non-@code{nil}, then these | |
91 | lines are truncated. | |
92 | ||
93 | If the variable @code{truncate-partial-width-windows} is non-@code{nil}, | |
94 | then truncation is always used for side-by-side windows (within one | |
95 | frame) regardless of the value of @code{truncate-lines}. | |
96 | @end defopt | |
97 | ||
bfe721d1 | 98 | @defopt default-truncate-lines |
42b85554 | 99 | This variable is the default value for @code{truncate-lines}, for |
969fe9b5 | 100 | buffers that do not have buffer-local values for it. |
bfe721d1 | 101 | @end defopt |
42b85554 RS |
102 | |
103 | @defopt truncate-partial-width-windows | |
104 | This variable controls display of lines that extend beyond the right | |
105 | edge of the window, in side-by-side windows (@pxref{Splitting Windows}). | |
106 | If it is non-@code{nil}, these lines are truncated; otherwise, | |
107 | @code{truncate-lines} says what to do with them. | |
108 | @end defopt | |
109 | ||
a9f0a989 RS |
110 | When horizontal scrolling (@pxref{Horizontal Scrolling}) is in use in |
111 | a window, that forces truncation. | |
112 | ||
f9f59935 RS |
113 | You can override the glyphs that indicate continuation or truncation |
114 | using the display table; see @ref{Display Tables}. | |
42b85554 | 115 | |
1911e6e5 | 116 | If your buffer contains @emph{very} long lines, and you use |
22697dac | 117 | continuation to display them, just thinking about them can make Emacs |
bfe721d1 KH |
118 | redisplay slow. The column computation and indentation functions also |
119 | become slow. Then you might find it advisable to set | |
120 | @code{cache-long-line-scans} to @code{t}. | |
22697dac KH |
121 | |
122 | @defvar cache-long-line-scans | |
123 | If this variable is non-@code{nil}, various indentation and motion | |
bfe721d1 KH |
124 | functions, and Emacs redisplay, cache the results of scanning the |
125 | buffer, and consult the cache to avoid rescanning regions of the buffer | |
126 | unless they are modified. | |
22697dac | 127 | |
bfe721d1 | 128 | Turning on the cache slows down processing of short lines somewhat. |
22697dac | 129 | |
969fe9b5 | 130 | This variable is automatically buffer-local in every buffer. |
22697dac KH |
131 | @end defvar |
132 | ||
42b85554 RS |
133 | @node The Echo Area |
134 | @section The Echo Area | |
135 | @cindex error display | |
136 | @cindex echo area | |
137 | ||
22697dac | 138 | The @dfn{echo area} is used for displaying messages made with the |
42b85554 RS |
139 | @code{message} primitive, and for echoing keystrokes. It is not the |
140 | same as the minibuffer, despite the fact that the minibuffer appears | |
141 | (when active) in the same place on the screen as the echo area. The | |
142 | @cite{GNU Emacs Manual} specifies the rules for resolving conflicts | |
143 | between the echo area and the minibuffer for use of that screen space | |
144 | (@pxref{Minibuffer,, The Minibuffer, emacs, The GNU Emacs Manual}). | |
145 | Error messages appear in the echo area; see @ref{Errors}. | |
146 | ||
147 | You can write output in the echo area by using the Lisp printing | |
148 | functions with @code{t} as the stream (@pxref{Output Functions}), or as | |
149 | follows: | |
150 | ||
151 | @defun message string &rest arguments | |
22697dac | 152 | This function displays a one-line message in the echo area. The |
42b85554 RS |
153 | argument @var{string} is similar to a C language @code{printf} control |
154 | string. See @code{format} in @ref{String Conversion}, for the details | |
155 | on the conversion specifications. @code{message} returns the | |
156 | constructed string. | |
157 | ||
b22f3a19 RS |
158 | In batch mode, @code{message} prints the message text on the standard |
159 | error stream, followed by a newline. | |
160 | ||
42b85554 RS |
161 | @c Emacs 19 feature |
162 | If @var{string} is @code{nil}, @code{message} clears the echo area. If | |
163 | the minibuffer is active, this brings the minibuffer contents back onto | |
164 | the screen immediately. | |
b22f3a19 | 165 | |
42b85554 RS |
166 | @example |
167 | @group | |
168 | (message "Minibuffer depth is %d." | |
169 | (minibuffer-depth)) | |
170 | @print{} Minibuffer depth is 0. | |
171 | @result{} "Minibuffer depth is 0." | |
172 | @end group | |
173 | ||
174 | @group | |
175 | ---------- Echo Area ---------- | |
176 | Minibuffer depth is 0. | |
177 | ---------- Echo Area ---------- | |
178 | @end group | |
179 | @end example | |
180 | @end defun | |
181 | ||
39d6d9bd RS |
182 | @defun message-or-box string &rest arguments |
183 | This function displays a message like @code{message}, but may display it | |
184 | in a dialog box instead of the echo area. If this function is called in | |
185 | a command that was invoked using the mouse---more precisely, if | |
186 | @code{last-nonmenu-event} (@pxref{Command Loop Info}) is either | |
187 | @code{nil} or a list---then it uses a dialog box or pop-up menu to | |
188 | display the message. Otherwise, it uses the echo area. (This is the | |
189 | same criterion that @code{y-or-n-p} uses to make a similar decision; see | |
190 | @ref{Yes-or-No Queries}.) | |
191 | ||
192 | You can force use of the mouse or of the echo area by binding | |
193 | @code{last-nonmenu-event} to a suitable value around the call. | |
194 | @end defun | |
195 | ||
196 | @defun message-box string &rest arguments | |
197 | This function displays a message like @code{message}, but uses a dialog | |
198 | box (or a pop-up menu) whenever that is possible. If it is impossible | |
199 | to use a dialog box or pop-up menu, because the terminal does not | |
200 | support them, then @code{message-box} uses the echo area, like | |
201 | @code{message}. | |
202 | @end defun | |
203 | ||
f9f59935 | 204 | @defun current-message |
a9f0a989 | 205 | @tindex current-message |
f9f59935 RS |
206 | This function returns the message currently being displayed in the |
207 | echo area, or @code{nil} if there is none. | |
208 | @end defun | |
209 | ||
969fe9b5 RS |
210 | @defvar cursor-in-echo-area |
211 | This variable controls where the cursor appears when a message is | |
212 | displayed in the echo area. If it is non-@code{nil}, then the cursor | |
213 | appears at the end of the message. Otherwise, the cursor appears at | |
214 | point---not in the echo area at all. | |
215 | ||
216 | The value is normally @code{nil}; Lisp programs bind it to @code{t} | |
217 | for brief periods of time. | |
218 | @end defvar | |
219 | ||
f9f59935 | 220 | @defvar echo-area-clear-hook |
a9f0a989 | 221 | @tindex echo-area-clear-hook |
f9f59935 RS |
222 | This normal hook is run whenever the echo area is cleared---either by |
223 | @code{(message nil)} or for any other reason. | |
224 | @end defvar | |
225 | ||
22697dac KH |
226 | Almost all the messages displayed in the echo area are also recorded |
227 | in the @samp{*Messages*} buffer. | |
228 | ||
229 | @defopt message-log-max | |
230 | This variable specifies how many lines to keep in the @samp{*Messages*} | |
231 | buffer. The value @code{t} means there is no limit on how many lines to | |
232 | keep. The value @code{nil} disables message logging entirely. Here's | |
233 | how to display a message and prevent it from being logged: | |
234 | ||
235 | @example | |
236 | (let (message-log-max) | |
237 | (message @dots{})) | |
238 | @end example | |
239 | @end defopt | |
240 | ||
bfe721d1 KH |
241 | @defvar echo-keystrokes |
242 | This variable determines how much time should elapse before command | |
243 | characters echo. Its value must be an integer, which specifies the | |
244 | number of seconds to wait before echoing. If the user types a prefix | |
245 | key (such as @kbd{C-x}) and then delays this many seconds before | |
a9f0a989 RS |
246 | continuing, the prefix key is echoed in the echo area. (Once echoing |
247 | begins in a key sequence, all subsequent characters in the same key | |
248 | sequence are echoed immediately.) | |
bfe721d1 KH |
249 | |
250 | If the value is zero, then command input is not echoed. | |
251 | @end defvar | |
252 | ||
22697dac KH |
253 | @node Invisible Text |
254 | @section Invisible Text | |
255 | ||
256 | @cindex invisible text | |
257 | You can make characters @dfn{invisible}, so that they do not appear on | |
258 | the screen, with the @code{invisible} property. This can be either a | |
a9f0a989 RS |
259 | text property (@pxref{Text Properties}) or a property of an overlay |
260 | (@pxref{Overlays}). | |
22697dac KH |
261 | |
262 | In the simplest case, any non-@code{nil} @code{invisible} property makes | |
263 | a character invisible. This is the default case---if you don't alter | |
264 | the default value of @code{buffer-invisibility-spec}, this is how the | |
969fe9b5 | 265 | @code{invisible} property works. |
22697dac KH |
266 | |
267 | More generally, you can use the variable @code{buffer-invisibility-spec} | |
268 | to control which values of the @code{invisible} property make text | |
269 | invisible. This permits you to classify the text into different subsets | |
270 | in advance, by giving them different @code{invisible} values, and | |
271 | subsequently make various subsets visible or invisible by changing the | |
272 | value of @code{buffer-invisibility-spec}. | |
273 | ||
274 | Controlling visibility with @code{buffer-invisibility-spec} is | |
275 | especially useful in a program to display the list of entries in a data | |
276 | base. It permits the implementation of convenient filtering commands to | |
277 | view just a part of the entries in the data base. Setting this variable | |
278 | is very fast, much faster than scanning all the text in the buffer | |
bfe721d1 | 279 | looking for properties to change. |
22697dac KH |
280 | |
281 | @defvar buffer-invisibility-spec | |
282 | This variable specifies which kinds of @code{invisible} properties | |
283 | actually make a character invisible. | |
284 | ||
285 | @table @asis | |
286 | @item @code{t} | |
287 | A character is invisible if its @code{invisible} property is | |
288 | non-@code{nil}. This is the default. | |
289 | ||
290 | @item a list | |
969fe9b5 RS |
291 | Each element of the list specifies a criterion for invisibility; if a |
292 | character's @code{invisible} property fits any one of these criteria, | |
293 | the character is invisible. The list can have two kinds of elements: | |
22697dac KH |
294 | |
295 | @table @code | |
296 | @item @var{atom} | |
969fe9b5 | 297 | A character is invisible if its @code{invisible} property value |
22697dac KH |
298 | is @var{atom} or if it is a list with @var{atom} as a member. |
299 | ||
300 | @item (@var{atom} . t) | |
969fe9b5 | 301 | A character is invisible if its @code{invisible} property value |
22697dac KH |
302 | is @var{atom} or if it is a list with @var{atom} as a member. |
303 | Moreover, if this character is at the end of a line and is followed | |
304 | by a visible newline, it displays an ellipsis. | |
305 | @end table | |
306 | @end table | |
307 | @end defvar | |
308 | ||
f9f59935 RS |
309 | Two functions are specifically provided for adding elements to |
310 | @code{buffer-invisibility-spec} and removing elements from it. | |
311 | ||
f9f59935 | 312 | @defun add-to-invisibility-spec element |
a9f0a989 | 313 | @tindex add-to-invisibility-spec |
f9f59935 RS |
314 | Add the element @var{element} to @code{buffer-invisibility-spec} |
315 | (if it is not already present in that list). | |
316 | @end defun | |
317 | ||
f9f59935 | 318 | @defun remove-from-invisibility-spec element |
a9f0a989 | 319 | @tindex remove-from-invisibility-spec |
f9f59935 RS |
320 | Remove the element @var{element} from @code{buffer-invisibility-spec}. |
321 | @end defun | |
322 | ||
323 | One convention about the use of @code{buffer-invisibility-spec} is | |
324 | that a major mode should use the mode's own name as an element of | |
325 | @code{buffer-invisibility-spec} and as the value of the @code{invisible} | |
326 | property: | |
327 | ||
328 | @example | |
969fe9b5 | 329 | ;; @r{If you want to display an ellipsis:} |
f9f59935 | 330 | (add-to-invisibility-spec '(my-symbol . t)) |
969fe9b5 | 331 | ;; @r{If you don't want ellipsis:} |
f9f59935 RS |
332 | (add-to-invisibility-spec 'my-symbol) |
333 | ||
334 | (overlay-put (make-overlay beginning end) | |
335 | 'invisible 'my-symbol) | |
336 | ||
969fe9b5 | 337 | ;; @r{When done with the overlays:} |
f9f59935 | 338 | (remove-from-invisibility-spec '(my-symbol . t)) |
969fe9b5 | 339 | ;; @r{Or respectively:} |
f9f59935 RS |
340 | (remove-from-invisibility-spec 'my-symbol) |
341 | @end example | |
342 | ||
5e8ae792 | 343 | @vindex line-move-ignore-invisible |
bfe721d1 | 344 | Ordinarily, commands that operate on text or move point do not care |
5e8ae792 RS |
345 | whether the text is invisible. The user-level line motion commands |
346 | explicitly ignore invisible newlines if | |
347 | @code{line-move-ignore-invisible} is non-@code{nil}, but only because | |
348 | they are explicitly programmed to do so. | |
bfe721d1 | 349 | |
f9f59935 RS |
350 | Incremental search can make invisible overlays visible temporarily |
351 | and/or permanently when a match includes invisible text. To enable | |
352 | this, the overlay should have a non-@code{nil} | |
353 | @code{isearch-open-invisible} property. The property value should be a | |
354 | function to be called with the overlay as an argument. This function | |
355 | should make the overlay visible permanently; it is used when the match | |
356 | overlaps the overlay on exit from the search. | |
357 | ||
358 | During the search, such overlays are made temporarily visible by | |
359 | temporarily modifying their invisible and intangible properties. If you | |
ebc6903b | 360 | want this to be done differently for a certain overlay, give it an |
f9f59935 RS |
361 | @code{isearch-open-invisible-temporary} property which is a function. |
362 | The function is called with two arguments: the first is the overlay, and | |
a9f0a989 RS |
363 | the second is @code{t} to make the overlay visible, or @code{nil} to |
364 | make it invisible again. | |
f9f59935 | 365 | |
42b85554 RS |
366 | @node Selective Display |
367 | @section Selective Display | |
368 | @cindex selective display | |
369 | ||
969fe9b5 RS |
370 | @dfn{Selective display} refers to a pair of related features for |
371 | hiding certain lines on the screen. | |
42b85554 RS |
372 | |
373 | The first variant, explicit selective display, is designed for use in | |
969fe9b5 RS |
374 | a Lisp program: it controls which lines are hidden by altering the text. |
375 | The invisible text feature (@pxref{Invisible Text}) has partially | |
376 | replaced this feature. | |
22697dac KH |
377 | |
378 | In the second variant, the choice of lines to hide is made | |
bfe721d1 | 379 | automatically based on indentation. This variant is designed to be a |
22697dac | 380 | user-level feature. |
42b85554 RS |
381 | |
382 | The way you control explicit selective display is by replacing a | |
78608595 | 383 | newline (control-j) with a carriage return (control-m). The text that |
42b85554 RS |
384 | was formerly a line following that newline is now invisible. Strictly |
385 | speaking, it is temporarily no longer a line at all, since only newlines | |
386 | can separate lines; it is now part of the previous line. | |
387 | ||
388 | Selective display does not directly affect editing commands. For | |
389 | example, @kbd{C-f} (@code{forward-char}) moves point unhesitatingly into | |
390 | invisible text. However, the replacement of newline characters with | |
391 | carriage return characters affects some editing commands. For example, | |
392 | @code{next-line} skips invisible lines, since it searches only for | |
393 | newlines. Modes that use selective display can also define commands | |
394 | that take account of the newlines, or that make parts of the text | |
395 | visible or invisible. | |
396 | ||
397 | When you write a selectively displayed buffer into a file, all the | |
398 | control-m's are output as newlines. This means that when you next read | |
399 | in the file, it looks OK, with nothing invisible. The selective display | |
400 | effect is seen only within Emacs. | |
401 | ||
402 | @defvar selective-display | |
403 | This buffer-local variable enables selective display. This means that | |
404 | lines, or portions of lines, may be made invisible. | |
405 | ||
406 | @itemize @bullet | |
407 | @item | |
408 | If the value of @code{selective-display} is @code{t}, then any portion | |
969fe9b5 RS |
409 | of a line that follows a control-m is not displayed. This is explicit |
410 | selective display. | |
42b85554 RS |
411 | |
412 | @item | |
413 | If the value of @code{selective-display} is a positive integer, then | |
414 | lines that start with more than that many columns of indentation are not | |
415 | displayed. | |
416 | @end itemize | |
417 | ||
418 | When some portion of a buffer is invisible, the vertical movement | |
419 | commands operate as if that portion did not exist, allowing a single | |
420 | @code{next-line} command to skip any number of invisible lines. | |
421 | However, character movement commands (such as @code{forward-char}) do | |
422 | not skip the invisible portion, and it is possible (if tricky) to insert | |
423 | or delete text in an invisible portion. | |
424 | ||
425 | In the examples below, we show the @emph{display appearance} of the | |
426 | buffer @code{foo}, which changes with the value of | |
427 | @code{selective-display}. The @emph{contents} of the buffer do not | |
428 | change. | |
429 | ||
430 | @example | |
431 | @group | |
432 | (setq selective-display nil) | |
433 | @result{} nil | |
434 | ||
435 | ---------- Buffer: foo ---------- | |
436 | 1 on this column | |
437 | 2on this column | |
438 | 3n this column | |
439 | 3n this column | |
440 | 2on this column | |
441 | 1 on this column | |
442 | ---------- Buffer: foo ---------- | |
443 | @end group | |
444 | ||
445 | @group | |
446 | (setq selective-display 2) | |
447 | @result{} 2 | |
448 | ||
449 | ---------- Buffer: foo ---------- | |
450 | 1 on this column | |
451 | 2on this column | |
452 | 2on this column | |
453 | 1 on this column | |
454 | ---------- Buffer: foo ---------- | |
455 | @end group | |
456 | @end example | |
457 | @end defvar | |
458 | ||
459 | @defvar selective-display-ellipses | |
460 | If this buffer-local variable is non-@code{nil}, then Emacs displays | |
461 | @samp{@dots{}} at the end of a line that is followed by invisible text. | |
462 | This example is a continuation of the previous one. | |
463 | ||
464 | @example | |
465 | @group | |
466 | (setq selective-display-ellipses t) | |
467 | @result{} t | |
468 | ||
469 | ---------- Buffer: foo ---------- | |
470 | 1 on this column | |
471 | 2on this column ... | |
472 | 2on this column | |
473 | 1 on this column | |
474 | ---------- Buffer: foo ---------- | |
475 | @end group | |
476 | @end example | |
477 | ||
478 | You can use a display table to substitute other text for the ellipsis | |
479 | (@samp{@dots{}}). @xref{Display Tables}. | |
480 | @end defvar | |
481 | ||
482 | @node Overlay Arrow | |
483 | @section The Overlay Arrow | |
484 | @cindex overlay arrow | |
485 | ||
486 | The @dfn{overlay arrow} is useful for directing the user's attention | |
487 | to a particular line in a buffer. For example, in the modes used for | |
488 | interface to debuggers, the overlay arrow indicates the line of code | |
489 | about to be executed. | |
490 | ||
491 | @defvar overlay-arrow-string | |
78608595 RS |
492 | This variable holds the string to display to call attention to a |
493 | particular line, or @code{nil} if the arrow feature is not in use. | |
42b85554 RS |
494 | @end defvar |
495 | ||
496 | @defvar overlay-arrow-position | |
78608595 RS |
497 | This variable holds a marker that indicates where to display the overlay |
498 | arrow. It should point at the beginning of a line. The arrow text | |
499 | appears at the beginning of that line, overlaying any text that would | |
500 | otherwise appear. Since the arrow is usually short, and the line | |
501 | usually begins with indentation, normally nothing significant is | |
502 | overwritten. | |
503 | ||
504 | The overlay string is displayed only in the buffer that this marker | |
42b85554 RS |
505 | points into. Thus, only one buffer can have an overlay arrow at any |
506 | given time. | |
507 | @c !!! overlay-arrow-position: but the overlay string may remain in the display | |
508 | @c of some other buffer until an update is required. This should be fixed | |
509 | @c now. Is it? | |
510 | @end defvar | |
511 | ||
969fe9b5 | 512 | You can do a similar job by creating an overlay with a |
22697dac KH |
513 | @code{before-string} property. @xref{Overlay Properties}. |
514 | ||
42b85554 RS |
515 | @node Temporary Displays |
516 | @section Temporary Displays | |
517 | ||
969fe9b5 RS |
518 | Temporary displays are used by Lisp programs to put output into a |
519 | buffer and then present it to the user for perusal rather than for | |
520 | editing. Many help commands use this feature. | |
42b85554 RS |
521 | |
522 | @defspec with-output-to-temp-buffer buffer-name forms@dots{} | |
523 | This function executes @var{forms} while arranging to insert any | |
524 | output they print into the buffer named @var{buffer-name}. The buffer | |
525 | is then shown in some window for viewing, displayed but not selected. | |
526 | ||
527 | The string @var{buffer-name} specifies the temporary buffer, which | |
528 | need not already exist. The argument must be a string, not a buffer. | |
529 | The buffer is erased initially (with no questions asked), and it is | |
530 | marked as unmodified after @code{with-output-to-temp-buffer} exits. | |
531 | ||
532 | @code{with-output-to-temp-buffer} binds @code{standard-output} to the | |
533 | temporary buffer, then it evaluates the forms in @var{forms}. Output | |
534 | using the Lisp output functions within @var{forms} goes by default to | |
535 | that buffer (but screen display and messages in the echo area, although | |
536 | they are ``output'' in the general sense of the word, are not affected). | |
537 | @xref{Output Functions}. | |
538 | ||
539 | The value of the last form in @var{forms} is returned. | |
540 | ||
541 | @example | |
542 | @group | |
543 | ---------- Buffer: foo ---------- | |
544 | This is the contents of foo. | |
545 | ---------- Buffer: foo ---------- | |
546 | @end group | |
547 | ||
548 | @group | |
549 | (with-output-to-temp-buffer "foo" | |
550 | (print 20) | |
551 | (print standard-output)) | |
552 | @result{} #<buffer foo> | |
553 | ||
554 | ---------- Buffer: foo ---------- | |
555 | 20 | |
556 | ||
557 | #<buffer foo> | |
558 | ||
559 | ---------- Buffer: foo ---------- | |
560 | @end group | |
561 | @end example | |
562 | @end defspec | |
563 | ||
564 | @defvar temp-buffer-show-function | |
78608595 | 565 | If this variable is non-@code{nil}, @code{with-output-to-temp-buffer} |
42b85554 RS |
566 | calls it as a function to do the job of displaying a help buffer. The |
567 | function gets one argument, which is the buffer it should display. | |
a9f0a989 RS |
568 | |
569 | It is a good idea for this function to run @code{temp-buffer-show-hook} | |
570 | just as @code{with-output-to-temp-buffer} normally would, inside of | |
571 | @code{save-window-excursion} and with the chosen window and buffer | |
572 | selected. | |
573 | @end defvar | |
574 | ||
575 | @defvar temp-buffer-show-hook | |
576 | This normal hook is run by @code{with-output-to-temp-buffer} after | |
577 | displaying the help buffer. When the hook runs, the help buffer is | |
578 | current, and the window it was displayed in is selected. | |
42b85554 RS |
579 | @end defvar |
580 | ||
581 | @defun momentary-string-display string position &optional char message | |
582 | This function momentarily displays @var{string} in the current buffer at | |
583 | @var{position}. It has no effect on the undo list or on the buffer's | |
584 | modification status. | |
585 | ||
586 | The momentary display remains until the next input event. If the next | |
587 | input event is @var{char}, @code{momentary-string-display} ignores it | |
588 | and returns. Otherwise, that event remains buffered for subsequent use | |
589 | as input. Thus, typing @var{char} will simply remove the string from | |
590 | the display, while typing (say) @kbd{C-f} will remove the string from | |
591 | the display and later (presumably) move point forward. The argument | |
592 | @var{char} is a space by default. | |
593 | ||
594 | The return value of @code{momentary-string-display} is not meaningful. | |
595 | ||
bfe721d1 | 596 | If the string @var{string} does not contain control characters, you can |
969fe9b5 RS |
597 | do the same job in a more general way by creating (and then subsequently |
598 | deleting) an overlay with a @code{before-string} property. | |
599 | @xref{Overlay Properties}. | |
bfe721d1 | 600 | |
42b85554 RS |
601 | If @var{message} is non-@code{nil}, it is displayed in the echo area |
602 | while @var{string} is displayed in the buffer. If it is @code{nil}, a | |
603 | default message says to type @var{char} to continue. | |
604 | ||
605 | In this example, point is initially located at the beginning of the | |
606 | second line: | |
607 | ||
608 | @example | |
609 | @group | |
610 | ---------- Buffer: foo ---------- | |
611 | This is the contents of foo. | |
612 | @point{}Second line. | |
613 | ---------- Buffer: foo ---------- | |
614 | @end group | |
615 | ||
616 | @group | |
617 | (momentary-string-display | |
618 | "**** Important Message! ****" | |
619 | (point) ?\r | |
620 | "Type RET when done reading") | |
621 | @result{} t | |
622 | @end group | |
623 | ||
624 | @group | |
625 | ---------- Buffer: foo ---------- | |
626 | This is the contents of foo. | |
627 | **** Important Message! ****Second line. | |
628 | ---------- Buffer: foo ---------- | |
629 | ||
630 | ---------- Echo Area ---------- | |
631 | Type RET when done reading | |
632 | ---------- Echo Area ---------- | |
633 | @end group | |
634 | @end example | |
635 | @end defun | |
636 | ||
637 | @node Overlays | |
638 | @section Overlays | |
639 | @cindex overlays | |
640 | ||
641 | You can use @dfn{overlays} to alter the appearance of a buffer's text on | |
bfe721d1 KH |
642 | the screen, for the sake of presentation features. An overlay is an |
643 | object that belongs to a particular buffer, and has a specified | |
644 | beginning and end. It also has properties that you can examine and set; | |
645 | these affect the display of the text within the overlay. | |
42b85554 RS |
646 | |
647 | @menu | |
648 | * Overlay Properties:: How to read and set properties. | |
649 | What properties do to the screen display. | |
650 | * Managing Overlays:: Creating, moving, finding overlays. | |
651 | @end menu | |
652 | ||
653 | @node Overlay Properties | |
654 | @subsection Overlay Properties | |
655 | ||
a9f0a989 RS |
656 | Overlay properties are like text properties in that the properties that |
657 | alter how a character is displayed can come from either source. But in | |
658 | most respects they are different. Text properties are considered a part | |
659 | of the text; overlays are specifically considered not to be part of the | |
660 | text. Thus, copying text between various buffers and strings preserves | |
661 | text properties, but does not try to preserve overlays. Changing a | |
662 | buffer's text properties marks the buffer as modified, while moving an | |
663 | overlay or changing its properties does not. Unlike text property | |
664 | changes, overlay changes are not recorded in the buffer's undo list. | |
665 | @xref{Text Properties}, for comparison. | |
42b85554 RS |
666 | |
667 | @table @code | |
668 | @item priority | |
669 | @kindex priority @r{(overlay property)} | |
670 | This property's value (which should be a nonnegative number) determines | |
671 | the priority of the overlay. The priority matters when two or more | |
672 | overlays cover the same character and both specify a face for display; | |
673 | the one whose @code{priority} value is larger takes priority over the | |
674 | other, and its face attributes override the face attributes of the lower | |
675 | priority overlay. | |
676 | ||
677 | Currently, all overlays take priority over text properties. Please | |
678 | avoid using negative priority values, as we have not yet decided just | |
679 | what they should mean. | |
680 | ||
681 | @item window | |
682 | @kindex window @r{(overlay property)} | |
683 | If the @code{window} property is non-@code{nil}, then the overlay | |
684 | applies only on that window. | |
685 | ||
22697dac KH |
686 | @item category |
687 | @kindex category @r{(overlay property)} | |
688 | If an overlay has a @code{category} property, we call it the | |
bfe721d1 | 689 | @dfn{category} of the overlay. It should be a symbol. The properties |
22697dac KH |
690 | of the symbol serve as defaults for the properties of the overlay. |
691 | ||
42b85554 RS |
692 | @item face |
693 | @kindex face @r{(overlay property)} | |
f9f59935 RS |
694 | This property controls the way text is displayed---for example, which |
695 | font and which colors. Its value is a face name or a list of face | |
696 | names. @xref{Faces}, for more information. | |
697 | ||
698 | If the property value is a list, elements may also have the form | |
699 | @code{(foreground-color . @var{color-name})} or @code{(background-color | |
700 | . @var{color-name})}. These elements specify just the foreground color | |
701 | or just the background color; therefore, there is no need to create a | |
702 | face for each color that you want to use. | |
42b85554 RS |
703 | |
704 | @item mouse-face | |
705 | @kindex mouse-face @r{(overlay property)} | |
706 | This property is used instead of @code{face} when the mouse is within | |
f9f59935 | 707 | the range of the overlay. |
42b85554 RS |
708 | |
709 | @item modification-hooks | |
710 | @kindex modification-hooks @r{(overlay property)} | |
711 | This property's value is a list of functions to be called if any | |
712 | character within the overlay is changed or if text is inserted strictly | |
22697dac KH |
713 | within the overlay. |
714 | ||
715 | The hook functions are called both before and after each change. | |
716 | If the functions save the information they receive, and compare notes | |
717 | between calls, they can determine exactly what change has been made | |
718 | in the buffer text. | |
719 | ||
720 | When called before a change, each function receives four arguments: the | |
721 | overlay, @code{nil}, and the beginning and end of the text range to be | |
a890e1b0 | 722 | modified. |
42b85554 | 723 | |
22697dac KH |
724 | When called after a change, each function receives five arguments: the |
725 | overlay, @code{t}, the beginning and end of the text range just | |
726 | modified, and the length of the pre-change text replaced by that range. | |
727 | (For an insertion, the pre-change length is zero; for a deletion, that | |
728 | length is the number of characters deleted, and the post-change | |
bfe721d1 | 729 | beginning and end are equal.) |
22697dac | 730 | |
42b85554 RS |
731 | @item insert-in-front-hooks |
732 | @kindex insert-in-front-hooks @r{(overlay property)} | |
22697dac KH |
733 | This property's value is a list of functions to be called before and |
734 | after inserting text right at the beginning of the overlay. The calling | |
735 | conventions are the same as for the @code{modification-hooks} functions. | |
42b85554 RS |
736 | |
737 | @item insert-behind-hooks | |
738 | @kindex insert-behind-hooks @r{(overlay property)} | |
22697dac KH |
739 | This property's value is a list of functions to be called before and |
740 | after inserting text right at the end of the overlay. The calling | |
741 | conventions are the same as for the @code{modification-hooks} functions. | |
42b85554 RS |
742 | |
743 | @item invisible | |
744 | @kindex invisible @r{(overlay property)} | |
22697dac KH |
745 | The @code{invisible} property can make the text in the overlay |
746 | invisible, which means that it does not appear on the screen. | |
747 | @xref{Invisible Text}, for details. | |
748 | ||
749 | @item intangible | |
750 | @kindex intangible @r{(overlay property)} | |
751 | The @code{intangible} property on an overlay works just like the | |
bfe721d1 | 752 | @code{intangible} text property. @xref{Special Properties}, for details. |
f9f59935 RS |
753 | |
754 | @item isearch-open-invisible | |
a9f0a989 RS |
755 | This property tells incremental search how to make an invisible overlay |
756 | visible, permanently, if the final match overlaps it. @xref{Invisible | |
f9f59935 | 757 | Text}. |
42b85554 | 758 | |
a9f0a989 RS |
759 | @item isearch-open-invisible-temporary |
760 | This property tells incremental search how to make an invisible overlay | |
761 | visible, temporarily, during the search. @xref{Invisible Text}. | |
762 | ||
42b85554 RS |
763 | @item before-string |
764 | @kindex before-string @r{(overlay property)} | |
765 | This property's value is a string to add to the display at the beginning | |
766 | of the overlay. The string does not appear in the buffer in any | |
22697dac KH |
767 | sense---only on the screen. The string should contain only characters |
768 | that display as a single column---control characters, including tabs or | |
769 | newlines, will give strange results. | |
42b85554 RS |
770 | |
771 | @item after-string | |
772 | @kindex after-string @r{(overlay property)} | |
773 | This property's value is a string to add to the display at the end of | |
774 | the overlay. The string does not appear in the buffer in any | |
22697dac KH |
775 | sense---only on the screen. The string should contain only characters |
776 | that display as a single column---control characters, including tabs or | |
777 | newlines, will give strange results. | |
778 | ||
779 | @item evaporate | |
780 | @kindex evaporate @r{(overlay property)} | |
781 | If this property is non-@code{nil}, the overlay is deleted automatically | |
782 | if it ever becomes empty (i.e., if it spans no characters). | |
d2609065 RS |
783 | |
784 | @item local-map | |
969fe9b5 RS |
785 | @cindex keymap of character (and overlays) |
786 | @kindex local-map @r{(overlay property)} | |
d2609065 RS |
787 | If this property is non-@code{nil}, it specifies a keymap for a portion |
788 | of the text. The property's value replaces the buffer's local map, when | |
789 | the character after point is within the overlay. @xref{Active Keymaps}. | |
42b85554 RS |
790 | @end table |
791 | ||
792 | These are the functions for reading and writing the properties of an | |
793 | overlay. | |
794 | ||
795 | @defun overlay-get overlay prop | |
796 | This function returns the value of property @var{prop} recorded in | |
22697dac KH |
797 | @var{overlay}, if any. If @var{overlay} does not record any value for |
798 | that property, but it does have a @code{category} property which is a | |
799 | symbol, that symbol's @var{prop} property is used. Otherwise, the value | |
800 | is @code{nil}. | |
42b85554 RS |
801 | @end defun |
802 | ||
803 | @defun overlay-put overlay prop value | |
804 | This function sets the value of property @var{prop} recorded in | |
805 | @var{overlay} to @var{value}. It returns @var{value}. | |
806 | @end defun | |
807 | ||
808 | See also the function @code{get-char-property} which checks both | |
809 | overlay properties and text properties for a given character. | |
810 | @xref{Examining Properties}. | |
811 | ||
812 | @node Managing Overlays | |
813 | @subsection Managing Overlays | |
814 | ||
815 | This section describes the functions to create, delete and move | |
816 | overlays, and to examine their contents. | |
817 | ||
f9f59935 | 818 | @defun make-overlay start end &optional buffer front-advance rear-advance |
78608595 | 819 | This function creates and returns an overlay that belongs to |
42b85554 RS |
820 | @var{buffer} and ranges from @var{start} to @var{end}. Both @var{start} |
821 | and @var{end} must specify buffer positions; they may be integers or | |
822 | markers. If @var{buffer} is omitted, the overlay is created in the | |
823 | current buffer. | |
f9f59935 RS |
824 | |
825 | The arguments @var{front-advance} and @var{rear-advance} specify the | |
826 | insertion type for the start of the overlay and for the end of the | |
827 | overlay. @xref{Marker Insertion Types}. | |
42b85554 RS |
828 | @end defun |
829 | ||
830 | @defun overlay-start overlay | |
f9f59935 RS |
831 | This function returns the position at which @var{overlay} starts, |
832 | as an integer. | |
42b85554 RS |
833 | @end defun |
834 | ||
835 | @defun overlay-end overlay | |
f9f59935 RS |
836 | This function returns the position at which @var{overlay} ends, |
837 | as an integer. | |
42b85554 RS |
838 | @end defun |
839 | ||
840 | @defun overlay-buffer overlay | |
841 | This function returns the buffer that @var{overlay} belongs to. | |
842 | @end defun | |
843 | ||
844 | @defun delete-overlay overlay | |
845 | This function deletes @var{overlay}. The overlay continues to exist as | |
a9f0a989 RS |
846 | a Lisp object, but ceases to be attached to the buffer it belonged to, |
847 | and ceases to have any effect on display. | |
848 | ||
849 | A deleted overlay is not permanently useless. You can give it | |
850 | a new buffer position by calling @code{move-overlay}. | |
42b85554 RS |
851 | @end defun |
852 | ||
853 | @defun move-overlay overlay start end &optional buffer | |
854 | This function moves @var{overlay} to @var{buffer}, and places its bounds | |
855 | at @var{start} and @var{end}. Both arguments @var{start} and @var{end} | |
856 | must specify buffer positions; they may be integers or markers. If | |
857 | @var{buffer} is omitted, the overlay stays in the same buffer. | |
858 | ||
859 | The return value is @var{overlay}. | |
860 | ||
861 | This is the only valid way to change the endpoints of an overlay. Do | |
862 | not try modifying the markers in the overlay by hand, as that fails to | |
863 | update other vital data structures and can cause some overlays to be | |
864 | ``lost''. | |
865 | @end defun | |
866 | ||
867 | @defun overlays-at pos | |
868 | This function returns a list of all the overlays that contain position | |
869 | @var{pos} in the current buffer. The list is in no particular order. | |
870 | An overlay contains position @var{pos} if it begins at or before | |
871 | @var{pos}, and ends after @var{pos}. | |
872 | @end defun | |
873 | ||
f9f59935 | 874 | @defun overlays-in beg end |
a9f0a989 | 875 | @tindex overlays-in |
f9f59935 RS |
876 | This function returns a list of the overlays that overlap the region |
877 | @var{beg} through @var{end}. ``Overlap'' means that at least one | |
878 | character is contained within the overlay and also contained within the | |
879 | specified region; however, empty overlays are included in the result if | |
880 | they are located at @var{beg} or between @var{beg} and @var{end}. | |
881 | @end defun | |
882 | ||
42b85554 RS |
883 | @defun next-overlay-change pos |
884 | This function returns the buffer position of the next beginning or end | |
885 | of an overlay, after @var{pos}. | |
886 | @end defun | |
887 | ||
22697dac KH |
888 | @defun previous-overlay-change pos |
889 | This function returns the buffer position of the previous beginning or | |
890 | end of an overlay, before @var{pos}. | |
891 | @end defun | |
892 | ||
f9f59935 RS |
893 | @node Width |
894 | @section Width | |
895 | ||
896 | Since not all characters have the same width, these functions let you | |
969fe9b5 RS |
897 | check the width of a character. @xref{Primitive Indent}, and |
898 | @ref{Screen Lines}, for related functions. | |
f9f59935 | 899 | |
f9f59935 | 900 | @defun char-width char |
a9f0a989 | 901 | @tindex char-width |
f9f59935 RS |
902 | This function returns the width in columns of the character @var{char}, |
903 | if it were displayed in the current buffer and the selected window. | |
904 | @end defun | |
905 | ||
f9f59935 | 906 | @defun string-width string |
a9f0a989 | 907 | @tindex string-width |
f9f59935 RS |
908 | This function returns the width in columns of the string @var{string}, |
909 | if it were displayed in the current buffer and the selected window. | |
910 | @end defun | |
911 | ||
f9f59935 | 912 | @defun truncate-string-to-width string width &optional start-column padding |
a9f0a989 | 913 | @tindex truncate-string-to-width |
f9f59935 RS |
914 | This function returns the part of @var{string} that fits within |
915 | @var{width} columns, as a new string. | |
916 | ||
917 | If @var{string} does not reach @var{width}, then the result ends where | |
918 | @var{string} ends. If one multi-column character in @var{string} | |
919 | extends across the column @var{width}, that character is not included in | |
920 | the result. Thus, the result can fall short of @var{width} but cannot | |
921 | go beyond it. | |
922 | ||
923 | The optional argument @var{start-column} specifies the starting column. | |
924 | If this is non-@code{nil}, then the first @var{start-column} columns of | |
925 | the string are omitted from the value. If one multi-column character in | |
926 | @var{string} extends across the column @var{start-column}, that | |
927 | character is not included. | |
928 | ||
929 | The optional argument @var{padding}, if non-@code{nil}, is a padding | |
930 | character added at the beginning and end of the result string, to extend | |
931 | it to exactly @var{width} columns. The padding character is used at the | |
932 | end of the result if it falls short of @var{width}. It is also used at | |
933 | the beginning of the result if one multi-column character in | |
934 | @var{string} extends across the column @var{start-column}. | |
935 | ||
936 | @example | |
937 | (truncate-string-to-width "\tab\t" 12 4) | |
938 | @result{} "ab" | |
939 | (truncate-string-to-width "\tab\t" 12 4 ?\ ) | |
940 | @result{} " ab " | |
941 | @end example | |
942 | @end defun | |
943 | ||
42b85554 RS |
944 | @node Faces |
945 | @section Faces | |
946 | @cindex face | |
947 | ||
948 | A @dfn{face} is a named collection of graphical attributes: font, | |
f9f59935 | 949 | foreground color, background color, and optional underlining. Faces |
42b85554 RS |
950 | control the display of text on the screen. |
951 | ||
952 | @cindex face id | |
969fe9b5 | 953 | Each face has its own @dfn{face number}, which distinguishes faces at |
42b85554 RS |
954 | low levels within Emacs. However, for most purposes, you can refer to |
955 | faces in Lisp programs by their names. | |
956 | ||
22697dac KH |
957 | @defun facep object |
958 | This function returns @code{t} if @var{object} is a face name symbol (or | |
959 | if it is a vector of the kind used internally to record face data). It | |
960 | returns @code{nil} otherwise. | |
961 | @end defun | |
962 | ||
42b85554 RS |
963 | Each face name is meaningful for all frames, and by default it has the |
964 | same meaning in all frames. But you can arrange to give a particular | |
965 | face name a special meaning in one frame if you wish. | |
966 | ||
967 | @menu | |
968 | * Standard Faces:: The faces Emacs normally comes with. | |
969fe9b5 | 969 | * Defining Faces:: How to define a face with @code{defface}. |
42b85554 RS |
970 | * Merging Faces:: How Emacs decides which face to use for a character. |
971 | * Face Functions:: How to define and examine faces. | |
972 | @end menu | |
973 | ||
974 | @node Standard Faces | |
975 | @subsection Standard Faces | |
976 | ||
977 | This table lists all the standard faces and their uses. | |
978 | ||
979 | @table @code | |
980 | @item default | |
981 | @kindex default @r{(face name)} | |
982 | This face is used for ordinary text. | |
983 | ||
984 | @item modeline | |
985 | @kindex modeline @r{(face name)} | |
986 | This face is used for mode lines and menu bars. | |
987 | ||
988 | @item region | |
989 | @kindex region @r{(face name)} | |
990 | This face is used for highlighting the region in Transient Mark mode. | |
991 | ||
992 | @item secondary-selection | |
993 | @kindex secondary-selection @r{(face name)} | |
994 | This face is used to show any secondary selection you have made. | |
995 | ||
996 | @item highlight | |
997 | @kindex highlight @r{(face name)} | |
998 | This face is meant to be used for highlighting for various purposes. | |
999 | ||
1000 | @item underline | |
1001 | @kindex underline @r{(face name)} | |
1002 | This face underlines text. | |
1003 | ||
1004 | @item bold | |
1005 | @kindex bold @r{(face name)} | |
1006 | This face uses a bold font, if possible. It uses the bold variant of | |
1007 | the frame's font, if it has one. It's up to you to choose a default | |
1008 | font that has a bold variant, if you want to use one. | |
1009 | ||
1010 | @item italic | |
1011 | @kindex italic @r{(face name)} | |
1012 | This face uses the italic variant of the frame's font, if it has one. | |
1013 | ||
1014 | @item bold-italic | |
1015 | @kindex bold-italic @r{(face name)} | |
1016 | This face uses the bold italic variant of the frame's font, if it has | |
1017 | one. | |
1018 | @end table | |
1019 | ||
969fe9b5 | 1020 | @node Defining Faces |
a9f0a989 | 1021 | @subsection Defining Faces |
969fe9b5 RS |
1022 | |
1023 | The way to define a new face is with @code{defface}. This creates a | |
1024 | kind of customization item (@pxref{Customization}) which the user can | |
1025 | customize using the Customization buffer (@pxref{Easy Customization,,, | |
1026 | emacs, The GNU Emacs Manual}). | |
1027 | ||
969fe9b5 | 1028 | @defmac defface face spec doc [keyword value]... |
a9f0a989 | 1029 | @tindex defface |
969fe9b5 RS |
1030 | Declare @var{face} as a customizable face that defaults according to |
1031 | @var{spec}. Do not quote the symbol @var{face}. The argument @var{doc} | |
1032 | specifies the face documentation. | |
1033 | ||
1034 | When @code{defface} executes, it defines the face according to | |
a9f0a989 RS |
1035 | @var{spec}, then uses any customizations that were read from the |
1036 | @file{.emacs} file to override that specification. | |
969fe9b5 RS |
1037 | |
1038 | The purpose of @var{spec} is to specify how the face should appear on | |
1039 | different kinds of terminals. It should be an alist whose elements have | |
1040 | the form @code{(@var{display} @var{atts})}. The element's @sc{car}, | |
1041 | @var{display}, specifies a class of terminals. The @sc{cdr}, | |
1042 | @var{atts}, is a list of face attributes and their values; it specifies | |
1043 | what the face should look like on that kind of terminal. The possible | |
1044 | attributes are defined in the value of @code{custom-face-attributes}. | |
1045 | ||
1046 | The @var{display} part of an element of @var{spec} determines which | |
1047 | frames the element applies to. If more than one element of @var{spec} | |
1048 | matches a given frame, the first matching element is the only one used | |
1049 | for that frame. There are two possibilities for @var{display}: | |
1050 | ||
1051 | @table @asis | |
1052 | @item @code{t} | |
1053 | This element of @var{spec} matches all frames. Therefore, any | |
1054 | subsequent elements of @var{spec} are never used. Normally | |
1055 | @code{t} is used in the last (or only) element of @var{spec}. | |
1056 | ||
a9f0a989 | 1057 | @item a list |
1911e6e5 | 1058 | If @var{display} is a list, each element should have the form |
969fe9b5 RS |
1059 | @code{(@var{characteristic} @var{value}@dots{})}. Here |
1060 | @var{characteristic} specifies a way of classifying frames, and the | |
1061 | @var{value}s are possible classifications which @var{display} should | |
1062 | apply to. Here are the possible values of @var{characteristic}: | |
1063 | ||
1064 | @table @code | |
1065 | @item type | |
1066 | The kind of window system the frame uses---either @code{x}, @code{pc} | |
1067 | (for the MS-DOS console), @code{w32} (for MS Windows 9X/NT), or | |
1068 | @code{tty}. | |
1069 | ||
1070 | @item class | |
1071 | What kinds of colors the frame supports---either @code{color}, | |
1072 | @code{grayscale}, or @code{mono}. | |
1073 | ||
1074 | @item background | |
1911e6e5 | 1075 | The kind of background---either @code{light} or @code{dark}. |
969fe9b5 RS |
1076 | @end table |
1077 | ||
1078 | If an element of @var{display} specifies more than one @var{value} for a | |
1079 | given @var{characteristic}, any of those values is acceptable. If | |
1080 | @var{display} has more than one element, each element should specify a | |
1081 | different @var{characteristic}; then @emph{each} characteristic of the | |
1082 | frame must match one of the @var{value}s specified for it in | |
1083 | @var{display}. | |
1084 | @end table | |
1085 | @end defmac | |
1086 | ||
1087 | Here's how the standard face @code{region} could be defined | |
1088 | with @code{defface}: | |
1089 | ||
1090 | @example | |
1091 | (defface region | |
1092 | ((((class color) (background dark)) | |
1093 | (:background "blue")) | |
1094 | (t (:background "gray"))) | |
1095 | "Used for displaying the region.") | |
1096 | @end example | |
1097 | ||
1098 | Internally, @code{defface} uses the symbol property | |
1099 | @code{face-defface-spec} to record the face attributes specified in | |
1100 | @code{defface}, @code{saved-face} for the attributes saved by the user | |
1101 | with the customization buffer, and @code{face-documentation} for the | |
1102 | documentation string. | |
1103 | ||
1911e6e5 RS |
1104 | @tindex frame-background-mode |
1105 | @defopt frame-background-mode | |
1106 | This option, if non-@code{nil}, specifies the background type to use for | |
1107 | interpreting face definitions. If it is @code{dark}, then Emacs treats | |
1108 | all frames as if they had a dark background, regardless of their actual | |
1109 | background colors. If it is @code{light}, then Emacs treats all frames | |
1110 | as if they had a light background. | |
1111 | @end defopt | |
1112 | ||
42b85554 RS |
1113 | @node Merging Faces |
1114 | @subsection Merging Faces for Display | |
1115 | ||
1116 | Here are all the ways to specify which face to use for display of text: | |
1117 | ||
1118 | @itemize @bullet | |
1119 | @item | |
969fe9b5 RS |
1120 | With defaults. Each frame has a @dfn{default face}, which is used for |
1121 | all text that doesn't somehow specify another face. (We may change this | |
1122 | in a forthcoming Emacs version to serve as a default for all text.) | |
42b85554 RS |
1123 | |
1124 | @item | |
1125 | With text properties. A character may have a @code{face} property; if so, | |
78608595 | 1126 | it is displayed with that face. @xref{Special Properties}. |
42b85554 RS |
1127 | |
1128 | If the character has a @code{mouse-face} property, that is used instead | |
1129 | of the @code{face} property when the mouse is ``near enough'' to the | |
1130 | character. | |
1131 | ||
1132 | @item | |
1133 | With overlays. An overlay may have @code{face} and @code{mouse-face} | |
1134 | properties too; they apply to all the text covered by the overlay. | |
1135 | ||
bfe721d1 KH |
1136 | @item |
1137 | With a region that is active. In Transient Mark mode, the region is | |
1138 | highlighted with a particular face (see @code{region-face}, below). | |
1139 | ||
42b85554 | 1140 | @item |
969fe9b5 | 1141 | With special glyphs. Each glyph can specify a particular face |
42b85554 RS |
1142 | number. @xref{Glyphs}. |
1143 | @end itemize | |
1144 | ||
1145 | If these various sources together specify more than one face for a | |
1146 | particular character, Emacs merges the attributes of the various faces | |
1147 | specified. The attributes of the faces of special glyphs come first; | |
bfe721d1 | 1148 | then comes the face for region highlighting, if appropriate; |
42b85554 RS |
1149 | then come attributes of faces from overlays, followed by those from text |
1150 | properties, and last the default face. | |
1151 | ||
1152 | When multiple overlays cover one character, an overlay with higher | |
1153 | priority overrides those with lower priority. @xref{Overlays}. | |
1154 | ||
1155 | If an attribute such as the font or a color is not specified in any of | |
1156 | the above ways, the frame's own font or color is used. | |
1157 | ||
1158 | @node Face Functions | |
1159 | @subsection Functions for Working with Faces | |
1160 | ||
1161 | The attributes a face can specify include the font, the foreground | |
1162 | color, the background color, and underlining. The face can also leave | |
1163 | these unspecified by giving the value @code{nil} for them. | |
1164 | ||
1165 | Here are the primitives for creating and changing faces. | |
1166 | ||
1167 | @defun make-face name | |
1168 | This function defines a new face named @var{name}, initially with all | |
1169 | attributes @code{nil}. It does nothing if there is already a face named | |
1170 | @var{name}. | |
1171 | @end defun | |
1172 | ||
1173 | @defun face-list | |
1174 | This function returns a list of all defined face names. | |
1175 | @end defun | |
1176 | ||
1177 | @defun copy-face old-face new-name &optional frame new-frame | |
1178 | This function defines the face @var{new-name} as a copy of the existing | |
1179 | face named @var{old-face}. It creates the face @var{new-name} if that | |
1180 | doesn't already exist. | |
1181 | ||
1182 | If the optional argument @var{frame} is given, this function applies | |
1183 | only to that frame. Otherwise it applies to each frame individually, | |
1184 | copying attributes from @var{old-face} in each frame to @var{new-face} | |
1185 | in the same frame. | |
1186 | ||
1187 | If the optional argument @var{new-frame} is given, then @code{copy-face} | |
1188 | copies the attributes of @var{old-face} in @var{frame} to @var{new-name} | |
1189 | in @var{new-frame}. | |
1190 | @end defun | |
1191 | ||
1192 | You can modify the attributes of an existing face with the following | |
1193 | functions. If you specify @var{frame}, they affect just that frame; | |
1194 | otherwise, they affect all frames as well as the defaults that apply to | |
1195 | new frames. | |
1196 | ||
1197 | @defun set-face-foreground face color &optional frame | |
1198 | @defunx set-face-background face color &optional frame | |
78608595 RS |
1199 | These functions set the foreground (or background, respectively) color |
1200 | of face @var{face} to @var{color}. The argument @var{color} should be a | |
42b85554 | 1201 | string, the name of a color. |
bfe721d1 KH |
1202 | |
1203 | Certain shades of gray are implemented by stipple patterns on | |
1204 | black-and-white screens. | |
1205 | @end defun | |
1206 | ||
1207 | @defun set-face-stipple face pattern &optional frame | |
1208 | This function sets the background stipple pattern of face @var{face} to | |
1209 | @var{pattern}. The argument @var{pattern} should be the name of a | |
1210 | stipple pattern defined by the X server, or @code{nil} meaning don't use | |
1211 | stipple. | |
1212 | ||
1213 | Normally there is no need to pay attention to stipple patterns, because | |
1214 | they are used automatically to handle certain shades of gray. | |
42b85554 RS |
1215 | @end defun |
1216 | ||
1217 | @defun set-face-font face font &optional frame | |
1218 | This function sets the font of face @var{face}. The argument @var{font} | |
a9f0a989 RS |
1219 | should be a string, either a valid font name for your system or the name |
1220 | of an Emacs fontset (@pxref{Fontsets}). Note that if you set the font | |
1221 | explicitly, the bold and italic attributes cease to have any effect, | |
1222 | because the precise font that you specified is always used. | |
21cffb83 RS |
1223 | @end defun |
1224 | ||
f9f59935 | 1225 | @defun set-face-bold-p face bold-p &optional frame |
a9f0a989 | 1226 | @tindex set-face-bold-p |
f9f59935 RS |
1227 | This function sets the bold attribute of face @var{face}. |
1228 | Non-@code{nil} means bold; @code{nil} means non-bold. | |
21cffb83 RS |
1229 | @end defun |
1230 | ||
f9f59935 | 1231 | @defun set-face-italic-p face italic-p &optional frame |
a9f0a989 | 1232 | @tindex set-face-italic-p |
f9f59935 RS |
1233 | This function sets the italic attribute of face @var{face}. |
1234 | Non-@code{nil} means italic; @code{nil} means non-italic. | |
42b85554 RS |
1235 | @end defun |
1236 | ||
969fe9b5 RS |
1237 | @defun set-face-underline-p face underline-p &optional frame |
1238 | This function sets the underline attribute of face @var{face}. | |
1239 | Non-@code{nil} means do underline; @code{nil} means don't. | |
1240 | @end defun | |
1241 | ||
42b85554 RS |
1242 | @defun invert-face face &optional frame |
1243 | Swap the foreground and background colors of face @var{face}. If the | |
1244 | face doesn't specify both foreground and background, then its foreground | |
78608595 RS |
1245 | and background are set to the default background and foreground, |
1246 | respectively. | |
42b85554 RS |
1247 | @end defun |
1248 | ||
1249 | These functions examine the attributes of a face. If you don't | |
1250 | specify @var{frame}, they refer to the default data for new frames. | |
1251 | ||
1252 | @defun face-foreground face &optional frame | |
1253 | @defunx face-background face &optional frame | |
78608595 RS |
1254 | These functions return the foreground color (or background color, |
1255 | respectively) of face @var{face}, as a string. | |
42b85554 RS |
1256 | @end defun |
1257 | ||
bfe721d1 KH |
1258 | @defun face-stipple face &optional frame |
1259 | This function returns the name of the background stipple pattern of face | |
1260 | @var{face}, or @code{nil} if it doesn't have one. | |
1261 | @end defun | |
1262 | ||
42b85554 RS |
1263 | @defun face-font face &optional frame |
1264 | This function returns the name of the font of face @var{face}. | |
1265 | @end defun | |
1266 | ||
f9f59935 | 1267 | @defun face-bold-p face &optional frame |
a9f0a989 | 1268 | @tindex face-bold-p |
f9f59935 RS |
1269 | This function returns the bold attribute of face @var{face}. |
1270 | @end defun | |
1271 | ||
f9f59935 | 1272 | @defun face-italic-p face &optional frame |
a9f0a989 | 1273 | @tindex face-italic-p |
f9f59935 RS |
1274 | This function returns the italic attribute of face @var{face}. |
1275 | @end defun | |
1276 | ||
969fe9b5 RS |
1277 | @defun face-underline-p face &optional frame |
1278 | This function returns the underline attribute of face @var{face}. | |
1279 | @end defun | |
1280 | ||
bfe721d1 | 1281 | @defun face-id face |
969fe9b5 | 1282 | This function returns the face number of face @var{face}. |
42b85554 RS |
1283 | @end defun |
1284 | ||
f9f59935 | 1285 | @defun face-documentation face |
a9f0a989 | 1286 | @tindex face-documentation |
f9f59935 RS |
1287 | This function returns the documentation string of face @var{face}, or |
1288 | @code{nil} if none was specified for it. | |
1289 | @end defun | |
1290 | ||
42b85554 RS |
1291 | @defun face-equal face1 face2 &optional frame |
1292 | This returns @code{t} if the faces @var{face1} and @var{face2} have the | |
1293 | same attributes for display. | |
1294 | @end defun | |
1295 | ||
1296 | @defun face-differs-from-default-p face &optional frame | |
1297 | This returns @code{t} if the face @var{face} displays differently from | |
1298 | the default face. A face is considered to be ``the same'' as the normal | |
1299 | face if each attribute is either the same as that of the default face or | |
1300 | @code{nil} (meaning to inherit from the default). | |
1301 | @end defun | |
1302 | ||
1303 | @defvar region-face | |
969fe9b5 | 1304 | This variable's value specifies the face number to use to display characters |
42b85554 RS |
1305 | in the region when it is active (in Transient Mark mode only). The face |
1306 | thus specified takes precedence over all faces that come from text | |
1307 | properties and overlays, for characters in the region. @xref{The Mark}, | |
1308 | for more information about Transient Mark mode. | |
1309 | ||
969fe9b5 | 1310 | Normally, the value is the face number of the face named @code{region}. |
42b85554 RS |
1311 | @end defvar |
1312 | ||
1911e6e5 RS |
1313 | @tindex frame-update-face-colors |
1314 | @defun frame-update-face-colors frame | |
1315 | This function updates the way faces display on @var{frame}, for a change | |
1316 | in @var{frame}'s foreground or background color. | |
1317 | @end defun | |
1318 | ||
42b85554 RS |
1319 | @node Blinking |
1320 | @section Blinking Parentheses | |
1321 | @cindex parenthesis matching | |
1322 | @cindex blinking | |
1323 | @cindex balancing parentheses | |
1324 | @cindex close parenthesis | |
1325 | ||
1326 | This section describes the mechanism by which Emacs shows a matching | |
1327 | open parenthesis when the user inserts a close parenthesis. | |
1328 | ||
42b85554 RS |
1329 | @defvar blink-paren-function |
1330 | The value of this variable should be a function (of no arguments) to | |
1331 | be called whenever a character with close parenthesis syntax is inserted. | |
1332 | The value of @code{blink-paren-function} may be @code{nil}, in which | |
1333 | case nothing is done. | |
42b85554 RS |
1334 | @end defvar |
1335 | ||
1911e6e5 | 1336 | @defopt blink-matching-paren |
42b85554 RS |
1337 | If this variable is @code{nil}, then @code{blink-matching-open} does |
1338 | nothing. | |
1911e6e5 | 1339 | @end defopt |
42b85554 | 1340 | |
1911e6e5 | 1341 | @defopt blink-matching-paren-distance |
42b85554 RS |
1342 | This variable specifies the maximum distance to scan for a matching |
1343 | parenthesis before giving up. | |
1911e6e5 | 1344 | @end defopt |
42b85554 | 1345 | |
1911e6e5 | 1346 | @defopt blink-matching-delay |
bfe721d1 KH |
1347 | This variable specifies the number of seconds for the cursor to remain |
1348 | at the matching parenthesis. A fraction of a second often gives | |
1349 | good results, but the default is 1, which works on all systems. | |
1911e6e5 | 1350 | @end defopt |
bfe721d1 | 1351 | |
1911e6e5 | 1352 | @deffn Command blink-matching-open |
42b85554 RS |
1353 | This function is the default value of @code{blink-paren-function}. It |
1354 | assumes that point follows a character with close parenthesis syntax and | |
1355 | moves the cursor momentarily to the matching opening character. If that | |
1356 | character is not already on the screen, it displays the character's | |
1357 | context in the echo area. To avoid long delays, this function does not | |
1358 | search farther than @code{blink-matching-paren-distance} characters. | |
1359 | ||
1360 | Here is an example of calling this function explicitly. | |
1361 | ||
1362 | @smallexample | |
1363 | @group | |
1364 | (defun interactive-blink-matching-open () | |
1365 | @c Do not break this line! -- rms. | |
1366 | @c The first line of a doc string | |
1367 | @c must stand alone. | |
1368 | "Indicate momentarily the start of sexp before point." | |
1369 | (interactive) | |
1370 | @end group | |
1371 | @group | |
1372 | (let ((blink-matching-paren-distance | |
1373 | (buffer-size)) | |
1374 | (blink-matching-paren t)) | |
1375 | (blink-matching-open))) | |
1376 | @end group | |
1377 | @end smallexample | |
1911e6e5 | 1378 | @end deffn |
42b85554 RS |
1379 | |
1380 | @node Inverse Video | |
1381 | @section Inverse Video | |
1382 | @cindex Inverse Video | |
1383 | ||
1384 | @defopt inverse-video | |
1385 | @cindex highlighting | |
1386 | This variable controls whether Emacs uses inverse video for all text | |
1387 | on the screen. Non-@code{nil} means yes, @code{nil} means no. The | |
1388 | default is @code{nil}. | |
1389 | @end defopt | |
1390 | ||
1391 | @defopt mode-line-inverse-video | |
1392 | This variable controls the use of inverse video for mode lines. If it | |
bfe721d1 KH |
1393 | is non-@code{nil}, then mode lines are displayed in inverse video. |
1394 | Otherwise, mode lines are displayed normally, just like text. The | |
1395 | default is @code{t}. | |
1396 | ||
969fe9b5 | 1397 | For window frames, this displays mode lines using the face named |
bfe721d1 KH |
1398 | @code{modeline}, which is normally the inverse of the default face |
1399 | unless you change it. | |
42b85554 RS |
1400 | @end defopt |
1401 | ||
1402 | @node Usual Display | |
1403 | @section Usual Display Conventions | |
1404 | ||
1405 | The usual display conventions define how to display each character | |
1406 | code. You can override these conventions by setting up a display table | |
1407 | (@pxref{Display Tables}). Here are the usual display conventions: | |
1408 | ||
1409 | @itemize @bullet | |
1410 | @item | |
1411 | Character codes 32 through 126 map to glyph codes 32 through 126. | |
1412 | Normally this means they display as themselves. | |
1413 | ||
1414 | @item | |
1415 | Character code 9 is a horizontal tab. It displays as whitespace | |
1416 | up to a position determined by @code{tab-width}. | |
1417 | ||
1418 | @item | |
1419 | Character code 10 is a newline. | |
1420 | ||
1421 | @item | |
1422 | All other codes in the range 0 through 31, and code 127, display in one | |
78608595 | 1423 | of two ways according to the value of @code{ctl-arrow}. If it is |
42b85554 RS |
1424 | non-@code{nil}, these codes map to sequences of two glyphs, where the |
1425 | first glyph is the @sc{ASCII} code for @samp{^}. (A display table can | |
1426 | specify a glyph to use instead of @samp{^}.) Otherwise, these codes map | |
1427 | just like the codes in the range 128 to 255. | |
1428 | ||
1429 | @item | |
1430 | Character codes 128 through 255 map to sequences of four glyphs, where | |
1431 | the first glyph is the @sc{ASCII} code for @samp{\}, and the others are | |
a9f0a989 | 1432 | digit characters representing the character code in octal. (A display |
969fe9b5 RS |
1433 | table can specify a glyph to use instead of @samp{\}.) |
1434 | ||
1435 | @item | |
1436 | Multibyte character codes above 256 are displayed as themselves, or as a | |
1437 | question mark or empty box if the terminal cannot display that | |
1438 | character. | |
42b85554 RS |
1439 | @end itemize |
1440 | ||
1441 | The usual display conventions apply even when there is a display | |
1442 | table, for any character whose entry in the active display table is | |
1443 | @code{nil}. Thus, when you set up a display table, you need only | |
969fe9b5 | 1444 | specify the characters for which you want special behavior. |
42b85554 RS |
1445 | |
1446 | These variables affect the way certain characters are displayed on the | |
1447 | screen. Since they change the number of columns the characters occupy, | |
f9f59935 RS |
1448 | they also affect the indentation functions. These variables also affect |
1449 | how the mode line is displayed; if you want to force redisplay of the | |
1450 | mode line using the new values, call the function | |
1451 | @code{force-mode-line-update} (@pxref{Mode Line Format}). | |
42b85554 RS |
1452 | |
1453 | @defopt ctl-arrow | |
1454 | @cindex control characters in display | |
1455 | This buffer-local variable controls how control characters are | |
1456 | displayed. If it is non-@code{nil}, they are displayed as a caret | |
1457 | followed by the character: @samp{^A}. If it is @code{nil}, they are | |
1458 | displayed as a backslash followed by three octal digits: @samp{\001}. | |
1459 | @end defopt | |
1460 | ||
1461 | @c Following may have overfull hbox. | |
1462 | @defvar default-ctl-arrow | |
1463 | The value of this variable is the default value for @code{ctl-arrow} in | |
1464 | buffers that do not override it. @xref{Default Value}. | |
1465 | @end defvar | |
1466 | ||
1467 | @defopt tab-width | |
1468 | The value of this variable is the spacing between tab stops used for | |
1469 | displaying tab characters in Emacs buffers. The default is 8. Note | |
f9f59935 | 1470 | that this feature is completely independent of the user-settable tab |
42b85554 RS |
1471 | stops used by the command @code{tab-to-tab-stop}. @xref{Indent Tabs}. |
1472 | @end defopt | |
1473 | ||
1474 | @node Display Tables | |
1475 | @section Display Tables | |
1476 | ||
1477 | @cindex display table | |
969fe9b5 RS |
1478 | You can use the @dfn{display table} feature to control how all possible |
1479 | character codes display on the screen. This is useful for displaying | |
1480 | European languages that have letters not in the @sc{ASCII} character | |
1481 | set. | |
42b85554 RS |
1482 | |
1483 | The display table maps each character code into a sequence of | |
1484 | @dfn{glyphs}, each glyph being an image that takes up one character | |
1485 | position on the screen. You can also define how to display each glyph | |
1486 | on your terminal, using the @dfn{glyph table}. | |
1487 | ||
f9f59935 RS |
1488 | Display tables affect how the mode line is displayed; if you want to |
1489 | force redisplay of the mode line using a new display table, call | |
1490 | @code{force-mode-line-update} (@pxref{Mode Line Format}). | |
1491 | ||
42b85554 RS |
1492 | @menu |
1493 | * Display Table Format:: What a display table consists of. | |
1494 | * Active Display Table:: How Emacs selects a display table to use. | |
1495 | * Glyphs:: How to define a glyph, and what glyphs mean. | |
42b85554 RS |
1496 | @end menu |
1497 | ||
1498 | @node Display Table Format | |
1499 | @subsection Display Table Format | |
1500 | ||
a9f0a989 RS |
1501 | A display table is actually a char-table (@pxref{Char-Tables}) with |
1502 | @code{display-table} as its subtype. | |
42b85554 RS |
1503 | |
1504 | @defun make-display-table | |
1505 | This creates and returns a display table. The table initially has | |
1506 | @code{nil} in all elements. | |
1507 | @end defun | |
1508 | ||
f9f59935 RS |
1509 | The ordinary elements of the display table are indexed by character |
1510 | codes; the element at index @var{c} says how to display the character | |
1511 | code @var{c}. The value should be @code{nil} or a vector of glyph | |
1512 | values (@pxref{Glyphs}). If an element is @code{nil}, it says to | |
1513 | display that character according to the usual display conventions | |
1514 | (@pxref{Usual Display}). | |
22697dac KH |
1515 | |
1516 | If you use the display table to change the display of newline | |
1517 | characters, the whole buffer will be displayed as one long ``line.'' | |
42b85554 | 1518 | |
f9f59935 | 1519 | The display table also has six ``extra slots'' which serve special |
969fe9b5 RS |
1520 | purposes. Here is a table of their meanings; @code{nil} in any slot |
1521 | means to use the default for that slot, as stated below. | |
42b85554 RS |
1522 | |
1523 | @table @asis | |
f9f59935 | 1524 | @item 0 |
42b85554 RS |
1525 | The glyph for the end of a truncated screen line (the default for this |
1526 | is @samp{$}). @xref{Glyphs}. | |
f9f59935 | 1527 | @item 1 |
42b85554 | 1528 | The glyph for the end of a continued line (the default is @samp{\}). |
f9f59935 | 1529 | @item 2 |
42b85554 RS |
1530 | The glyph for indicating a character displayed as an octal character |
1531 | code (the default is @samp{\}). | |
f9f59935 | 1532 | @item 3 |
42b85554 | 1533 | The glyph for indicating a control character (the default is @samp{^}). |
f9f59935 | 1534 | @item 4 |
42b85554 RS |
1535 | A vector of glyphs for indicating the presence of invisible lines (the |
1536 | default is @samp{...}). @xref{Selective Display}. | |
f9f59935 | 1537 | @item 5 |
50b04c36 JB |
1538 | The glyph used to draw the border between side-by-side windows (the |
1539 | default is @samp{|}). @xref{Splitting Windows}. | |
42b85554 RS |
1540 | @end table |
1541 | ||
1542 | For example, here is how to construct a display table that mimics the | |
1543 | effect of setting @code{ctl-arrow} to a non-@code{nil} value: | |
1544 | ||
1545 | @example | |
1546 | (setq disptab (make-display-table)) | |
1547 | (let ((i 0)) | |
1548 | (while (< i 32) | |
1549 | (or (= i ?\t) (= i ?\n) | |
1550 | (aset disptab i (vector ?^ (+ i 64)))) | |
1551 | (setq i (1+ i))) | |
1552 | (aset disptab 127 (vector ?^ ??))) | |
1553 | @end example | |
1554 | ||
f9f59935 | 1555 | @defun display-table-slot display-table slot |
a9f0a989 | 1556 | @tindex display-table-slot |
f9f59935 RS |
1557 | This function returns the value of the extra slot @var{slot} of |
1558 | @var{display-table}. The argument @var{slot} may be a number from 0 to | |
1559 | 5 inclusive, or a slot name (symbol). Valid symbols are | |
1560 | @code{truncation}, @code{wrap}, @code{escape}, @code{control}, | |
1561 | @code{selective-display}, and @code{vertical-border}. | |
1562 | @end defun | |
1563 | ||
f9f59935 | 1564 | @defun set-display-table-slot display-table slot value |
a9f0a989 | 1565 | @tindex set-display-table-slot |
f9f59935 RS |
1566 | This function stores @var{value} in the extra slot @var{slot} of |
1567 | @var{display-table}. The argument @var{slot} may be a number from 0 to | |
1568 | 5 inclusive, or a slot name (symbol). Valid symbols are | |
1569 | @code{truncation}, @code{wrap}, @code{escape}, @code{control}, | |
1570 | @code{selective-display}, and @code{vertical-border}. | |
1571 | @end defun | |
1572 | ||
42b85554 RS |
1573 | @node Active Display Table |
1574 | @subsection Active Display Table | |
1575 | @cindex active display table | |
1576 | ||
1577 | Each window can specify a display table, and so can each buffer. When | |
1578 | a buffer @var{b} is displayed in window @var{w}, display uses the | |
1579 | display table for window @var{w} if it has one; otherwise, the display | |
1580 | table for buffer @var{b} if it has one; otherwise, the standard display | |
1581 | table if any. The display table chosen is called the @dfn{active} | |
1582 | display table. | |
1583 | ||
1584 | @defun window-display-table window | |
1585 | This function returns @var{window}'s display table, or @code{nil} | |
1586 | if @var{window} does not have an assigned display table. | |
1587 | @end defun | |
1588 | ||
1589 | @defun set-window-display-table window table | |
1590 | This function sets the display table of @var{window} to @var{table}. | |
1591 | The argument @var{table} should be either a display table or | |
1592 | @code{nil}. | |
1593 | @end defun | |
1594 | ||
1595 | @defvar buffer-display-table | |
969fe9b5 RS |
1596 | This variable is automatically buffer-local in all buffers; its value in |
1597 | a particular buffer specifies the display table for that buffer. If it | |
1598 | is @code{nil}, that means the buffer does not have an assigned display | |
1599 | table. | |
42b85554 RS |
1600 | @end defvar |
1601 | ||
1602 | @defvar standard-display-table | |
1603 | This variable's value is the default display table, used whenever a | |
1604 | window has no display table and neither does the buffer displayed in | |
1605 | that window. This variable is @code{nil} by default. | |
1606 | @end defvar | |
1607 | ||
1608 | If there is no display table to use for a particular window---that is, | |
f9f59935 RS |
1609 | if the window specifies none, its buffer specifies none, and |
1610 | @code{standard-display-table} is @code{nil}---then Emacs uses the usual | |
42b85554 RS |
1611 | display conventions for all character codes in that window. @xref{Usual |
1612 | Display}. | |
1613 | ||
1614 | @node Glyphs | |
1615 | @subsection Glyphs | |
1616 | ||
1617 | @cindex glyph | |
1618 | A @dfn{glyph} is a generalization of a character; it stands for an | |
1619 | image that takes up a single character position on the screen. Glyphs | |
1620 | are represented in Lisp as integers, just as characters are. | |
1621 | ||
1622 | @cindex glyph table | |
1623 | The meaning of each integer, as a glyph, is defined by the glyph | |
1624 | table, which is the value of the variable @code{glyph-table}. | |
1625 | ||
1626 | @defvar glyph-table | |
1627 | The value of this variable is the current glyph table. It should be a | |
1628 | vector; the @var{g}th element defines glyph code @var{g}. If the value | |
1629 | is @code{nil} instead of a vector, then all glyphs are simple (see | |
1630 | below). | |
1631 | @end defvar | |
1632 | ||
1633 | Here are the possible types of elements in the glyph table: | |
1634 | ||
1911e6e5 RS |
1635 | @table @asis |
1636 | @item @var{string} | |
42b85554 RS |
1637 | Send the characters in @var{string} to the terminal to output |
1638 | this glyph. This alternative is available on character terminals, | |
969fe9b5 | 1639 | but not under a window system. |
42b85554 | 1640 | |
1911e6e5 | 1641 | @item @var{integer} |
969fe9b5 RS |
1642 | Define this glyph code as an alias for glyph code @var{integer}. You |
1643 | can use an alias to specify a face code for the glyph; see below. | |
42b85554 RS |
1644 | |
1645 | @item @code{nil} | |
969fe9b5 RS |
1646 | This glyph is simple. On an ordinary terminal, the glyph code mod |
1647 | 524288 is the character to output. In a window system, the glyph code | |
1648 | mod 524288 is the character to output, and the glyph code divided by | |
1649 | 524288 specifies the face number (@pxref{Face Functions}) to use while | |
1650 | outputting it. (524288 is | |
f9f59935 | 1651 | @ifinfo |
969fe9b5 | 1652 | 2**19.) |
f9f59935 RS |
1653 | @end ifinfo |
1654 | @tex | |
969fe9b5 | 1655 | $2^{19}$.) |
f9f59935 RS |
1656 | @end tex |
1657 | @xref{Faces}. | |
42b85554 RS |
1658 | @end table |
1659 | ||
1660 | If a glyph code is greater than or equal to the length of the glyph | |
1661 | table, that code is automatically simple. | |
1662 | ||
42b85554 RS |
1663 | @node Beeping |
1664 | @section Beeping | |
1665 | @cindex beeping | |
1666 | @cindex bell | |
1667 | ||
f9f59935 RS |
1668 | This section describes how to make Emacs ring the bell (or blink the |
1669 | screen) to attract the user's attention. Be conservative about how | |
1670 | often you do this; frequent bells can become irritating. Also be | |
1671 | careful not to use just beeping when signaling an error is more | |
1672 | appropriate. (@xref{Errors}.) | |
42b85554 | 1673 | |
a9f0a989 | 1674 | @defun ding &optional do-not-terminate |
42b85554 RS |
1675 | @cindex keyboard macro termination |
1676 | This function beeps, or flashes the screen (see @code{visible-bell} below). | |
1677 | It also terminates any keyboard macro currently executing unless | |
a9f0a989 | 1678 | @var{do-not-terminate} is non-@code{nil}. |
42b85554 RS |
1679 | @end defun |
1680 | ||
a9f0a989 | 1681 | @defun beep &optional do-not-terminate |
42b85554 RS |
1682 | This is a synonym for @code{ding}. |
1683 | @end defun | |
1684 | ||
1911e6e5 | 1685 | @defopt visible-bell |
42b85554 RS |
1686 | This variable determines whether Emacs should flash the screen to |
1687 | represent a bell. Non-@code{nil} means yes, @code{nil} means no. This | |
969fe9b5 RS |
1688 | is effective on a window system, and on a character-only terminal |
1689 | provided the terminal's Termcap entry defines the visible bell | |
1690 | capability (@samp{vb}). | |
1911e6e5 | 1691 | @end defopt |
42b85554 | 1692 | |
f9f59935 | 1693 | @defvar ring-bell-function |
a9f0a989 | 1694 | @tindex ring-bell-function |
f9f59935 | 1695 | If this is non-@code{nil}, it specifies how Emacs should ``ring the |
a9f0a989 | 1696 | bell.'' Its value should be a function of no arguments. |
f9f59935 RS |
1697 | @end defvar |
1698 | ||
42b85554 RS |
1699 | @node Window Systems |
1700 | @section Window Systems | |
1701 | ||
1702 | Emacs works with several window systems, most notably the X Window | |
1703 | System. Both Emacs and X use the term ``window'', but use it | |
1704 | differently. An Emacs frame is a single window as far as X is | |
1705 | concerned; the individual Emacs windows are not known to X at all. | |
1706 | ||
1707 | @defvar window-system | |
42b85554 | 1708 | This variable tells Lisp programs what window system Emacs is running |
1911e6e5 RS |
1709 | under. The possible values are |
1710 | ||
1711 | @table @code | |
1712 | @item x | |
1713 | @cindex X Window System | |
1714 | Emacs is displaying using X. | |
1715 | @item pc | |
1716 | Emacs is displaying using MSDOS. | |
1717 | @item w32 | |
1718 | Emacs is displaying using Windows NT or Windows 95. | |
1719 | @item nil | |
1720 | Emacs is using a character-based terminal. | |
1721 | @end table | |
42b85554 RS |
1722 | @end defvar |
1723 | ||
42b85554 | 1724 | @defvar window-setup-hook |
f9f59935 RS |
1725 | This variable is a normal hook which Emacs runs after handling the |
1726 | initialization files. Emacs runs this hook after it has completed | |
1727 | loading your @file{.emacs} file, the default initialization file (if | |
a9f0a989 | 1728 | any), and the terminal-specific Lisp code, and running the hook |
42b85554 RS |
1729 | @code{term-setup-hook}. |
1730 | ||
1731 | This hook is used for internal purposes: setting up communication with | |
1732 | the window system, and creating the initial window. Users should not | |
1733 | interfere with it. | |
1734 | @end defvar |