Mercurial > emacs
comparison lispref/display.texi @ 63957:8bd575c72fe0
(Displaying Messages): New node, with most of what was in The Echo Area.
(Progress): Moved under The Echo Area.
(Logging Messages): New node with new text.
(Echo Area Customization): New node, the rest of what was
in The Echo Area. Document message-truncate-lines with @defvar.
(Display): Update menu.
author | Richard M. Stallman <rms@gnu.org> |
---|---|
date | Sun, 03 Jul 2005 19:05:09 +0000 |
parents | a750e72f48e7 |
children | bbc8b6b4962d |
comparison
equal
deleted
inserted
replaced
63956:c08c89b91e11 | 63957:8bd575c72fe0 |
---|---|
12 | 12 |
13 @menu | 13 @menu |
14 * Refresh Screen:: Clearing the screen and redrawing everything on it. | 14 * Refresh Screen:: Clearing the screen and redrawing everything on it. |
15 * Forcing Redisplay:: Forcing redisplay. | 15 * Forcing Redisplay:: Forcing redisplay. |
16 * Truncation:: Folding or wrapping long text lines. | 16 * Truncation:: Folding or wrapping long text lines. |
17 * The Echo Area:: Where messages are displayed. | 17 * The Echo Area:: Displaying messages at the bottom of the screen. |
18 * Warnings:: Displaying warning messages for the user. | 18 * Warnings:: Displaying warning messages for the user. |
19 * Progress:: Informing user about progress of a long operation. | |
20 * Invisible Text:: Hiding part of the buffer text. | 19 * Invisible Text:: Hiding part of the buffer text. |
21 * Selective Display:: Hiding part of the buffer text (the old way). | 20 * Selective Display:: Hiding part of the buffer text (the old way). |
22 * Temporary Displays:: Displays that go away automatically. | 21 * Temporary Displays:: Displays that go away automatically. |
23 * Overlays:: Use overlays to highlight parts of the buffer. | 22 * Overlays:: Use overlays to highlight parts of the buffer. |
24 * Width:: How wide a character or string is on the screen. | 23 * Width:: How wide a character or string is on the screen. |
182 @node The Echo Area | 181 @node The Echo Area |
183 @section The Echo Area | 182 @section The Echo Area |
184 @cindex error display | 183 @cindex error display |
185 @cindex echo area | 184 @cindex echo area |
186 | 185 |
187 The @dfn{echo area} is used for displaying error messages | 186 The @dfn{echo area} is used for displaying error messages |
188 (@pxref{Errors}), for messages made with the @code{message} primitive, | 187 (@pxref{Errors}), for messages made with the @code{message} primitive, |
189 and for echoing keystrokes. It is not the same as the minibuffer, | 188 and for echoing keystrokes. It is not the same as the minibuffer, |
190 despite the fact that the minibuffer appears (when active) in the same | 189 despite the fact that the minibuffer appears (when active) in the same |
191 place on the screen as the echo area. The @cite{GNU Emacs Manual} | 190 place on the screen as the echo area. The @cite{GNU Emacs Manual} |
192 specifies the rules for resolving conflicts between the echo area and | 191 specifies the rules for resolving conflicts between the echo area and |
193 the minibuffer for use of that screen space (@pxref{Minibuffer,, The | 192 the minibuffer for use of that screen space (@pxref{Minibuffer,, The |
194 Minibuffer, emacs, The GNU Emacs Manual}). | 193 Minibuffer, emacs, The GNU Emacs Manual}). |
195 | 194 |
196 You can write output in the echo area by using the Lisp printing | 195 You can write output in the echo area by using the Lisp printing |
197 functions with @code{t} as the stream (@pxref{Output Functions}), or as | 196 functions with @code{t} as the stream (@pxref{Output Functions}), or |
198 follows: | 197 explicitly. |
198 | |
199 @menu | |
200 * Displaying Messages:: Explicitly displaying text in the echo area. | |
201 * Progress Reports:: Informing user about progress of a long operation. | |
202 * Logging Messages:: Echo area messages are logged for the user. | |
203 * Echo Area Customization:: Controlling the echo area. | |
204 @end menu | |
205 | |
206 @node Displaying Messages | |
207 @subsection Displaying Messages in the Echo Area | |
208 | |
209 This section describes the functions for explicitly producing echo | |
210 area messages. Many other Emacs features display messages there, too. | |
199 | 211 |
200 @defun message string &rest arguments | 212 @defun message string &rest arguments |
201 This function displays a message in the echo area. The | 213 This function displays a message in the echo area. The |
202 argument @var{string} is similar to a C language @code{printf} control | 214 argument @var{string} is similar to a C language @code{printf} control |
203 string. See @code{format} in @ref{Formatting Strings}, for the details | 215 string. See @code{format} in @ref{Formatting Strings}, for the details |
213 @c Emacs 19 feature | 225 @c Emacs 19 feature |
214 If @var{string} is @code{nil}, @code{message} clears the echo area; if | 226 If @var{string} is @code{nil}, @code{message} clears the echo area; if |
215 the echo area has been expanded automatically, this brings it back to | 227 the echo area has been expanded automatically, this brings it back to |
216 its normal size. If the minibuffer is active, this brings the | 228 its normal size. If the minibuffer is active, this brings the |
217 minibuffer contents back onto the screen immediately. | 229 minibuffer contents back onto the screen immediately. |
218 | |
219 @vindex message-truncate-lines | |
220 Normally, displaying a long message resizes the echo area to display | |
221 the entire message. But if the variable @code{message-truncate-lines} | |
222 is non-@code{nil}, the echo area does not resize, and the message is | |
223 truncated to fit it, as in Emacs 20 and before. | |
224 | 230 |
225 @example | 231 @example |
226 @group | 232 @group |
227 (message "Minibuffer depth is %d." | 233 (message "Minibuffer depth is %d." |
228 (minibuffer-depth)) | 234 (minibuffer-depth)) |
238 @end example | 244 @end example |
239 | 245 |
240 To automatically display a message in the echo area or in a pop-buffer, | 246 To automatically display a message in the echo area or in a pop-buffer, |
241 depending on its size, use @code{display-message-or-buffer} (see below). | 247 depending on its size, use @code{display-message-or-buffer} (see below). |
242 @end defun | 248 @end defun |
243 | |
244 @defopt max-mini-window-height | |
245 This variable specifies the maximum height for resizing minibuffer | |
246 windows. If a float, it specifies a fraction of the height of the | |
247 frame. If an integer, it specifies a number of lines. | |
248 @end defopt | |
249 | 249 |
250 @tindex with-temp-message | 250 @tindex with-temp-message |
251 @defmac with-temp-message message &rest body | 251 @defmac with-temp-message message &rest body |
252 This construct displays a message in the echo area temporarily, during | 252 This construct displays a message in the echo area temporarily, during |
253 the execution of @var{body}. It displays @var{message}, executes | 253 the execution of @var{body}. It displays @var{message}, executes |
301 @defun current-message | 301 @defun current-message |
302 This function returns the message currently being displayed in the | 302 This function returns the message currently being displayed in the |
303 echo area, or @code{nil} if there is none. | 303 echo area, or @code{nil} if there is none. |
304 @end defun | 304 @end defun |
305 | 305 |
306 @node Progress | |
307 @subsection Reporting Operation Progress | |
308 @cindex progress reporting | |
309 | |
310 When an operation can take a while to finish, you should inform the | |
311 user about the progress it makes. This way the user can estimate | |
312 remaining time and clearly see that Emacs is busy working, not hung. | |
313 | |
314 Functions listed in this section provide simple and efficient way of | |
315 reporting operation progress. Here is a working example that does | |
316 nothing useful: | |
317 | |
318 @smallexample | |
319 (let ((progress-reporter | |
320 (make-progress-reporter "Collecting mana for Emacs..." | |
321 0 500))) | |
322 (dotimes (k 500) | |
323 (sit-for 0.01) | |
324 (progress-reporter-update progress-reporter k)) | |
325 (progress-reporter-done progress-reporter)) | |
326 @end smallexample | |
327 | |
328 @defun make-progress-reporter message min-value max-value &optional current-value min-change min-time | |
329 This function creates and returns a @dfn{progress reporter}---an | |
330 object you will use as an argument for all other functions listed | |
331 here. The idea is to precompute as much data as possible to make | |
332 progress reporting very fast. | |
333 | |
334 When this progress reporter is subsequently used, it will display | |
335 @var{message} in the echo area, followed by progress percentage. | |
336 @var{message} is treated as a simple string. If you need it to depend | |
337 on a filename, for instance, use @code{format} before calling this | |
338 function. | |
339 | |
340 @var{min-value} and @var{max-value} arguments stand for starting and | |
341 final states of your operation. For instance, if you scan a buffer, | |
342 they should be the results of @code{point-min} and @code{point-max} | |
343 correspondingly. It is required that @var{max-value} is greater than | |
344 @var{min-value}. If you create progress reporter when some part of | |
345 the operation has already been completed, then specify | |
346 @var{current-value} argument. But normally you should omit it or set | |
347 it to @code{nil}---it will default to @var{min-value} then. | |
348 | |
349 Remaining arguments control the rate of echo area updates. Progress | |
350 reporter will wait for at least @var{min-change} more percents of the | |
351 operation to be completed before printing next message. | |
352 @var{min-time} specifies the minimum time in seconds to pass between | |
353 successive prints. It can be fractional. Depending on Emacs and | |
354 system capabilities, progress reporter may or may not respect this | |
355 last argument or do it with varying precision. Default value for | |
356 @var{min-change} is 1 (one percent), for @var{min-time}---0.2 | |
357 (seconds.) | |
358 | |
359 This function calls @code{progress-reporter-update}, so the first | |
360 message is printed immediately. | |
361 @end defun | |
362 | |
363 @defun progress-reporter-update reporter value | |
364 This function does the main work of reporting progress of your | |
365 operation. It displays the message of @var{reporter}, followed by | |
366 progress percentage determined by @var{value}. If percentage is zero, | |
367 or close enough according to the @var{min-change} and @var{min-time} | |
368 arguments, then it is omitted from the output. | |
369 | |
370 @var{reporter} must be the result of a call to | |
371 @code{make-progress-reporter}. @var{value} specifies the current | |
372 state of your operation and must be between @var{min-value} and | |
373 @var{max-value} (inclusive) as passed to | |
374 @code{make-progress-reporter}. For instance, if you scan a buffer, | |
375 then @var{value} should be the result of a call to @code{point}. | |
376 | |
377 This function respects @var{min-change} and @var{min-time} as passed | |
378 to @code{make-progress-reporter} and so does not output new messages | |
379 on every invocation. It is thus very fast and normally you should not | |
380 try to reduce the number of calls to it: resulting overhead will most | |
381 likely negate your effort. | |
382 @end defun | |
383 | |
384 @defun progress-reporter-force-update reporter value &optional new-message | |
385 This function is similar to @code{progress-reporter-update} except | |
386 that it prints a message in the echo area unconditionally. | |
387 | |
388 The first two arguments have the same meaning as for | |
389 @code{progress-reporter-update}. Optional @var{new-message} allows | |
390 you to change the message of the @var{reporter}. Since this functions | |
391 always updates the echo area, such a change will be immediately | |
392 presented to the user. | |
393 @end defun | |
394 | |
395 @defun progress-reporter-done reporter | |
396 This function should be called when the operation is finished. It | |
397 prints the message of @var{reporter} followed by word ``done'' in the | |
398 echo area. | |
399 | |
400 You should always call this function and not hope for | |
401 @code{progress-reporter-update} to print ``100%.'' Firstly, it may | |
402 never print it, there are many good reasons for this not to happen. | |
403 Secondly, ``done'' is more explicit. | |
404 @end defun | |
405 | |
406 @defmac dotimes-with-progress-reporter (var count [result]) message body... | |
407 This is a convenience macro that works the same way as @code{dotimes} | |
408 does, but also reports loop progress using the functions described | |
409 above. It allows you to save some typing. | |
410 | |
411 You can rewrite the example in the beginning of this node using | |
412 this macro this way: | |
413 | |
414 @example | |
415 (dotimes-with-progress-reporter | |
416 (k 500) | |
417 "Collecting some mana for Emacs..." | |
418 (sit-for 0.01)) | |
419 @end example | |
420 @end defmac | |
421 | |
422 @node Logging Messages | |
423 @subsection Logging Messages in @samp{*Messages*} | |
424 @cindex logging echo-area messages | |
425 | |
426 Almost all the messages displayed in the echo area are also recorded | |
427 in the @samp{*Messages*} buffer so that the user can refer back to | |
428 them. This includes all the messages that are output with | |
429 @code{message}. | |
430 | |
431 @defopt message-log-max | |
432 This variable specifies how many lines to keep in the @samp{*Messages*} | |
433 buffer. The value @code{t} means there is no limit on how many lines to | |
434 keep. The value @code{nil} disables message logging entirely. Here's | |
435 how to display a message and prevent it from being logged: | |
436 | |
437 @example | |
438 (let (message-log-max) | |
439 (message @dots{})) | |
440 @end example | |
441 @end defopt | |
442 | |
443 To make @samp{*Messages*} more convenient for the user, the logging | |
444 facility combines successive identical messages. It also combines | |
445 successive related messages for the sake of two cases: question | |
446 followed by answer, and a series of progress messages. | |
447 | |
448 A ``question followed by an answer'' means two messages like the | |
449 ones produced by @code{y-or-n-p}: the first is @samp{@var{question}}, | |
450 and the second is @samp{@var{question}...@var{answer}}. The first | |
451 message conveys no additional information beyond what's in the second, | |
452 so logging the second message discards the first from the log. | |
453 | |
454 A ``series of progress messages'' means successive messages like | |
455 those produced by @code{make-progress-reporter}. They have the form | |
456 @samp{@var{base}...@var{how-far}}, where @var{base} is the same each | |
457 time, while @var{how-far} varies. Logging each message in the series | |
458 discards the previous one, provided they are consecutive. | |
459 | |
460 The functions @code{make-progress-reporter} and @code{y-or-n-p} | |
461 don't have to do anything special to activate the message log | |
462 combination feature. It operates whenever two consecutive messages | |
463 are logged that share a common prefix ending in @samp{...}. | |
464 | |
465 @node Echo Area Customization | |
466 @subsection Echo Area Customization | |
467 | |
468 These variables control details of how the echo area works. | |
469 | |
306 @defvar cursor-in-echo-area | 470 @defvar cursor-in-echo-area |
307 This variable controls where the cursor appears when a message is | 471 This variable controls where the cursor appears when a message is |
308 displayed in the echo area. If it is non-@code{nil}, then the cursor | 472 displayed in the echo area. If it is non-@code{nil}, then the cursor |
309 appears at the end of the message. Otherwise, the cursor appears at | 473 appears at the end of the message. Otherwise, the cursor appears at |
310 point---not in the echo area at all. | 474 point---not in the echo area at all. |
315 | 479 |
316 @defvar echo-area-clear-hook | 480 @defvar echo-area-clear-hook |
317 This normal hook is run whenever the echo area is cleared---either by | 481 This normal hook is run whenever the echo area is cleared---either by |
318 @code{(message nil)} or for any other reason. | 482 @code{(message nil)} or for any other reason. |
319 @end defvar | 483 @end defvar |
320 | |
321 Almost all the messages displayed in the echo area are also recorded | |
322 in the @samp{*Messages*} buffer. | |
323 | |
324 @defopt message-log-max | |
325 This variable specifies how many lines to keep in the @samp{*Messages*} | |
326 buffer. The value @code{t} means there is no limit on how many lines to | |
327 keep. The value @code{nil} disables message logging entirely. Here's | |
328 how to display a message and prevent it from being logged: | |
329 | |
330 @example | |
331 (let (message-log-max) | |
332 (message @dots{})) | |
333 @end example | |
334 @end defopt | |
335 | 484 |
336 @defvar echo-keystrokes | 485 @defvar echo-keystrokes |
337 This variable determines how much time should elapse before command | 486 This variable determines how much time should elapse before command |
338 characters echo. Its value must be an integer or floating point number, | 487 characters echo. Its value must be an integer or floating point number, |
339 which specifies the | 488 which specifies the |
342 continuing, the prefix key is echoed in the echo area. (Once echoing | 491 continuing, the prefix key is echoed in the echo area. (Once echoing |
343 begins in a key sequence, all subsequent characters in the same key | 492 begins in a key sequence, all subsequent characters in the same key |
344 sequence are echoed immediately.) | 493 sequence are echoed immediately.) |
345 | 494 |
346 If the value is zero, then command input is not echoed. | 495 If the value is zero, then command input is not echoed. |
496 @end defvar | |
497 | |
498 @defopt max-mini-window-height | |
499 This variable specifies the maximum height for resizing minibuffer | |
500 windows. If a float, it specifies a fraction of the height of the | |
501 frame. If an integer, it specifies a number of lines. | |
502 @end defopt | |
503 | |
504 @defvar message-truncate-lines | |
505 Normally, displaying a long message resizes the echo area to display | |
506 the entire message. But if the variable @code{message-truncate-lines} | |
507 is non-@code{nil}, the echo area does not resize, and the message is | |
508 truncated to fit it, as in Emacs 20 and before. | |
347 @end defvar | 509 @end defvar |
348 | 510 |
349 @node Warnings | 511 @node Warnings |
350 @section Reporting Warnings | 512 @section Reporting Warnings |
351 @cindex warnings | 513 @cindex warnings |
532 This list specifies which warning types should not be logged in the | 694 This list specifies which warning types should not be logged in the |
533 warnings buffer. Each element of the list should be a list of | 695 warnings buffer. Each element of the list should be a list of |
534 symbols. If it matches the first few elements in a warning type, then | 696 symbols. If it matches the first few elements in a warning type, then |
535 that warning is not logged. | 697 that warning is not logged. |
536 @end defopt | 698 @end defopt |
537 | |
538 @node Progress | |
539 @section Reporting Operation Progress | |
540 @cindex progress reporting | |
541 | |
542 When an operation can take a while to finish, you should inform the | |
543 user about the progress it makes. This way the user can estimate | |
544 remaining time and clearly see that Emacs is busy working, not hung. | |
545 | |
546 Functions listed in this section provide simple and efficient way of | |
547 reporting operation progress. Here is a working example that does | |
548 nothing useful: | |
549 | |
550 @smallexample | |
551 (let ((progress-reporter | |
552 (make-progress-reporter "Collecting mana for Emacs..." | |
553 0 500))) | |
554 (dotimes (k 500) | |
555 (sit-for 0.01) | |
556 (progress-reporter-update progress-reporter k)) | |
557 (progress-reporter-done progress-reporter)) | |
558 @end smallexample | |
559 | |
560 @defun make-progress-reporter message min-value max-value &optional current-value min-change min-time | |
561 This function creates and returns a @dfn{progress reporter}---an | |
562 object you will use as an argument for all other functions listed | |
563 here. The idea is to precompute as much data as possible to make | |
564 progress reporting very fast. | |
565 | |
566 When this progress reporter is subsequently used, it will display | |
567 @var{message} in the echo area, followed by progress percentage. | |
568 @var{message} is treated as a simple string. If you need it to depend | |
569 on a filename, for instance, use @code{format} before calling this | |
570 function. | |
571 | |
572 @var{min-value} and @var{max-value} arguments stand for starting and | |
573 final states of your operation. For instance, if you scan a buffer, | |
574 they should be the results of @code{point-min} and @code{point-max} | |
575 correspondingly. It is required that @var{max-value} is greater than | |
576 @var{min-value}. If you create progress reporter when some part of | |
577 the operation has already been completed, then specify | |
578 @var{current-value} argument. But normally you should omit it or set | |
579 it to @code{nil}---it will default to @var{min-value} then. | |
580 | |
581 Remaining arguments control the rate of echo area updates. Progress | |
582 reporter will wait for at least @var{min-change} more percents of the | |
583 operation to be completed before printing next message. | |
584 @var{min-time} specifies the minimum time in seconds to pass between | |
585 successive prints. It can be fractional. Depending on Emacs and | |
586 system capabilities, progress reporter may or may not respect this | |
587 last argument or do it with varying precision. Default value for | |
588 @var{min-change} is 1 (one percent), for @var{min-time}---0.2 | |
589 (seconds.) | |
590 | |
591 This function calls @code{progress-reporter-update}, so the first | |
592 message is printed immediately. | |
593 @end defun | |
594 | |
595 @defun progress-reporter-update reporter value | |
596 This function does the main work of reporting progress of your | |
597 operation. It displays the message of @var{reporter}, followed by | |
598 progress percentage determined by @var{value}. If percentage is zero, | |
599 or close enough according to the @var{min-change} and @var{min-time} | |
600 arguments, then it is omitted from the output. | |
601 | |
602 @var{reporter} must be the result of a call to | |
603 @code{make-progress-reporter}. @var{value} specifies the current | |
604 state of your operation and must be between @var{min-value} and | |
605 @var{max-value} (inclusive) as passed to | |
606 @code{make-progress-reporter}. For instance, if you scan a buffer, | |
607 then @var{value} should be the result of a call to @code{point}. | |
608 | |
609 This function respects @var{min-change} and @var{min-time} as passed | |
610 to @code{make-progress-reporter} and so does not output new messages | |
611 on every invocation. It is thus very fast and normally you should not | |
612 try to reduce the number of calls to it: resulting overhead will most | |
613 likely negate your effort. | |
614 @end defun | |
615 | |
616 @defun progress-reporter-force-update reporter value &optional new-message | |
617 This function is similar to @code{progress-reporter-update} except | |
618 that it prints a message in the echo area unconditionally. | |
619 | |
620 The first two arguments have the same meaning as for | |
621 @code{progress-reporter-update}. Optional @var{new-message} allows | |
622 you to change the message of the @var{reporter}. Since this functions | |
623 always updates the echo area, such a change will be immediately | |
624 presented to the user. | |
625 @end defun | |
626 | |
627 @defun progress-reporter-done reporter | |
628 This function should be called when the operation is finished. It | |
629 prints the message of @var{reporter} followed by word ``done'' in the | |
630 echo area. | |
631 | |
632 You should always call this function and not hope for | |
633 @code{progress-reporter-update} to print ``100%.'' Firstly, it may | |
634 never print it, there are many good reasons for this not to happen. | |
635 Secondly, ``done'' is more explicit. | |
636 @end defun | |
637 | |
638 @defmac dotimes-with-progress-reporter (var count [result]) message body... | |
639 This is a convenience macro that works the same way as @code{dotimes} | |
640 does, but also reports loop progress using the functions described | |
641 above. It allows you to save some typing. | |
642 | |
643 You can rewrite the example in the beginning of this node using | |
644 this macro this way: | |
645 | |
646 @example | |
647 (dotimes-with-progress-reporter | |
648 (k 500) | |
649 "Collecting some mana for Emacs..." | |
650 (sit-for 0.01)) | |
651 @end example | |
652 @end defmac | |
653 | 699 |
654 @node Invisible Text | 700 @node Invisible Text |
655 @section Invisible Text | 701 @section Invisible Text |
656 | 702 |
657 @cindex invisible text | 703 @cindex invisible text |