/[emacs]/emacs/lispref/display.texi
ViewVC logotype

Diff of /emacs/lispref/display.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.95.2.8 by miles, Thu Sep 30 01:20:38 2004 UTC revision 1.95.2.9 by miles, Thu Oct 14 08:49:57 2004 UTC
# Line 16  that Emacs presents to the user. Line 16  that Emacs presents to the user.
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.
# Line 533  symbols.  If it matches the first few el Line 534  symbols.  If it matches the first few el
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    
# Line 2655  symbols have their own name space. Line 2754  symbols have their own name space.
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.

Legend:
Removed from v.1.95.2.8  
changed lines
  Added in v.1.95.2.9

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26