.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Animation 3"
.TH Animation 3 2023-07-25 "perl v5.38.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Tk::Animation \- Display sequence of Tk::Photo images
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\&  use Tk::Animation
\&  my $img = $widget\->Animation(\*(Aq\-format\*(Aq => \*(Aqgif\*(Aq, \-file => \*(Aqsomefile.gif\*(Aq);
\&
\&  $img\->add_frame(@images);
\&
\&  $img\->start_animation;
\&  $img\->start_animation( $period );
\&
\&  $img\->next_image;
\&  $img\->prev_image;
\&  $img\->set_image( 0 .. $#frames );
\&
\&  $img\->pause_animation;
\&  $img\->resume_animation( $period );
\&
\&  $img\->fast_forward( $multiplier );
\&  $img\->fast_reverse( $multiplier );
\&
\&  $img\->stop_animation;
\&
\&  $img\->set_disposal_method( $boolean );
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
In the simple case when \f(CW\*(C`Animation\*(C'\fR is passed a GIF89 style GIF with
multiple 'frames', it will build an internal array of \f(CW\*(C`Photo\*(C'\fR images.
.PP
The \f(CW\*(C`add_frame\*(C'\fR method adds images to the sequence. It is provided
to allow animations to be constructed from separate images.
All images must be \f(CW\*(C`Photo\*(C'\fRs and should all be the same size.
.PP
\&\f(CWstart_animation($period)\fR then initiates a \f(CW\*(C`repeat\*(C'\fR with specified
\&\fR\f(CI$period\fR\fI\fR to sequence through these images. As for raw \f(CW\*(C`repeat\*(C'\fR
\&\fI\fR\f(CI$period\fR\fI\fR is in milliseconds, for a 50Hz monitor it should be at
least 20ms. If \fI\fR\f(CI$period\fR\fI\fR is omitted it is determined from the GIF
metadata (see below), or if this is not possible it defaults to 100
milliseconds.
.PP
\&\f(CW\*(C`stop_animation\*(C'\fR cancels the \f(CW\*(C`repeat\*(C'\fR and resets the image to the first
image in the sequence.
.PP
For fine-grained control \f(CW\*(C`next_image\*(C'\fR and \f(CW\*(C`prev_image\*(C'\fR move one frame forward
or backward.  \f(CW\*(C`set_image\*(C'\fR randomly positions the animation to a particular frame.
.PP
\&\f(CW\*(C`pause_animation\*(C'\fR pauses the movie and \f(CW\*(C`resume_animation\*(C'\fR continues from the
pause point.
.PP
\&\f(CW\*(C`fast_forward\*(C'\fR and \f(CW\*(C`fast_reverse\*(C'\fR speed through the movie either
forwards or backwards.  \f(CW$multiplier\fR specifies how much faster the
animation moves.
.PP
If Image::Info is installed, then the repeat period time and
disposal method of GIF animations are determined from the GIF metadata
directly. Otherwise the disposal method must be set manually by using
\&\f(CW\*(C`set_disposal_method\*(C'\fR (1 for blanking the previous images, 0 for
leaving the previous images as is). The repeat period time may be
given in the \f(CW\*(C`start_animation\*(C'\fR method.
.SH NOTES
.IX Header "NOTES"
\&\f(CW\*(C`set_disposal_method\*(C'\fR was formerly known as \f(CW\*(C`blank\*(C'\fR method, but the
naming of this method was a mistake.
.PP
If the disposal method is not set correctly, either by
\&\f(CW\*(C`set_disposal_method\*(C'\fR or by determining from the GIF metadata, then
the following may happen: By default Animation leaves the previous
movie frame in the animation photo. Many times overlaying subsequent
frames produces a composite that looks blurred.
.SH BUGS
.IX Header "BUGS"
This module should not depend on a module which is not declared as a
dependency (Image::Info).
.PP
The delays between images may vary in a GIF animation. This cannot be
handled by this module yet.
.PP
The handling of the various disposal methods is not correct.