[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] /srv/bzr/emacs/trunk r107072: Document animated image API
From: |
Glenn Morris |
Subject: |
[Emacs-diffs] /srv/bzr/emacs/trunk r107072: Document animated image API |
Date: |
Fri, 03 Feb 2012 00:44:30 -0800 |
User-agent: |
Bazaar (2.3.1) |
------------------------------------------------------------
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))
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] /srv/bzr/emacs/trunk r107072: Document animated image API,
Glenn Morris <=