Mercurial > hg > xemacs-beta
annotate man/lispref/display.texi @ 5610:d69ea1ff4ce3
Add the zero, *then* flush, when reading integers for the #N=... syntax.
src/ChangeLog addition:
2011-12-10 Aidan Kehoe <kehoea@parhasard.net>
* lread.c (read1): Add the zero, *then* flush, when reading an
integer into Vread_buffer_stream.
| author | Aidan Kehoe <kehoea@parhasard.net> |
|---|---|
| date | Sat, 10 Dec 2011 16:17:49 +0000 |
| parents | 62b9ef1ed4ac |
| children | 9fae6227ede5 |
| rev | line source |
|---|---|
| 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 | |
|
5361
62b9ef1ed4ac
Change "special form" to "special operator" in the manuals, too
Aidan Kehoe <kehoea@parhasard.net>
parents:
1738
diff
changeset
|
723 @deffn {Special Operator} with-output-to-temp-buffer buffer-name forms@dots{} |
| 428 | 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 | |
|
5361
62b9ef1ed4ac
Change "special form" to "special operator" in the manuals, too
Aidan Kehoe <kehoea@parhasard.net>
parents:
1738
diff
changeset
|
763 @end deffn |
| 428 | 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 |