16 |
* Truncation:: Folding or wrapping long text lines. |
* Truncation:: Folding or wrapping long text lines. |
17 |
* The Echo Area:: Where messages are displayed. |
* The Echo Area:: Where messages are displayed. |
18 |
* Warnings:: Displaying warning messages for the user. |
* 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. |
* Invisible Text:: Hiding part of the buffer text. |
21 |
* Selective Display:: Hiding part of the buffer text (the old way). |
* Selective Display:: Hiding part of the buffer text (the old way). |
22 |
* Overlay Arrow:: Display of an arrow to indicate position. |
* Overlay Arrow:: Display of an arrow to indicate position. |
534 |
that warning is not logged. |
that warning is not logged. |
535 |
@end defopt |
@end defopt |
536 |
|
|
537 |
|
@node Progress |
538 |
|
@section Reporting Operation Progress |
539 |
|
@cindex progress reporting |
540 |
|
|
541 |
|
When an operation can take a while to finish, you should inform the |
542 |
|
user about the progress it makes. This way the user can estimate |
543 |
|
remaining time and clearly see that Emacs is busy working, not hung. |
544 |
|
|
545 |
|
Functions listed in this section provide simple and efficient way of |
546 |
|
reporting operation progress. Here is a working example that does |
547 |
|
nothing useful: |
548 |
|
|
549 |
|
@example |
550 |
|
(let ((progress-reporter |
551 |
|
(make-progress-reporter "Collecting some mana for Emacs..." |
552 |
|
0 500))) |
553 |
|
(dotimes (k 500) |
554 |
|
(sit-for 0.01) |
555 |
|
(progress-reporter-update progress-reporter k)) |
556 |
|
(progress-reporter-done progress-reporter)) |
557 |
|
@end example |
558 |
|
|
559 |
|
@defun make-progress-reporter message min-value max-value &optional current-value min-change min-time |
560 |
|
This function creates a progress reporter---the object you will use as |
561 |
|
an argument for all other functions listed here. The idea is to |
562 |
|
precompute as much data as possible to make progress reporting very |
563 |
|
fast. |
564 |
|
|
565 |
|
The @var{message} will be displayed in the echo area, followed by |
566 |
|
progress percentage. @var{message} is treated as a simple string. If |
567 |
|
you need it to depend on a filename, for instance, use @code{format} |
568 |
|
before calling this function. |
569 |
|
|
570 |
|
@var{min-value} and @var{max-value} arguments stand for starting and |
571 |
|
final states of your operation. For instance, if you scan a buffer, |
572 |
|
they should be the results of @code{point-min} and @code{point-max} |
573 |
|
correspondingly. It is required that @var{max-value} is greater than |
574 |
|
@var{min-value}. If you create progress reporter when some part of |
575 |
|
the operation has already been completed, then specify |
576 |
|
@var{current-value} argument. But normally you should omit it or set |
577 |
|
it to @code{nil}---it will default to @var{min-value} then. |
578 |
|
|
579 |
|
Remaining arguments control the rate of echo area updates. Progress |
580 |
|
reporter will wait for at least @var{min-change} more percents of the |
581 |
|
operation to be completed before printing next message. |
582 |
|
@var{min-time} specifies the minimum time in seconds to pass between |
583 |
|
successive prints. It can be fractional. Depending on Emacs and |
584 |
|
system capabilities, progress reporter may or may not respect this |
585 |
|
last argument or do it with varying precision. Default value for |
586 |
|
@var{min-change} is 1 (one percent), for @var{min-time}---0.2 |
587 |
|
(seconds.) |
588 |
|
|
589 |
|
This function calls @code{progress-reporter-update}, so the first |
590 |
|
message is printed immediately. |
591 |
|
@end defun |
592 |
|
|
593 |
|
@defun progress-reporter-update reporter value |
594 |
|
This function does the main work of reporting progress of your |
595 |
|
operation. It print the message of @var{reporter} followed by |
596 |
|
progress percentage determined by @var{value}. If percentage is zero, |
597 |
|
then it is not printed at all. |
598 |
|
|
599 |
|
@var{reporter} must be the result of a call to |
600 |
|
@code{make-progress-reporter}. @var{value} specifies the current |
601 |
|
state of your operation and must be between @var{min-value} and |
602 |
|
@var{max-value} (inclusive) as passed to |
603 |
|
@code{make-progress-reporter}. For instance, if you scan a buffer, |
604 |
|
then @var{value} should be the result of a call to @code{point}. |
605 |
|
|
606 |
|
This function respects @var{min-change} and @var{min-time} as passed |
607 |
|
to @code{make-progress-reporter} and so does not output new messages |
608 |
|
on every invocation. It is thus very fast and normally you should not |
609 |
|
try to reduce the number of calls to it: resulting overhead will most |
610 |
|
likely negate your effort. |
611 |
|
@end defun |
612 |
|
|
613 |
|
@defun progress-reporter-force-update reporter value &optional new-message |
614 |
|
This function is similar to @code{progress-reporter-update} except |
615 |
|
that it prints a message in the echo area unconditionally. |
616 |
|
|
617 |
|
The first two arguments have the same meaning as for |
618 |
|
@code{progress-reporter-update}. Optional @var{new-message} allows |
619 |
|
you to change the message of the @var{reporter}. Since this functions |
620 |
|
always updates the echo area, such a change will be immediately |
621 |
|
presented to the user. |
622 |
|
@end defun |
623 |
|
|
624 |
|
@defun progress-reporter-done reporter |
625 |
|
This function should be called when the operation is finished. It |
626 |
|
prints the message of @var{reporter} followed by word ``done'' in the |
627 |
|
echo area. |
628 |
|
|
629 |
|
You should always call this function and not hope for |
630 |
|
@code{progress-reporter-update} to print ``100%.'' Firstly, it may |
631 |
|
never print it, there are many good reasons for this not to happen. |
632 |
|
Secondly, ``done'' is more explicit. |
633 |
|
@end defun |
634 |
|
|
635 |
@node Invisible Text |
@node Invisible Text |
636 |
@section Invisible Text |
@section Invisible Text |
637 |
|
|
2754 |
@defun fringe-bitmaps-at-pos &optional pos window |
@defun fringe-bitmaps-at-pos &optional pos window |
2755 |
This function returns the fringe bitmaps of the display line |
This function returns the fringe bitmaps of the display line |
2756 |
containing position @var{pos} in window @var{window}. The return |
containing position @var{pos} in window @var{window}. The return |
2757 |
value has the form @code{(@var{left} . @var{right})}, where @var{left} |
value has the form @code{(@var{left} @var{right} @var{ov})}, where @var{left} |
2758 |
is the symbol for the fringe bitmap in the left fringe (or @code{nil} |
is the symbol for the fringe bitmap in the left fringe (or @code{nil} |
2759 |
if no bitmap), and @var{right} is similar for the right fringe. |
if no bitmap), @var{right} is similar for the right fringe, and @var{ov} |
2760 |
|
is non-@code{nil} if there is an overlay arrow in the left fringe. |
2761 |
|
|
2762 |
The value is @code{nil} if @var{pos} is not visible in @var{window}. |
The value is @code{nil} if @var{pos} is not visible in @var{window}. |
2763 |
If @var{window} is @code{nil}, that stands for the selected window. |
If @var{window} is @code{nil}, that stands for the selected window. |