Mercurial > hg > xemacs-beta
annotate man/lispref/display.texi @ 5753:dbd8305e13cb
Warn about non-string non-integer ARG to #'gensym, bytecomp.el.
lisp/ChangeLog addition:
2013-08-21 Aidan Kehoe <kehoea@parhasard.net>
* bytecomp.el:
* bytecomp.el (gensym):
* bytecomp.el (byte-compile-gensym): New.
Warn that gensym called in a for-effect context is unlikely to be
useful.
Warn about non-string non-integer ARGs, this is incorrect.
Am not changing the function to error with same, most code that
makes the mistake is has no problems, which is why it has survived
so long.
* window-xemacs.el (save-window-excursion/mapping):
* window.el (save-window-excursion):
Call #'gensym with a string, not a symbol.
| author | Aidan Kehoe <kehoea@parhasard.net> |
|---|---|
| date | Wed, 21 Aug 2013 19:02:59 +0100 |
| 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 |