Development/Tutorials/Plasma4/JavaScript/Animations

    From KDE TechBase

    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)

    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 rotation.js=RotationAnimation

    The above example would associate the file in animations/stockanim.js with the ZoomAnimation and PulseAnimation animations and rotation.js with the RotationAnimation animation. Whenever these animations were requested by name, they would be loaded from the respective script and an Animation object would be returned.

    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().

    In Plasmoids

    A scripted Plasmoid can include one or more JS scripts in the contents/animations/ subdirectory of the package. Each script can contain one or more animations.

    To make Plasma aware of the animations, create an [Animations] section in the Plasmoid'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 rotation.js=RotationAnimation

    The above example would associate the file in contents/animations/stockanim.js with the ZoomAnimation and PulseAnimation animations and rotation.js with the RotationAnimation animation. Whenever these animations were requested by name, they would be loaded from the respective script and an Animation object would be returned.

    In Plasma Applications

    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.

    API

    The following API is available to Javascript animations.

    Read-Only Properties

    • number duration: the time in milliseconds that the animation is set to run
    • QGraphicsWidget target: the item to be animated

    Accessing Other Animations

    An Animation object can be created by calling the Animation animation(string type) function. The string corresponds to the type of animation, which are listed below.

    By setting the widgetToAnimate property it can be assigned to animate any QGraphicsWidget desired.

    Enumerations

    All Animation objects have the following enumerations:

    MovementDirection
    • MoveUp
    • MoveUpRight
    • MoveRight
    • MoveDownRight
    • MoveDown
    • MoveDownLeft
    • MoveLeft
    • MoveUpLeft
    Reference

    The reference point, relative to the target widget, for the animation.

    • Center
    • Up
    • Down
    • Left
    • Right
    State
    • Paused
    • Running
    • Stopped

    Common API

    With the exception of Pause and Property animations, all animations support the following read/write properties:

    • AnimationDirection direction: the direction the animation should play: AnimationForward or AnimationBackward
    • int duration: length of the animation in ms.
    • EasingCurveType easingCurveType: The easing curve to use in the animation
    • QGraphicsWidget targetWidget: the QGraphicsWidget (e.g. a Plasma::Widget) that this animation should operate on

    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.

    Animation Types

    Below is a list of all current animation types and their particular read/write properties:

    Fade
    • number startOpacity: the opacity, between 0 and 1, that the target widget starts at when the animation begins
    • number targetOpacity: the opacity, between 0 and 1, that the target widget will be at the end of the animation
    Geometry
    • QRectF startGeometry: the geometry that the target widget should start with
    • QRectF targetGeometry: the geometry the target widget will have at the end of the animation
    Grow
    • number factor: the factor by which the target widget will grow to by the end of the animation
    Pause
    • number duration: the number of milliseconds to pause for
    Property

    Animates an object (must be a QObject internally, which includes all Plasma Widgets) by manipulating one of its properties. Property animations have the following read/write properties:

    • any startValue
    • any endValue
    • ByteArray propertyName
    • QObject targetObject
    • number duration
    • EasingCurve easingCurve
    Pulser
    • number targetScale: the maximum scale of the pulse-shadow item, relative to the target widget
    Rotate
    • QtAxis axis: the axis along which to rotate the item
    • Reference reference: the reference point around which to rotate the target widget
    • number angle: the number of degrees to rotate the item
    RotateStacked
    • MovementDirection movementDirection: the direction to rotate the widgets in the stack around
    • QGraphicsLayoutItem layout
    • Reference reference: the reference point around which to rotate the target widget
    • QGraphicsWidget backingWidget: the widget in the "back" to rotate to the front of the target widget
    Slide
    • MovementDirection movementDirection: the direction to slide the widget
    • number distance: the distance to slide the widget
    Zoom
    • number zoom: the factor by which to zoom the target widget

    QEasingCurve

    Used to set the progress shape of Animation objects, this class has the following read-only properties:

    • string toString
    • number valueForProgress(number progress): returns effective progress for the easing curve at progress. While progress must be between 0 and 1, the returned effective progress can be outside those bounds.

    as well as the following read/write property:

    • EasingCurveType type: the shape of this easing curve

    and the following enumeration:

    • EasingCurveType
      • Linear
      • InQuad
      • OutQuad
      • InOutQuad
      • OutInQuad
      • InCubic
      • OutCubic
      • InOutCubic
      • OutInCubic
      • InQuart
      • OutQuart
      • InOutQuart
      • OutInQuart
      • InQuint
      • OutQuint
      • InOutQuint
      • OutInQuint
      • InSize
      • OutSine
      • InOutSine
      • OutInSine
      • InExpo
      • OutExpo
      • InOutExpo
      • OutInExpo
      • InCirc
      • OutCirc
      • InOutCirc
      • InOutCirc
      • OutInCirc
      • InElastic
      • OutElastic
      • InOutElastic
      • OutInElastic
      • InBack
      • OutBack
      • InOutBack
      • OutInBack
      • InBounc
      • OutBounce
      • InOutBounce
      • OutInBounce
      • InCurve
      • OutCurve
      • SineCurve
      • CosineCurve