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
