diff options
| -rw-r--r-- | Master/texmf-dist/doc/latex/media9/ChangeLog | 4 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/media9/media9.pdf | bin | 1955423 -> 1972925 bytes | |||
| -rw-r--r-- | Master/texmf-dist/doc/latex/media9/media9.tex | 182 | ||||
| -rw-r--r-- | Master/texmf-dist/tex/latex/media9/media9.sty | 218 |
4 files changed, 320 insertions, 84 deletions
diff --git a/Master/texmf-dist/doc/latex/media9/ChangeLog b/Master/texmf-dist/doc/latex/media9/ChangeLog index de69f360ce6..b83e40e354e 100644 --- a/Master/texmf-dist/doc/latex/media9/ChangeLog +++ b/Master/texmf-dist/doc/latex/media9/ChangeLog @@ -1,3 +1,7 @@ +2013-01-31 + * v0.22 + * new: user command \mediabutton for creating media control buttons + 2013-01-23 * v0.21 * fix: swf media inserted after a 3D object didn't work, reported by C. diff --git a/Master/texmf-dist/doc/latex/media9/media9.pdf b/Master/texmf-dist/doc/latex/media9/media9.pdf Binary files differindex 397badd4a6f..18c3fd6c3c0 100644 --- a/Master/texmf-dist/doc/latex/media9/media9.pdf +++ b/Master/texmf-dist/doc/latex/media9/media9.pdf diff --git a/Master/texmf-dist/doc/latex/media9/media9.tex b/Master/texmf-dist/doc/latex/media9/media9.tex index ec55465fe7d..3dd94675dfe 100644 --- a/Master/texmf-dist/doc/latex/media9/media9.tex +++ b/Master/texmf-dist/doc/latex/media9/media9.tex @@ -172,12 +172,15 @@ Except for `\verb+dvipdfmx+', `\verb+xetex+' and `\verb+bigfiles+', the options Option `\verb+bigfiles+' is only relevant for the \verb+latex+ $\rightarrow$ \verb+dvips+ $\rightarrow$ \verb+ps2pdf+ workflow. It may be needed if large media files cause \verb+latex+ to abort with error `\verb+TeX capacity exceeded+'. See Sect.\ \ref{bugs}. \section{The user interface} -Package `media9' provides the command +Package `media9' provides commands for media inclusion (\verb+\includemedia+) and insertion of media control buttons (\verb+\mediabutton+). The latter is introduced in Sect. \ref{mbtn}. + +\subsection{Media inclusion} \begin{verbatim} \includemedia[<options>]{<poster text>}{ <main Flash (SWF) file or URL | 3D (PRC, U3D) file>} \end{verbatim} -Its last argument, \verb+<main Flash (SWF) file or URL | 3D (PRC, U3D) file>+, is the main interactive application to be inserted into the PDF. In case of Flash, this can be a local SWF file, or a URL, such as a YouTube video. A local file will become part of the final PDF file, while Flash content from a URL requires an internet connection when the user activates it in Adobe Reader. As for 3D content, Adobe Reader only supports U3D or PRC files embedded in the PDF; they cannot be loaded or streamed during runtime. The most frequent use of \verb+\includemedia+ will likely be embedding video or sound files for playback in Adobe Reader. For this we need some media player, which is an SWF file we embed as our main application. It will be configured to load, upon activation, a particular video or sound file that was embedded as a resource into the PDF or is to be streamed from the internet. This will be shown later. Note that a local file (main application or resource) will only once be physically embedded in order to keep final PDF file size small. If the same file (identified by MD5 checksum) appears in other \verb+\includemedia+ commands, only a reference will be inserted that points to the same storage location in the PDF. + +The last, \verb+<main Flash (SWF) file or URL | 3D (PRC, U3D) file>+, is the main interactive application to be inserted into the PDF. In case of Flash, this can be a local SWF file, or a URL, such as a YouTube video. A local file will become part of the final PDF file, while Flash content from a URL requires an internet connection when the user activates it in Adobe Reader. As for 3D content, Adobe Reader only supports U3D or PRC files embedded in the PDF; they cannot be loaded or streamed during runtime. The most frequent use of \verb+\includemedia+ will likely be embedding video or sound files for playback in Adobe Reader. For this we need some media player, which is an SWF file we embed as our main application. It will be configured to load, upon activation, a particular video or sound file that was embedded as a resource into the PDF or is to be streamed from the internet. This will be shown later. Note that a local file (main application or resource) will only once be physically embedded in order to keep final PDF file size small. If the same file (identified by MD5 checksum) appears in other \verb+\includemedia+ commands, only a reference will be inserted that points to the same storage location in the PDF. Argument \verb+<poster text>+ defines the size of the rectangular region of the document page in which the media will be displayed. Moreover, \verb+<poster text>+ will be shown in case the media has not been activated. %(Internally, \verb+<poster text>+ is put into a \LaTeX{} box, which is used as the appearance of the PDF annotation, i.\,e. the interactive region created by \verb+\includemedia+, in PDF specification parlance.) @@ -191,7 +194,7 @@ This command appends one directory at a time to the search list. To specify more The following section explains all command options provided. They are passed to the media inclusion command as a comma separated list enclosed in a pair of square brackets. -\section{Command options} +\subsection{Command options} A subset of the command options (see Sect. \ref{pkguse}) can also be used as package options, which lets them apply to all embedded media. Some of the options listed here are meaningful only for a specific media type (either Flash or 3D), which will be noted explicitly if not obvious. Dedicated sections covering Flash, video and sound as well as 3D inclusion will follow later on in this document. \begin{verbatim} @@ -202,9 +205,9 @@ depth=<depth> Resize the media playback area, overriding the original dimensions of the {\tt<poster text>} argument. Option `\verb+depth+' specifies how far the playback area should extend below the base line of the running text. If only one of `\verb+width+' or `\verb+height+' is given, the other dimension is scaled to maintain the aspect ratio of \verb+<poster text>+. Any valid \TeX{} dimension is accepted as a parameter. In addition, the length commands \verb+\width+, \verb+\height+, \verb+\depth+ and \verb+\totalheight+ can be used to refer to the original dimensions of \verb+<poster text>+. \begin{verbatim} -label=<label string> +label=<label key> \end{verbatim} -The media annotation is given a label, \verb+<label string>+, which should be unique. This option defines JavaScript reference \verb+annotRM['<label string>']+ for easy accessing the media annotation object from within JavaScript. Note that the reference is known only after the first opening of the page containing the media. For an example, see Fig.~\ref{videoa}. +The media annotation is given a label, \verb+<label key>+, which should be unique. Labelled media annotations can be targeted by the media actions of a control button (see description of the \verb+\mediabutton+ command in Sect. ~\ref{mbtn}). Moreover, a reference to the RichMedia Annotation object (of type `\verb+AnnotRichMedia+') is assigned to the JavaScript variable \verb+annotRM['<label key>']+ in order to facilitate its access in JavaScript. Note that the JavaScript reference is known only after the first opening of the page containing the media. \begin{verbatim} scale=<factor> @@ -334,6 +337,7 @@ Sets the default render mode. The following values are honoured: `\verb+Solid+', When the user selects another view from the list of predefined views (see option `\verb+3Dviews+'), attributes of individual parts, such as opacity, visibility, render mode, translation in space, which all can be set from within the Reader or by means of a file of predefined views, are reset to their original states as defined in the embedded 3D file, before any new part settings are applied. This default behaviour can be overridden by `\verb+3Dpartsattrs=keep+'. This will preserve current part attributes when the user selects another predefined 3D view in the Reader. +\hypertarget{3Dviews}{}% \begin{verbatim} 3Dviews=<views file> \end{verbatim} @@ -397,6 +401,7 @@ A non-negative \verb+<integer number>+ represents the number of times the animat 3Dplayspeed=<positive number> \end{verbatim} This option can be used to adjust the keyframe animation speed. A value of `1' corresponds to the default speed defined in the 3D file. +\hypertarget{add3Djscript}{}% \begin{verbatim} add3Djscript=<3D JavaScript file>, add3Djscript=<another 3D JavaScript file>, @@ -462,7 +467,39 @@ Things like animation, lighting, background of 3D objects etc. may also be scrip \end{tabular} \end{table} -\clearpage +\subsection{Control buttons}\label{mbtn} +\begin{verbatim} +\mediabutton[<options>]{<normal button text or graphic>} +\end{verbatim} +This command inserts a clickable button for media control. Actions to be performed are specified through options `\verb+mediacommand+', `\verb+3Dgotoview+' and `\verb+jsaction+'. By using these options repeatedly and in any combination, several actions can be bound to one media button, and one media button can be used to control several media at the same time. Media actions are started in the given order but performed in parallel, because they do not wait for each other to finish. The target of an action is specified via the label key that was also given to a particular media by the `\verb+label+' option of `\verb+\includemedia+'. Individual button faces can be defined for the `mouse-over' and `mouse-button-down' events using the `\verb+overface+' and `\verb+downface+' options. Without options, the button produced does nothing. The options provided are as follows: + +\begin{verbatim} +overface=<mouse-over text or graphic> +\end{verbatim} +If specified, the media button changes its appearance when the mouse pointer is moved over it. Without this option, the button appearance does not change. An \verb+\includegraphics+ command may need to be enclosed in braces. + +\begin{verbatim} +downface=<mouse-button-down text or graphic> +\end{verbatim} +If specified, the media button changes its appearance when the mouse button is pressed while the pointer is over it. Without this option, the pressed button is visualized by colour inversion of the normal button appearance. An \verb+\includegraphics+ command may need to be enclosed in braces. + +\begin{verbatim} +3Dgotoview=<label key>[:<view specification>] +\end{verbatim} +Selects a view from the list of predefined views associated with a 3D media inclusion (see option `\verb+3Dviews+'). The target media is specified by \verb+<label key>+, as defined by the `\verb+label+' option of `\verb+\includemedia+'. \verb+<label key>+ alone without a view specification simply activates the 3D object if not yet activated. {\tt<view specification>} which is separated from the label key by a colon (\verb+:+) can be one of the following: an integer specifying the zero-based index into the list of views in the 3D views file; one of `\verb+D+', `\verb+F+', `\verb+L+', `\verb+N+', `\verb+P+' indicating the default, first, last, next or previous view in the list of views; a string delimited by `\verb+(+' and `\verb+)+' matching the name of a view as specified by the `\verb+VIEW=...+' entry in the views file. The option can be given several times to simultaneously change the view in more than one 3D inclusion. However, it cannot be used to create an animation effect within the same 3D inclusion, because \verb+3Dgotoview+ actions are executed in parallel. +%For this, one may implement a 3D JavaScript function that is associated with the media button using the `\verb+mediacommand+' option. + +\begin{verbatim} +mediacommand=<label key>[:<command> [<arg1> <arg2> ...]] +\end{verbatim} +A media command \verb+<command>+, with arguments if required, is sent to a media inclusion identified by \verb+<label key>+, as defined by the `\verb+label+' option of `\verb+\includemedia+'. \verb+<label key>+ alone without a command specification simply activates the media, if not yet activated. The option can be multiply used within the same button to target different media inclusions at the same time or to execute several commands for the same media. Depending on the type of the target media (3D or Flash), \verb+<command>+ is either the name of a JavaScript function defined in a 3D JavaScript file associated with the 3D media (see option `\verb+add3Djscript+') or the name of an ActionScript function that was exposed by the embedded Flash file. ActionScript functions are exposed to the scripting context of the hosting document by using the \verb+ExternalInterface+ call within the Flash file. Arguments to be passed to \verb+<command>+ must be enclosed in `\verb+[+' and `\verb+]+' and separated by spaces. Arguments can be of Boolean type (\verb+true+, \verb+false+), numbers (integer, reals) and strings. String arguments must be passed as \verb+(string arg)+, i.\,e. enclosed in parentheses, while numbers and Booleans are passed as they are. Of course, the number of arguments and their types must match the definition of the function to be called. Media players VPlayer.swf and APlayer.swf shipping with media9 expose a number of ActionScript functions that can be used with this option (see Tab. \ref{AVPlayerMethods}). + +\begin{verbatim} +jsaction=[<label key>:]{<JavaScript code>} +\end{verbatim} +The JavaScript code is executed in the context of the document's instance of the JavaScript engine (there is one instance of the JavaScript engine per open document in Adobe Reader). \verb+<JavaScript code>+ is required and must be enclosed in braces. Unlike media actions defined with options `\verb+mediacommand+' and `\verb+3Dgotoview+', the JavaScript action defined here is not targeted at a particular embedded media and can be used to run arbitrary code. Therefore, \verb+<label key>+ is optional. If provided, it must be separated from \verb+<JavaScript code>+ by a colon. However, it is recommended to provide a label key. It ensures that \verb+annotRM['<label key>']+ is a valid JavaScript reference to the \verb+AnnotRichMedia+ object. \verb+annotRM['<label key>']+ can be used to get access to the global context of the annotation's instance of the 3D JavaScript engine (there is one instance of the 3D JavaScript engine per activated RichMedia Annotation with 3D content). The 3D JavaScript context of a 3D model can be accessed as \verb+annotRM['<label key>'].context3D+. Refer to the Acrobat 3D JavaScript Reference~\cite{jscript3D} for details on built-in JavaScript objects that are available in the 3D context. + +%\clearpage \section[Embedding Flash, video and sound (with examples)]{Embedding Flash, video and sound} A YouTube video clip, as shown in Fig.~\ref{alien}, may serve as a basic example of loading Flash content from a URL to be displayed in an embedded fashion in a PDF document. Indeed, a YouTube clip is nothing more than a small SWF file which loads a video stream and other necessary resources, such as user controls and a player skin from a remote server. It can be configured via ActionScript variables, to play several videos in a row, to play a video in a loop etc. Player parameters are documented on \url{http://code.google.com/apis/youtube/player_parameters.html} and can be passed to the player using either the `\verb+flashvars+' option, as in the example, or appended to the URL string after the video ID. A question mark `\verb+?+' must be put between the video ID and the parameter string. Some of the documented parameters, such as `\verb+rel+', seem to have an effect only if they are passed as part of the URL. @@ -511,10 +548,10 @@ Like YouTube videos, media players are configured via ActionScript variables whi Playback of embedded video files is shown in Fig.~\ref{videoa}. Besides embedded files, also video streamed from remote servers via HTTP and RTMP protocols is supported, as shown in Fig.~\ref{videob}. -`VPlayer.swf' and `APlayer.swf' expose a number of ActionScript functions to the JavaScript engine of Adobe Reader, allowing for playback control of media through PDF interactive forms and various trigger events. The functions and their calling convention are listed in Table~\ref{AVPlayerMethods}. An example of playing and pausing a video clip and setting the video source via interactive push buttons is given in Fig.~\ref{videoa}. +`VPlayer.swf' and `APlayer.swf' expose a number of ActionScript functions to the JavaScript engine of Adobe Reader, allowing for playback control of media through push buttons (see Sect. \ref{mbtn}) and various trigger events. The functions and their calling convention are listed in Table~\ref{AVPlayerMethods}. An example of playing and pausing a video clip and setting the video source via interactive push buttons is given in Fig.~\ref{videoa}. Sound files and streams in the MP3 format can be played with `APlayer.swf'. Fig.~\ref{radio} contains examples of an audio live stream and a remote MP3 sound file. In one of the sound examples, the player is loaded from a CTAN mirror during runtime because an internet connection is required anyway for streaming the audio. If a local sound file is to be embedded into the PDF this would have to be done in the same way as with the video file in one of the previous examples using the `\verb+addresource+' option. -\clearpage +%\clearpage \begin{table} \centering @@ -548,7 +585,7 @@ parameter & description\\\hline\hline \begin{table}[p] \centering -\caption{Exposed ActionScript functions of media players `VPlayer.swf' and `APlayer.swf', that can be called from JavaScript using the `{\tt callAS}' method of the `{\tt AnnotRichMedia}' JavaScript object. Calling convention: \hbox to \linewidth {\hss\tt <RMA reference>.callAS('<function>' [,'<argument>']);\hss} Function name and its argument must be given as quoted strings. See~\cite{jscript} for further information.}\label{AVPlayerMethods} +\caption{Exposed ActionScript functions of media players `VPlayer.swf' and `APlayer.swf', that can be called from within media buttons (see Sect. \ref{mbtn}) or from JavaScript using the `{\tt callAS}' method of the `{\tt AnnotRichMedia}' JavaScript object (see~\cite{jscript} for further information).}\label{AVPlayerMethods} \begin{tabular}[t]{lp{0.25\linewidth}p{0.5\linewidth}}\hline function & argument &description\\\hline\hline {\tt play} & & play media\\ @@ -590,7 +627,7 @@ parameter & description\\\hline\hline \centering \begin{Verbatim} \includemedia[ - label=some_dice, % defines JavaScript object annotRM['some_dice'] + label=some_dice, width=0.4\linewidth,height=0.3\linewidth, activate=pageopen, addresource=random.mp4, %two video files @@ -602,24 +639,17 @@ parameter & description\\\hline\hline } ]{}{VPlayer.swf} -\PushButton[ %requires package `hyperref' - onclick={ - annotRM['some_dice'].activated=true; - annotRM['some_dice'].callAS('playPause'); - } -]{\fbox{Play/Pause}} -\PushButton[ - onclick={ - annotRM['some_dice'].activated=true; - annotRM['some_dice'].callAS('setSource', 'random.mp4'); - } -]{\fbox{random.mp4}} -\PushButton[ - onclick={ - annotRM['some_dice'].activated=true; - annotRM['some_dice'].callAS('setSource', 'cube.mp4'); - } -]{\fbox{cube.mp4}} +\mediabutton[ + mediacommand=some_dice:playPause, + overface=\color{blue}{\fbox{\strut Play/Pause}}, + downface=\color{red}{\fbox{\strut Play/Pause}}, +]{\fbox{\strut Play/Pause}} +\mediabutton[ + mediacommand=some_dice:setSource [(random.mp4)], +]{\fbox{\strut random.mp4}} +\mediabutton[ + mediacommand=some_dice:setSource [(cube.mp4)], +]{\fbox{\strut cube.mp4}} \end{Verbatim} \vspace{1ex} \makebox[\linewidth]{\hfill\includemedia[ @@ -635,11 +665,19 @@ parameter & description\\\hline\hline } ]{}{VPlayer.swf}\hfill} \makebox[\linewidth]{\hfill% - \PushButton[onclick={annotRM['some_dice'].activated=true;annotRM['some_dice'].callAS('playPause');}]{\fbox{\strut Play/Pause}} - \PushButton[onclick={annotRM['some_dice'].activated=true;annotRM['some_dice'].callAS('setSource', 'random.mp4');}]{\fbox{\strut random.mp4}} - \PushButton[onclick={annotRM['some_dice'].activated=true;annotRM['some_dice'].callAS('setSource', 'cube.mp4');}]{\fbox{\strut cube.mp4}} +\mediabutton[ + mediacommand=some_dice:playPause, + overface=\color{blue}{\fbox{\strut Play/Pause}}, + downface=\color{red}{\fbox{\strut Play/Pause}}, +]{\fbox{\strut Play/Pause}} +\mediabutton[ + mediacommand=some_dice:setSource [(random.mp4)], +]{\fbox{\strut random.mp4}} +\mediabutton[ + mediacommand=some_dice:setSource [(cube.mp4)], +]{\fbox{\strut cube.mp4}} \hfill} -\caption{Example of playing back two different embedded MP4 video files in the same video player instance. The player, `VPlayer.swf', is also embedded in the PDF. Exposed ActionScript functions `{\tt playPause}' and `{\tt setSource}' of `VPlayer.swf' (Table~\ref{AVPlayerMethods}) are used to set-up the JavaScript actions of interactive push buttons.}\label{videoa} +\caption{Example of playing back two different embedded MP4 video files in the same video player instance. The player, `VPlayer.swf', is also embedded in the PDF. Exposed ActionScript functions `{\tt playPause}' and `{\tt setSource}' of `VPlayer.swf' (Table~\ref{AVPlayerMethods}) are used to set-up media control buttons. Different button faces have been defined for the Play/Pause button.}\label{videoa} \end{figure} \begin{figure}[p] @@ -774,17 +812,22 @@ Below, several examples of embedded 3D files are shown. The first one, Fig.~\ref \end{figure} \begin{figure}[bp] -\begin{Verbatim} +\begin{Verbatim}[fontsize=\footnotesize] \includemedia[ + label=dice, width=0.5\linewidth,height=0.5\linewidth, activate=pageopen, 3Dtoolbar, 3Dmenu, 3Dviews=dice.vws, ]{}{dice.u3d} + +\mediabutton[3Dgotoview=dice:N]{\fbox{Next view}} +\mediabutton[3Dgotoview=dice:(Back)]{\fbox{View `Back'}} +\mediabutton[3Dgotoview=dice:5]{\fbox{6th view in the list}} \end{Verbatim} \vspace{1ex} Contents of `dice.vws': -\begin{Verbatim}[fontsize=\small] +\begin{Verbatim}[fontsize=\footnotesize] VIEW=Front ROO=27 END @@ -813,14 +856,18 @@ Contents of `dice.vws': END \end{Verbatim} \centering -\includemedia[ +\raisebox{-0.7\height}{\includemedia[ + label=dice, width=0.5\linewidth,height=0.5\linewidth, activate=pageopen, 3Dtoolbar, 3Dviews=dice.vws, 3Dmenu, -]{}{dice.u3d} -\caption{Embedded U3D file, based on a VRML model by Peter Whitehouse, \url{http://www.wonko.info/vrml/index.htm}; conversion to U3D was done using DeepExploration\textsuperscript{\scriptsize\textregistered}\cite{dexp}. The file `{\tt dice.vws}' provides predefined views to be selected from the 3D toolbar or by right click.}\label{u3dex} +]{}{dice.u3d}}\quad\parbox[t]{0.4\linewidth}{% +\mediabutton[3Dgotoview=dice:N]{\fbox{Next view}}\\ +\mediabutton[3Dgotoview=dice:(Back)]{\fbox{View `Back'}}\\ +\mediabutton[3Dgotoview=dice:5]{\fbox{6th view in the list}}} +\caption{Embedded U3D file, based on a VRML model by Peter Whitehouse, \url{http://www.wonko.info/vrml/index.htm}; conversion to U3D was done using DeepExploration\textsuperscript{\scriptsize\textregistered}\cite{dexp}. The file `{\tt dice.vws}' provides predefined views. Buttons are created with {\tt\string\mediabutton} using the `{\tt 3Dgotoview}' option.}\label{u3dex} \end{figure} \begin{figure} @@ -836,26 +883,26 @@ Contents of `dice.vws': add3Djscript=malte.js ]{}{malte.u3d} - \PushButton[ - onclick={annotRM['malte'].context3D.cntrClockWise();} + \mediabutton[ + jsaction=malte:{annotRM['malte'].context3D.cntrClockWise();} ]{\includegraphics[height=1.44em]{boutona}} - \PushButton[ - onclick={annotRM['malte'].context3D.pause();} + \mediabutton[ + jsaction=malte:{annotRM['malte'].context3D.pause();} ]{\includegraphics[height=1.44em]{boutonb}} - \PushButton[ - onclick={annotRM['malte'].context3D.clockWise();} + \mediabutton[ + jsaction=malte:{annotRM['malte'].context3D.clockWise();} ]{\includegraphics[height=1.44em]{boutonc}} \hspace{1em} - \PushButton[ - onclick={annotRM['malte'].context3D.slower();} + \mediabutton[ + jsaction=malte:{annotRM['malte'].context3D.scaleSpeed(1/1.1);} ]{\includegraphics[height=1.44em]{boutond}} - \PushButton[ - onclick={annotRM['malte'].context3D.origSpeed();} + \mediabutton[ + jsaction=malte:{annotRM['malte'].context3D.origSpeed();} ]{\includegraphics[height=1.44em]{boutone}} - \PushButton[ - onclick={annotRM['malte'].context3D.faster();} + \mediabutton[ + jsaction=malte:{annotRM['malte'].context3D.scaleSpeed(1.1);} ]{\includegraphics[height=1.44em]{boutonf}} - \end{Verbatim} + \end{Verbatim} \centering \includemedia[ label=malte, @@ -868,14 +915,33 @@ Contents of `dice.vws': add3Djscript=malte.js ]{}{malte.u3d} - \PushButton[onclick={annotRM['malte'].context3D.cntrClockWise();}]{\includegraphics[height=1.44em]{boutona}} - \PushButton[onclick={annotRM['malte'].context3D.pause();}]{\includegraphics[height=1.44em]{boutonb}} - \PushButton[onclick={annotRM['malte'].context3D.clockWise();}]{\includegraphics[height=1.44em]{boutonc}} + \mediabutton[jsaction=malte:{annotRM['malte'].context3D.cntrClockWise();}]{\includegraphics[height=1.44em]{boutona}} + \mediabutton[jsaction=malte:{annotRM['malte'].context3D.pause();}]{\includegraphics[height=1.44em]{boutonb}} + \mediabutton[jsaction=malte:{annotRM['malte'].context3D.clockWise();}]{\includegraphics[height=1.44em]{boutonc}} \hspace{1em} - \PushButton[onclick={annotRM['malte'].context3D.slower();}]{\includegraphics[height=1.44em]{boutond}} - \PushButton[onclick={annotRM['malte'].context3D.origSpeed();}]{\includegraphics[height=1.44em]{boutone}} - \PushButton[onclick={annotRM['malte'].context3D.faster();}]{\includegraphics[height=1.44em]{boutonf}} - \caption{Animated U3D example of a Maltese drive contributed by Jean-Luc Chesnot. The animation is defined in the JavaScript file `{\tt malte.js}'.}\label{u3dex2} + \mediabutton[jsaction=malte:{annotRM['malte'].context3D.scaleSpeed(1/1.1);}]{\includegraphics[height=1.44em]{boutond}} + \mediabutton[jsaction=malte:{annotRM['malte'].context3D.origSpeed();}]{\includegraphics[height=1.44em]{boutone}} + \mediabutton[jsaction=malte:{annotRM['malte'].context3D.scaleSpeed(1.1);}]{\includegraphics[height=1.44em]{boutonf}} +% \mediabutton[ +% mediacommand=malte:cntrClockWise +% ]{\includegraphics[height=1.44em]{boutona}} +% \mediabutton[ +% mediacommand=malte:pause +% ]{\includegraphics[height=1.44em]{boutonb}} +% \mediabutton[ +% mediacommand=malte:clockWise +% ]{\includegraphics[height=1.44em]{boutonc}} +% \hspace{1em} +% \mediabutton[ +% mediacommand=malte:scaleSpeed [0.91] +% ]{\includegraphics[height=1.44em]{boutond}} +% \mediabutton[ +% mediacommand=malte:origSpeed +% ]{\includegraphics[height=1.44em]{boutone}} +% \mediabutton[ +% mediacommand=malte:scaleSpeed [1.1] +% ]{\includegraphics[height=1.44em]{boutonf}} + \caption{Animated U3D example of a Maltese drive contributed by Jean-Luc Chesnot. The animation and the functions called in the JavaScript actions of the media buttons are defined in the JavaScript file `{\tt malte.js}'.}\label{u3dex2} \end{figure} \clearpage \subsection{3D quick-start guide}\label{sec:3Dtut} @@ -918,7 +984,7 @@ Contents of `dice.vws': 3Dmenu ]{}{myfile.u3d} \end{Verbatim} - If you are satisfied with the predefined views in the views file, the default view first specified through the options of {\tt\string\includemovie} can be deleted. The first view in the views file becomes the default view then. + If you are satisfied with the predefined views in the views file, the default view first specified through the options of {\tt\string\includemedia} can be deleted. The first view in the views file becomes the default view then. \end{itemize} \item Associate any number of 3D JavaScript files with the 3D object: \begin{Verbatim} diff --git a/Master/texmf-dist/tex/latex/media9/media9.sty b/Master/texmf-dist/tex/latex/media9/media9.sty index 3acd29c393a..93dfbedbe82 100644 --- a/Master/texmf-dist/tex/latex/media9/media9.sty +++ b/Master/texmf-dist/tex/latex/media9/media9.sty @@ -35,12 +35,14 @@ % The Current Maintainer of this work is A. Grahn. \RequirePackage{expl3} -\RequirePackage{xparse} +\RequirePackage{l3regex} \RequirePackage{l3keys2e} +\RequirePackage{xparse} \RequirePackage{ifpdf} +\RequirePackage{atbegshi} -\def\g@mix@date@tl{2013/01/23} -\def\g@mix@version@tl{0.21} +\def\g@mix@date@tl{2013/01/31} +\def\g@mix@version@tl{0.22} \def\g@mix@liiikerneldate{2012/07/16} \def\g@mix@liiipkgdate{2012/07/16} @@ -81,9 +83,6 @@ %testing for PDF output \bool_new:N\g_mix_pdfoutput_bool \bool_gset_false:N\g_mix_pdfoutput_bool -%\cs_if_exist:NT\pdfoutput{ -% \int_compare:nT{\pdfoutput>0}{\bool_gset_true:N\g_mix_pdfoutput_bool} -%} \ifpdf \bool_gset_true:N\g_mix_pdfoutput_bool \fi %pdfTeX version check @@ -238,6 +237,10 @@ \int_new:N\g_mix_rmcnt_int \int_new:N\l_mix_viewcnt_int %counter for 3D views per annot +\int_new:N\g@mix@page@int %abs. page counter (zero based) +\int_gset:Nn\g@mix@page@int{\c_minus_one} +\AtBeginShipout{\int_gincr:N\g@mix@page@int} + \bool_new:N\g_mix_url_bool \bool_new:N\l_mix_url_bool \bool_new:N\g_mix_iiidcalc_bool @@ -283,6 +286,16 @@ %macros for writing global defs to \jobname.aux \msg_set:nnn{media9}{rerun}{Rerun~to~get~media~labels~right!} +\msg_set:nnn{media9}{undefined~reference}{ + Line~\msg_line_number: :~Media~reference~`#1'~not~defined. +} +\msg_set:nnn{media9}{undefined~references}{ + There~were~undefined~media~references!} +\msg_set:nnn{media9}{same~label}{ + Line~\msg_line_number: :~Label~`#1'~multiply~defined. +} +\msg_set:nnn{media9}{multiple~labels}{There~were~multiply-defined~labels!} + \cs_gset:Nn\mix_keytoaux_now:nn{ \iow_now:Nx\@auxout{\token_to_str:N\mix@newkey{#1}{#2}} \bool_if:nF{ @@ -1057,6 +1070,9 @@ \tl_gtrim_spaces:N\g_mix_flashvars_tl \mix_scale:n{\l_mix_poster_box} \bool_if:NTF\g_mix_usrdraft_bool{ + \tl_if_empty:NF\g_mix_usrlabel_tl{ + \mix_keytoaux_now:nn{ann@\g_mix_usrlabel_tl}{draft} + } \mix_draftbox:n{\tl_to_str:n{#3}} }{ %embed main asset @@ -1249,11 +1265,15 @@ } \tl_if_empty:NF\g_mix_usrlabel_tl{ \mix_keytoaux_now:nn{ann@\g_mix_usrlabel_tl}{\g_mix_pdflastann_tl} + \mix_keytoaux_shipout:nn{page@\g_mix_usrlabel_tl}{ + \noexpand\the\g@mix@page@int} \mix_pdfobj:nnn{}{dict}{ /S/JavaScript/JS~( if(typeof(annotRM)=='undefined'){annotRM=new~Array();} - annotRM['\g_mix_label_tl']= - this.getAnnotRichMedia(this.pageNum,~'\g_mix_label_tl'); + if(typeof(annotRM['\g_mix_label_tl'])=='undefined'){ + annotRM['\g_mix_label_tl']= + this.getAnnotRichMedia(this.pageNum,'\g_mix_label_tl'); + } ) } \mix_pdfannot:nnnn{0pt}{0pt}{0pt}{ @@ -1428,7 +1448,7 @@ /NA~[\l_mix_naarray_tl] /SA~[\l_mix_saarray_tl] \l_mix_bg_tl\l_mix_ls_tl\l_mix_rm_tl - /XN~(#1) + /XN~(#1)/IN~(#1) } } @@ -1453,12 +1473,6 @@ perhaps~it~is~spelled~incorrectly. } -\msg_set:nnn{media9}{same~label}{ - Line~\msg_line_number: :~Label~`#1'~multiply~defined. -} - -\msg_set:nnn{media9}{multiple~labels}{ There~were~multiply-defined~labels!} - \bool_new:N\g_mix_usrdraft_bool \bool_new:N\g_mix_opt_iiidview_bool \bool_new:N\l_mix_roo_bool @@ -1476,6 +1490,7 @@ %user override automatic label label .code:n = { \tl_gset:Nx\g_mix_usrlabel_tl{#1} + \tl_gtrim_spaces:N\g_mix_usrlabel_tl \cs_if_exist:cTF{rm@#1}{ \msg_warning:nnx{media9}{same~label}{#1} \cs_if_exist:NF\g_mix_samelabel_tl{ @@ -1802,6 +1817,7 @@ \tl_set:Nn\l_mix_level_tl{\c_zero} \tl_set:Nn\l_mix_cscount_tl{\c_zero} \tl_set:Nx\l_mix_xname_tl{#1}%optional name of the view + \tl_trim_spaces:N\l_mix_xname_tl %reset 3D settings to defaults \mix_iiidreset: }, @@ -2117,24 +2133,174 @@ } %options for \mediabutton command + +%helpers for option parsing +\cs_new:Npn\mix_separate_cmd_from_actn:w#1[#2]#3\q_stop{#1} +\cs_new:Npn\mix_separate_arg_from_actn:w#1[#2]#3\q_stop{#2} +\cs_generate_variant:Nn\regex_match:nnTF{nV} +\cs_generate_variant:Nn\tl_if_blank:nF{c} + \keys_define:nn{media9/mbtn}{ overface .code:n = { - \hbox_set:Nn\l_tmpa_box{#1} - \mix_pdfxform:n{\l_tmpa_box} + \hbox_set:Nn\l_mix_poster_box{#1} + \mix_pdfxform:n{\l_mix_poster_box} \tl_gset:Nx\g_mix_overbtn_tl{\g_mix_pdflastxform_tl} }, overface .value_required:, downface .code:n = { - \hbox_set:Nn\l_tmpa_box{#1} - \mix_pdfxform:n{\l_tmpa_box} + \hbox_set:Nn\l_mix_poster_box{#1} + \mix_pdfxform:n{\l_mix_poster_box} \tl_gset:Nx\g_mix_downbtn_tl{\g_mix_pdflastxform_tl} }, downface .value_required:, - 3Dviewindex .code:n ={ + 3Dgotoview .code:n = { + \tl_set:Nx\l_tmpa_tl{#1} %extract ref + \regex_replace_once:nnN{([^:]+):??.*}{\1}\l_tmpa_tl + \tl_trim_spaces:N\l_tmpa_tl + \tl_if_exist:cTF{ann@\l_tmpa_tl}{ + \str_if_eq_x:nnF{\tl_use:c{ann@\l_tmpa_tl}}{draft}{ + \tl_set:Nx\l_tmpb_tl{#1} %extract idx + \regex_replace_once:nnN{[^:]+:?}{}\l_tmpb_tl + \tl_trim_spaces:N\l_tmpb_tl + \tl_if_blank:VF\l_tmpb_tl{ + \regex_match:nVTF{^[DFLNP]$}\l_tmpb_tl{ + \tl_set:Nx\l_mix_vidx_tl{/\l_tmpb_tl} + }{ + \regex_match:nVTF{^\d+$}\l_tmpb_tl{ + \tl_set:Nx\l_mix_vidx_tl{~\l_tmpb_tl} + }{ + \regex_replace_once:nnN{^\(\s*}{}\l_tmpb_tl + \regex_replace_once:nnN{\s*\)$}{}\l_tmpb_tl + \tl_set:Nx\l_mix_vidx_tl{~(\l_tmpb_tl)} + } + } + } + \mix_pdfobj:nnn{}{dict}{ + /S/JavaScript/JS~( + if(typeof(annotRM)=='undefined'){annotRM=new~Array();} + if(typeof(annotRM['\l_tmpa_tl'])=='undefined'){ + annotRM['\l_tmpa_tl']= + this.getAnnotRichMedia(\tl_use:c{page@\l_tmpa_tl},'\l_tmpa_tl'); + } + annotRM['\l_tmpa_tl'].activated=true; + ) + \tl_if_blank:VF\l_tmpb_tl{ + /Next~<< + /S/GoTo3DView + /TA~\tl_use:c{ann@\l_tmpa_tl} + /V\l_mix_vidx_tl + >> + } + } + \tl_gput_right:Nx\g_mix_btnactions_tl{~\g_mix_pdflastobj_tl} + } + }{ + \msg_warning:nnx{media9}{undefined~reference}{\l_tmpa_tl} + \cs_if_exist:NF\g_mix_refundefwarned_tl{ + \tl_new:N\g_mix_refundefwarned_tl + \AtEndDocument{\msg_warning:nn{media9}{undefined~references}} + } + } + }, + 3Dgotoview .value_required:, + + mediacommand .code:n = { + \tl_set:Nx\l_tmpa_tl{#1} + \regex_replace_once:nnN{([^:]+):??.*}{\1}\l_tmpa_tl %extract ref + \tl_trim_spaces:N\l_tmpa_tl + \tl_if_exist:cTF{ann@\l_tmpa_tl}{ + \str_if_eq_x:nnF{\tl_use:c{ann@\l_tmpa_tl}}{draft}{ + \tl_set:Nx\l_tmpb_tl{#1} + \regex_replace_once:nnN{[^:]+\:?}{}\l_tmpb_tl + \tl_set:Nx\l_mix_cmd_tl{ + \exp_after:wN\mix_separate_cmd_from_actn:w\l_tmpb_tl[]\q_stop} + \tl_trim_spaces:N\l_mix_cmd_tl + \tl_set:Nx\l_mix_arg_tl{ + \exp_after:wN\mix_separate_arg_from_actn:w\l_tmpb_tl[]\q_stop} + \tl_trim_spaces:N\l_mix_arg_tl + \mix_pdfobj:nnn{}{dict}{ + /S/JavaScript/JS~( + if(typeof(annotRM)=='undefined'){annotRM=new~Array();} + if(typeof(annotRM['\l_tmpa_tl'])=='undefined'){ + annotRM['\l_tmpa_tl']= + this.getAnnotRichMedia(\tl_use:c{page@\l_tmpa_tl},'\l_tmpa_tl'); + } + annotRM['\l_tmpa_tl'].activated=true; + ) + \tl_if_blank:VF\l_mix_cmd_tl{ + /Next~<< + /S/RichMediaExecute + /TA~\tl_use:c{ann@\l_tmpa_tl} + /TI~\tl_use:c{main@\l_tmpa_tl} + /CMD~<< + /C~(\l_mix_cmd_tl) + \tl_if_blank:VF\l_mix_arg_tl{ + /A~[\l_mix_arg_tl] + } + >> + >> + } + } + \tl_gput_right:Nx\g_mix_btnactions_tl{~\g_mix_pdflastobj_tl} + } + }{ + \msg_warning:nnx{media9}{undefined~reference}{\l_tmpa_tl} + \cs_if_exist:NF\g_mix_refundefwarned_tl{ + \tl_new:N\g_mix_refundefwarned_tl + \AtEndDocument{\msg_warning:nn{media9}{undefined~references}} + } + } + }, + mediacommand .value_required:, + + jsaction .code:n = { + \tl_set:Nx\l_tmpa_tl{#1} + \regex_match:nVTF{^[^\{:]+:.*$}\l_tmpa_tl{ + \regex_replace_once:nnN{([^:]+):??.*}{\1}\l_tmpa_tl %extract ref + \tl_trim_spaces:N\l_tmpa_tl + }{\tl_clear:N\l_tmpa_tl} + \tl_set:Nx\l_tmpb_tl{#1} + \tl_if_blank:VF\l_tmpa_tl{ + \tl_if_exist:cF{ann@\l_tmpa_tl}{ + \msg_warning:nnx{media9}{undefined~reference}{\l_tmpa_tl} + \cs_if_exist:NF\g_mix_refundefwarned_tl{ + \tl_new:N\g_mix_refundefwarned_tl + \AtEndDocument{\msg_warning:nn{media9}{undefined~references}} + } + } + \regex_replace_once:nnN{[^:]+\:}{}\l_tmpb_tl + } + \tl_set:Nx\l_tmpb_tl{\exp_after:wN\use:n\l_tmpb_tl} + \tl_trim_spaces:N\l_tmpb_tl + \tl_if_blank:VF\l_tmpb_tl{ + \mix_pdfobj:nnn{}{dict}{/S/JavaScript/JS~(try{\l_tmpb_tl}catch(e){})}} + \bool_if:nT{ + \tl_if_exist_p:c{ann@\l_tmpa_tl}&& + !\str_if_eq_x_p:nn{\tl_use:c{ann@\l_tmpa_tl}}{draft} + }{ + \mix_pdfobj:nnn{}{dict}{ + /S/JavaScript/JS~( + if(typeof(annotRM)=='undefined'){annotRM=new~Array();} + if(typeof(annotRM['\l_tmpa_tl'])=='undefined'){ + annotRM['\l_tmpa_tl']= + this.getAnnotRichMedia(\tl_use:c{page@\l_tmpa_tl},'\l_tmpa_tl'); + } + annotRM['\l_tmpa_tl'].activated=true; + ) + \tl_if_blank:VF\l_tmpb_tl{/Next~\g_mix_pdflastobj_tl} + } + } + \bool_if:nT{ + \tl_if_exist_p:c{ann@\l_tmpa_tl}&& + !\str_if_eq_x_p:nn{\tl_use:c{ann@\l_tmpa_tl}}{draft}|| + !\tl_if_blank_p:V\l_tmpb_tl + }{ + \tl_gput_right:Nx\g_mix_btnactions_tl{~\g_mix_pdflastobj_tl} + } }, - 3Dviewindex .value_required:, + jsaction .value_required:, unknown .code:n = { \msg_error:nnx{media9}{unknown~option}{\l_keys_key_tl} @@ -2155,11 +2321,11 @@ \keys_set:nn{media9/mbtn}{#1} \mix_uriend: %normal button appearance - \hbox_set:Nn\l_tmpa_box{#2} - \tl_set:Nx\width {\dim_use:N\box_wd:N\l_tmpa_box} - \tl_set:Nx\height{\dim_use:N\box_ht:N\l_tmpa_box} - \tl_set:Nx\depth {\dim_use:N\box_dp:N\l_tmpa_box} - \mix_pdfxform:n{\l_tmpa_box} + \hbox_set:Nn\l_mix_poster_box{#2} + \tl_set:Nx\width {\dim_use:N\box_wd:N\l_mix_poster_box} + \tl_set:Nx\height{\dim_use:N\box_ht:N\l_mix_poster_box} + \tl_set:Nx\depth {\dim_use:N\box_dp:N\l_mix_poster_box} + \mix_pdfxform:n{\l_mix_poster_box} \tl_set:Nx\g_mix_normalbtn_tl{\g_mix_pdflastxform_tl} %insert widget annotation \mix_pdfannot:nnnn{\width}{\height}{\depth}{ |