6 The advi.sty L^AT_EX package

Active-DVI provides some L^AT_EX packages to facilitate animations and interaction with the presenter from within your L^AT_EX source text.

The advi.sty package is the main package to include when writing a presentation for Active-DVI. It defines the main set of interactive commands for Active-DVI to animate the show. However, there is no need to load the package if no Active-DVI special effects are required for the presentation.

Warning!

Most commands of advi.sty use the T_EX \special command to insert into the DVI output file the Active-DVI specific commands that implement their semantics. Those commands are interpreted by Active-DVI afterwhile during the DVI file previewing. Note that a \special{bla bla} command is equivalent to a \hbox{} for T_EX’s mouth, hence it may alter the document layout accordingly. Thus, be aware that most commands of the advi.sty package are equivalent to a \hbox{} command as far as the document layout is concerned.

6.1 Printing the presentation

The advi.sty package recognizes the special option ignore, which helps the production of a printable version of the presentation: the ignore option makes the package not to produce Active-DVI specials, so that the show can be previewed by other DVI previewers or turned into Postscript using dvips. Of course, this option disables most effects that cannot be printed, although some of them are still approximated.

If the ignore option is not set globally, it can be set locally with the commands \adviignore. However, this will not prevent all effects, since some decisions are taken when the package is loaded.

The package also defines the conditional \ifadvi which evaluates its first argument if advi is not in ignore mode and its second argument otherwise.

6.2 Pauses

Active-DVI provides partial display of pages (slide “strip-tease”): the Active-DVI’s rendering engine stops before the display of the current page is complete. The corresponding state is named a pause. Upon reaching a pause, Active-DVI may wait for a specified delay, or for user input. \adviwait[⟨ seconds⟩]

Wait for ⟨ seconds⟩. If no argument is provided, waits until the user requests to continue (hitting a key to move to next pause or to change page).

6.3 Active-DVI records

Active-DVI allows (almost) any piece of L^AT_EX code to be recorded, and the corresponding DVI code to be rendered later upon request. To be able to render the code in any order we choose, we must bind the recorded L^AT_EX code to a name (called a tag): this L^AT_EX code together with its tag defines the notion of an Active-DVI record.

Warning!

The entire DVI image of an Active-DVI record must fit on a single DVI page. The corresponding check is left to the writer of the document.

The command defining an Active-DVI record is as follows: \advirecord[play]{⟨ tag⟩}{⟨ latex code⟩}
\begin{advirecording}[play]{⟨ tag⟩}{⟨ latex code⟩}⟨ text⟩\end{advirecording}

This command processes ⟨ latex code⟩ and records the corresponding DVI output, then binds it to the tag ⟨ tag⟩. While recording, the DVI output is not displayed, unless the option play is set.

Active-DVI records may be nested. In this case, the inner record is bound to its own tag as usual; in addition, if the inner record is defined with the play option, it is also recorded as a part of the outer tag record.

If the environment syntax form of Active-DVI record definition is used, the ⟨ latex code⟩ may contain fragile commands.

To play an Active-DVI record, the corresponding DVI must have been recorded on the current DVI page and before issuing the play command. With the proviso that these requirements are satisfied, the syntax of the command to display an Active-DVI record is as follows: \adviplay[⟨ color⟩]{⟨ tag⟩}

This command plays the DVI code previously recorded and bound to ⟨ tag⟩.

The optional argument changes the text color to ⟨ color⟩ during replay.

6.4 Active-DVI anchors

Active-DVI gives the ability to define Active-DVI anchors: an anchor is specified by (1) an Active-DVI record, (2) a L^AT_EX piece of code that defines the area of the page where the anchor is active, and (3) an activation method.

The anchor is activated when some mouse events specified by the activation method occur in the area. The anchor is de-activated when the event that triggered the activation does not hold any more.

The Active-DVI record associated with the anchor is automatically rendered anew each time the anchor is activated. The page is reset to its original appearance when the anchor is de-activated.

The activation method of an anchor may be either over or click. If the activation method is over, the anchor is activated whenever the mouse pointer is inside the anchor area; conversely, the anchor is de-activated when the mouse leaves the anchor area. If the activation method is click, the anchor is activated whenever the button is pressed inside the anchor area; conversely, the anchor is de-activated when the button is released. \advianchor[⟨ activation⟩]{⟨ tag⟩}{⟨ text⟩}
\begin{advianchoring}[⟨ activation⟩]{⟨ tag⟩}⟨ text⟩\end{advianchoring}

This command defines the DVI rendering of {⟨ text⟩} as an Active-DVI anchor area that plays the Active-DVI record bound to ⟨ tag⟩ when the anchor is activated.

The argument ⟨ activation⟩ specifies the activation method of the anchor.

If the environment syntax form is used, ⟨ text⟩ may contain fragile commands.

6.5 Images

Images can be encapsulated into the presentation using the Caml library CamlImages provided with the distribution of Active-DVI (see section ‍8.4).

Images can be lighten by specifying an alpha value (a floating point number between 0 and 1) that measures the mixing between the background and the image.

Images can also be blended, meaning that you can choose the algorithm that superimposes the image to the background. Blending modes are reminiscent of the Ghostscript blending options: the blend mode must be one of the following: normal, multiply, screen, overlay, dodge, burn, darken, lighten, difference, exclusion, (none means unset).

{\setblend{burn}
  {\setalpha{0.5}
    {\includegraphics[width = 0.7\textwidth]{bar.eps}}}}

6.6 Colors

The color L^AT_EX package

In Active-DVI, colors can be specified with the conventions of the L^AT_EX package color.sty, that is, it should either be a previously defined color or a specification of the form [⟨ model⟩] {⟨ model color specification⟩}.

For example, the following specifications are all correct:

\color{blue}
\color[named]{Yellow}
\color[rgb]{0.7,0.3,0.8}

Named colors

Colors can be named using the keyword ⟨ named⟩. If you use named colors, the color names are case sensitive and should generally be capitalized; for instance: \color[named]{White} specifies the white color. Hence, \color[named]{Red}{some text} writes some text in red.

The names of available colors can be found in the dvipsnam.def file, generally at location
/usr/share/texmf/tex/latex/graphics/dvipsnam.def.

To give an idea, the names and colors available on a standard installation of L^AT_EX are:

GreenYellow   Yellow   Goldenrod   Dandelion   Apricot  

Peach   Melon   YellowOrange   Orange   BurntOrange  

Bittersweet   RedOrange   Mahogany   Maroon   BrickRed  

Red   OrangeRed   RubineRed   WildStrawberry   Salmon  

CarnationPink   Magenta   VioletRed   Rhodamine   Mulberry  

RedViolet   Fuchsia   Lavender   Thistle   Orchid   DarkOrchid  

Purple   Plum   Violet   RoyalPurple   BlueViolet  

Periwinkle   CadetBlue   CornflowerBlue   MidnightBlue  

NavyBlue   RoyalBlue   Blue   Cerulean   Cyan   ProcessBlue  

SkyBlue   Turquoise   TealBlue   Aquamarine   BlueGreen  

Emerald   JungleGreen   SeaGreen   Green   ForestGreen  

PineGreen   LimeGreen   YellowGreen   SpringGreen  

OliveGreen   RawSienna   Sepia   Brown   Tan  

Gray   Black  

The CMYK specifications of colors

You may also explicitly use a CMYK (Cyan, Magenta, Yellow, Black) specification. In this case the cyan, magenta, yellow and black values follow the ⟨ cmyk⟩ keyword, and are given as a list of four integers in the range 0.0 .. 1.0. For instance, \color[cmyk]{0,1,0,0} is a valid specification for magenta.

The RGB specifications of colors

RGB (Red, Green, Blue) specifications are similar to the CMYK specifications: following the ⟨ rbg⟩ keyword, the red, green, or blue color values, are given as floating point numbers in the range 0.0 .. 1.0. Hence, \color[rgb]{1.0,0.0,0.0} is a valid specification for red.

The X -Window System colors

Active-DVI provides the package xwindows-colors, an extension to the color package, that defines a large set of the X Window System color names, as found in the file rgb.txt of a typical X installation (this file is generally located on /usr/X11R6/lib/X11/rgb.txt). To know which colors are available look at the source file of the package xwindows-colors.sty in the directory tex of the distribution.

6.7 Background

You can modify the background of your presentation in the L^AT_EX source of the pages. Background can be defined either as a plain color, as an image, or as a gradient (or as a combination of these!).

You can specify a global option to the background settings, so that these settings are used for the remaining pages of the presentation (otherwise the presenter resets the background options at each new page).

To modify the background of your presentation, you can:

• define the background color,
• define a gradient function to be run on the background (or a defined area of the background) using the predefined color gradients,
• add a background image (which can be alpha-blended on top of the background color).

If these options are used together, they are applied in this order: first the solid background color is drawn, then the gradient function is applied, finally the image is drawn on the resulting background. \advibg[global]{⟨ decl⟩}

where ⟨ decl⟩ is a list of settings of the following from:

color=⟨ color⟩  (default value is none)

Set the background color to ⟨ color⟩. If ⟨ color⟩ is none this unsets the background color. Otherwise, ⟨ color⟩ must follow the notation above to designate colors.

image=⟨ file⟩  (default value is none)

Use the image found in ⟨ file⟩ as background (none means unset).

fit=⟨ fit style⟩  (default value is auto)

Fit the background image according to ⟨ style⟩, which may be one of the following keywords:

auto or

topleft		top		topright
left		center		right
bottomleft		bottom		bottomright

The auto fit style means scaling the image as desired in both directions so that it fits the entire page. Other styles only force the same scaling factor in both directions:

• Corner-styles means set the image in the corresponding corner and scale it to cover the entire page.
• center means set the image in the center of the page and scale it to cover the entire page.
• Segment-styles means adjust the image and the page on the segment (in which case, the image may not completely cover the page on the opposite side).

alpha=⟨ float⟩  (default value is none)

Set the alpha channel factor for the background image to ⟨ float⟩ (none means unset). An alpha factor of 0 means that the image is not visible at all; conversely, an alpha factor of 1 means that the image covers the background.

blend=⟨ blend mode⟩  (default value is none)

Set the blend mode to ⟨ blend mode⟩, which are reminiscent of Ghostscript blending options. The blend mode should be one of the following: normal, multiply, screen, overlay, dodge, burn, darken, lighten, difference, exclusion, (none means unset).

gradient=⟨ function⟩  (default value is none)

Set the gradient function to ⟨ function⟩, one of the predefined functions that convert the plain background color into a color gradient from the chosen color colorstart to the color colorstop (which is white by default). Available gradients are:

• hgradient horizontal gradient (the gradient is a serie of vertical lines),
• vgradient vertical gradient (the gradient is a serie of horizontal lines),
• d1gradient first bissector gradient (the gradient is a serie of lines which are parallel to the first bissector),
• d2gradient second bissector gradient (the gradient is a serie of lines which are parallel to the second bissector),
• cgradient centered gradient (the gradient is a serie of concentric squares),
• circgradient circular gradient (the gradient is a serie of concentric circles).

colorstart=⟨ color⟩  (default value is white)

Set the starting color of the gradient. When left unspecified defaults to white.

colorstop=⟨ color⟩  (default value is background)

Set the end color of the gradient. When left unspecified defaults to the background color.

xstart=⟨ int⟩  (default value is 0)

Set the abscissa of the lower left point of the area where the gradient is drawn.

ystart=⟨ int⟩  (default value is 0)

Set the ordinate of the lower left point of the area where the gradient is drawn.

width=⟨ float⟩  (default value is 1.0)

Set the width of the area where the gradient is drawn. The width is a number in the range [0 .. 1] that gives the ratio of the area width with respect to the page width (hence 0.0 means a null width and 1.0 means the entire page width).

height=⟨ float⟩  (default value is 1.0)

Set the height of the area where the gradient is drawn. The width is a number in the range [0 .. 1] that gives the ratio of the area height with respect to the page height (hence 0.0 means a null height and 1.0 means the entire page height).

xcenter=⟨ float⟩  (default value is 0.5)

For a centered or circular gradient, set the abscissa of the center point of the gradient into the gradient area. xcenter is a ratio of the gradient area’s width. It defaults to 0.5, meaning the middle of the gradient area width.

ycenter=⟨ float⟩  (default value is 0.5)

For a centered or circular gradient, set the ordinate of the center point of the gradient into the gradient area. ycenter is a ratio of the gradient area’s height. It defaults to 0.5, meaning the middle of the gradient area height.

none

Unset all background parameters. This key must appear on its own, no arguments or keys are allowed.

The optional parameter global indicates that the definition is global and will affect the following pages, as well as the current page.

By default, the background settings only affect the current page.

6.8 Transitions

\advitransition[global]{⟨ decl⟩}

where ⟨ decl⟩ is a list of settings of the following from:

none or slide or block or wipe

Set the transition mode to the corresponding key. One of this key is mandatory (if several are provided the last one is selected).

from=⟨ direction⟩

Make the transition come from ⟨ direction⟩. Directions should be one of the following:

topleft		top		topright
left		center		right
bottomleft		bottom		bottomright

The default direction, to be used when no local or global direction has been specified, is determined dynamically: right when coming from previous page, left when coming from next page, and top otherwise.

steps=⟨ n⟩

Make the transition in ⟨ n⟩ steps.

As for \advibg, the optional parameter global indicates that the definition is global and will affect the following pages, as well as the current page.

By default, the transition definitions affect the current page only.

\advitransbox{⟨ key=val list⟩}{⟨ hbox material⟩}

where ⟨ key=val list⟩ is as above and {⟨ hbox material⟩} is whatever can follow an \hbox command. In particular, the material may contain verbatim commands, since as for the \hbox it is parsed incrementally.

The optional parameter global indicates that the definition is global and will affect the following pages, as well as the current page.

By default, the transition affects the current page only.

6.9 Embedded applications

To animate your show, Active-DVI can launch arbitrary applications you need.

6.9.1 Launching embedded applications

The L^AT_EX command to launch an application during the presentation is \adviembed[⟨ key=value list⟩]{⟨ command⟩}

where ⟨ key=value list⟩ is a list of bindings of the following kind:

name=⟨ name⟩

Allows to refer to the embedded application as ⟨ name⟩. Anonymous applications have actually the default name anonymous.

ephemeral=⟨ name⟩

This is the default case: the application is specific to a given page. An ephemeral application is automatically launched whenever the page is displayed, and automatically killed when the page is turned.

persistent=⟨ name⟩

A persistent application is launched only once and keeps running in the background; however, Active-DVI automatically hides and shows the window where the application runs, so that the application is visible only on the page where it has been launched.

sticky=⟨ name⟩

A stiky application is launched only once, keeps running, and remains visible when turning pages. It is also resized and moved as necessary to fit the page size.

raw=⟨ name⟩

A raw application is launched each time its embedding command is encountered. A raw application is not managed automatically by Active-DVI, except for the initial launching and the final clean-up that occurs when Active-DVI exits; hence, you can completely monitor the raw applications graphical behavior, using the advikillembed command and the window mapping facilities for raw applications described below.

width=⟨ dim⟩
height=⟨ dim⟩

The application takes ⟨ dim⟩ width (respectively height) space in L^AT_EX. Both values default to 0pt.

These dimensions are also substituted for all occurrences of @g in the command string.

6.9.2 Monitoring embedded applications

To monitor embedded applications, Active-DVI provides the advikillembed primitive to send a signal to any named embedded application. For raw applications, there are additional functions to map or un-map the window allocated to a named raw application. Mapping or un-mapping windows of non-raw applications is unspecified, since it may interfere in a non trivial way with Active-DVI’s automatic treatment of those applications.

Monitoring a single application

\advikillembed{⟨ name⟩}

Kill the embedded application named ⟨ name⟩. An optional signal value or symbolic name can be given to send to the designed process: for instance, \advikillembed[SIGUSR1]{clock} will send the SIGUSR1 signal to the embedded application named clock.

Signal value defaults to -9.

\advimapembed{⟨ name⟩}

Map the window of the (raw) embedded application named ⟨ name⟩.

\adviunmapembed{⟨ name⟩}

Un-map the window of the (raw) embedded application named ⟨ name⟩.

Monitoring a group of embedded applications

The primitives advikillallembed, advimapallembed, and adviunmapallembed behave the same as their non-all counterparts, except that they operate on all the applications that have been launched with the given name. \advikillallembed{⟨ name⟩}

Similar to advikillembed but kill all the embedded applications named ⟨ name⟩.

\advimapallembed{⟨ name⟩}

Map the windows of all the (raw) embedded applications named ⟨ name⟩.

\adviunmapallembed{⟨ name⟩}

Un-map the windows of all the (raw) embedded applications named ⟨ name⟩.

6.10 Active anchors

Active anchors are annotated pieces of text that get associated activation records. To define an active anchor, the command is \advianchor[⟨ decl⟩]{⟨ tag⟩}{⟨ text⟩}
\begin{advianchor}[⟨ decl⟩]{⟨ tag⟩} ⟨ text⟩\end{advianchor}

The text is first displayed as usual, then the anchor is drawn according to the style given by ⟨ decl⟩, and made active. Its activation, which depends on the mode given by ⟨ decl⟩, will play the record named ⟨ tag⟩.

The declarations ⟨ decl⟩ are of the following form:

over, click, or stick

The mode stick plays the tag ⟨ tag⟩ on click. The mode click is similar, except that it restores the previous state when leaving the anchor area. The mode over is as click but display the ⟨ tag⟩ when the mouse is over the anchor instead of waiting for a click.

box, invisible, or underline

this defines the style in which the anchor should be drawn. The default style is box.

In the environment form, ⟨ text⟩ may contain fragile commands.

\adviemphasize[⟨ color⟩]{⟨ text⟩}

This makes an invisible anchor around ⟨ text⟩, which when activated will redraw text in a box colored with ⟨ color⟩, which defaults to yellow.

6.11 Postscript specials

Active-DVI can deal with most of PStricks by calling ghostscript on included Postscripts. Basic change of coordinates are implemented, but this feature remain fragile, as Active-DVI must in turn call ghostscript to get the new coordinates. Also, rotations will definitely not work for text, which is rendered by Active-DVI and cannot be rotated.

6.11.1 Overlays

The overlay class implements overlays with PStricks. By contrast, Active-DVI implements overlays directly, using records and plays. This is more efficient, and of course more natural. (In fact, Active-DVI chooses the cumulative semantics of overlays, displaying all layers below the current overlay.)

The xprosper style, derived from the prosper class, uses the overlay class and works with Active-DVI in exactly the same way (relaxing the \overlay@loop macro inhibits all layers, but the first page).

6.11.2 PStricks known to work

Active-DVI can deal with main PStricks. In particular, the following work

• + Simple drawings, such as \psframe, \ovalnode, ….
• + Connections between nodes \ncline, \ncarc, also works.
• + Labels over arrows \Aput, Bput, etc.
• + \SpecialCoor, i.e. commands of the form \rput(A){bla bla} works where A is a node name.
• + Embeddded-Postcript figures, including scaling.

Other PStricks may or may not work.