Animation

Robin Houston edited this page Nov 15, 2013 · 11 revisions

WikiAPI ReferenceAnimation

Conceptually, Talkie’s animation support is in two parts, though they are most often used together. The timeline module supports attaching actions to an audio-triggered timeline, and the animation module provides some useful actions for you to attach.

(If for some reason you wish not to use d3, you may use the timeline module without the animation module. Only the latter relies on d3.)

The timeline module

# Talkie.timeline(audio, timeline)

It returns a timeline object.

    var caption = Talkie.animate().select("#caption");
    var timeline = Talkie.timeline("#soundtrack", {
      "0:05": caption.text("This text will appear after five seconds"),
      "0:10": caption.text("And be replaced by this after a further five")
    });

The audio parameter should refer to an HTML 5 <audio> or <video> element. It should be a CSS selector or a DOM element.

The timeline parameter defines what happens when. Its keys are timecodes, either strings in "mm:ss" format (e.g. "03:15.20") or just a number of seconds (e.g. 195.20). Its values are actions, which fire when the play head crosses the specified point on the track. See actions below.

The timeline object

The timeline object has the following methods. These three are self-explanatory:

  • play()
  • pause()
  • rewind()

These two are explained below:

  • setUndo(undo_function)
  • undoInteraction(undo_function)

Actions

A good Talkie will allow random access as well as sequential play: the user may click about in the audio controls, skipping back and forth between different parts of the track. The Talkie library takes care of the necessary book-keeping, and the actions defined by the animation module are built to undo themselves where necessary, but if you define your own custom actions then you will need to define what (if anything) needs to happen when the action is undone.

A user-defined action is just a function, run at the appropriate point. When the function is called by Talkie, the "this" object is the timeline. If the action leaves a lasting change that should be undone when the user skips back, the action should call this.setUndo passing the reversal procedure. If this.fast_forward is true, the animation should be skipped over rather than performed at normal speed.

When an undo action is called, the undoing property is set on the timeline object. Sometimes it is useful to write a function that may be called either from the timeline itself or as an undo action, and this property allows you to distinguish them. Also, if an undo action is in the process of being performed, the setUndo and undoInteraction methods do nothing. This is useful, for example, if you have an animation that runs during a certain portion of the timeline. Then you can write:

    Talkie.timeline("#soundtrack", {
      "0:02": startAnimation,
      "0:25": stopAnimation
    });

    function startAnimation() {
        // ... start the animation ...
        setUndo(stopAnimation);
    }

    function stopAnimation() {
        // ... start the animation ...
        setUndo(startAnimation);
    }

This will make the animation start and stop appropriately, however you move about in the timeline.

Here is a complete example of a custom action that uses jQuery to fade in a particular element at the two-second mark:

    Talkie.timeline("#soundtrack", {
      "0:02": function() {
        if (this.fast_forward) {
          // If we’re just skipping past this point rather than lingering here,
          // it typically looks better just to transition the element to its
          // post-animation state immediately without performing the actual animation.
          $("#logo").show();
        }
        else {
          // This is the common case where the animation is just playing through
          // (or less commonly if the user has skipped just past this timecode)
          // where we should perform the animation as normal.
          $("#logo").fadeIn();
        }
        
        this.setUndo(function() {
          // To undo the action, hide the logo
          $("#logo").hide();
        });
      }
    );

As well as defining your own actions, you can use the actions defined by the animation module, which use d3 to animate DOM attributes and CSS styles.

Undoing user interaction

If the user interrupts your Talkie to play with you visualisation, and then resumes the Talkie, you may want to revert the user’s changes before continuing. You can accomplish this in a straightforward way by using the undoInteraction method to record how the user interactions are to be reverted.

The slider demo has a simple example. If you interrupt the Talkie by pressing one of the arrows on the panel slider, your changes will be reverted when you resume it.

The animation module

# Talkie.animate([root element])

    var animate = Talkie.animate();
    Talkie.timeline("#soundtrack", {
      "0:02": animate.select("#box").style("opacity", 1, 200),
      "0:04": animate.select("#stick").style("transform", "rotate(90)", 1000)
    });

This is the initial entry point to the animation module. Talkie.animate() returns an object that you can use to animate elements in the document. The optional parameter is used when the document you are animating is not the main document: typically an SVG file loaded by an <object> element. See stickman for an example.

# animate.select(selector)

Point to a particular element that you want to animate. Returns a Talkie.Animate_Element object that points to the selected element but has no associated animations yet. Use the methods below to attach animations.

These objects are immutable. The animation methods return a new object, leaving the original unchanged.

# animate_element.style(name, value, [duration], [easing])

Animate a CSS style. In other words, returns a new Animate_Element object that has an animation for this style added to the end of its animation queue. Duration is in milliseconds. If the duration is omitted then the transition is performed immediately.

# animate_element.style(styles, [duration], [easing])

Animate several styles simultaneously. For example:

    "0:05": number.style("font-size", "12px").text("")
                  .style({"font-size": "576px", "color": "#F83195"}, 500)

This example is taken from the countdown demo.

# animate_element.attr(name, value, [duration], [easing])

Animate an attribute value.

# animate_element.morphTo(target, [duration], [easing])

Morph a shape to match the target element. Typically the target element will be hidden, and used only to define the final shape after this morph.

# animate_element.and(another_animation)

Used to create compound animations that affect several elements. The other_animation will typically be another Animate_Element object, but it may also be a user-defined action.

# animate_element.run(timeline)

Run the animation immediately. You shouldn’t need to call this method yourself under ordinary circumstances, but it might occasionally be useful within a sophisticated user-defined action. You need to pass in the timeline object.

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.