Commit 110683ad authored by Chong Yidong's avatar Chong Yidong

Rename image-refresh to image-flush.

* image.c (Fimage_flush): Rename from image-refresh.

* image.el (image-refresh): Define as an alias for image-flush.

* image-mode.el (image-toggle-display-image): Caller changed.

* display.texi (Image Cache): Update documentation about image
caching.
parent 4e3028f8
......@@ -4730,29 +4730,35 @@ cache, it can always be displayed, even if the value of
efficiently. When Emacs displays an image, it searches the image
cache for an existing image specification @code{equal} to the desired
specification. If a match is found, the image is displayed from the
cache; otherwise, Emacs loads the image normally.
Occasionally, you may need to tell Emacs to refresh the images
associated with a given image specification. For example, suppose you
display an image using a specification that contains a @code{:file}
property. The image is automatically cached, and subsequent displays
of that image, with the same image specification, will use the image
cache. If the image file changes in the meantime, Emacs would be
displaying the old version of the image. In such a situation, you can
``refresh'' the image by calling @code{image-refresh}.
In Emacs' current implementation, each graphical terminal possesses
an image cache, which is shared by all the frames on that terminal
cache. Otherwise, Emacs loads the image normally.
@defun image-flush spec &optional frame
This function removes the image with specification @var{spec} from the
image cache of frame @var{frame}. Image specifications are compared
using @code{equal}. If @var{frame} is @code{nil}, it defaults to the
selected frame. If @var{frame} is @code{t}, the image is flushed on
all existing frames.
In Emacs' current implementation, each graphical terminal possesses an
image cache, which is shared by all the frames on that terminal
(@pxref{Multiple Terminals}). Thus, refreshing an image in one frame
also refreshes it in all other frames on the same terminal.
@defun image-refresh spec &optional frame
This function refreshes any images with image specifications
@code{equal} to @var{spec} on frame @var{frame}. If @var{frame} is
@code{nil}, it defaults to the selected frame. If @var{frame} is
@code{t}, the refresh is applied to all existing frames.
@end defun
One use for @code{image-flush} is to tell Emacs about a change in an
image file. If an image specification contains a @code{:file}
property, the image is cached based on the file's contents when the
image is first displayed. Even if the file subsequently changes,
Emacs continues displaying the old version of the image. Calling
@code{image-flush} flushes the image from the cache, forcing Emacs to
re-read the file the next time it needs to display that image.
Another use for @code{image-flush} is for memory conservation. If
your Lisp program creates a large number of temporary images over a
period much shorter than @code{image-cache-eviction-delay} (see
below), you can opt to flush unused images yourself, instead of
waiting for Emacs to do it automatically.
@defun clear-image-cache &optional filter
This function clears an image cache, removing all the images stored in
it. If @var{filter} is omitted or @code{nil}, it clears the cache for
......@@ -4768,9 +4774,12 @@ period of time, Emacs removes it from the cache and frees the
associated memory.
@defvar image-cache-eviction-delay
This variable specifies the number of seconds an image can remain in the
cache without being displayed. When an image is not displayed for this
length of time, Emacs removes it from the image cache.
This variable specifies the number of seconds an image can remain in
the cache without being displayed. When an image is not displayed for
this length of time, Emacs removes it from the image cache.
Under some circumstances, if the number of images in the cache grows
too large, the actual eviction delay may be shorter than this.
If the value is @code{nil}, Emacs does not remove images from the cache
except when you explicitly clear it. This mode can be useful for
......
2010-05-22 Chong Yidong <cyd@stupidchicken.com>
* image.el (image-refresh): Define as an alias for image-flush.
* image-mode.el (image-toggle-display-image): Caller changed.
2010-05-21 Juri Linkov <juri@jurta.org>
* progmodes/grep.el (grep-read-files): Fix multi-pattern aliases.
......
......@@ -448,7 +448,7 @@ Remove text properties that display the image."
(defvar archive-superior-buffer)
(defvar tar-superior-buffer)
(declare-function image-refresh "image.c" (spec &optional frame))
(declare-function image-flush "image.c" (spec &optional frame))
(defun image-toggle-display-image ()
"Show the image of the image file.
......@@ -477,7 +477,7 @@ was inserted."
(inhibit-read-only t)
(buffer-undo-list t)
(modified (buffer-modified-p)))
(image-refresh image)
(image-flush image)
(let ((buffer-file-truename nil)) ; avoid changing dir mtime by lock_file
(add-text-properties (point-min) (point-max) props)
(restore-buffer-modified-p modified))
......
......@@ -30,6 +30,7 @@
"Image support."
:group 'multimedia)
(defalias 'image-refresh 'image-flush)
(defconst image-type-header-regexps
`(("\\`/[\t\n\r ]*\\*.*XPM.\\*/" . xpm)
......
2010-05-22 Chong Yidong <cyd@stupidchicken.com>
* image.c (Fimage_flush): Rename from image-refresh.
2010-05-21 Chong Yidong <cyd@stupidchicken.com>
* xdisp.c (redisplay_internal): Clear caches even if redisplaying
......
......@@ -1689,11 +1689,13 @@ which is then usually a filename. */)
}
DEFUN ("image-refresh", Fimage_refresh, Simage_refresh,
DEFUN ("image-flush", Fimage_flush, Simage_flush,
1, 2, 0,
doc: /* Refresh the image with specification SPEC on frame FRAME.
If SPEC specifies an image file, the displayed image is updated with
the current contents of that file.
doc: /* Fush the image with specification SPEC on frame FRAME.
This removes the image from the Emacs image cache. If SPEC specifies
an image file, the next redisplay of this image will read from the
current contents of that file.
FRAME nil or omitted means use the selected frame.
FRAME t means refresh the image on all frames. */)
(spec, frame)
......@@ -8526,7 +8528,7 @@ non-numeric, there is no explicit limit on the size of images. */);
defsubr (&Sinit_image_library);
defsubr (&Sclear_image_cache);
defsubr (&Simage_refresh);
defsubr (&Simage_flush);
defsubr (&Simage_size);
defsubr (&Simage_mask_p);
defsubr (&Simage_metadata);
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment