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