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