Document animated image API

* doc/lispref/display.texi (GIF Images): Mention animation.
Remove commented-out old example of animation.
(Animated Images): New subsection.
* doc/lispref/elisp.texi (Top):
* doc/lispref/vol1.texi (Top):
* doc/lispref/vol2.texi (Top): Add Animated Images menu entry.

* lisp/image-mode.el (image-animate-loop, image-toggle-animation): Doc fixes.

* lisp/image.el (image-animated-p): Doc fix.  Use image-animated-types.
(image-animate-timeout): Doc fix.

* etc/NEWS: Markup.

doc/lispref/ChangeLog

@@ -1,5 +1,12 @@
 2012-02-03  Glenn Morris  <rgm@gnu.org>
 
+	* display.texi (GIF Images): Mention animation.
+	Remove commented-out old example of animation.
+	(Animated Images): New subsection.
+	* elisp.texi (Top):
+	* vol1.texi (Top):
+	* vol2.texi (Top): Add Animated Images menu entry.
+
 	* display.texi (Image Formats): Remove oddly specific information
 	on versions of image libraries.
 	(GIF Images, TIFF Images): Minor rephrasing.

doc/lispref/display.texi

@@ -4134,6 +4134,7 @@ displayed (@pxref{Display Feature Testing}).
 * Other Image Types::   Various other formats are supported.
 * Defining Images::     Convenient ways to define an image for later use.
 * Showing Images::      Convenient ways to display an image once it is defined.
+* Animated Images::     Some image formats can be animated.
 * Image Cache::         Internal mechanisms of image display.
 @end menu
 
@@ -4472,30 +4473,10 @@ specifies the actual color to use for displaying that name.
 You can use @code{:index} to specify image number @var{index} from a
 GIF file that contains more than one image.  If the GIF file doesn't
 contain an image with the specified index, the image displays as a
-hollow box.
+hollow box.  GIF files with more than one image can be animated,
+@pxref{Animated Images}.
 @end table
 
-@ignore
-This could be used to implement limited support for animated GIFs.
-For example, the following function displays a multi-image GIF file
-at point-min in the current buffer, switching between sub-images
-every 0.1 seconds.
-
-(defun show-anim (file max)
-  "Display multi-image GIF file FILE which contains MAX subimages."
-  (display-anim (current-buffer) file 0 max t))
-
-(defun display-anim (buffer file idx max first-time)
-  (when (= idx max)
-    (setq idx 0))
-  (let ((img (create-image file nil :image idx)))
-    (with-current-buffer buffer
-      (goto-char (point-min))
-      (unless first-time (delete-char 1))
-      (insert-image img))
-    (run-with-timer 0.1 nil 'display-anim buffer file (1+ idx) max nil)))
-@end ignore
-
 @node TIFF Images
 @subsection TIFF Images
 @cindex TIFF
@@ -4855,6 +4836,39 @@ cache, it can always be displayed, even if the value of
 @var{max-image-size} is subsequently changed (@pxref{Image Cache}).
 @end defvar
 
+@node Animated Images
+@subsection Animated Images
+
+@cindex animation
+@cindex image animation
+Some image files can contain more than one image.  This can be used to
+create animation.  Currently, Emacs only supports animated GIF files.
+The following functions related to animated images are available.
+
+@defun image-animated-p image
+This function returns non-nil if @var{image} can be animated.
+The actual return value is a cons @code{(@var{nimages} . @var{delay})}, 
+where @var{nimages} is the number of frames and @var{delay} is the
+delay in seconds between them.
+@end defun
+
+@defun image-animate image &optional index limit
+This function animates @var{image}.  The optional integer @var{index}
+specifies the frame from which to start (default 0).  The optional
+argument @var{limit} controls the length of the animation.  If omitted
+or @code{nil}, the image animates once only; if @code{t} it loops
+forever; if a number animation stops after that many seconds.
+@end defun
+
+@noindent Animation operates by means of a timer.  Note that Emacs imposes a
+minimum frame delay of 0.01 seconds.
+
+@defun image-animate-timer image
+This function returns the timer responsible for animating @var{image},
+if there is one.
+@end defun
+
+
 @node Image Cache
 @subsection Image Cache
 @cindex image cache

doc/lispref/elisp.texi

@@ -1351,6 +1351,7 @@ Images
 * Defining Images::         Convenient ways to define an image for later use.
 * Showing Images::          Convenient ways to display an image once
                               it is defined.
+* Animated Images::         Some image formats can be animated.
 * Image Cache::             Internal mechanisms of image display.
 
 Buttons

doc/lispref/vol1.texi

@@ -1372,6 +1372,7 @@ Images
 * Defining Images::         Convenient ways to define an image for later use.
 * Showing Images::          Convenient ways to display an image once
                               it is defined.
+* Animated Images::         Some image formats can be animated.
 * Image Cache::             Internal mechanisms of image display.
 
 Buttons

doc/lispref/vol2.texi

@@ -1371,6 +1371,7 @@ Images
 * Defining Images::         Convenient ways to define an image for later use.
 * Showing Images::          Convenient ways to display an image once
                               it is defined.
+* Animated Images::         Some image formats can be animated.
 * Image Cache::             Internal mechanisms of image display.
 
 Buttons

etc/NEWS

@@ -1323,12 +1323,16 @@ i.e. via menu entries of the form `(menu-item "--")'.
 
 ** Image API
 
++++
 *** Animated images support (currently animated gifs only).
 
++++
 **** `image-animated-p' returns non-nil if an image can be animated.
 
++++
 **** `image-animate' animates a supplied image spec.
 
++++
 **** `image-animate-timer' returns the timer object for an image that
 is being animated.
 

lisp/ChangeLog

@@ -1,3 +1,10 @@
+2012-02-03  Glenn Morris  <rgm@gnu.org>
+
+	* image.el (image-animated-p): Doc fix.  Use image-animated-types.
+	(image-animate-timeout): Doc fix.
+
+	* image-mode.el (image-animate-loop, image-toggle-animation): Doc fixes.
+
 2012-02-02  Glenn Morris  <rgm@gnu.org>
 
 	* server.el (server-auth-dir): Doc fix.

lisp/image-mode.el

@@ -557,13 +557,15 @@ the image by calling `image-mode'."
 ;;; Animated images
 
 (defcustom image-animate-loop nil
-  "Whether to play animated images on a loop in Image mode."
+  "Non-nil means animated images loop forever, rather than playing once."
   :type 'boolean
   :version "24.1"
   :group 'image)
 
 (defun image-toggle-animation ()
-  "Start or stop animating the current image."
+  "Start or stop animating the current image.
+If `image-animate-loop' is non-nil, animation loops forever.
+Otherwise it plays once, then stops."
   (interactive)
   (let ((image (image-get-display-property))
 	animation)

lisp/image.el

@@ -595,13 +595,15 @@ Example:
   "List of supported animated image types.")
 
 (defun image-animated-p (image)
-  "Return non-nil if image can be animated.
-Actually, the return value is a cons (NIMAGES . DELAY), where
-NIMAGES is the number of sub-images in the animated image and
-DELAY is the delay in second until the next sub-image shall be
-displayed."
+  "Return non-nil if IMAGE can be animated.
+To be capable of being animated, an image must be of a type
+listed in `image-animated-types', and contain more than one
+sub-image, with a specified animation delay.  The actual return
+value is a cons (NIMAGES . DELAY), where NIMAGES is the number
+of sub-images in the animated image and DELAY is the delay in
+seconds until the next sub-image should be displayed."
   (cond
-   ((eq (plist-get (cdr image) :type) 'gif)
+   ((memq (plist-get (cdr image) :type) image-animated-types)
     (let* ((metadata (image-metadata image))
 	   (images (plist-get metadata 'count))
 	   (delay (plist-get metadata 'delay)))
@@ -609,6 +611,7 @@ displayed."
 	(if (< delay 0) (setq delay 0.1))
 	(cons images delay))))))
 
+;; "Destructively"?
 (defun image-animate (image &optional index limit)
   "Start animating IMAGE.
 Animation occurs by destructively altering the IMAGE spec list.
@@ -639,16 +642,20 @@ number, play until that number of seconds has elapsed."
 	(setq timer nil)))
     timer))
 
+;; FIXME? The delay may not be the same for different sub-images,
+;; hence we need to call image-animated-p to return it.
+;; But it also returns count, so why do we bother passing that as an
+;; argument?
 (defun image-animate-timeout (image n count time-elapsed limit)
   "Display animation frame N of IMAGE.
 N=0 refers to the initial animation frame.
 COUNT is the total number of frames in the animation.
-DELAY is the time between animation frames, in seconds.
 TIME-ELAPSED is the total time that has elapsed since
 `image-animate-start' was called.
 LIMIT determines when to stop.  If t, loop forever.  If nil, stop
  after displaying the last animation frame.  Otherwise, stop
- after LIMIT seconds have elapsed."
+ after LIMIT seconds have elapsed.
+The minimum delay between successive frames is 0.01s."
   (plist-put (cdr image) :index n)
   (force-window-update)
   (setq n (1+ n))