\documentclass[a4paper,12pt]{article}
\usepackage[english]{babel}
\usepackage{interactiveanimation}
\usepackage{hyperref}

\def\keywords{build button controllable animation branching animation LaTeX pdfLaTeX JavaScript Adobe Reader}

\hypersetup{
	pdftitle={The interactiveanimation Package},
	pdfauthor={Luis Gonz\'alez, Javier Toro, Pedro Linares},
	pdfsubject={Documentation},
	pdfkeywords={\keywords}
}

\begin{document}
\title{The {\sffamily interactiveanimation} Package}
\author{Luis Gonz\'alez, Javier Toro, Pedro Linares}
\maketitle

\begin{abstract}\noindent
A \LaTeX{} package for creating branching and button controllable PDF animations from image files.
\vskip 0.2\baselineskip

\emph{Keywords}: \keywords
\end{abstract}

\tableofcontents

%\newpage
\section{Introduction}
This package provides an interface to create Portable Document Format (PDF) files with branching animations. Animations are built up as a set of concatenated interactive frames. Each interactive frame can be set to display an image and a set of buttons that allows the course of the overall animation to be controlled by the user. Buttons can be configured to transfer the action focus to another interactive frame and to display an animated image sequence before the forthcoming frame is displayed.

By now, the only supported way for compiling using this package is by producing the PDF file with pdf\TeX{}.

The final PDF can be viewed in current Adobe Readers on all supported platforms as long as they have JavaScript support.

\section{Requirements}
\begin{trivlist}
\item pdf\TeX{}, version $\ge1.20$
\item Adobe Reader, version $\ge6$
\end{trivlist}

\section{Installation}
Unzip the file `interactiveanimation.zip' and copy the `interactiveanimation.sty' and the folder `javascript' in a place where \LaTeX{} can find them.

MiK\TeX{} users should run the package manager for installation.

\section{Using the package}
Invoke the package by putting the line
\begin{verbatim}
    \usepackage{interactiveanimation}
\end{verbatim}
to the preamble of your document, i.\,e. somewhere between \verb+\documentclass+ and \verb+\begin{document}+.

\section{The user interface}
Interactive animations are defined using three basic instructions provided by this package:
\begin{itemize}
\item The animation is inserted, using the environment \verb+animation+.
\item Frames are inserted, using the environment \verb+aframe+ inside of \verb+animation+.
\item Control buttons are inserted, using the command \verb+\controlbutton+ inside \verb+aframe+.
\end{itemize}

\begin{verbatim}
\begin{animation}{<width>}{<height>}
\begin{aframe}{<frame name>}{<image file>[,<file page>]}
\controlbutton[<sequence file>,<start page>[,<end page>]]
{<caption>}{<target frame>}{<options>}
    ... other buttons
\end{aframe}
    ... other frames
\end{animation}
\end{verbatim}

\subsection{Inserting the animation}
The \verb+<width>+ and \verb+<height>+ arguments must be given in valid \TeX{} dimensions. Horizontal and vertical dimensions of the animation are scaled independently to fit \verb+<width>+ and \verb+<height>+.

\subsection{Inserting frames}
If present, argument \verb+<frame name>+ is used in control buttons to identify which frame will be displayed when the button is pressed, so it should be unique in current animation.

\verb+<image file>+ and \verb+<file page>+ specify a page of a PDF file to be displayed as an image by the frame. If \verb+<file page>+ is not specified, first page is assumed; if any image is not specified, a blank frame  will be displayed.

\subsection{Inserting control buttons}
A control button may display, before changing the current frame, a sequence of images. All of those images must be into the same external PDF file. If you want to display a sequence, you should specify the file where images are stored in \verb+<sequence file>+ and the start and end page range in \verb+<start page>+ and \verb+<end page>+, respectively; if only \verb+<start page>+ is given in the range, first page is assumed as range start and the given number as range end. Range may also be decreasing if \verb+<end page>+ is less than \verb+<start page>+.

\verb+<caption>+ gives a text to be displayed by the control button.

\verb+<target frame>+ specifies the name of a frame to be displayed when that control button is pressed, you may also, instead of specifying a frame name, use \verb+first+, \verb+last+, \verb+previous+ or \verb+next+ for first, last, previous and next frame defined into the animation, respectively. If not specified, current frame is assumed. 

\verb+<options>+ a comma-separated list that describes the appearance and behavior of the control button. See section below for more details.

\subsubsection{Control button options}
\begin{verbatim}
X=<coordinate> | start | center | end
Y=<coordinate> | start | center | end
\end{verbatim}
give X and Y coordinates of a point to take reference for specifying where button's drawing should start (see below). The coordinates should be non-negative integers and represent a point into the animation. Point \verb+X=0,Y=0+ will be the lower left corner.

Instead of given a number, you can also use \verb+start+, \verb+center+ and \verb+end+ to specify the start, center or end (X or Y) coordinates of the animation, respectively. For example, for an animation of $400\times300$, \verb+X=end+ whould be equivalent to \verb+X=400+ and \verb+Y=center+ whould be equivalent to \verb+Y=150+.

Note that \verb+X+ and \verb+Y+ are uppercase, so if you use lowercase it will not work.
\begin{verbatim}
position=left | right | above | below | center | from
\end{verbatim}
Describes where the button will be positioned relative to the given point. For example, if \verb+position=right+ is specified, the button will be at the right of the given point, if below, it will be below of the point and so on. If \verb+from+ is specified, the point will be the upper left corner of the button.

Note: if \verb+position+ is not specified, the button will be at upper corner of the animation for first button or at right for other buttons. If it is especified but it was not given any point, the reference will be the last inserted button.

\begin{verbatim}
width=<width>
height=<height>
scale=<factor>
\end{verbatim}
By default, button's width and height are automatically set to fit button's caption. However, you may also set specific dimensions using those options. If specified, \verb+width+ and \verb+height+'s argument must be a non-negative integer representing a distance in points. In addition, instead of setting manually the dimensions, you may scale automatically fixed dimensions using \verb+scale+; that allows you to increase the size of a button without breaking the proportion; for example, \verb+scale=2+ will multiply width and height by 2.
\medskip
\begin{verbatim}
hidden
\end{verbatim}
Makes the button becomes visible only when the mouse is over it and invisible otherwise.
\begin{verbatim}
transparent
\end{verbatim}
Makes visible only button's caption, the button still being pressable. If you want a fully transparent button, you just should specify a blank caption.

Note: if you want to define a transparent button on the same area of others, make sure to define it before those other buttons so it is not over them to prevent from activating.
\begin{verbatim}
span=<milliseconds>
\end{verbatim}
If the button has an associated sequence of images, this option sets the time span, in milliseconds, for images change. Default value is \verb+1000+.
\begin{verbatim}
keep
\end{verbatim}
Keep running the image sequence until frame is pressed.

\section{Examples}
The following example is an analog clock and consist of four frames. Each frame displays an interval of 15 minutes on the clock and has two buttons to going back and going forward. Before going back and forward, the buttons display a sequence which represents the movement that performs hand of the clock to reach, passing throught every minute between original and destination positions.

The file `clock.pdf', where images are stored, consists of 60 images cor\-re\-spond\-ing with 60 minutes of an our.

\small
\begin{verbatim}
\begin{animation}{450 pt}{450 pt}
	\begin{aframe}{12:00}{clock.pdf,60}
		\controlbutton[clock.pdf,60,45]{<< Backward}{12:45}{%
			position=right, X=start, Y=start, span=75}
		\controlbutton[clock.pdf,1,15]{Forward >>}{12:15}{%
			position=left, X=end, Y=start, span=75}
	\end{aframe}

	\begin{aframe}{12:15}{clock.pdf,15}
		\controlbutton[clock.pdf,15,1]{<< Backward}{12:00}{%
			position=right, X=start, Y=start, span=75}
		\controlbutton[clock.pdf,15,30]{Forward >>}{12:30}{%
			position=left, X=end, Y=start, span=75}
	\end{aframe}

	\begin{aframe}{12:30}{clock.pdf,30}
		\controlbutton[clock.pdf,30,15]{<< Backward}{12:15}{%
			position=right, X=start, Y=start, span=75}
		\controlbutton[clock.pdf,30,45]{Forward >>}{12:45}{%
			position=left, X=end, Y=start, span=75}
	\end{aframe}

	\begin{aframe}{12:45}{clock.pdf,45}
		\controlbutton[clock.pdf,45,30]{<< Backward}{12:30}{%
			position=right, X=start, Y=start, span=75}
		\controlbutton[clock.pdf,45,60]{Forward >>}{12:00}{%
			position=left, X=end, Y=start, span=75}
	\end{aframe}
\end{animation}
\end{verbatim}
\normalsize

\newpage
\begin{animation}{450 pt}{450 pt}
	\begin{aframe}{12:00}{clock.pdf,60}
		\controlbutton[clock.pdf,60,45]{<< Backward}{12:45}{%
			position=right, X=start, Y=start, span=75}
		\controlbutton[clock.pdf,1,15]{Forward >>}{12:15}{%
			position=left, X=end, Y=start, span=75}
	\end{aframe}

	\begin{aframe}{12:15}{clock.pdf,15}
		\controlbutton[clock.pdf,15,1]{<< Backward}{12:00}{%
			position=right, X=start, Y=start, span=75}
		\controlbutton[clock.pdf,15,30]{Forward >>}{12:30}{%
			position=left, X=end, Y=start, span=75}
	\end{aframe}

	\begin{aframe}{12:30}{clock.pdf,30}
		\controlbutton[clock.pdf,30,15]{<< Backward}{12:15}{%
			position=right, X=start, Y=start, span=75}
		\controlbutton[clock.pdf,30,45]{Forward >>}{12:45}{%
			position=left, X=end, Y=start, span=75}
	\end{aframe}

	\begin{aframe}{12:45}{clock.pdf,45}
		\controlbutton[clock.pdf,45,30]{<< Backward}{12:30}{%
			position=right, X=start, Y=start, span=75}
		\controlbutton[clock.pdf,45,60]{Forward >>}{12:00}{%
			position=left, X=end, Y=start, span=75}
	\end{aframe}
\end{animation}

\section{Known issues}

	When trying to insert an animation with not enought space in current page, the animation will be placed in the next one. However, only the part wich could not fit in previous page will be visible. The simplest solution to solve it is inserting a page skip before the animation, e.\,g. \verb+\newpage+.

\end{document}
