aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorRichard M. Stallman2005-07-03 19:05:09 +0000
committerRichard M. Stallman2005-07-03 19:05:09 +0000
commitac1d7a06c113a0ca9a6edaa31517af1a62af80c5 (patch)
tree651ee3cd4192c556911a1e81478a91a4ba16c1bc
parent2d859fe05c8900cc1445b327c4be4fa11d88eab2 (diff)
downloademacs-ac1d7a06c113a0ca9a6edaa31517af1a62af80c5.tar.gz
emacs-ac1d7a06c113a0ca9a6edaa31517af1a62af80c5.zip
(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.
-rw-r--r--lispref/display.texi342
1 files changed, 194 insertions, 148 deletions
diff --git a/lispref/display.texi b/lispref/display.texi
index 4b7e0558b01..f6b3e8de386 100644
--- a/lispref/display.texi
+++ b/lispref/display.texi
@@ -14,9 +14,8 @@ that Emacs presents to the user.
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.
@@ -184,7 +183,7 @@ This variable is automatically buffer-local in every buffer.
184@cindex error display 183@cindex error display
185@cindex echo area 184@cindex echo area
186 185
187The @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,
189and for echoing keystrokes. It is not the same as the minibuffer, 188and for echoing keystrokes. It is not the same as the minibuffer,
190despite the fact that the minibuffer appears (when active) in the same 189despite the fact that the minibuffer appears (when active) in the same
@@ -193,9 +192,22 @@ specifies the rules for resolving conflicts between the echo area and
193the minibuffer for use of that screen space (@pxref{Minibuffer,, The 192the minibuffer for use of that screen space (@pxref{Minibuffer,, The
194Minibuffer, emacs, The GNU Emacs Manual}). 193Minibuffer, emacs, The GNU Emacs Manual}).
195 194
196You 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
197functions with @code{t} as the stream (@pxref{Output Functions}), or as 196functions with @code{t} as the stream (@pxref{Output Functions}), or
198follows: 197explicitly.
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
210area messages. Many other Emacs features display messages there, too.
199 211
200@defun message string &rest arguments 212@defun message string &rest arguments
201This function displays a message in the echo area. The 213This function displays a message in the echo area. The
@@ -216,12 +228,6 @@ the echo area has been expanded automatically, this brings it back to
216its normal size. If the minibuffer is active, this brings the 228its normal size. If the minibuffer is active, this brings the
217minibuffer contents back onto the screen immediately. 229minibuffer contents back onto the screen immediately.
218 230
219@vindex message-truncate-lines
220Normally, displaying a long message resizes the echo area to display
221the entire message. But if the variable @code{message-truncate-lines}
222is non-@code{nil}, the echo area does not resize, and the message is
223truncated to fit it, as in Emacs 20 and before.
224
225@example 231@example
226@group 232@group
227(message "Minibuffer depth is %d." 233(message "Minibuffer depth is %d."
@@ -241,12 +247,6 @@ To automatically display a message in the echo area or in a pop-buffer,
241depending on its size, use @code{display-message-or-buffer} (see below). 247depending on its size, use @code{display-message-or-buffer} (see below).
242@end defun 248@end defun
243 249
244@defopt max-mini-window-height
245This variable specifies the maximum height for resizing minibuffer
246windows. If a float, it specifies a fraction of the height of the
247frame. If an integer, it specifies a number of lines.
248@end defopt
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
252This construct displays a message in the echo area temporarily, during 252This construct displays a message in the echo area temporarily, during
@@ -303,23 +303,130 @@ This function returns the message currently being displayed in the
303echo area, or @code{nil} if there is none. 303echo area, or @code{nil} if there is none.
304@end defun 304@end defun
305 305
306@defvar cursor-in-echo-area 306@node Progress
307This variable controls where the cursor appears when a message is 307@subsection Reporting Operation Progress
308displayed in the echo area. If it is non-@code{nil}, then the cursor 308@cindex progress reporting
309appears at the end of the message. Otherwise, the cursor appears at
310point---not in the echo area at all.
311 309
312The value is normally @code{nil}; Lisp programs bind it to @code{t} 310 When an operation can take a while to finish, you should inform the
313for brief periods of time. 311user about the progress it makes. This way the user can estimate
314@end defvar 312remaining time and clearly see that Emacs is busy working, not hung.
315 313
316@defvar echo-area-clear-hook 314 Functions listed in this section provide simple and efficient way of
317This normal hook is run whenever the echo area is cleared---either by 315reporting operation progress. Here is a working example that does
318@code{(message nil)} or for any other reason. 316nothing useful:
319@end defvar
320 317
321Almost all the messages displayed in the echo area are also recorded 318@smallexample
322in the @samp{*Messages*} buffer. 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
329This function creates and returns a @dfn{progress reporter}---an
330object you will use as an argument for all other functions listed
331here. The idea is to precompute as much data as possible to make
332progress reporting very fast.
333
334When 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
337on a filename, for instance, use @code{format} before calling this
338function.
339
340@var{min-value} and @var{max-value} arguments stand for starting and
341final states of your operation. For instance, if you scan a buffer,
342they should be the results of @code{point-min} and @code{point-max}
343correspondingly. It is required that @var{max-value} is greater than
344@var{min-value}. If you create progress reporter when some part of
345the operation has already been completed, then specify
346@var{current-value} argument. But normally you should omit it or set
347it to @code{nil}---it will default to @var{min-value} then.
348
349Remaining arguments control the rate of echo area updates. Progress
350reporter will wait for at least @var{min-change} more percents of the
351operation to be completed before printing next message.
352@var{min-time} specifies the minimum time in seconds to pass between
353successive prints. It can be fractional. Depending on Emacs and
354system capabilities, progress reporter may or may not respect this
355last 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
359This function calls @code{progress-reporter-update}, so the first
360message is printed immediately.
361@end defun
362
363@defun progress-reporter-update reporter value
364This function does the main work of reporting progress of your
365operation. It displays the message of @var{reporter}, followed by
366progress percentage determined by @var{value}. If percentage is zero,
367or close enough according to the @var{min-change} and @var{min-time}
368arguments, 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
372state 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,
375then @var{value} should be the result of a call to @code{point}.
376
377This function respects @var{min-change} and @var{min-time} as passed
378to @code{make-progress-reporter} and so does not output new messages
379on every invocation. It is thus very fast and normally you should not
380try to reduce the number of calls to it: resulting overhead will most
381likely negate your effort.
382@end defun
383
384@defun progress-reporter-force-update reporter value &optional new-message
385This function is similar to @code{progress-reporter-update} except
386that it prints a message in the echo area unconditionally.
387
388The first two arguments have the same meaning as for
389@code{progress-reporter-update}. Optional @var{new-message} allows
390you to change the message of the @var{reporter}. Since this functions
391always updates the echo area, such a change will be immediately
392presented to the user.
393@end defun
394
395@defun progress-reporter-done reporter
396This function should be called when the operation is finished. It
397prints the message of @var{reporter} followed by word ``done'' in the
398echo area.
399
400You should always call this function and not hope for
401@code{progress-reporter-update} to print ``100%.'' Firstly, it may
402never print it, there are many good reasons for this not to happen.
403Secondly, ``done'' is more explicit.
404@end defun
405
406@defmac dotimes-with-progress-reporter (var count [result]) message body...
407This is a convenience macro that works the same way as @code{dotimes}
408does, but also reports loop progress using the functions described
409above. It allows you to save some typing.
410
411You can rewrite the example in the beginning of this node using
412this 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
427in the @samp{*Messages*} buffer so that the user can refer back to
428them. This includes all the messages that are output with
429@code{message}.
323 430
324@defopt message-log-max 431@defopt message-log-max
325This variable specifies how many lines to keep in the @samp{*Messages*} 432This variable specifies how many lines to keep in the @samp{*Messages*}
@@ -333,6 +440,48 @@ how to display a message and prevent it from being logged:
333@end example 440@end example
334@end defopt 441@end defopt
335 442
443 To make @samp{*Messages*} more convenient for the user, the logging
444facility combines successive identical messages. It also combines
445successive related messages for the sake of two cases: question
446followed by answer, and a series of progress messages.
447
448 A ``question followed by an answer'' means two messages like the
449ones produced by @code{y-or-n-p}: the first is @samp{@var{question}},
450and the second is @samp{@var{question}...@var{answer}}. The first
451message conveys no additional information beyond what's in the second,
452so logging the second message discards the first from the log.
453
454 A ``series of progress messages'' means successive messages like
455those produced by @code{make-progress-reporter}. They have the form
456@samp{@var{base}...@var{how-far}}, where @var{base} is the same each
457time, while @var{how-far} varies. Logging each message in the series
458discards the previous one, provided they are consecutive.
459
460 The functions @code{make-progress-reporter} and @code{y-or-n-p}
461don't have to do anything special to activate the message log
462combination feature. It operates whenever two consecutive messages
463are 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
470@defvar cursor-in-echo-area
471This variable controls where the cursor appears when a message is
472displayed in the echo area. If it is non-@code{nil}, then the cursor
473appears at the end of the message. Otherwise, the cursor appears at
474point---not in the echo area at all.
475
476The value is normally @code{nil}; Lisp programs bind it to @code{t}
477for brief periods of time.
478@end defvar
479
480@defvar echo-area-clear-hook
481This normal hook is run whenever the echo area is cleared---either by
482@code{(message nil)} or for any other reason.
483@end defvar
484
336@defvar echo-keystrokes 485@defvar echo-keystrokes
337This variable determines how much time should elapse before command 486This variable determines how much time should elapse before command
338characters echo. Its value must be an integer or floating point number, 487characters echo. Its value must be an integer or floating point number,
@@ -346,6 +495,19 @@ sequence are echoed immediately.)
346If the value is zero, then command input is not echoed. 495If the value is zero, then command input is not echoed.
347@end defvar 496@end defvar
348 497
498@defopt max-mini-window-height
499This variable specifies the maximum height for resizing minibuffer
500windows. If a float, it specifies a fraction of the height of the
501frame. If an integer, it specifies a number of lines.
502@end defopt
503
504@defvar message-truncate-lines
505Normally, displaying a long message resizes the echo area to display
506the entire message. But if the variable @code{message-truncate-lines}
507is non-@code{nil}, the echo area does not resize, and the message is
508truncated to fit it, as in Emacs 20 and before.
509@end defvar
510
349@node Warnings 511@node Warnings
350@section Reporting Warnings 512@section Reporting Warnings
351@cindex warnings 513@cindex warnings
@@ -535,122 +697,6 @@ symbols. If it matches the first few elements in a warning type, then
535that warning is not logged. 697that warning is not logged.
536@end defopt 698@end defopt
537 699
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
543user about the progress it makes. This way the user can estimate
544remaining time and clearly see that Emacs is busy working, not hung.
545
546 Functions listed in this section provide simple and efficient way of
547reporting operation progress. Here is a working example that does
548nothing 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
561This function creates and returns a @dfn{progress reporter}---an
562object you will use as an argument for all other functions listed
563here. The idea is to precompute as much data as possible to make
564progress reporting very fast.
565
566When 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
569on a filename, for instance, use @code{format} before calling this
570function.
571
572@var{min-value} and @var{max-value} arguments stand for starting and
573final states of your operation. For instance, if you scan a buffer,
574they should be the results of @code{point-min} and @code{point-max}
575correspondingly. It is required that @var{max-value} is greater than
576@var{min-value}. If you create progress reporter when some part of
577the operation has already been completed, then specify
578@var{current-value} argument. But normally you should omit it or set
579it to @code{nil}---it will default to @var{min-value} then.
580
581Remaining arguments control the rate of echo area updates. Progress
582reporter will wait for at least @var{min-change} more percents of the
583operation to be completed before printing next message.
584@var{min-time} specifies the minimum time in seconds to pass between
585successive prints. It can be fractional. Depending on Emacs and
586system capabilities, progress reporter may or may not respect this
587last 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
591This function calls @code{progress-reporter-update}, so the first
592message is printed immediately.
593@end defun
594
595@defun progress-reporter-update reporter value
596This function does the main work of reporting progress of your
597operation. It displays the message of @var{reporter}, followed by
598progress percentage determined by @var{value}. If percentage is zero,
599or close enough according to the @var{min-change} and @var{min-time}
600arguments, 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
604state 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,
607then @var{value} should be the result of a call to @code{point}.
608
609This function respects @var{min-change} and @var{min-time} as passed
610to @code{make-progress-reporter} and so does not output new messages
611on every invocation. It is thus very fast and normally you should not
612try to reduce the number of calls to it: resulting overhead will most
613likely negate your effort.
614@end defun
615
616@defun progress-reporter-force-update reporter value &optional new-message
617This function is similar to @code{progress-reporter-update} except
618that it prints a message in the echo area unconditionally.
619
620The first two arguments have the same meaning as for
621@code{progress-reporter-update}. Optional @var{new-message} allows
622you to change the message of the @var{reporter}. Since this functions
623always updates the echo area, such a change will be immediately
624presented to the user.
625@end defun
626
627@defun progress-reporter-done reporter
628This function should be called when the operation is finished. It
629prints the message of @var{reporter} followed by word ``done'' in the
630echo area.
631
632You should always call this function and not hope for
633@code{progress-reporter-update} to print ``100%.'' Firstly, it may
634never print it, there are many good reasons for this not to happen.
635Secondly, ``done'' is more explicit.
636@end defun
637
638@defmac dotimes-with-progress-reporter (var count [result]) message body...
639This is a convenience macro that works the same way as @code{dotimes}
640does, but also reports loop progress using the functions described
641above. It allows you to save some typing.
642
643You can rewrite the example in the beginning of this node using
644this 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
654@node Invisible Text 700@node Invisible Text
655@section Invisible Text 701@section Invisible Text
656 702