\f
;;; Animated image API
-(defconst image-animated-types '(gif)
- "List of supported animated image types.")
-
-(defun image-animated-p (image)
- "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
- ((memq (plist-get (cdr image) :type) image-animated-types)
- (let* ((metadata (image-metadata image))
- (images (plist-get metadata 'count))
- (delay (plist-get metadata 'delay)))
- (when (and images (> images 1) (numberp delay))
- (if (< delay 0) (setq delay 0.1))
- (cons images delay))))))
+(defvar image-default-frame-delay 0.1
+ "Default interval in seconds between frames of a multi-frame image.
+Only used if the image does not specify a value.")
+
+(defun image-multi-frame-p (image)
+ "Return non-nil if IMAGE contains more than one frame.
+The actual return value is a cons (NIMAGES . DELAY), where NIMAGES is
+the number of frames (or sub-images) in the image and DELAY is the delay
+in seconds that the image specifies between each frame. DELAY may be nil,
+in which case you might want to use `image-default-frame-delay'."
+ (let* ((metadata (image-metadata image))
+ (images (plist-get metadata 'count))
+ (delay (plist-get metadata 'delay)))
+ (when (and images (> images 1))
+ (if (or (not (numberp delay)) (< delay 0))
+ (setq delay image-default-frame-delay))
+ (cons images delay))))
+
+(define-obsolete-function-alias 'image-animated-p 'image-multi-frame-p "24.4")
;; "Destructively"?
(defun image-animate (image &optional index limit)
LIMIT specifies how long to animate the image. If omitted or
nil, play the animation until the end. If t, loop forever. If a
number, play until that number of seconds has elapsed."
- (let ((animation (image-animated-p image))
+ (let ((animation (image-multi-frame-p image))
timer)
(when animation
(if (setq timer (image-animate-timer image))
(setq timer nil)))
timer))
+(defconst image-minimum-frame-delay 0.01
+ "Minimum interval in seconds between frames of an animated image.")
+
+(defun image-current-frame (image)
+ "The current frame number of IMAGE, indexed from 0."
+ (or (plist-get (cdr image) :index) 0))
+
+(defun image-show-frame (image n &optional nocheck)
+ "Show frame N of IMAGE.
+Frames are indexed from 0. Optional argument NOCHECK non-nil means
+do not check N is within the range of frames present in the image."
+ (unless nocheck
+ (if (< n 0) (setq n 0)
+ (setq n (min n (1- (car (image-multi-frame-p image)))))))
+ (plist-put (cdr image) :index n)
+ (force-window-update))
+
;; FIXME? The delay may not be the same for different sub-images,
-;; hence we need to call image-animated-p to return it.
+;; hence we need to call image-multi-frame-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)
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.
-The minimum delay between successive frames is 0.01s."
- (plist-put (cdr image) :index n)
- (force-window-update)
+The minimum delay between successive frames is `image-minimum-frame-delay'."
+ (image-show-frame image n t)
(setq n (1+ n))
(let* ((time (float-time))
- (animation (image-animated-p image))
+ (animation (image-multi-frame-p image))
;; Subtract off the time we took to load the image from the
;; stated delay time.
- (delay (max (+ (cdr animation) time (- (float-time)))
- 0.01))
+ (delay (max (+ (or (cdr animation) image-default-frame-delay)
+ time (- (float-time)))
+ image-minimum-frame-delay))
done)
(if (>= n count)
(if limit