|
428
|
1 @c -*-texinfo-*-
|
|
|
2 @c This is part of the XEmacs Lisp Reference Manual.
|
|
444
|
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998 Free Software Foundation, Inc.
|
|
428
|
4 @c See the file lispref.texi for copying conditions.
|
|
|
5 @setfilename ../../info/display.info
|
|
|
6 @node Display, Hash Tables, Annotations, Top
|
|
|
7 @chapter Emacs Display
|
|
|
8
|
|
|
9 This chapter describes a number of other features related to the display
|
|
|
10 that XEmacs 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.
|
|
|
16 * Warnings:: Display of Warnings.
|
|
|
17 * Invisible Text:: Hiding part of the buffer text.
|
|
|
18 * Selective Display:: Hiding part of the buffer text (the old way).
|
|
|
19 * Overlay Arrow:: Display of an arrow to indicate position.
|
|
|
20 * Temporary Displays:: Displays that go away automatically.
|
|
|
21 * Blinking:: How XEmacs shows the matching open parenthesis.
|
|
|
22 * Usual Display:: The usual conventions for displaying nonprinting chars.
|
|
|
23 * Display Tables:: How to specify other conventions.
|
|
|
24 * Beeping:: Audible signal to the user.
|
|
|
25 @end menu
|
|
|
26
|
|
|
27 @node Refresh Screen
|
|
|
28 @section Refreshing the Screen
|
|
|
29
|
|
|
30 The function @code{redraw-frame} redisplays the entire contents of a
|
|
|
31 given frame. @xref{Frames}.
|
|
|
32
|
|
444
|
33 @defun redraw-frame &optional frame no-preempt
|
|
428
|
34 This function clears and redisplays frame @var{frame}.
|
|
444
|
35
|
|
|
36 @var{frame} defaults to the selected frame if omitted.
|
|
|
37
|
|
|
38 Normally, redisplay is preempted as normal if input arrives. However,
|
|
|
39 if optional second arg @var{no-preempt} is non-@code{nil}, redisplay
|
|
|
40 will not stop for input and is guaranteed to proceed to completion.
|
|
428
|
41 @end defun
|
|
|
42
|
|
|
43 Even more powerful is @code{redraw-display}:
|
|
|
44
|
|
|
45 @deffn Command redraw-display &optional device
|
|
|
46 This function redraws all frames on @var{device} marked as having their
|
|
|
47 image garbled. @var{device} defaults to the selected device. If
|
|
|
48 @var{device} is @code{t}, all devices will have their frames checked.
|
|
|
49 @end deffn
|
|
|
50
|
|
|
51 Processing user input takes absolute priority over redisplay. If you
|
|
|
52 call these functions when input is available, they do nothing
|
|
|
53 immediately, but a full redisplay does happen eventually---after all the
|
|
|
54 input has been processed.
|
|
|
55
|
|
|
56 Normally, suspending and resuming XEmacs also refreshes the screen.
|
|
|
57 Some terminal emulators record separate contents for display-oriented
|
|
|
58 programs such as XEmacs and for ordinary sequential display. If you are
|
|
|
59 using such a terminal, you might want to inhibit the redisplay on
|
|
|
60 resumption. @xref{Suspending XEmacs}.
|
|
|
61
|
|
|
62 @defvar no-redraw-on-reenter
|
|
|
63 @cindex suspend (cf. @code{no-redraw-on-reenter})
|
|
|
64 @cindex resume (cf. @code{no-redraw-on-reenter})
|
|
|
65 This variable controls whether XEmacs redraws the entire screen after it
|
|
|
66 has been suspended and resumed. Non-@code{nil} means yes, @code{nil}
|
|
|
67 means no.
|
|
|
68 @end defvar
|
|
|
69
|
|
|
70 @cindex display update
|
|
|
71 @cindex update display
|
|
|
72 @cindex refresh display
|
|
|
73 The above functions do not actually cause the display to be updated;
|
|
|
74 rather, they clear out the internal display records that XEmacs
|
|
|
75 maintains, so that the next time the display is updated it will be
|
|
|
76 redrawn from scratch. Normally this occurs the next time that
|
|
|
77 @code{next-event} or @code{sit-for} is called; however, a display update
|
|
|
78 will not occur if there is input pending. @xref{Command Loop}.
|
|
|
79
|
|
444
|
80 @defun force-cursor-redisplay &optional frame
|
|
|
81 This function causes an immediate update of the cursor on @var{frame},
|
|
|
82 which defaults to the selected frame.
|
|
428
|
83 @end defun
|
|
|
84
|
|
|
85 @node Truncation
|
|
|
86 @section Truncation
|
|
|
87 @cindex line wrapping
|
|
|
88 @cindex continuation lines
|
|
|
89 @cindex @samp{$} in display
|
|
|
90 @cindex @samp{\} in display
|
|
|
91
|
|
|
92 When a line of text extends beyond the right edge of a window, the
|
|
|
93 line can either be truncated or continued on the next line. When a line
|
|
|
94 is truncated, this is normally shown with a @samp{\} in the rightmost
|
|
|
95 column of the window on X displays, and with a @samp{$} on TTY devices.
|
|
|
96 When a line is continued or ``wrapped'' onto the next line, this is
|
|
|
97 shown with a curved arrow in the rightmost column of the window (or with
|
|
|
98 a @samp{\} on TTY devices). The additional screen lines used to display
|
|
|
99 a long text line are called @dfn{continuation} lines.
|
|
|
100
|
|
|
101 Normally, whenever line truncation is in effect for a particular
|
|
|
102 window, a horizontal scrollbar is displayed in that window if the
|
|
|
103 device supports scrollbars. @xref{Scrollbars}.
|
|
|
104
|
|
|
105 Note that continuation is different from filling; continuation happens
|
|
|
106 on the screen only, not in the buffer contents, and it breaks a line
|
|
|
107 precisely at the right margin, not at a word boundary. @xref{Filling}.
|
|
|
108
|
|
|
109 @defopt truncate-lines
|
|
|
110 This buffer-local variable controls how XEmacs displays lines that
|
|
|
111 extend beyond the right edge of the window. If it is non-@code{nil},
|
|
|
112 then XEmacs does not display continuation lines; rather each line of
|
|
|
113 text occupies exactly one screen line, and a backslash appears at the
|
|
|
114 edge of any line that extends to or beyond the edge of the window. The
|
|
|
115 default is @code{nil}.
|
|
|
116
|
|
|
117 If the variable @code{truncate-partial-width-windows} is non-@code{nil},
|
|
|
118 then truncation is always used for side-by-side windows (within one
|
|
|
119 frame) regardless of the value of @code{truncate-lines}.
|
|
|
120 @end defopt
|
|
|
121
|
|
|
122 @defopt default-truncate-lines
|
|
|
123 This variable is the default value for @code{truncate-lines}, for
|
|
|
124 buffers that do not have local values for it.
|
|
|
125 @end defopt
|
|
|
126
|
|
|
127 @defopt truncate-partial-width-windows
|
|
|
128 This variable controls display of lines that extend beyond the right
|
|
|
129 edge of the window, in side-by-side windows (@pxref{Splitting Windows}).
|
|
|
130 If it is non-@code{nil}, these lines are truncated; otherwise,
|
|
|
131 @code{truncate-lines} says what to do with them.
|
|
|
132 @end defopt
|
|
|
133
|
|
|
134 The backslash and curved arrow used to indicate truncated or continued
|
|
|
135 lines are only defaults, and can be changed. These images are actually
|
|
|
136 glyphs (@pxref{Glyphs}). XEmacs provides a great deal of flexibility
|
|
|
137 in how glyphs can be controlled. (This differs from FSF Emacs, which
|
|
|
138 uses display tables to control these images.)
|
|
|
139
|
|
|
140 For details, @ref{Redisplay Glyphs}.
|
|
|
141
|
|
|
142 @ignore Not yet in XEmacs
|
|
|
143 If your buffer contains @strong{very} long lines, and you use
|
|
|
144 continuation to display them, just thinking about them can make Emacs
|
|
|
145 redisplay slow. The column computation and indentation functions also
|
|
|
146 become slow. Then you might find it advisable to set
|
|
|
147 @code{cache-long-line-scans} to @code{t}.
|
|
|
148
|
|
|
149 @defvar cache-long-line-scans
|
|
|
150 If this variable is non-@code{nil}, various indentation and motion
|
|
|
151 functions, and Emacs redisplay, cache the results of scanning the
|
|
|
152 buffer, and consult the cache to avoid rescanning regions of the buffer
|
|
|
153 unless they are modified.
|
|
|
154
|
|
|
155 Turning on the cache slows down processing of short lines somewhat.
|
|
|
156
|
|
|
157 This variable is automatically local in every buffer.
|
|
|
158 @end defvar
|
|
|
159 @end ignore
|
|
|
160
|
|
|
161 @node The Echo Area
|
|
|
162 @section The Echo Area
|
|
|
163 @cindex error display
|
|
|
164 @cindex echo area
|
|
|
165
|
|
|
166 The @dfn{echo area} is used for displaying messages made with the
|
|
|
167 @code{message} primitive, and for echoing keystrokes. It is not the
|
|
|
168 same as the minibuffer, despite the fact that the minibuffer appears
|
|
|
169 (when active) in the same place on the screen as the echo area. The
|
|
446
|
170 @cite{XEmacs Lisp Reference Manual} specifies the rules for resolving conflicts
|
|
428
|
171 between the echo area and the minibuffer for use of that screen space
|
|
446
|
172 (@pxref{Minibuffer,, The Minibuffer, xemacs, The XEmacs Lisp Reference Manual}).
|
|
1703
|
173 Such a conflicts may be avoided at all as described in @ref{Customizing Message
|
|
|
174 Display}.
|
|
|
175
|
|
428
|
176 Error messages appear in the echo area; see @ref{Errors}.
|
|
|
177
|
|
|
178 You can write output in the echo area by using the Lisp printing
|
|
|
179 functions with @code{t} as the stream (@pxref{Output Functions}), or as
|
|
|
180 follows:
|
|
|
181
|
|
|
182 @defun message string &rest arguments
|
|
|
183 This function displays a one-line message in the echo area. The
|
|
|
184 argument @var{string} is similar to a C language @code{printf} control
|
|
|
185 string. See @code{format} in @ref{String Conversion}, for the details
|
|
|
186 on the conversion specifications. @code{message} returns the
|
|
|
187 constructed string.
|
|
|
188
|
|
|
189 In batch mode, @code{message} prints the message text on the standard
|
|
|
190 error stream, followed by a newline.
|
|
|
191
|
|
|
192 @c Emacs 19 feature
|
|
|
193 If @var{string} is @code{nil}, @code{message} clears the echo area. If
|
|
|
194 the minibuffer is active, this brings the minibuffer contents back onto
|
|
|
195 the screen immediately.
|
|
|
196
|
|
|
197 @example
|
|
|
198 @group
|
|
|
199 (message "Minibuffer depth is %d."
|
|
|
200 (minibuffer-depth))
|
|
|
201 @print{} Minibuffer depth is 0.
|
|
|
202 @result{} "Minibuffer depth is 0."
|
|
|
203 @end group
|
|
|
204
|
|
|
205 @group
|
|
|
206 ---------- Echo Area ----------
|
|
|
207 Minibuffer depth is 0.
|
|
|
208 ---------- Echo Area ----------
|
|
|
209 @end group
|
|
|
210 @end example
|
|
|
211 @end defun
|
|
|
212
|
|
|
213 In addition to only displaying a message, XEmacs allows you to
|
|
|
214 @dfn{label} your messages, giving you fine-grained control of their
|
|
|
215 display. Message label is a symbol denoting the message type. Some
|
|
|
216 standard labels are:
|
|
|
217
|
|
|
218 @itemize @bullet
|
|
|
219 @item @code{message}---default label used by the @code{message}
|
|
|
220 function;
|
|
|
221
|
|
|
222 @item @code{error}---default label used for reporting errors;
|
|
|
223
|
|
|
224 @item @code{progress}---progress indicators like
|
|
|
225 @samp{Converting... 45%} (not logged by default);
|
|
|
226
|
|
444
|
227 @item @code{prompt}---prompt-like messages like @samp{Isearch: foo} (not
|
|
428
|
228 logged by default);
|
|
|
229
|
|
444
|
230 @item @code{command}---helper command messages like @samp{Mark set} (not
|
|
428
|
231 logged by default);
|
|
|
232
|
|
|
233 @item @code{no-log}---messages that should never be logged
|
|
|
234 @end itemize
|
|
|
235
|
|
444
|
236 Several messages may be stacked in the echo area at once. Lisp programs
|
|
428
|
237 may access these messages, or remove them as appropriate, via the
|
|
|
238 message stack.
|
|
|
239
|
|
|
240 @defun display-message label message &optional frame stdout-p
|
|
|
241 This function displays @var{message} (a string) labeled as @var{label},
|
|
|
242 as described above.
|
|
|
243
|
|
|
244 The @var{frame} argument specifies the frame to whose minibuffer the
|
|
|
245 message should be printed. This is currently unimplemented. The
|
|
|
246 @var{stdout-p} argument is used internally.
|
|
|
247
|
|
|
248 @example
|
|
|
249 (display-message 'command "Mark set")
|
|
|
250 @end example
|
|
|
251 @end defun
|
|
|
252
|
|
|
253 @defun lmessage label string &rest arguments
|
|
|
254 This function displays a message @var{string} with label @var{label}.
|
|
|
255 It is similar to @code{message} in that it accepts a @code{printf}-like
|
|
|
256 strings and any number of arguments.
|
|
|
257
|
|
|
258 @example
|
|
|
259 @group
|
|
|
260 ;; @r{Display a command message.}
|
|
|
261 (lmessage 'command "Comment column set to %d" comment-column)
|
|
|
262 @end group
|
|
|
263
|
|
|
264 @group
|
|
|
265 ;; @r{Display a progress message.}
|
|
|
266 (lmessage 'progress "Fontifying %s... (%d)" buffer percentage)
|
|
|
267 @end group
|
|
|
268
|
|
|
269 @group
|
|
|
270 ;; @r{Display a message that should not be logged.}
|
|
|
271 (lmessage 'no-log "Done")
|
|
|
272 @end group
|
|
|
273 @end example
|
|
|
274 @end defun
|
|
|
275
|
|
|
276 @defun clear-message &optional label frame stdout-p no-restore
|
|
|
277 This function remove any message with the given @var{label}
|
|
|
278 from the message-stack, erasing it from the echo area if it's currently
|
|
|
279 displayed there.
|
|
|
280
|
|
|
281 If a message remains at the head of the message-stack and
|
|
|
282 @var{no-restore} is @code{nil}, it will be displayed. The string which
|
|
|
283 remains in the echo area will be returned, or @code{nil} if the
|
|
444
|
284 message-stack is now empty. If @var{label} is @code{nil}, the entire
|
|
428
|
285 message-stack is cleared.
|
|
|
286
|
|
|
287 @example
|
|
|
288 ;; @r{Show a message, wait for 2 seconds, and restore old minibuffer}
|
|
|
289 ;; @r{contents.}
|
|
|
290 (message "A message")
|
|
|
291 @print{} A message
|
|
|
292 @result{} "A Message"
|
|
|
293 (lmessage 'my-label "Newsflash! Newsflash!")
|
|
|
294 @print{} Newsflash! Newsflash!
|
|
|
295 @result{} "Newsflash! Newsflash!"
|
|
|
296 (sit-for 2)
|
|
|
297 (clear-message 'my-label)
|
|
|
298 @print{} A message
|
|
|
299 @result{} "A message"
|
|
|
300 @end example
|
|
|
301
|
|
|
302 Unless you need the return value or you need to specify a label,
|
|
|
303 you should just use @code{(message nil)}.
|
|
|
304 @end defun
|
|
|
305
|
|
|
306 @defun current-message &optional frame
|
|
|
307 This function returns the current message in the echo area, or
|
|
|
308 @code{nil}. The @var{frame} argument is currently unused.
|
|
|
309 @end defun
|
|
|
310
|
|
|
311 Some of the messages displayed in the echo area are also recorded in the
|
|
|
312 @samp{ *Message-Log*} buffer. Exactly which messages will be recorded
|
|
|
313 can be tuned using the following variables.
|
|
|
314
|
|
|
315 @defopt log-message-max-size
|
|
|
316 This variable specifies the maximum size of the @samp{ *Message-log*}
|
|
|
317 buffer.
|
|
|
318 @end defopt
|
|
|
319
|
|
|
320 @defvar log-message-ignore-labels
|
|
|
321 This variable specifies the labels whose messages will not be logged.
|
|
|
322 It should be a list of symbols.
|
|
|
323 @end defvar
|
|
|
324
|
|
|
325 @defvar log-message-ignore-regexps
|
|
|
326 This variable specifies the regular expressions matching messages that
|
|
|
327 will not be logged. It should be a list of regular expressions.
|
|
|
328
|
|
|
329 Normally, packages that generate messages that might need to be ignored
|
|
|
330 should label them with @code{progress}, @code{prompt}, or @code{no-log},
|
|
|
331 so they can be filtered by @code{log-message-ignore-labels}.
|
|
|
332 @end defvar
|
|
|
333
|
|
|
334 @defvar echo-keystrokes
|
|
|
335 This variable determines how much time should elapse before command
|
|
|
336 characters echo. Its value must be a number, which specifies the number
|
|
|
337 of seconds to wait before echoing. If the user types a prefix key (such
|
|
|
338 as @kbd{C-x}) and then delays this many seconds before continuing, the
|
|
|
339 prefix key is echoed in the echo area. Any subsequent characters in the
|
|
|
340 same command will be echoed as well.
|
|
|
341
|
|
|
342 If the value is zero, then command input is not echoed.
|
|
|
343 @end defvar
|
|
|
344
|
|
|
345 @defvar cursor-in-echo-area
|
|
|
346 This variable controls where the cursor appears when a message is
|
|
|
347 displayed in the echo area. If it is non-@code{nil}, then the cursor
|
|
|
348 appears at the end of the message. Otherwise, the cursor appears at
|
|
|
349 point---not in the echo area at all.
|
|
|
350
|
|
|
351 The value is normally @code{nil}; Lisp programs bind it to @code{t}
|
|
|
352 for brief periods of time.
|
|
|
353 @end defvar
|
|
|
354
|
|
1703
|
355 @menu
|
|
|
356 * Customizing Message Display::
|
|
|
357 @end menu
|
|
|
358
|
|
|
359 @node Customizing Message Display
|
|
|
360 @subsection Customizing Message Display
|
|
|
361
|
|
|
362 Message display function specify message intended for echo area by
|
|
|
363 putting message text into @code{" *Echo Area*"} buffer. When event
|
|
|
364 loop code decides to update display after displaying the message, text
|
|
|
365 of this buffer is erased. How exactly the text will be displayed may
|
|
|
366 be affected by the following.
|
|
|
367
|
|
|
368 @findex redisplay-echo-area
|
|
|
369 @defvar redisplay-echo-area-function
|
|
|
370 The function called to display echo area text. The default variable
|
|
|
371 value, @code{redisplay-echo-area} function, does that by displaying
|
|
|
372 the text in the same place on the screen as the echo area. So does
|
|
|
373 other redisplay code. User code can avoid this regardless of what
|
|
|
374 redisplay code will run afterwards by erasing text of @code{" *Echo
|
|
|
375 Area*"} buffer.
|
|
|
376 @end defvar
|
|
|
377
|
|
|
378 @defvar undisplay-echo-area-function
|
|
|
379 The variable value, if non-@code{nil}, is called by command loop after
|
|
|
380 erasing text of @code{" *Echo Area*"} buffer. It must clean up data
|
|
|
381 created by @code{redisplay-echo-area-function} value.
|
|
|
382 @end defvar
|
|
|
383
|
|
|
384 @defvar minibuffer-echo-wait-function
|
|
|
385 The function is called by command loop only when minibuffer was active
|
|
|
386 and message was displayed (text appeared in @code{" *Echo Area*"}
|
|
|
387 buffer). It must wait after displaying message so that user can read
|
|
|
388 it. By default, when the variable value is @code{nil}, the equivalent
|
|
|
389 of @code{(sit-for 2)} is run.
|
|
|
390 @end defvar
|
|
|
391
|
|
428
|
392 @node Warnings
|
|
|
393 @section Warnings
|
|
|
394
|
|
|
395 XEmacs contains a facility for unified display of various warnings.
|
|
|
396 Unlike errors, warnings are displayed in the situations when XEmacs
|
|
|
397 encounters a problem that is recoverable, but which should be fixed for
|
|
|
398 safe future operation.
|
|
|
399
|
|
|
400 For example, warnings are printed by the startup code when it encounters
|
|
|
401 problems with X keysyms, when there is an error in @file{.emacs}, and in
|
|
|
402 other problematic situations. Unlike messages, warnings are displayed
|
|
|
403 in a separate buffer, and include an explanatory message that may span
|
|
|
404 across several lines. Here is an example of how a warning is displayed:
|
|
|
405
|
|
|
406 @example
|
|
|
407 (1) (initialization/error) An error has occurred while loading ~/.emacs:
|
|
|
408
|
|
|
409 Symbol's value as variable is void: bogus-variable
|
|
|
410
|
|
|
411 To ensure normal operation, you should investigate the cause of the error
|
|
|
412 in your initialization file and remove it. Use the `-debug-init' option
|
|
|
413 to XEmacs to view a complete error backtrace.
|
|
|
414 @end example
|
|
|
415
|
|
|
416 Each warning has a @dfn{class} and a @dfn{priority level}. The class is
|
|
|
417 a symbol describing what sort of warning this is, such as
|
|
|
418 @code{initialization}, @code{resource} or @code{key-mapping}.
|
|
|
419
|
|
|
420 The warning priority level specifies how important the warning is. The
|
|
|
421 recognized warning levels, in increased order of priority, are:
|
|
|
422 @code{debug}, @code{info}, @code{notice}, @code{warning}, @code{error},
|
|
|
423 @code{critical}, @code{alert} and @code{emergency}.
|
|
|
424
|
|
|
425 @defun display-warning class message &optional level
|
|
|
426 This function displays a warning message @var{message} (a string).
|
|
|
427 @var{class} should be a warning class symbol, as described above, or a
|
|
|
428 list of such symbols. @var{level} describes the warning priority level.
|
|
|
429 If unspecified, it default to @code{warning}.
|
|
|
430
|
|
|
431 @example
|
|
|
432 @group
|
|
|
433 (display-warning 'resource
|
|
|
434 "Bad resource specification encountered:
|
|
|
435 something like
|
|
|
436
|
|
|
437 Emacs*foo: bar
|
|
|
438
|
|
|
439 You should replace the * with a . in order to get proper behavior when
|
|
|
440 you use the specifier and/or `set-face-*' functions.")
|
|
|
441 @end group
|
|
|
442
|
|
|
443 @group
|
|
|
444 ---------- Warning buffer ----------
|
|
|
445 (1) (resource/warning) Bad resource specification encountered:
|
|
|
446 something like
|
|
|
447
|
|
|
448 Emacs*foo: bar
|
|
|
449
|
|
|
450 You should replace the * with a . in order to get proper behavior when
|
|
|
451 you use the specifier and/or `set-face-*' functions.
|
|
|
452 ---------- Warning buffer ----------
|
|
|
453 @end group
|
|
|
454 @end example
|
|
|
455 @end defun
|
|
|
456
|
|
|
457 @defun lwarn class level message &rest args
|
|
|
458 This function displays a formatted labeled warning message. As above,
|
|
|
459 @var{class} should be the warning class symbol, or a list of such
|
|
|
460 symbols, and @var{level} should specify the warning priority level
|
|
|
461 (@code{warning} by default).
|
|
|
462
|
|
|
463 Unlike in @code{display-warning}, @var{message} may be a formatted
|
|
|
464 message, which will be, together with the rest of the arguments, passed
|
|
|
465 to @code{format}.
|
|
|
466
|
|
|
467 @example
|
|
|
468 (lwarn 'message-log 'warning
|
|
|
469 "Error caught in `remove-message-hook': %s"
|
|
|
470 (error-message-string e))
|
|
|
471 @end example
|
|
|
472 @end defun
|
|
|
473
|
|
|
474 @defvar log-warning-minimum-level
|
|
|
475 This variable specifies the minimum level of warnings that should be
|
|
|
476 generated. Warnings with level lower than defined by this variable are
|
|
|
477 completely ignored, as if they never happened.
|
|
|
478 @end defvar
|
|
|
479
|
|
|
480 @defvar display-warning-minimum-level
|
|
|
481 This variable specifies the minimum level of warnings that should be
|
|
|
482 displayed. Unlike @code{log-warning-minimum-level}, setting this
|
|
|
483 function does not suppress warnings entirely---they are still generated
|
|
|
484 in the @samp{*Warnings*} buffer, only they are not displayed by default.
|
|
|
485 @end defvar
|
|
|
486
|
|
|
487 @defvar log-warning-suppressed-classes
|
|
|
488 This variable specifies a list of classes that should not be logged or
|
|
|
489 displayed. If any of the class symbols associated with a warning is the
|
|
|
490 same as any of the symbols listed here, the warning will be completely
|
|
|
491 ignored, as it they never happened.
|
|
|
492 @end defvar
|
|
|
493
|
|
|
494 @defvar display-warning-suppressed-classes
|
|
|
495 This variable specifies a list of classes that should not be logged or
|
|
|
496 displayed. If any of the class symbols associated with a warning is the
|
|
|
497 same as any of the symbols listed here, the warning will not be
|
|
|
498 displayed. The warning will still logged in the *Warnings* buffer
|
|
|
499 (unless also contained in `log-warning-suppressed-classes'), but the
|
|
|
500 buffer will not be automatically popped up.
|
|
|
501 @end defvar
|
|
|
502
|
|
|
503 @node Invisible Text
|
|
|
504 @section Invisible Text
|
|
|
505
|
|
|
506 @cindex invisible text
|
|
|
507 You can make characters @dfn{invisible}, so that they do not appear on
|
|
|
508 the screen, with the @code{invisible} property. This can be either a
|
|
|
509 text property or a property of an overlay.
|
|
|
510
|
|
|
511 In the simplest case, any non-@code{nil} @code{invisible} property makes
|
|
|
512 a character invisible. This is the default case---if you don't alter
|
|
|
513 the default value of @code{buffer-invisibility-spec}, this is how the
|
|
|
514 @code{invisibility} property works. This feature is much like selective
|
|
|
515 display (@pxref{Selective Display}), but more general and cleaner.
|
|
|
516
|
|
|
517 More generally, you can use the variable @code{buffer-invisibility-spec}
|
|
|
518 to control which values of the @code{invisible} property make text
|
|
|
519 invisible. This permits you to classify the text into different subsets
|
|
|
520 in advance, by giving them different @code{invisible} values, and
|
|
|
521 subsequently make various subsets visible or invisible by changing the
|
|
|
522 value of @code{buffer-invisibility-spec}.
|
|
|
523
|
|
|
524 Controlling visibility with @code{buffer-invisibility-spec} is
|
|
|
525 especially useful in a program to display the list of entries in a data
|
|
|
526 base. It permits the implementation of convenient filtering commands to
|
|
|
527 view just a part of the entries in the data base. Setting this variable
|
|
|
528 is very fast, much faster than scanning all the text in the buffer
|
|
|
529 looking for properties to change.
|
|
|
530
|
|
|
531 @defvar buffer-invisibility-spec
|
|
|
532 This variable specifies which kinds of @code{invisible} properties
|
|
|
533 actually make a character invisible.
|
|
|
534
|
|
|
535 @table @asis
|
|
|
536 @item @code{t}
|
|
|
537 A character is invisible if its @code{invisible} property is
|
|
|
538 non-@code{nil}. This is the default.
|
|
|
539
|
|
|
540 @item a list
|
|
|
541 Each element of the list makes certain characters invisible.
|
|
|
542 Ultimately, a character is invisible if any of the elements of this list
|
|
|
543 applies to it. The list can have two kinds of elements:
|
|
|
544
|
|
|
545 @table @code
|
|
|
546 @item @var{atom}
|
|
|
547 A character is invisible if its @code{invisible} property value
|
|
|
548 is @var{atom} or if it is a list with @var{atom} as a member.
|
|
|
549
|
|
|
550 @item (@var{atom} . t)
|
|
|
551 A character is invisible if its @code{invisible} property value
|
|
|
552 is @var{atom} or if it is a list with @var{atom} as a member.
|
|
|
553 Moreover, if this character is at the end of a line and is followed
|
|
|
554 by a visible newline, it displays an ellipsis.
|
|
|
555 @end table
|
|
|
556 @end table
|
|
|
557 @end defvar
|
|
|
558
|
|
|
559 Ordinarily, commands that operate on text or move point do not care
|
|
|
560 whether the text is invisible. However, the user-level line motion
|
|
1620
|
561 commands explicitly ignore invisible newlines. Since this causes a
|
|
|
562 slow-down of these commands it is turned off by default, controlled by
|
|
|
563 the variable @code{line-move-ignore-invisible}.
|
|
428
|
564
|
|
|
565 @node Selective Display
|
|
|
566 @section Selective Display
|
|
|
567 @cindex selective display
|
|
|
568
|
|
|
569 @dfn{Selective display} is a pair of features that hide certain
|
|
|
570 lines on the screen.
|
|
|
571
|
|
|
572 The first variant, explicit selective display, is designed for use in
|
|
|
573 a Lisp program. The program controls which lines are hidden by altering
|
|
|
574 the text. Outline mode has traditionally used this variant. It has
|
|
|
575 been partially replaced by the invisible text feature (@pxref{Invisible
|
|
|
576 Text}); there is a new version of Outline mode which uses that instead.
|
|
|
577
|
|
|
578 In the second variant, the choice of lines to hide is made
|
|
|
579 automatically based on indentation. This variant is designed to be a
|
|
|
580 user-level feature.
|
|
|
581
|
|
|
582 The way you control explicit selective display is by replacing a
|
|
|
583 newline (control-j) with a carriage return (control-m). The text that
|
|
|
584 was formerly a line following that newline is now invisible. Strictly
|
|
|
585 speaking, it is temporarily no longer a line at all, since only newlines
|
|
|
586 can separate lines; it is now part of the previous line.
|
|
|
587
|
|
|
588 Selective display does not directly affect editing commands. For
|
|
|
589 example, @kbd{C-f} (@code{forward-char}) moves point unhesitatingly into
|
|
|
590 invisible text. However, the replacement of newline characters with
|
|
|
591 carriage return characters affects some editing commands. For example,
|
|
|
592 @code{next-line} skips invisible lines, since it searches only for
|
|
|
593 newlines. Modes that use selective display can also define commands
|
|
|
594 that take account of the newlines, or that make parts of the text
|
|
|
595 visible or invisible.
|
|
|
596
|
|
|
597 When you write a selectively displayed buffer into a file, all the
|
|
|
598 control-m's are output as newlines. This means that when you next read
|
|
|
599 in the file, it looks OK, with nothing invisible. The selective display
|
|
|
600 effect is seen only within XEmacs.
|
|
|
601
|
|
|
602 @defvar selective-display
|
|
|
603 This buffer-local variable enables selective display. This means that
|
|
444
|
604 lines, or portions of lines, may be made invisible.
|
|
428
|
605
|
|
|
606 @itemize @bullet
|
|
|
607 @item
|
|
|
608 If the value of @code{selective-display} is @code{t}, then any portion
|
|
|
609 of a line that follows a control-m is not displayed.
|
|
|
610
|
|
|
611 @item
|
|
|
612 If the value of @code{selective-display} is a positive integer, then
|
|
|
613 lines that start with more than that many columns of indentation are not
|
|
|
614 displayed.
|
|
|
615 @end itemize
|
|
|
616
|
|
|
617 When some portion of a buffer is invisible, the vertical movement
|
|
|
618 commands operate as if that portion did not exist, allowing a single
|
|
|
619 @code{next-line} command to skip any number of invisible lines.
|
|
|
620 However, character movement commands (such as @code{forward-char}) do
|
|
|
621 not skip the invisible portion, and it is possible (if tricky) to insert
|
|
|
622 or delete text in an invisible portion.
|
|
|
623
|
|
|
624 In the examples below, we show the @emph{display appearance} of the
|
|
|
625 buffer @code{foo}, which changes with the value of
|
|
|
626 @code{selective-display}. The @emph{contents} of the buffer do not
|
|
|
627 change.
|
|
|
628
|
|
|
629 @example
|
|
|
630 @group
|
|
|
631 (setq selective-display nil)
|
|
|
632 @result{} nil
|
|
|
633
|
|
|
634 ---------- Buffer: foo ----------
|
|
|
635 1 on this column
|
|
|
636 2on this column
|
|
|
637 3n this column
|
|
|
638 3n this column
|
|
|
639 2on this column
|
|
|
640 1 on this column
|
|
|
641 ---------- Buffer: foo ----------
|
|
|
642 @end group
|
|
|
643
|
|
|
644 @group
|
|
|
645 (setq selective-display 2)
|
|
|
646 @result{} 2
|
|
|
647
|
|
|
648 ---------- Buffer: foo ----------
|
|
|
649 1 on this column
|
|
|
650 2on this column
|
|
|
651 2on this column
|
|
|
652 1 on this column
|
|
|
653 ---------- Buffer: foo ----------
|
|
|
654 @end group
|
|
|
655 @end example
|
|
|
656 @end defvar
|
|
|
657
|
|
|
658 @defvar selective-display-ellipses
|
|
|
659 If this buffer-local variable is non-@code{nil}, then XEmacs displays
|
|
|
660 @samp{@dots{}} at the end of a line that is followed by invisible text.
|
|
|
661 This example is a continuation of the previous one.
|
|
|
662
|
|
|
663 @example
|
|
|
664 @group
|
|
|
665 (setq selective-display-ellipses t)
|
|
|
666 @result{} t
|
|
|
667
|
|
|
668 ---------- Buffer: foo ----------
|
|
|
669 1 on this column
|
|
|
670 2on this column ...
|
|
|
671 2on this column
|
|
|
672 1 on this column
|
|
|
673 ---------- Buffer: foo ----------
|
|
|
674 @end group
|
|
|
675 @end example
|
|
|
676
|
|
|
677 You can use a display table to substitute other text for the ellipsis
|
|
|
678 (@samp{@dots{}}). @xref{Display Tables}.
|
|
|
679 @end defvar
|
|
|
680
|
|
|
681 @node Overlay Arrow
|
|
|
682 @section The Overlay Arrow
|
|
|
683 @cindex overlay arrow
|
|
|
684
|
|
|
685 The @dfn{overlay arrow} is useful for directing the user's attention
|
|
|
686 to a particular line in a buffer. For example, in the modes used for
|
|
|
687 interface to debuggers, the overlay arrow indicates the line of code
|
|
|
688 about to be executed.
|
|
|
689
|
|
|
690 @defvar overlay-arrow-string
|
|
|
691 This variable holds the string to display to call attention to a
|
|
|
692 particular line, or @code{nil} if the arrow feature is not in use.
|
|
|
693 Despite its name, the value of this variable can be either a string
|
|
|
694 or a glyph (@pxref{Glyphs}).
|
|
|
695 @end defvar
|
|
|
696
|
|
|
697 @defvar overlay-arrow-position
|
|
|
698 This variable holds a marker that indicates where to display the overlay
|
|
|
699 arrow. It should point at the beginning of a line. The arrow text
|
|
|
700 appears at the beginning of that line, overlaying any text that would
|
|
|
701 otherwise appear. Since the arrow is usually short, and the line
|
|
|
702 usually begins with indentation, normally nothing significant is
|
|
|
703 overwritten.
|
|
|
704
|
|
|
705 The overlay string is displayed only in the buffer that this marker
|
|
|
706 points into. Thus, only one buffer can have an overlay arrow at any
|
|
|
707 given time.
|
|
|
708 @c !!! overlay-arrow-position: but the overlay string may remain in the display
|
|
|
709 @c of some other buffer until an update is required. This should be fixed
|
|
|
710 @c now. Is it?
|
|
|
711 @end defvar
|
|
|
712
|
|
|
713 You can do the same job by creating an extent with a
|
|
|
714 @code{begin-glyph} property. @xref{Extent Properties}.
|
|
|
715
|
|
|
716 @node Temporary Displays
|
|
|
717 @section Temporary Displays
|
|
|
718
|
|
|
719 Temporary displays are used by commands to put output into a buffer
|
|
|
720 and then present it to the user for perusal rather than for editing.
|
|
|
721 Many of the help commands use this feature.
|
|
|
722
|
|
|
723 @defspec with-output-to-temp-buffer buffer-name forms@dots{}
|
|
|
724 This function executes @var{forms} while arranging to insert any
|
|
|
725 output they print into the buffer named @var{buffer-name}. The buffer
|
|
|
726 is then shown in some window for viewing, displayed but not selected.
|
|
|
727
|
|
|
728 The string @var{buffer-name} specifies the temporary buffer, which
|
|
|
729 need not already exist. The argument must be a string, not a buffer.
|
|
|
730 The buffer is erased initially (with no questions asked), and it is
|
|
|
731 marked as unmodified after @code{with-output-to-temp-buffer} exits.
|
|
|
732
|
|
|
733 @code{with-output-to-temp-buffer} binds @code{standard-output} to the
|
|
|
734 temporary buffer, then it evaluates the forms in @var{forms}. Output
|
|
|
735 using the Lisp output functions within @var{forms} goes by default to
|
|
|
736 that buffer (but screen display and messages in the echo area, although
|
|
|
737 they are ``output'' in the general sense of the word, are not affected).
|
|
|
738 @xref{Output Functions}.
|
|
|
739
|
|
|
740 The value of the last form in @var{forms} is returned.
|
|
|
741
|
|
|
742 @example
|
|
|
743 @group
|
|
|
744 ---------- Buffer: foo ----------
|
|
|
745 This is the contents of foo.
|
|
|
746 ---------- Buffer: foo ----------
|
|
|
747 @end group
|
|
|
748
|
|
|
749 @group
|
|
|
750 (with-output-to-temp-buffer "foo"
|
|
|
751 (print 20)
|
|
|
752 (print standard-output))
|
|
|
753 @result{} #<buffer foo>
|
|
|
754
|
|
|
755 ---------- Buffer: foo ----------
|
|
|
756 20
|
|
|
757
|
|
|
758 #<buffer foo>
|
|
|
759
|
|
|
760 ---------- Buffer: foo ----------
|
|
|
761 @end group
|
|
|
762 @end example
|
|
|
763 @end defspec
|
|
|
764
|
|
|
765 @defvar temp-buffer-show-function
|
|
|
766 If this variable is non-@code{nil}, @code{with-output-to-temp-buffer}
|
|
|
767 calls it as a function to do the job of displaying a help buffer. The
|
|
|
768 function gets one argument, which is the buffer it should display.
|
|
|
769
|
|
|
770 In Emacs versions 18 and earlier, this variable was called
|
|
|
771 @code{temp-buffer-show-hook}.
|
|
|
772 @end defvar
|
|
|
773
|
|
|
774 @defun momentary-string-display string position &optional char message
|
|
|
775 This function momentarily displays @var{string} in the current buffer at
|
|
|
776 @var{position}. It has no effect on the undo list or on the buffer's
|
|
|
777 modification status.
|
|
|
778
|
|
|
779 The momentary display remains until the next input event. If the next
|
|
|
780 input event is @var{char}, @code{momentary-string-display} ignores it
|
|
|
781 and returns. Otherwise, that event remains buffered for subsequent use
|
|
|
782 as input. Thus, typing @var{char} will simply remove the string from
|
|
|
783 the display, while typing (say) @kbd{C-f} will remove the string from
|
|
|
784 the display and later (presumably) move point forward. The argument
|
|
|
785 @var{char} is a space by default.
|
|
|
786
|
|
|
787 The return value of @code{momentary-string-display} is not meaningful.
|
|
|
788
|
|
|
789 You can do the same job in a more general way by creating an extent
|
|
|
790 with a begin-glyph property. @xref{Extent Properties}.
|
|
|
791
|
|
|
792 If @var{message} is non-@code{nil}, it is displayed in the echo area
|
|
|
793 while @var{string} is displayed in the buffer. If it is @code{nil}, a
|
|
|
794 default message says to type @var{char} to continue.
|
|
|
795
|
|
|
796 In this example, point is initially located at the beginning of the
|
|
|
797 second line:
|
|
|
798
|
|
|
799 @example
|
|
|
800 @group
|
|
|
801 ---------- Buffer: foo ----------
|
|
|
802 This is the contents of foo.
|
|
|
803 @point{}Second line.
|
|
|
804 ---------- Buffer: foo ----------
|
|
|
805 @end group
|
|
|
806
|
|
|
807 @group
|
|
|
808 (momentary-string-display
|
|
|
809 "**** Important Message! ****"
|
|
|
810 (point) ?\r
|
|
|
811 "Type RET when done reading")
|
|
|
812 @result{} t
|
|
|
813 @end group
|
|
|
814
|
|
|
815 @group
|
|
|
816 ---------- Buffer: foo ----------
|
|
|
817 This is the contents of foo.
|
|
|
818 **** Important Message! ****Second line.
|
|
|
819 ---------- Buffer: foo ----------
|
|
|
820
|
|
|
821 ---------- Echo Area ----------
|
|
|
822 Type RET when done reading
|
|
|
823 ---------- Echo Area ----------
|
|
|
824 @end group
|
|
|
825 @end example
|
|
|
826
|
|
|
827 This function works by actually changing the text in the buffer. As a
|
|
|
828 result, if you later undo in this buffer, you will see the message come
|
|
|
829 and go.
|
|
|
830 @end defun
|
|
|
831
|
|
|
832 @node Blinking
|
|
|
833 @section Blinking Parentheses
|
|
|
834 @cindex parenthesis matching
|
|
|
835 @cindex blinking
|
|
|
836 @cindex balancing parentheses
|
|
|
837 @cindex close parenthesis
|
|
|
838
|
|
|
839 This section describes the mechanism by which XEmacs shows a matching
|
|
|
840 open parenthesis when the user inserts a close parenthesis.
|
|
|
841
|
|
|
842 @vindex blink-paren-hook
|
|
|
843 @defvar blink-paren-function
|
|
|
844 The value of this variable should be a function (of no arguments) to
|
|
|
845 be called whenever a character with close parenthesis syntax is inserted.
|
|
|
846 The value of @code{blink-paren-function} may be @code{nil}, in which
|
|
|
847 case nothing is done.
|
|
|
848
|
|
|
849 @quotation
|
|
|
850 @strong{Please note:} This variable was named @code{blink-paren-hook} in
|
|
|
851 older Emacs versions, but since it is not called with the standard
|
|
|
852 convention for hooks, it was renamed to @code{blink-paren-function} in
|
|
|
853 version 19.
|
|
|
854 @end quotation
|
|
|
855 @end defvar
|
|
|
856
|
|
|
857 @defvar blink-matching-paren
|
|
|
858 If this variable is @code{nil}, then @code{blink-matching-open} does
|
|
|
859 nothing.
|
|
|
860 @end defvar
|
|
|
861
|
|
|
862 @defvar blink-matching-paren-distance
|
|
|
863 This variable specifies the maximum distance to scan for a matching
|
|
|
864 parenthesis before giving up.
|
|
|
865 @end defvar
|
|
|
866
|
|
|
867 @defvar blink-matching-paren-delay
|
|
|
868 This variable specifies the number of seconds for the cursor to remain
|
|
|
869 at the matching parenthesis. A fraction of a second often gives
|
|
|
870 good results, but the default is 1, which works on all systems.
|
|
|
871 @end defvar
|
|
|
872
|
|
444
|
873 @deffn Command blink-matching-open
|
|
428
|
874 This function is the default value of @code{blink-paren-function}. It
|
|
|
875 assumes that point follows a character with close parenthesis syntax and
|
|
|
876 moves the cursor momentarily to the matching opening character. If that
|
|
|
877 character is not already on the screen, it displays the character's
|
|
|
878 context in the echo area. To avoid long delays, this function does not
|
|
|
879 search farther than @code{blink-matching-paren-distance} characters.
|
|
|
880
|
|
|
881 Here is an example of calling this function explicitly.
|
|
|
882
|
|
|
883 @smallexample
|
|
|
884 @group
|
|
|
885 (defun interactive-blink-matching-open ()
|
|
|
886 "Indicate momentarily the start of sexp before point."
|
|
|
887 (interactive)
|
|
|
888 @end group
|
|
|
889 @group
|
|
|
890 (let ((blink-matching-paren-distance
|
|
|
891 (buffer-size))
|
|
|
892 (blink-matching-paren t))
|
|
|
893 (blink-matching-open)))
|
|
|
894 @end group
|
|
|
895 @end smallexample
|
|
444
|
896 @end deffn
|
|
428
|
897
|
|
|
898 @node Usual Display
|
|
|
899 @section Usual Display Conventions
|
|
|
900
|
|
|
901 The usual display conventions define how to display each character
|
|
|
902 code. You can override these conventions by setting up a display table
|
|
|
903 (@pxref{Display Tables}). Here are the usual display conventions:
|
|
|
904
|
|
|
905 @itemize @bullet
|
|
|
906 @item
|
|
|
907 Character codes 32 through 126 map to glyph codes 32 through 126.
|
|
|
908 Normally this means they display as themselves.
|
|
|
909
|
|
|
910 @item
|
|
|
911 Character code 9 is a horizontal tab. It displays as whitespace
|
|
|
912 up to a position determined by @code{tab-width}.
|
|
|
913
|
|
|
914 @item
|
|
|
915 Character code 10 is a newline.
|
|
|
916
|
|
|
917 @item
|
|
|
918 All other codes in the range 0 through 31, and code 127, display in one
|
|
|
919 of two ways according to the value of @code{ctl-arrow}. If it is
|
|
|
920 non-@code{nil}, these codes map to sequences of two glyphs, where the
|
|
|
921 first glyph is the @sc{ascii} code for @samp{^}. (A display table can
|
|
|
922 specify a glyph to use instead of @samp{^}.) Otherwise, these codes map
|
|
|
923 just like the codes in the range 128 to 255.
|
|
|
924
|
|
|
925 @item
|
|
|
926 Character codes 128 through 255 map to sequences of four glyphs, where
|
|
|
927 the first glyph is the @sc{ascii} code for @samp{\}, and the others are
|
|
|
928 digit characters representing the code in octal. (A display table can
|
|
|
929 specify a glyph to use instead of @samp{\}.)
|
|
|
930 @end itemize
|
|
|
931
|
|
|
932 The usual display conventions apply even when there is a display
|
|
|
933 table, for any character whose entry in the active display table is
|
|
|
934 @code{nil}. Thus, when you set up a display table, you need only
|
|
|
935 specify the characters for which you want unusual behavior.
|
|
|
936
|
|
|
937 These variables affect the way certain characters are displayed on the
|
|
|
938 screen. Since they change the number of columns the characters occupy,
|
|
|
939 they also affect the indentation functions.
|
|
|
940
|
|
|
941 @defopt ctl-arrow
|
|
|
942 @cindex control characters in display
|
|
|
943 This buffer-local variable controls how control characters are
|
|
|
944 displayed. If it is non-@code{nil}, they are displayed as a caret
|
|
|
945 followed by the character: @samp{^A}. If it is @code{nil}, they are
|
|
|
946 displayed as a backslash followed by three octal digits: @samp{\001}.
|
|
|
947 @end defopt
|
|
|
948
|
|
|
949 @c Following may have overfull hbox.
|
|
|
950 @defvar default-ctl-arrow
|
|
|
951 The value of this variable is the default value for @code{ctl-arrow} in
|
|
|
952 buffers that do not override it. @xref{Default Value}.
|
|
|
953 @end defvar
|
|
|
954
|
|
|
955 @defopt tab-width
|
|
|
956 The value of this variable is the spacing between tab stops used for
|
|
|
957 displaying tab characters in Emacs buffers. The default is 8. Note
|
|
|
958 that this feature is completely independent from the user-settable tab
|
|
|
959 stops used by the command @code{tab-to-tab-stop}. @xref{Indent Tabs}.
|
|
|
960 @end defopt
|
|
|
961
|
|
|
962 @node Display Tables
|
|
|
963 @section Display Tables
|
|
|
964
|
|
|
965 @cindex display table
|
|
|
966 You can use the @dfn{display table} feature to control how all 256
|
|
|
967 possible character codes display on the screen. This is useful for
|
|
|
968 displaying European languages that have letters not in the @sc{ascii}
|
|
|
969 character set.
|
|
|
970
|
|
|
971 The display table maps each character code into a sequence of
|
|
|
972 @dfn{runes}, each rune being an image that takes up one character
|
|
|
973 position on the screen. You can also define how to display each rune
|
|
|
974 on your terminal, using the @dfn{rune table}.
|
|
|
975
|
|
|
976 @menu
|
|
|
977 * Display Table Format:: What a display table consists of.
|
|
|
978 * Active Display Table:: How XEmacs selects a display table to use.
|
|
|
979 * Character Descriptors:: Format of an individual element of a
|
|
|
980 display table.
|
|
|
981 @end menu
|
|
|
982
|
|
|
983 @ignore Not yet working in XEmacs?
|
|
|
984 * ISO Latin 1:: How to use display tables
|
|
|
985 to support the ISO Latin 1 character set.
|
|
|
986 @end ignore
|
|
|
987
|
|
|
988 @node Display Table Format
|
|
|
989 @subsection Display Table Format
|
|
|
990
|
|
|
991 A display table is an array of 256 elements. (In FSF Emacs, a display
|
|
|
992 table is 262 elements. The six extra elements specify the truncation
|
|
|
993 and continuation glyphs, etc. This method is very kludgey, and in
|
|
|
994 XEmacs the variables @code{truncation-glyph}, @code{continuation-glyph},
|
|
|
995 etc. are used. @xref{Truncation}.)
|
|
|
996
|
|
|
997 @defun make-display-table
|
|
|
998 This creates and returns a display table. The table initially has
|
|
|
999 @code{nil} in all elements.
|
|
|
1000 @end defun
|
|
|
1001
|
|
|
1002 The 256 elements correspond to character codes; the @var{n}th
|
|
|
1003 element says how to display the character code @var{n}. The value
|
|
|
1004 should be @code{nil}, a string, a glyph, or a vector of strings and
|
|
|
1005 glyphs (@pxref{Character Descriptors}). If an element is @code{nil},
|
|
|
1006 it says to display that character according to the usual display
|
|
|
1007 conventions (@pxref{Usual Display}).
|
|
|
1008
|
|
|
1009 If you use the display table to change the display of newline
|
|
|
1010 characters, the whole buffer will be displayed as one long ``line.''
|
|
|
1011
|
|
|
1012 For example, here is how to construct a display table that mimics the
|
|
|
1013 effect of setting @code{ctl-arrow} to a non-@code{nil} value:
|
|
|
1014
|
|
|
1015 @example
|
|
|
1016 (setq disptab (make-display-table))
|
|
|
1017 (let ((i 0))
|
|
|
1018 (while (< i 32)
|
|
|
1019 (or (= i ?\t) (= i ?\n)
|
|
|
1020 (aset disptab i (concat "^" (char-to-string (+ i 64)))))
|
|
|
1021 (setq i (1+ i)))
|
|
|
1022 (aset disptab 127 "^?"))
|
|
|
1023 @end example
|
|
|
1024
|
|
|
1025 @node Active Display Table
|
|
|
1026 @subsection Active Display Table
|
|
|
1027 @cindex active display table
|
|
|
1028
|
|
|
1029 The active display table is controlled by the variable
|
|
|
1030 @code{current-display-table}. This is a specifier, which means
|
|
|
1031 that you can specify separate values for it in individual buffers,
|
|
|
1032 windows, frames, and devices, as well as a global value. It also
|
|
|
1033 means that you cannot set this variable using @code{setq}; use
|
|
|
1034 @code{set-specifier} instead. @xref{Specifiers}. (FSF Emacs
|
|
|
1035 uses @code{window-display-table}, @code{buffer-display-table},
|
|
|
1036 @code{standard-display-table}, etc. to control the display table.
|
|
|
1037 However, specifiers are a cleaner and more powerful way of doing
|
|
|
1038 the same thing. FSF Emacs also uses a different format for
|
|
|
1039 the contents of a display table, using additional indirection
|
|
|
1040 to a ``glyph table'' and such. Note that ``glyph'' has a different
|
|
|
1041 meaning in XEmacs.)
|
|
|
1042
|
|
442
|
1043 @defvar current-display-table
|
|
|
1044
|
|
|
1045 The display table currently in use. This is a specifier.
|
|
|
1046
|
|
|
1047 Display tables are used to control how characters are displayed. Each
|
|
|
1048 time that redisplay processes a character, it is looked up in all the
|
|
|
1049 display tables that apply (obtained by calling @code{specifier-instance}
|
|
|
1050 on @code{current-display-table} and any overriding display tables
|
|
|
1051 specified in currently active faces). The first entry found that
|
|
|
1052 matches the character determines how the character is displayed. If
|
|
|
1053 there is no matching entry, the default display method is
|
|
|
1054 used. (Non-control characters are displayed as themselves and control
|
|
|
1055 characters are displayed according to the buffer-local variable
|
|
|
1056 @code{ctl-arrow}. Control characters are further affected by
|
|
|
1057 @code{control-arrow-glyph} and @code{octal-escape-glyph}.)
|
|
|
1058
|
|
|
1059 Each instantiator in this specifier and the display-table specifiers
|
|
|
1060 in faces is a display table or a list of such tables. If a list, each
|
|
|
1061 table will be searched in turn for an entry matching a particular
|
|
|
1062 character. Each display table is one of
|
|
|
1063
|
|
|
1064 @itemize @bullet
|
|
|
1065 @item
|
|
|
1066 A vector, specifying values for characters starting at 0.
|
|
|
1067 @item
|
|
|
1068 A char table, either of type @code{char} or @code{generic}.
|
|
|
1069 @item
|
|
|
1070 A range table.
|
|
|
1071 @end itemize
|
|
|
1072
|
|
|
1073 Each entry in a display table should be one of
|
|
|
1074
|
|
|
1075 @itemize @bullet
|
|
|
1076 @item
|
|
|
1077 nil (this entry is ignored and the search continues).
|
|
|
1078 @item
|
|
|
1079 A character (use this character; if it happens to be the same as
|
|
|
1080 the original character, default processing happens, otherwise
|
|
|
1081 redisplay attempts to display this character directly;
|
|
|
1082 #### At some point recursive display-table lookup will be
|
|
|
1083 implemented).
|
|
|
1084 @item
|
|
|
1085 A string (display each character in the string directly;
|
|
|
1086 #### At some point recursive display-table lookup will be
|
|
|
1087 implemented).
|
|
|
1088 @item
|
|
|
1089 A glyph (display the glyph;
|
|
|
1090 #### At some point recursive display-table lookup will be
|
|
|
1091 implemented when a string glyph is being processed).
|
|
|
1092 @item
|
|
|
1093 A cons of the form (format "@var{string}") where @var{string} is a
|
|
|
1094 printf-like spec used to process the character. #### Unfortunately no
|
|
|
1095 formatting directives other than %% are implemented.
|
|
|
1096 @item
|
|
|
1097 A vector (each element of the vector is processed recursively;
|
|
|
1098 in such a case, nil elements in the vector are simply ignored).
|
|
|
1099
|
|
|
1100 #### At some point in the near future, display tables are likely to
|
|
|
1101 be expanded to include other features, such as referencing characters
|
|
|
1102 in particular fonts and allowing the character search to continue
|
|
|
1103 all the way up the chain of specifier instantiators. These features
|
|
|
1104 are necessary to properly display Unicode characters.
|
|
|
1105 @end itemize
|
|
|
1106 @end defvar
|
|
|
1107
|
|
428
|
1108 Individual faces can also specify an overriding display table;
|
|
|
1109 this is set using @code{set-face-display-table}. @xref{Faces}.
|
|
|
1110
|
|
|
1111 If no display table can be determined for a particular window,
|
|
|
1112 then XEmacs uses the usual display conventions. @xref{Usual Display}.
|
|
|
1113
|
|
|
1114 @node Character Descriptors
|
|
|
1115 @subsection Character Descriptors
|
|
|
1116
|
|
|
1117 @cindex character descriptor
|
|
|
1118 Each element of the display-table vector describes how to display
|
|
|
1119 a particular character and is called a @dfn{character descriptor}.
|
|
|
1120 A character descriptor can be:
|
|
|
1121
|
|
|
1122 @table @asis
|
|
|
1123 @item a string
|
|
|
1124 Display this particular string wherever the character is to be displayed.
|
|
|
1125
|
|
|
1126 @item a glyph
|
|
|
1127 Display this particular glyph wherever the character is to be displayed.
|
|
|
1128
|
|
|
1129 @item a vector
|
|
|
1130 The vector may contain strings and/or glyphs. Display the elements of
|
|
|
1131 the vector one after another wherever the character is to be displayed.
|
|
|
1132
|
|
|
1133 @item @code{nil}
|
|
|
1134 Display according to the standard interpretation (@pxref{Usual Display}).
|
|
|
1135 @end table
|
|
|
1136
|
|
|
1137 @ignore Not yet working in XEmacs?
|
|
|
1138 @node ISO Latin 1
|
|
|
1139 @subsection ISO Latin 1
|
|
|
1140
|
|
|
1141 If you have a terminal that can handle the entire ISO Latin 1 character
|
|
|
1142 set, you can arrange to use that character set as follows:
|
|
|
1143
|
|
|
1144 @example
|
|
|
1145 (require 'disp-table)
|
|
|
1146 ;; @r{Set char codes 160--255 to display as themselves.}
|
|
|
1147 ;; @r{(Codes 128--159 are the additional control characters.)}
|
|
|
1148 (standard-display-8bit 160 255)
|
|
|
1149 @end example
|
|
|
1150
|
|
|
1151 If you are editing buffers written in the ISO Latin 1 character set and
|
|
|
1152 your terminal doesn't handle anything but @sc{ascii}, you can load the
|
|
|
1153 file @file{iso-ascii} to set up a display table that displays the other
|
|
|
1154 ISO characters as explanatory sequences of @sc{ascii} characters. For
|
|
|
1155 example, the character ``o with umlaut'' displays as @samp{@{"o@}}.
|
|
|
1156
|
|
|
1157 Some European countries have terminals that don't support ISO Latin 1
|
|
|
1158 but do support the special characters for that country's language. You
|
|
|
1159 can define a display table to work one language using such terminals.
|
|
|
1160 For an example, see @file{lisp/iso-swed.el}, which handles certain
|
|
|
1161 Swedish terminals.
|
|
|
1162
|
|
|
1163 You can load the appropriate display table for your terminal
|
|
|
1164 automatically by writing a terminal-specific Lisp file for the terminal
|
|
|
1165 type.
|
|
|
1166 @end ignore
|
|
|
1167
|
|
|
1168 @node Beeping
|
|
|
1169 @section Beeping
|
|
|
1170 @cindex beeping
|
|
|
1171 @cindex bell
|
|
|
1172 @cindex sound
|
|
|
1173
|
|
|
1174 You can make XEmacs ring a bell, play a sound, or blink the screen to
|
|
|
1175 attract the user's attention. Be conservative about how often you do
|
|
|
1176 this; frequent bells can become irritating. Also be careful not to use
|
|
|
1177 beeping alone when signaling an error is appropriate. (@xref{Errors}.)
|
|
|
1178
|
|
|
1179 @defun ding &optional dont-terminate sound device
|
|
|
1180 @cindex keyboard macro termination
|
|
|
1181 This function beeps, or flashes the screen (see @code{visible-bell}
|
|
|
1182 below). It also terminates any keyboard macro currently executing
|
|
|
1183 unless @var{dont-terminate} is non-@code{nil}. If @var{sound} is
|
|
|
1184 specified, it should be a symbol specifying which sound to make. This
|
|
|
1185 sound will be played if @code{visible-bell} is @code{nil}. (This only
|
|
|
1186 works if sound support was compiled into the executable and you are
|
|
|
1187 running on the console of a Sun SparcStation, SGI, HP9000s700, or Linux
|
|
|
1188 PC. Otherwise you just get a beep.) The optional third argument
|
|
|
1189 specifies what device to make the sound on, and defaults to the selected
|
|
|
1190 device.
|
|
|
1191 @end defun
|
|
|
1192
|
|
|
1193 @defun beep &optional dont-terminate sound device
|
|
|
1194 This is a synonym for @code{ding}.
|
|
|
1195 @end defun
|
|
|
1196
|
|
|
1197 @defopt visible-bell
|
|
|
1198 This variable determines whether XEmacs should flash the screen to
|
|
|
1199 represent a bell. Non-@code{nil} means yes, @code{nil} means no. On
|
|
|
1200 TTY devices, this is effective only if the Termcap entry for the
|
|
|
1201 terminal type has the visible bell flag (@samp{vb}) set.
|
|
|
1202 @end defopt
|
|
|
1203
|
|
|
1204 @defvar sound-alist
|
|
|
1205 This variable holds an alist associating names with sounds. When
|
|
|
1206 @code{beep} or @code{ding} is called with one of the name symbols, the
|
|
|
1207 associated sound will be generated instead of the standard beep.
|
|
|
1208
|
|
|
1209 Each element of @code{sound-alist} is a list describing a sound. The
|
|
|
1210 first element of the list is the name of the sound being defined.
|
|
|
1211 Subsequent elements of the list are alternating keyword/value pairs:
|
|
|
1212
|
|
|
1213 @table @code
|
|
|
1214 @item sound
|
|
|
1215 A string of raw sound data, or the name of another sound to play. The
|
|
|
1216 symbol @code{t} here means use the default X beep.
|
|
|
1217 @item volume
|
|
|
1218 An integer from 0-100, defaulting to @code{bell-volume}.
|
|
|
1219 @item pitch
|
|
|
1220 If using the default X beep, the pitch (Hz) to generate.
|
|
|
1221 @item duration
|
|
|
1222 If using the default X beep, the duration (milliseconds).
|
|
|
1223 @end table
|
|
|
1224
|
|
|
1225 For compatibility, elements of `sound-alist' may also be:
|
|
|
1226
|
|
|
1227 @itemize @bullet
|
|
|
1228 @item
|
|
|
1229 @code{( sound-name . <sound> )}
|
|
|
1230 @item
|
|
|
1231 @code{( sound-name <volume> <sound> )}
|
|
|
1232 @end itemize
|
|
|
1233
|
|
|
1234 You should probably add things to this list by calling the function
|
|
|
1235 @code{load-sound-file}.
|
|
|
1236
|
|
|
1237 Caveats:
|
|
|
1238
|
|
|
1239 @itemize @minus
|
|
|
1240 @item
|
|
|
1241 You can only play audio data if running on the console screen of a Sun
|
|
|
1242 SparcStation, SGI, or HP9000s700.
|
|
|
1243
|
|
|
1244 @item
|
|
|
1245 The pitch, duration, and volume options are available everywhere, but
|
|
|
1246 many X servers ignore the `pitch' option.
|
|
|
1247 @end itemize
|
|
|
1248
|
|
|
1249 The following beep-types are used by XEmacs itself:
|
|
|
1250
|
|
|
1251 @table @code
|
|
|
1252 @item auto-save-error
|
|
|
1253 when an auto-save does not succeed
|
|
|
1254 @item command-error
|
|
|
1255 when the XEmacs command loop catches an error
|
|
|
1256 @item undefined-key
|
|
|
1257 when you type a key that is undefined
|
|
|
1258 @item undefined-click
|
|
|
1259 when you use an undefined mouse-click combination
|
|
|
1260 @item no-completion
|
|
|
1261 during completing-read
|
|
|
1262 @item y-or-n-p
|
|
|
1263 when you type something other than 'y' or 'n'
|
|
|
1264 @item yes-or-no-p
|
|
|
1265 when you type something other than 'yes' or 'no'
|
|
|
1266 @item default
|
|
|
1267 used when nothing else is appropriate.
|
|
|
1268 @end table
|
|
|
1269
|
|
|
1270 Other lisp packages may use other beep types, but these are the ones that
|
|
|
1271 the C kernel of XEmacs uses.
|
|
|
1272 @end defvar
|
|
|
1273
|
|
|
1274 @defopt bell-volume
|
|
|
1275 This variable specifies the default volume for sounds, from 0 to 100.
|
|
|
1276 @end defopt
|
|
|
1277
|
|
|
1278 @deffn Command load-default-sounds
|
|
|
1279 This function loads and installs some sound files as beep-types.
|
|
|
1280 @end deffn
|
|
|
1281
|
|
|
1282 @deffn Command load-sound-file filename sound-name &optional volume
|
|
|
1283 This function reads in an audio file and adds it to @code{sound-alist}.
|
|
|
1284 The sound file must be in the Sun/NeXT U-LAW format. @var{sound-name}
|
|
|
1285 should be a symbol, specifying the name of the sound. If @var{volume}
|
|
|
1286 is specified, the sound will be played at that volume; otherwise, the
|
|
1738
|
1287 value of @code{bell-volume} will be used.
|
|
428
|
1288 @end deffn
|
|
|
1289
|
|
|
1290 @defun play-sound sound &optional volume device
|
|
|
1291 This function plays sound @var{sound}, which should be a symbol
|
|
|
1292 mentioned in @code{sound-alist}. If @var{volume} is specified, it
|
|
|
1293 overrides the value (if any) specified in @code{sound-alist}.
|
|
|
1294 @var{device} specifies the device to play the sound on, and defaults
|
|
|
1295 to the selected device.
|
|
|
1296 @end defun
|
|
|
1297
|
|
|
1298 @deffn Command play-sound-file file &optional volume device
|
|
|
1299 This function plays the named sound file at volume @var{volume}, which
|
|
|
1300 defaults to @code{bell-volume}. @var{device} specifies the device to
|
|
|
1301 play the sound on, and defaults to the selected device.
|
|
|
1302 @end deffn
|
