[Emacs-diffs] /srv/bzr/emacs/trunk r107072: Document animated image API

[Glenn Morris]

------------------------------------------------------------
revno: 107072
committer: Glenn Morris <address@hidden>
branch nick: trunk
timestamp: Fri 2012-02-03 00:44:30 -0800
message:
  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.
modified:
  doc/lispref/ChangeLog
  doc/lispref/display.texi
  doc/lispref/elisp.texi
  doc/lispref/vol1.texi
  doc/lispref/vol2.texi
  etc/NEWS
  lisp/ChangeLog
  lisp/image-mode.el
  lisp/image.el

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-02-03 08:38:46 +0000
+++ b/doc/lispref/ChangeLog     2012-02-03 08:44:30 +0000
@@ -1,5 +1,12 @@
 2012-02-03  Glenn Morris  <address@hidden>
 
+       * 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.

=== modified file 'doc/lispref/display.texi'
--- a/doc/lispref/display.texi  2012-02-03 08:38:46 +0000
+++ b/doc/lispref/display.texi  2012-02-03 08:44:30 +0000
@@ -4134,6 +4134,7 @@
 * 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 @@
 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,
address@hidden Images}.
 @end table
 
address@hidden
-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)))
address@hidden ignore
-
 @node TIFF Images
 @subsection TIFF Images
 @cindex TIFF
@@ -4855,6 +4836,39 @@
 @var{max-image-size} is subsequently changed (@pxref{Image Cache}).
 @end defvar
 
address@hidden Animated Images
address@hidden Animated Images
+
address@hidden animation
address@hidden 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.
+
address@hidden 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.
address@hidden defun
+
address@hidden 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.
address@hidden defun
+
address@hidden Animation operates by means of a timer.  Note that Emacs imposes 
a
+minimum frame delay of 0.01 seconds.
+
address@hidden image-animate-timer image
+This function returns the timer responsible for animating @var{image},
+if there is one.
address@hidden defun
+
+
 @node Image Cache
 @subsection Image Cache
 @cindex image cache

=== modified file 'doc/lispref/elisp.texi'
--- a/doc/lispref/elisp.texi    2012-01-24 16:08:00 +0000
+++ b/doc/lispref/elisp.texi    2012-02-03 08:44:30 +0000
@@ -1351,6 +1351,7 @@
 * 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

=== modified file 'doc/lispref/vol1.texi'
--- a/doc/lispref/vol1.texi     2012-01-19 07:21:25 +0000
+++ b/doc/lispref/vol1.texi     2012-02-03 08:44:30 +0000
@@ -1372,6 +1372,7 @@
 * 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

=== modified file 'doc/lispref/vol2.texi'
--- a/doc/lispref/vol2.texi     2012-01-19 07:21:25 +0000
+++ b/doc/lispref/vol2.texi     2012-02-03 08:44:30 +0000
@@ -1371,6 +1371,7 @@
 * 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

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2012-02-03 08:10:17 +0000
+++ b/etc/NEWS  2012-02-03 08:44:30 +0000
@@ -1323,12 +1323,16 @@
 
 ** 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.
 

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2012-02-02 12:24:30 +0000
+++ b/lisp/ChangeLog    2012-02-03 08:44:30 +0000
@@ -1,3 +1,10 @@
+2012-02-03  Glenn Morris  <address@hidden>
+
+       * 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  <address@hidden>
 
        * server.el (server-auth-dir): Doc fix.

=== modified file 'lisp/image-mode.el'
--- a/lisp/image-mode.el        2012-02-02 00:49:06 +0000
+++ b/lisp/image-mode.el        2012-02-03 08:44:30 +0000
@@ -557,13 +557,15 @@
 ;;; 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)

=== modified file 'lisp/image.el'
--- a/lisp/image.el     2012-01-19 07:21:25 +0000
+++ b/lisp/image.el     2012-02-03 08:44:30 +0000
@@ -595,13 +595,15 @@
   "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 @@
        (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 @@
        (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))