[ViewVC] Diff of: cvs/rxvt-unicode/src/perl/background

Comparing rxvt-unicode/src/perl/background (file contents):
Revision 1.65 by sf-exg, Wed Jun 20 18:18:14 2012 UTC vs.
Revision 1.68 by root, Sun Jul 1 21:47:07 2012 UTC

       } else {
          return load "$HOME/sunday.png";
       }
    }
-This expression is evaluated once per hour. It will set F<sunday.png> as
+This inner expression is evaluated once per hour (and whenever the
+temrinal window is resized). It sets F<sunday.png> as background on
-background on Sundays, and F<weekday.png> on all other days.
+Sundays, and F<weekday.png> on all other days.
 Fortunately, we expect that most expressions will be much simpler, with
 little Perl knowledge needed.
 Basically, you always start with a function that "generates" an image
 horizontal and vertical dimensions. For example, this halves the image
 width and doubles the image height:
    scale 0.5, 2, load "$HOME/mypic.png"
-IF you try out these expressions, you might suffer from sluggishness,
+IF you try out these expressions, you might suffer from some sluggishness,
-because each time the terminal is resized, it again loads the PNG image
+because each time the terminal is resized, it loads the PNG image agin
-and scales it. Scaling is usually fast, but loading the image can be quite
+and scales it. Scaling is usually fast (and unavoidable), but loading the
-time consuming. This is where C<keep> comes in handy:
+image can be quite time consuming. This is where C<keep> comes in handy:
    scale 0.5, 2, keep { load "$HOME/mypic.png" }
 The C<keep> operator executes all the statements inside the braces only
 once, or when it thinks the outcome might change. In other cases it
 ... }>. The C<keep> operator takes a block of multiple statements enclosed
 by C<{}> and keeps the return value in memory.
 An expression can be "sensitive" to various external events, such as
 scaling or moving the window, root background changes and timers. Simply
-using an expression (such as C<scale> without parameters) that depend on
+using an expression (such as C<scale> without parameters) that depends on
 certain changing values (called "variables"), or using those variables
 directly, will make an expression sensitive to these events - for example,
 using C<scale> or C<TW> will make the expression sensitive to the terminal
 size, and thus to resizing events.
 When such an event happens, C<keep> will automatically trigger a
 reevaluation of the whole expression with the new value of the expression.
 C<keep> is most useful for expensive operations, such as C<blur>:
-   rootalign once { blur 20, root }
+   rootalign keep { blur 20, root }
 This makes a blurred copy of the root background once, and on subsequent
 calls, just root-aligns it. Since C<blur> is usually quite slow and
 C<rootalign> is quite fast, this trades extra memory (for the cached
 blurred pixmap) with speed (blur only needs to be redone when root
 Anything that didn't fit any of the other categories, even after applying
 force and closing our eyes.
 =over 4
-=item once { ... }
+=item keep { ... }
-This function takes a code block as argument, that is, one or more
+This operator takes a code block as argument, that is, one or more
 statements enclosed by braces.
-The trick is that this code block is only evaluated once - future calls
+The trick is that this code block is only evaluated when the outcome
-will simply return the original image (yes, it should only be used with
+changes - on other calls the C<keep> simply returns the image it computed
-images).
+previously (yes, it should only be used with images). Or in other words,
+C<keep> I<caches> the result of the code block so it doesn't need to be
+computed again.
-This can be extremely useful to avoid redoing the same slow operations
+This can be extremely useful to avoid redoing slow operations - for
-again and again- for example, if your background expression takes the root
+example, if your background expression takes the root background, blurs it
-background, blurs it and then root-aligns it it would have to blur the
+and then root-aligns it it would have to blur the root background on every
-root background on every window move or resize.
+window move or resize.
+Another example is C<load>, which can be quite slow.
 In fact, urxvt itself encloses the whole expression in some kind of
-C<once> block so it only is reevaluated as required.
+C<keep> block so it only is reevaluated as required.
-Putting the blur into a C<once> block will make sure the blur is only done
+Putting the blur into a C<keep> block will make sure the blur is only done
-once:
+once, while the C<rootalign> is still done each time the window moves.
-   rootlign once { blur 10, root }
+   rootlign keep { blur 10, root }
 This leaves the question of how to force reevaluation of the block,
 in case the root background changes: If expression inside the block
 is sensitive to some event (root background changes, window geometry
 changes), then it will be reevaluated automatically as needed.
-=item once_again
-Resets all C<once> block as if they had never been called, i.e. on the
-next call they will be reevaluated again.
 =cut
-   sub once(&) {
+   sub keep(&) {
       my $id = $_[0]+0;
       local $frame = $self->{frame_cache}{$id} ||= [$frame];
       unless ($frame->[FR_CACHE]) {
       wantarray
          ? @{ $frame->[FR_CACHE] }
          : $frame->[FR_CACHE][0]
    }
-   sub once_again() {
+#   sub keep_clear() {
-      delete $self->{frame_cache};
+#      delete $self->{frame_cache};
-   }
+#   }
 =back
 =cut

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing rxvt-unicode/src/perl/background (file contents): Revision 1.65 by sf-exg, Wed Jun 20 18:18:14 2012 UTC vs. Revision 1.68 by root, Sun Jul 1 21:47:07 2012 UTC

Diff Legend

Comparing rxvt-unicode/src/perl/background (file contents):
Revision 1.65 by sf-exg, Wed Jun 20 18:18:14 2012 UTC vs.
Revision 1.68 by root, Sun Jul 1 21:47:07 2012 UTC