Mercurial > emacs
changeset 108746:24d486687f54
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.
| author | Chong Yidong <cyd@stupidchicken.com> |
|---|---|
| date | Sat, 22 May 2010 12:48:01 -0400 |
| parents | 9e1b87832dbf |
| children | 59a0f034c5cf |
| files | doc/lispref/display.texi lisp/ChangeLog lisp/image-mode.el lisp/image.el src/ChangeLog src/image.c |
| diffstat | 6 files changed, 51 insertions(+), 29 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/lispref/display.texi Sat May 22 13:59:09 2010 +0200 +++ b/doc/lispref/display.texi Sat May 22 12:48:01 2010 -0400 @@ -4730,29 +4730,35 @@ 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 @@ 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
--- a/lisp/ChangeLog Sat May 22 13:59:09 2010 +0200 +++ b/lisp/ChangeLog Sat May 22 12:48:01 2010 -0400 @@ -1,3 +1,9 @@ +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.
--- a/lisp/image-mode.el Sat May 22 13:59:09 2010 +0200 +++ b/lisp/image-mode.el Sat May 22 12:48:01 2010 -0400 @@ -448,7 +448,7 @@ (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 @@ (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))
--- a/lisp/image.el Sat May 22 13:59:09 2010 +0200 +++ b/lisp/image.el Sat May 22 12:48:01 2010 -0400 @@ -30,6 +30,7 @@ "Image support." :group 'multimedia) +(defalias 'image-refresh 'image-flush) (defconst image-type-header-regexps `(("\\`/[\t\n\r ]*\\*.*XPM.\\*/" . xpm)
--- a/src/ChangeLog Sat May 22 13:59:09 2010 +0200 +++ b/src/ChangeLog Sat May 22 12:48:01 2010 -0400 @@ -1,3 +1,7 @@ +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
--- a/src/image.c Sat May 22 13:59:09 2010 +0200 +++ b/src/image.c Sat May 22 12:48:01 2010 -0400 @@ -1689,11 +1689,13 @@ } -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 @@ defsubr (&Sinit_image_library); defsubr (&Sclear_image_cache); - defsubr (&Simage_refresh); + defsubr (&Simage_flush); defsubr (&Simage_size); defsubr (&Simage_mask_p); defsubr (&Simage_metadata);