Development/Tutorials/Plasma4/JavaScript/Animations

Introduction To Javascript Animations

Plasma builds on top of the QtKinetic animation framework to provide a set of ready-made animations. Starting with KDE Development Platform v4.5, it is also possible to write new animations or mash up existing ones using Javascript. This tutorial describes how Javascript animations are defined, where they are stored and how you can access them from your code.

Writing An Animation

The key components of a Javascript animation are the constructor function, the updateCurrentTime function and the registerAnimation call.

The constructor function is called whenever a new instance of the animation is requested. The name of the function is not critical.

The updateCurrentTime function drives the actual animation: it is called whenever an animation frame is to be processed. The current time of the animation is passed in to it as the first parameter.

To let Plasma know that the animation exists, the registerAnimation function must be called from the script's global scope. registerAnimation takes two parameters: the name by which the animation will be identified and the constructor function.

A simple example of a zoom animation:

// constructor function for a zoom animation function ZoomAnimation() {

   // we could do some set up here

   // updateCurrentTime
   this.updateCurrentTime = function(currentTime) {
       var delta = currentTime/this.duration;
       this.target.scale = delta;
   }

}

registerAnimation("ZoomAnimation", ZoomAnimation)

API

Animation Groups

Animations may be put into groups for convenient sequential or parallel running. Sequential groups, where the animations run one after the other, are handled by the AnimationGroup class. Parallel aniations, where the animations run simultaneously, are handled the ParallelAnimationGroup class.

Animations are added to a group by calling add(Animation) on the group object. Groups may also be added to other groups.

Script Files

In Desktop Themes

A Plasma desktop theme can include one or more JS scripts in the animations/ subdirectory, each of which can contain one or more animations.

To make Plasma aware of the animations, create an [Animations] section in the theme's metadata.desktop file. This group must contain mappings between the script name and the animations the script contains. For example:

[Animations] stockanims.js=ZoomAnimation,PulseAnimation,RotationAnimation

Theme inheritance is respected and supported as well, so animations defined in inherited themes as well as the default fallback theme will be available if they are not overridden by an animation of the same name in the theme.

Animations with the same name as a value in the Plasma::Animator::Animation enumeration will be automatically mapped as a replacement for the native C++ animation that is usually returned by Plasma::Animator::create().

Accessing A Javascript Animation

C++

In the Plasma::Animator class there is a create(const QString &animationName, QObject *parent = 0) method which returns a QAbstractAnimation that can be used like any other. The animationName parameter is the name of the Javascript animation as defined at animation registration. If no such animation is available, a null pointer will be returned.

Javascript

Javascript animations can be retrieved like any other animation: by name using the animation(String) method.