forked from emacs-mirror/emacs
-
Notifications
You must be signed in to change notification settings - Fork 0
/
display.texi
8395 lines (7011 loc) · 337 KB
/
display.texi
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
@c -*- mode: texinfo; coding: utf-8 -*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990--1995, 1998--2021 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Display
@chapter Emacs Display
This chapter describes a number of features related to the display
that Emacs presents to the user.
@menu
* Refresh Screen:: Clearing the screen and redrawing everything on it.
* Forcing Redisplay:: Forcing redisplay.
* Truncation:: Folding or wrapping long text lines.
* The Echo Area:: Displaying messages at the bottom of the screen.
* Warnings:: Displaying warning messages for the user.
* Invisible Text:: Hiding part of the buffer text.
* Selective Display:: Hiding part of the buffer text (the old way).
* Temporary Displays:: Displays that go away automatically.
* Overlays:: Use overlays to highlight parts of the buffer.
* Size of Displayed Text:: How large displayed text is.
* Line Height:: Controlling the height of lines.
* Faces:: A face defines a graphics style for text characters:
font, colors, etc.
* Fringes:: Controlling window fringes.
* Scroll Bars:: Controlling scroll bars.
* Window Dividers:: Separating windows visually.
* Display Property:: Images, margins, text size, etc.
* Images:: Displaying images in Emacs buffers.
* Xwidgets:: Displaying native widgets in Emacs buffers.
* Buttons:: Adding clickable buttons to Emacs buffers.
* Abstract Display:: Emacs's Widget for Object Collections.
* Blinking:: How Emacs shows the matching open parenthesis.
* Character Display:: How Emacs displays individual characters.
* Beeping:: Audible signal to the user.
* Window Systems:: Which window system is being used.
* Tooltips:: Tooltip display in Emacs.
* Bidirectional Display:: Display of bidirectional scripts, such as
Arabic and Farsi.
@end menu
@node Refresh Screen
@section Refreshing the Screen
@cindex refresh the screen
@cindex screen refresh
The function @code{redraw-frame} clears and redisplays the entire
contents of a given frame (@pxref{Frames}). This is useful if the
screen is corrupted.
@defun redraw-frame &optional frame
This function clears and redisplays frame @var{frame}. If @var{frame}
is omitted or @code{nil}, it redraws the selected frame.
@end defun
Even more powerful is @code{redraw-display}:
@deffn Command redraw-display
This function clears and redisplays all visible frames.
@end deffn
In Emacs, processing user input takes priority over redisplay. If
you call these functions when input is available, they don't redisplay
immediately, but the requested redisplay does happen
eventually---after all the input has been processed.
On text terminals, suspending and resuming Emacs normally also
refreshes the screen. Some terminal emulators record separate
contents for display-oriented programs such as Emacs and for ordinary
sequential display. If you are using such a terminal, you might want
to inhibit the redisplay on resumption.
@defopt no-redraw-on-reenter
@cindex suspend (cf. @code{no-redraw-on-reenter})
@cindex resume (cf. @code{no-redraw-on-reenter})
This variable controls whether Emacs redraws the entire screen after it
has been suspended and resumed. Non-@code{nil} means there is no need
to redraw, @code{nil} means redrawing is needed. The default is @code{nil}.
@end defopt
@node Forcing Redisplay
@section Forcing Redisplay
@cindex forcing redisplay
Emacs normally tries to redisplay the screen whenever it waits for
input. With the following function, you can request an immediate
attempt to redisplay, in the middle of Lisp code, without actually
waiting for input.
@defun redisplay &optional force
This function tries immediately to redisplay. The optional argument
@var{force}, if non-@code{nil}, forces the redisplay to be performed,
instead of being preempted if input is pending.
The function returns @code{t} if it actually tried to redisplay, and
@code{nil} otherwise. A value of @code{t} does not mean that
redisplay proceeded to completion; it could have been preempted by
newly arriving input.
@end defun
Although @code{redisplay} tries immediately to redisplay, it does
not change how Emacs decides which parts of its frame(s) to redisplay.
By contrast, the following function adds certain windows to the
pending redisplay work (as if their contents had completely changed),
but does not immediately try to perform redisplay.
@defun force-window-update &optional object
This function forces some or all windows to be updated the next time
Emacs does a redisplay. If @var{object} is a window, that window is
to be updated. If @var{object} is a buffer or buffer name, all
windows displaying that buffer are to be updated. If @var{object} is
@code{nil} (or omitted), all windows are to be updated.
This function does not do a redisplay immediately; Emacs does that as
it waits for input, or when the function @code{redisplay} is called.
@end defun
@defvar pre-redisplay-function
A function run just before redisplay. It is called with one argument,
the set of windows to be redisplayed. The set can be @code{nil},
meaning only the selected window, or @code{t}, meaning all the
windows.
@end defvar
@defvar pre-redisplay-functions
This hook is run just before redisplay. It is called once in each
window that is about to be redisplayed, with @code{current-buffer} set
to the buffer displayed in that window.
@end defvar
@node Truncation
@section Truncation
@cindex line wrapping
@cindex line truncation
@cindex continuation lines
@cindex @samp{$} in display
@cindex @samp{\} in display
When a line of text extends beyond the right edge of a window, Emacs
can @dfn{continue} the line (make it wrap to the next screen
line), or @dfn{truncate} the line (limit it to one screen line). The
additional screen lines used to display a long text line are called
@dfn{continuation} lines. Continuation is not the same as filling;
continuation happens on the screen only, not in the buffer contents,
and it breaks a line precisely at the right margin, not at a word
boundary. @xref{Filling}.
On a graphical display, tiny arrow images in the window fringes
indicate truncated and continued lines (@pxref{Fringes}). On a text
terminal, a @samp{$} in the rightmost column of the window indicates
truncation; a @samp{\} on the rightmost column indicates a line that
wraps. (The display table can specify alternate characters to use
for this; @pxref{Display Tables}).
@defopt truncate-lines
If this buffer-local variable is non-@code{nil}, lines that extend
beyond the right edge of the window are truncated; otherwise, they are
continued. As a special exception, the variable
@code{truncate-partial-width-windows} takes precedence in
@dfn{partial-width} windows (i.e., windows that do not occupy the
entire frame width).
@end defopt
@defopt truncate-partial-width-windows
@cindex partial-width windows
This variable controls line truncation in @dfn{partial-width} windows.
A partial-width window is one that does not occupy the entire frame
width (@pxref{Splitting Windows}). If the value is @code{nil}, line
truncation is determined by the variable @code{truncate-lines} (see
above). If the value is an integer @var{n}, lines are truncated if
the partial-width window has fewer than @var{n} columns, regardless of
the value of @code{truncate-lines}; if the partial-width window has
@var{n} or more columns, line truncation is determined by
@code{truncate-lines}. For any other non-@code{nil} value, lines are
truncated in every partial-width window, regardless of the value of
@code{truncate-lines}.
@end defopt
When horizontal scrolling (@pxref{Horizontal Scrolling}) is in use in
a window, that forces truncation.
@defvar wrap-prefix
If this buffer-local variable is non-@code{nil}, it defines a
@dfn{wrap prefix} which Emacs displays at the start of every
continuation line. (If lines are truncated, @code{wrap-prefix} is
never used.) Its value may be a string or an image (@pxref{Other
Display Specs}), or a stretch of whitespace such as specified by the
@code{:width} or @code{:align-to} display properties (@pxref{Specified
Space}). The value is interpreted in the same way as a @code{display}
text property. @xref{Display Property}.
A wrap prefix may also be specified for regions of text, using the
@code{wrap-prefix} text or overlay property. This takes precedence
over the @code{wrap-prefix} variable. @xref{Special Properties}.
@end defvar
@defvar line-prefix
If this buffer-local variable is non-@code{nil}, it defines a
@dfn{line prefix} which Emacs displays at the start of every
non-continuation line. Its value may be a string or an image
(@pxref{Other Display Specs}), or a stretch of whitespace such as
specified by the @code{:width} or @code{:align-to} display properties
(@pxref{Specified Space}). The value is interpreted in the same way
as a @code{display} text property. @xref{Display Property}.
A line prefix may also be specified for regions of text using the
@code{line-prefix} text or overlay property. This takes precedence
over the @code{line-prefix} variable. @xref{Special Properties}.
@end defvar
@ignore
If your buffer contains only very short lines, you might find it
advisable to set @code{cache-long-scans} to @code{nil}.
@defvar cache-long-scans
If this variable is non-@code{nil} (the default), various indentation
and motion functions, and Emacs redisplay, cache the results of
scanning the buffer, and consult the cache to avoid rescanning regions
of the buffer unless they are modified.
Turning off the cache speeds up processing of short lines somewhat.
This variable is automatically buffer-local in every buffer.
@end defvar
@end ignore
@node The Echo Area
@section The Echo Area
@cindex error display
@cindex echo area
@c FIXME: Why not use @xref{Minibuffers} directly? --xfq
The @dfn{echo area} is used for displaying error messages
(@pxref{Errors}), for messages made with the @code{message} primitive,
and for echoing keystrokes. It is not the same as the minibuffer,
despite the fact that the minibuffer appears (when active) in the same
place on the screen as the echo area. @xref{Minibuffer,, The
Minibuffer, emacs, The GNU Emacs Manual}.
Apart from the functions documented in this section, you can print
Lisp objects to the echo area by specifying @code{t} as the output
stream. @xref{Output Streams}.
@menu
* Displaying Messages:: Explicitly displaying text in the echo area.
* Progress:: Informing user about progress of a long operation.
* Logging Messages:: Echo area messages are logged for the user.
* Echo Area Customization:: Controlling the echo area.
@end menu
@node Displaying Messages
@subsection Displaying Messages in the Echo Area
@cindex display message in echo area
This section describes the standard functions for displaying
messages in the echo area.
@defun message format-string &rest arguments
This function displays a message in the echo area.
@var{format-string} is a format string, and @var{arguments} are the
objects for its format specifications, like in the @code{format-message}
function (@pxref{Formatting Strings}). The resulting formatted string
is displayed in the echo area; if it contains @code{face} text
properties, it is displayed with the specified faces (@pxref{Faces}).
The string is also added to the @file{*Messages*} buffer, but without
text properties (@pxref{Logging Messages}).
Typically grave accent and apostrophe in the format translate to
matching curved quotes, e.g., @t{"Missing `%s'"} might result in
@t{"Missing ‘foo’"}. @xref{Text Quoting Style}, for how to influence
or inhibit this translation.
In batch mode, the message is printed to the standard error stream,
followed by a newline.
When @code{inhibit-message} is non-@code{nil}, no message will be displayed
in the echo area, it will only be logged to @samp{*Messages*}.
If @var{format-string} is @code{nil} or the empty string,
@code{message} clears the echo area; if the echo area has been
expanded automatically, this brings it back to its normal size. If
the minibuffer is active, this brings the minibuffer contents back
onto the screen immediately.
@example
@group
(message "Reverting `%s'..." (buffer-name))
@print{} Reverting ‘subr.el’...
@result{} "Reverting ‘subr.el’..."
@end group
@group
---------- Echo Area ----------
Reverting ‘subr.el’...
---------- Echo Area ----------
@end group
@end example
To automatically display a message in the echo area or in a pop-buffer,
depending on its size, use @code{display-message-or-buffer} (see below).
@strong{Warning:} If you want to use your own string as a message
verbatim, don't just write @code{(message @var{string})}. If
@var{string} contains @samp{%}, @samp{`}, or @samp{'} it may be
reformatted, with undesirable results. Instead, use @code{(message
"%s" @var{string})}.
@end defun
@defvar set-message-function
If this variable is non-@code{nil}, it should be a function of one
argument, the text of a message to display in the echo area. This
function will be called by @code{message} and related functions. If
the function returns @code{nil}, the message is displayed in the echo
area as usual. If this function returns a string, that string is
displayed in the echo area instead of the original one. If this
function returns other non-@code{nil} values, that means the message
was already handled, so @code{message} will not display anything in
the echo area. See also @code{clear-message-function} that can be
used to clear the message displayed by this function.
The default value is the function that displays the message at the end
of the minibuffer when the minibuffer is active. However, if the text
shown in the active minibuffer has the @code{minibuffer-message} text
property (@pxref{Special Properties}) on some character, the message
will be displayed before the first character having that property.
@end defvar
@defvar clear-message-function
If this variable is non-@code{nil}, @code{message} and related
functions call it with no arguments when their argument message is
@code{nil} or the empty string.
Usually this function is called when the next input event arrives
after displaying an echo-area message. The function is expected to
clear the message displayed by its counterpart function specified by
@code{set-message-function}.
The default value is the function that clears the message displayed in
an active minibuffer.
@end defvar
@defvar inhibit-message
When this variable is non-@code{nil}, @code{message} and related functions
will not use the Echo Area to display messages.
@end defvar
@defmac with-temp-message message &rest body
This construct displays a message in the echo area temporarily, during
the execution of @var{body}. It displays @var{message}, executes
@var{body}, then returns the value of the last body form while restoring
the previous echo area contents.
@end defmac
@defun message-or-box format-string &rest arguments
This function displays a message like @code{message}, but may display it
in a dialog box instead of the echo area. If this function is called in
a command that was invoked using the mouse---more precisely, if
@code{last-nonmenu-event} (@pxref{Command Loop Info}) is either
@code{nil} or a list---then it uses a dialog box or pop-up menu to
display the message. Otherwise, it uses the echo area. (This is the
same criterion that @code{y-or-n-p} uses to make a similar decision; see
@ref{Yes-or-No Queries}.)
You can force use of the mouse or of the echo area by binding
@code{last-nonmenu-event} to a suitable value around the call.
@end defun
@defun message-box format-string &rest arguments
@anchor{message-box}
This function displays a message like @code{message}, but uses a dialog
box (or a pop-up menu) whenever that is possible. If it is impossible
to use a dialog box or pop-up menu, because the terminal does not
support them, then @code{message-box} uses the echo area, like
@code{message}.
@end defun
@defun display-message-or-buffer message &optional buffer-name action frame
This function displays the message @var{message}, which may be either a
string or a buffer. If it is shorter than the maximum height of the
echo area, as defined by @code{max-mini-window-height}, it is displayed
in the echo area, using @code{message}. Otherwise,
@code{display-buffer} is used to show it in a pop-up buffer.
Returns either the string shown in the echo area, or when a pop-up
buffer is used, the window used to display it.
If @var{message} is a string, then the optional argument
@var{buffer-name} is the name of the buffer used to display it when a
pop-up buffer is used, defaulting to @file{*Message*}. In the case
where @var{message} is a string and displayed in the echo area, it is
not specified whether the contents are inserted into the buffer anyway.
The optional arguments @var{action} and @var{frame} are as for
@code{display-buffer}, and only used if a buffer is displayed.
@end defun
@defun current-message
This function returns the message currently being displayed in the
echo area, or @code{nil} if there is none.
@end defun
@node Progress
@subsection Reporting Operation Progress
@cindex progress reporting
When an operation can take a while to finish, you should inform the
user about the progress it makes. This way the user can estimate
remaining time and clearly see that Emacs is busy working, not hung.
A convenient way to do this is to use a @dfn{progress reporter}.
Here is a working example that does nothing useful:
@smallexample
(let ((progress-reporter
(make-progress-reporter "Collecting mana for Emacs..."
0 500)))
(dotimes (k 500)
(sit-for 0.01)
(progress-reporter-update progress-reporter k))
(progress-reporter-done progress-reporter))
@end smallexample
@defun make-progress-reporter message &optional min-value max-value current-value min-change min-time
This function creates and returns a progress reporter object, which
you will use as an argument for the other functions listed below. The
idea is to precompute as much data as possible to make progress
reporting very fast.
When this progress reporter is subsequently used, it will display
@var{message} in the echo area, followed by progress percentage.
@var{message} is treated as a simple string. If you need it to depend
on a filename, for instance, use @code{format-message} before calling this
function.
The arguments @var{min-value} and @var{max-value} should be numbers
standing for the starting and final states of the operation. For
instance, an operation that scans a buffer should set these to the
results of @code{point-min} and @code{point-max} correspondingly.
@var{max-value} should be greater than @var{min-value}.
Alternatively, you can set @var{min-value} and @var{max-value} to
@code{nil}. In that case, the progress reporter does not report
process percentages; it instead displays a ``spinner'' that rotates a
notch each time you update the progress reporter.
If @var{min-value} and @var{max-value} are numbers, you can give the
argument @var{current-value} a numerical value specifying the initial
progress; if omitted, this defaults to @var{min-value}.
The remaining arguments control the rate of echo area updates. The
progress reporter will wait for at least @var{min-change} more
percents of the operation to be completed before printing next
message; the default is one percent. @var{min-time} specifies the
minimum time in seconds to pass between successive prints; the default
is 0.2 seconds. (On some operating systems, the progress reporter may
handle fractions of seconds with varying precision).
This function calls @code{progress-reporter-update}, so the first
message is printed immediately.
@end defun
@defun progress-reporter-update reporter &optional value suffix
This function does the main work of reporting progress of your
operation. It displays the message of @var{reporter}, followed by
progress percentage determined by @var{value}. If percentage is zero,
or close enough according to the @var{min-change} and @var{min-time}
arguments, then it is omitted from the output.
@var{reporter} must be the result of a call to
@code{make-progress-reporter}. @var{value} specifies the current
state of your operation and must be between @var{min-value} and
@var{max-value} (inclusive) as passed to
@code{make-progress-reporter}. For instance, if you scan a buffer,
then @var{value} should be the result of a call to @code{point}.
Optional argument @var{suffix} is a string to be displayed after
@var{reporter}'s main message and progress text. If @var{reporter} is
a non-numerical reporter, then @var{value} should be @code{nil}, or a
string to use instead of @var{suffix}.
This function respects @var{min-change} and @var{min-time} as passed
to @code{make-progress-reporter} and so does not output new messages
on every invocation. It is thus very fast and normally you should not
try to reduce the number of calls to it: resulting overhead will most
likely negate your effort.
@end defun
@defun progress-reporter-force-update reporter &optional value new-message suffix
This function is similar to @code{progress-reporter-update} except
that it prints a message in the echo area unconditionally.
@var{reporter}, @var{value}, and @var{suffix} have the same meaning as for
@code{progress-reporter-update}. Optional @var{new-message} allows
you to change the message of the @var{reporter}. Since this function
always updates the echo area, such a change will be immediately
presented to the user.
@end defun
@defun progress-reporter-done reporter
This function should be called when the operation is finished. It
prints the message of @var{reporter} followed by word @samp{done} in the
echo area.
You should always call this function and not hope for
@code{progress-reporter-update} to print @samp{100%}. Firstly, it may
never print it, there are many good reasons for this not to happen.
Secondly, @samp{done} is more explicit.
@end defun
@defmac dotimes-with-progress-reporter (var count [result]) reporter-or-message body@dots{}
This is a convenience macro that works the same way as @code{dotimes}
does, but also reports loop progress using the functions described
above. It allows you to save some typing. The argument
@var{reporter-or-message} can be either a string or a progress
reporter object.
You can rewrite the example in the beginning of this subsection using
this macro as follows:
@example
@group
(dotimes-with-progress-reporter
(k 500)
"Collecting some mana for Emacs..."
(sit-for 0.01))
@end group
@end example
Using a reporter object as the @var{reporter-or-message} argument is
useful if you want to specify the optional arguments in
@var{make-progress-reporter}. For instance, you can write the
previous example as follows:
@example
@group
(dotimes-with-progress-reporter
(k 500)
(make-progress-reporter "Collecting some mana for Emacs..." 0 500 0 1 1.5)
(sit-for 0.01))
@end group
@end example
@end defmac
@defmac dolist-with-progress-reporter (var count [result]) reporter-or-message body@dots{}
This is another convenience macro that works the same way as @code{dolist}
does, but also reports loop progress using the functions described
above. As in @code{dotimes-with-progress-reporter},
@code{reporter-or-message} can be a progress reporter or a string.
You can rewrite the previous example with this macro as follows:
@example
@group
(dolist-with-progress-reporter
(k (number-sequence 0 500))
"Collecting some mana for Emacs..."
(sit-for 0.01))
@end group
@end example
@end defmac
@node Logging Messages
@subsection Logging Messages in @file{*Messages*}
@cindex logging echo-area messages
Almost all the messages displayed in the echo area are also recorded
in the @file{*Messages*} buffer so that the user can refer back to
them. This includes all the messages that are output with
@code{message}. By default, this buffer is read-only and uses the major
mode @code{messages-buffer-mode}. Nothing prevents the user from
killing the @file{*Messages*} buffer, but the next display of a message
recreates it. Any Lisp code that needs to access the
@file{*Messages*} buffer directly and wants to ensure that it exists
should use the function @code{messages-buffer}.
@defun messages-buffer
This function returns the @file{*Messages*} buffer. If it does not
exist, it creates it, and switches it to @code{messages-buffer-mode}.
@end defun
@defopt message-log-max
This variable specifies how many lines to keep in the @file{*Messages*}
buffer. The value @code{t} means there is no limit on how many lines to
keep. The value @code{nil} disables message logging entirely. Here's
how to display a message and prevent it from being logged:
@example
(let (message-log-max)
(message @dots{}))
@end example
@end defopt
To make @file{*Messages*} more convenient for the user, the logging
facility combines successive identical messages. It also combines
successive related messages for the sake of two cases: question
followed by answer, and a series of progress messages.
A question followed by an answer has two messages like the
ones produced by @code{y-or-n-p}: the first is @samp{@var{question}},
and the second is @samp{@var{question}...@var{answer}}. The first
message conveys no additional information beyond what's in the second,
so logging the second message discards the first from the log.
A series of progress messages has successive messages like
those produced by @code{make-progress-reporter}. They have the form
@samp{@var{base}...@var{how-far}}, where @var{base} is the same each
time, while @var{how-far} varies. Logging each message in the series
discards the previous one, provided they are consecutive.
The functions @code{make-progress-reporter} and @code{y-or-n-p}
don't have to do anything special to activate the message log
combination feature. It operates whenever two consecutive messages
are logged that share a common prefix ending in @samp{...}.
@node Echo Area Customization
@subsection Echo Area Customization
@cindex echo area customization
These variables control details of how the echo area works.
@defvar cursor-in-echo-area
This variable controls where the cursor appears when a message is
displayed in the echo area. If it is non-@code{nil}, then the cursor
appears at the end of the message. Otherwise, the cursor appears at
point---not in the echo area at all.
The value is normally @code{nil}; Lisp programs bind it to @code{t}
for brief periods of time.
@end defvar
@defvar echo-area-clear-hook
This normal hook is run whenever the echo area is cleared---either by
@code{(message nil)} or for any other reason.
@end defvar
@defopt echo-keystrokes
This variable determines how much time should elapse before command
characters echo. Its value must be a number, and specifies the
number of seconds to wait before echoing. If the user types a prefix
key (such as @kbd{C-x}) and then delays this many seconds before
continuing, the prefix key is echoed in the echo area. (Once echoing
begins in a key sequence, all subsequent characters in the same key
sequence are echoed immediately.)
If the value is zero, then command input is not echoed.
@end defopt
@defvar message-truncate-lines
Normally, displaying a long message resizes the echo area to display
the entire message. But if the variable @code{message-truncate-lines}
is non-@code{nil}, the echo area does not resize, and the message is
truncated to fit it.
@end defvar
The variable @code{max-mini-window-height}, which specifies the
maximum height for resizing minibuffer windows, also applies to the
echo area (which is really a special use of the minibuffer window;
@pxref{Minibuffer Windows}).
@node Warnings
@section Reporting Warnings
@cindex warnings
@dfn{Warnings} are a facility for a program to inform the user of a
possible problem, but continue running.
@menu
* Warning Basics:: Warnings concepts and functions to report them.
* Warning Variables:: Variables programs bind to customize their warnings.
* Warning Options:: Variables users set to control display of warnings.
* Delayed Warnings:: Deferring a warning until the end of a command.
@end menu
@node Warning Basics
@subsection Warning Basics
@cindex severity level
Every warning has a textual message, which explains the problem for
the user, and a @dfn{severity level} which is a symbol. Here are the
possible severity levels, in order of decreasing severity, and their
meanings:
@table @code
@item :emergency
A problem that will seriously impair Emacs operation soon
if you do not attend to it promptly.
@item :error
A report of data or circumstances that are inherently wrong.
@item :warning
A report of data or circumstances that are not inherently wrong, but
raise suspicion of a possible problem.
@item :debug
A report of information that may be useful if you are debugging.
@end table
When your program encounters invalid input data, it can either
signal a Lisp error by calling @code{error} or @code{signal} or report
a warning with severity @code{:error}. Signaling a Lisp error is the
easiest thing to do, but it means the program cannot continue
processing. If you want to take the trouble to implement a way to
continue processing despite the bad data, then reporting a warning of
severity @code{:error} is the right way to inform the user of the
problem. For instance, the Emacs Lisp byte compiler can report an
error that way and continue compiling other functions. (If the
program signals a Lisp error and then handles it with
@code{condition-case}, the user won't see the error message; it could
show the message to the user by reporting it as a warning.)
@c FIXME: Why use "(bytecomp)" instead of "'bytecomp" or simply
@c "bytecomp" here? The parens are part of warning-type-format but
@c not part of the warning type. --xfq
@cindex warning type
Each warning has a @dfn{warning type} to classify it. The type is a
list of symbols. The first symbol should be the custom group that you
use for the program's user options. For example, byte compiler
warnings use the warning type @code{(bytecomp)}. You can also
subcategorize the warnings, if you wish, by using more symbols in the
list.
@defun display-warning type message &optional level buffer-name
This function reports a warning, using @var{message} as the message
and @var{type} as the warning type. @var{level} should be the
severity level, with @code{:warning} being the default.
@var{buffer-name}, if non-@code{nil}, specifies the name of the buffer
for logging the warning. By default, it is @file{*Warnings*}.
@end defun
@defun lwarn type level message &rest args
This function reports a warning using the value of @code{(format-message
@var{message} @var{args}...)} as the message in the @file{*Warnings*}
buffer. In other respects it is equivalent to @code{display-warning}.
@end defun
@defun warn message &rest args
This function reports a warning using the value of @code{(format-message
@var{message} @var{args}...)} as the message, @code{(emacs)} as the
type, and @code{:warning} as the severity level. It exists for
compatibility only; we recommend not using it, because you should
specify a specific warning type.
@end defun
@node Warning Variables
@subsection Warning Variables
@cindex warning variables
Programs can customize how their warnings appear by binding
the variables described in this section.
@defvar warning-levels
This list defines the meaning and severity order of the warning
severity levels. Each element defines one severity level,
and they are arranged in order of decreasing severity.
Each element has the form @code{(@var{level} @var{string}
@var{function})}, where @var{level} is the severity level it defines.
@var{string} specifies the textual description of this level.
@var{string} should use @samp{%s} to specify where to put the warning
type information, or it can omit the @samp{%s} so as not to include
that information.
The optional @var{function}, if non-@code{nil}, is a function to call
with no arguments, to get the user's attention.
Normally you should not change the value of this variable.
@end defvar
@defvar warning-prefix-function
If non-@code{nil}, the value is a function to generate prefix text for
warnings. Programs can bind the variable to a suitable function.
@code{display-warning} calls this function with the warnings buffer
current, and the function can insert text in it. That text becomes
the beginning of the warning message.
The function is called with two arguments, the severity level and its
entry in @code{warning-levels}. It should return a list to use as the
entry (this value need not be an actual member of
@code{warning-levels}). By constructing this value, the function can
change the severity of the warning, or specify different handling for
a given severity level.
If the variable's value is @code{nil} then there is no function
to call.
@end defvar
@defvar warning-series
Programs can bind this variable to @code{t} to say that the next
warning should begin a series. When several warnings form a series,
that means to leave point on the first warning of the series, rather
than keep moving it for each warning so that it appears on the last one.
The series ends when the local binding is unbound and
@code{warning-series} becomes @code{nil} again.
The value can also be a symbol with a function definition. That is
equivalent to @code{t}, except that the next warning will also call
the function with no arguments with the warnings buffer current. The
function can insert text which will serve as a header for the series
of warnings.
Once a series has begun, the value is a marker which points to the
buffer position in the warnings buffer of the start of the series.
The variable's normal value is @code{nil}, which means to handle
each warning separately.
@end defvar
@defvar warning-fill-prefix
When this variable is non-@code{nil}, it specifies a fill prefix to
use for filling each warning's text.
@end defvar
@defvar warning-fill-column
The column at which to fill warnings.
@end defvar
@defvar warning-type-format
This variable specifies the format for displaying the warning type
in the warning message. The result of formatting the type this way
gets included in the message under the control of the string in the
entry in @code{warning-levels}. The default value is @code{" (%s)"}.
If you bind it to @code{""} then the warning type won't appear at
all.
@end defvar
@node Warning Options
@subsection Warning Options
@cindex warning options
These variables are used by users to control what happens
when a Lisp program reports a warning.
@defopt warning-minimum-level
This user option specifies the minimum severity level that should be
shown immediately to the user. The default is @code{:warning}, which
means to immediately display all warnings except @code{:debug}
warnings.
@end defopt
@defopt warning-minimum-log-level
This user option specifies the minimum severity level that should be
logged in the warnings buffer. The default is @code{:warning}, which
means to log all warnings except @code{:debug} warnings.
@end defopt
@defopt warning-suppress-types
This list specifies which warning types should not be displayed
immediately for the user. Each element of the list should be a list
of symbols. If its elements match the first elements in a warning
type, then that warning is not displayed immediately.
@end defopt
@defopt warning-suppress-log-types
This list specifies which warning types should not be logged in the
warnings buffer. Each element of the list should be a list of
symbols. If it matches the first few elements in a warning type, then
that warning is not logged.
@end defopt
@node Delayed Warnings
@subsection Delayed Warnings
@cindex delayed warnings
Sometimes, you may wish to avoid showing a warning while a command is
running, and only show it only after the end of the command. You can
use the function @code{delay-warning} for this.
@defun delay-warning type message &optional level buffer-name
This function is the delayed counterpart to @code{display-warning}
(@pxref{Warning Basics}), and it is called with the same arguments.
The warning message is queued into @code{delayed-warnings-list}.
@end defun
@defvar delayed-warnings-list
The value of this variable is a list of warnings to be displayed after
the current command has finished. Each element must be a list
@smallexample
(@var{type} @var{message} [@var{level} [@var{buffer-name}]])
@end smallexample
@noindent
with the same form, and the same meanings, as the argument list of
@code{display-warning}. Immediately after running
@code{post-command-hook} (@pxref{Command Overview}), the Emacs
command loop displays all the warnings specified by this variable,
then resets it to @code{nil}.
@end defvar
Programs which need to further customize the delayed warnings
mechanism can change the variable @code{delayed-warnings-hook}:
@defvar delayed-warnings-hook
This is a normal hook which is run by the Emacs command loop, after
@code{post-command-hook}, in order to process and display delayed
warnings.
Its default value is a list of two functions:
@smallexample
(collapse-delayed-warnings display-delayed-warnings)
@end smallexample
@findex collapse-delayed-warnings
@findex display-delayed-warnings
@noindent
The function @code{collapse-delayed-warnings} removes repeated entries
from @code{delayed-warnings-list}. The function
@code{display-delayed-warnings} calls @code{display-warning} on each
of the entries in @code{delayed-warnings-list}, in turn, and then sets
@code{delayed-warnings-list} to @code{nil}.
@end defvar
@node Invisible Text
@section Invisible Text
@cindex invisible text
You can make characters @dfn{invisible}, so that they do not appear on
the screen, with the @code{invisible} property. This can be either a
text property (@pxref{Text Properties}) or an overlay property
(@pxref{Overlays}). Cursor motion also partly ignores these
characters; if the command loop finds that point is inside a range of
invisible text after a command, it relocates point to the other side
of the text.
In the simplest case, any non-@code{nil} @code{invisible} property makes
a character invisible. This is the default case---if you don't alter
the default value of @code{buffer-invisibility-spec}, this is how the
@code{invisible} property works. You should normally use @code{t}
as the value of the @code{invisible} property if you don't plan
to set @code{buffer-invisibility-spec} yourself.
More generally, you can use the variable @code{buffer-invisibility-spec}
to control which values of the @code{invisible} property make text
invisible. This permits you to classify the text into different subsets
in advance, by giving them different @code{invisible} values, and
subsequently make various subsets visible or invisible by changing the
value of @code{buffer-invisibility-spec}.
Controlling visibility with @code{buffer-invisibility-spec} is
especially useful in a program to display the list of entries in a
database. It permits the implementation of convenient filtering
commands to view just a part of the entries in the database. Setting
this variable is very fast, much faster than scanning all the text in
the buffer looking for properties to change.
@defvar buffer-invisibility-spec
This variable specifies which kinds of @code{invisible} properties
actually make a character invisible. Setting this variable makes it
buffer-local.
@table @asis
@item @code{t}
A character is invisible if its @code{invisible} property is
non-@code{nil}. This is the default.
@item a list
Each element of the list specifies a criterion for invisibility; if a
character's @code{invisible} property fits any one of these criteria,
the character is invisible. The list can have two kinds of elements:
@table @code
@item @var{atom}
A character is invisible if its @code{invisible} property value is
@var{atom} or if it is a list with @var{atom} as a member; comparison
is done with @code{eq}.
@item (@var{atom} . t)
A character is invisible if its @code{invisible} property value is
@var{atom} or if it is a list with @var{atom} as a member; comparison
is done with @code{eq}. Moreover, a sequence of such characters
displays as an ellipsis.
@end table
@end table
@end defvar
Two functions are specifically provided for adding elements to
@code{buffer-invisibility-spec} and removing elements from it.
@defun add-to-invisibility-spec element
This function adds the element @var{element} to
@code{buffer-invisibility-spec}. If @code{buffer-invisibility-spec}
was @code{t}, it changes to a list, @code{(t)}, so that text whose
@code{invisible} property is @code{t} remains invisible.
@end defun
@defun remove-from-invisibility-spec element
This removes the element @var{element} from
@code{buffer-invisibility-spec}. This does nothing if @var{element}
is not in the list.
@end defun
A convention for use of @code{buffer-invisibility-spec} is that a
major mode should use the mode's own name as an element of
@code{buffer-invisibility-spec} and as the value of the
@code{invisible} property:
@example
;; @r{If you want to display an ellipsis:}
(add-to-invisibility-spec '(my-symbol . t))
;; @r{If you don't want ellipsis:}
(add-to-invisibility-spec 'my-symbol)