Flex Layout Animation

Volt MX Application Design and Development Guidelines: Flex Layout Guidelines > Flex Layout Animation

Widget Level Animation Using Flex Forms

Widget Level Animation feature enables you to animate widgets placed in a container (for example, Form). This feature supports 2D and 3D animations and transformations. The 2D animations are supported on iOS, Android, Windows, and SPA platforms and the 3D animations are supported on iOS, SPA and Android (limited support) for the applications created in JavaScript language using the Volt MX Platform.

When the transformation matrix is identity, the 3D directions are as follows:

• x-axis is towards the right of the widget
• y-axis is towards bottom of the widget
• z-axis is coming out of the screen

Note: 3D animations should be applied on widgets when they are in normal state. Otherwise it may have undefined behavior.

The animation is classified into the following sub classes:

• Key Frame Animations
• Animation Properties Events and Methods

Key Frame Animations

Key frame animations allows you to define animations by changing the widget level properties.

Key Frame Animation Definition

Key frame definition consists of one or more properties of the widget along with changes in their values and the steps (key frame) involved in changing the value from the initial value to final value. Each step from initial value to the final value can be configured with an animation behavior.

Key frame animation can be defined dictionary of steps with each step configured again using a JavaScript Object (Dictionary). Step-config is optional parameter. Following is the syntax:

Note: If the animation definition does not follow the above syntax then animate API throws Invalid Animation Definition exception.

{  

<step>: { 

<widget_property> : <value> , 

<widget_property> : <value> ,

 …

stepConfig : { … }
}

        ,
<step>: { 

<widget_property>  : <value> , 

<widget_property>  : <value> ,  

…

stepConfig : { … }

}
,
       ….

}

References

APIs does not completely adhere to the CSS3 specifications but is influenced by CSS3 animations and transformations. 

The following URLs help as a reference:

• http://dev.w3.org/csswg/css3-animations/
• http://dev.w3.org/csswg/css3-2d-transforms/
• http://cubic-bezier.com/
• http://dev.w3.org/csswg/css3-2d-transforms/
• http://dev.w3.org/csswg/css3-3d-transforms/

Animation Properties Events and Methods

Following are the widget level properties, events, and methods that are allowed to be part of the animation definition.

animate

This method applies the animation to the widget immediately, if the widget is part of the currently visible view hierarchy. If widget is not part of the currently visible view hierarchy then this API invocation is ignored. This method is asynchronous and immediately returns and do not wait for the animation to start or complete.

All the animation callbacks will receive animate as a second parameter.

Signature

animate(  
   animationObj,  
  animationConfig,  
   animationCallbacks)

Input Parameters

animationObj

An object defined using voltmx.ui.createAnimation() API. Refer voltmx.ui.createAnimation for more details.

animationConfig

Optional. As defined in Animation Configuration section.

animationCallbacks[JSObject]

Optional. A dictionary represents JavaScript functions that work as animation call backs. Following are the animation callbacks:

• animationStart (source, animationHandle, elapsedTime): This event occurs at the start of the animation. If there is 'animation-delay' configured then this event will fire only after the delay period. This event gets called asynchronously.
• animationEnd (source, animationHandle, elapsedTime): The animationEnd event occurs when the animation finishes. This event gets called asynchronously.

source: A widget that is being animated.

animationHandle: A handle returned by applyAnimation method.

elapsedTime: The amount of time the animation has been running in seconds, when this event is fired.

Return Values

Returns a handle to the animation, that is platform-defined object. This handle is of no use for now, but is returned for the future requirements such as cancellation of animations etc.

Remarks

This method throws Invalid Animation Definition Exception if animation definition, does not follow the dictionary structure expected. This method is ignored if this is called on widget whose immediate parent is not FlexForm, FlexContainer or FlexScrollContainer.

Example

//Sample code of animation   

function AnimateBoth()
{
  var getFuncName = frm1.listbox18.selectedKey;

    if(getFuncName == "BothLT") {
        frm1.textbox26.animate(myAnimDefinition(), animConfiguration(), {});
    }
    else if(getFuncName == "BothTBL"){
    frm1.textbox26.animate(myAnimDefinitionsc1(), animConfiguration(), {});

    }
}  

Availability

• iOS
• Android/Android Tablet
• Windows
• SPA

This method creates an animation object that can be used to animate the widgets using animate API.

Signature

voltmx.ui.createAnimation (  
   animationDef)

Input Parameters

animationDef [Number]

A sample animation definition.

``` { : {

    <widget_property>: <value>,
    <widget_property>: <value>,
    ---

stepConfig: {…} } : {

    <widget_property>: <value>,
    <widget_property>: <value>,
    ---

stepConfig: {…}
},
  ---

}

```

Return Values

None

Exceptions

WidgetError

Remarks

Values cannot be specified using pixels.

Example

//Sample code of animation   

function myAnimDefinition()
{
    var animDefinition = 
    {
       0 : 
       {
         "width":50,
         "left":0
        },
       100 : 
       {
         "width":50,
         "left":90
        }
      } ;
    animDef = voltmx.ui.createAnimation(animDefinition);
    return animDef;
}  

Availability

• iOS
• Android/Android Tablet
• Windows
• SPA

anchorPoint

Specifies the anchor point of the widget bounds rectangle using the widgets coordinate space. The possible values are dictionary with x,y as possible keys with the values as numbers ranging from 0 to 1. All geometric manipulations to the widget occur about the specified point. For example, applying a rotation transform to a widget with the default anchor point causes the widget to rotate around its center.

Syntax

anchorPoint

Type

JSObject

Permissions

Read + Write

Remarks

The default value for this property is center ( {"x":0.5, "y":0.5} ), that represents the center of the widgets bounds rectangle. The behavior is undefined if the values are outside the range zero (0) to one (1).

Availability

Not available in the IDE.

• iOS
• Android
• Windows
• SPA

transform

This property is set to identify transform by default. Any transformations applied to the widget, occur relative to the widget anchor point. Values that can be set to this property must be created using voltmx.ui.makeAffineTransform.

Syntax

transform

Type

JSObject

Permissions

Read + Write

Example

//Sample code of animation 
function animDeftranslate() {
    var transformProp1 = voltmx.ui.makeAffineTransform();
    transformProp1.translate(100, 100);
    var transformProp2 = voltmx.ui.makeAffineTransform();
    transformProp2.scale(2, 2);
    var transformProp3 = voltmx.ui.makeAffineTransform();
    transformProp3.rotate(90);
    var animDefinitionOne = {
        0: {
            "transform": transformProp1
        },
        50: {

            "transform": transformProp2
        },
        100: {

            "transform": transformProp3
        }
    }
    animDef = voltmx.ui.createAnimation(animDefinitionOne);
    return animDef;

}

Function getParent() {

    Var result = this.parent;
}  

Availability

Not available in the IDE.

• iOS
• Android
• Windows
• SPA

voltmx.ui.makeAffineTransform

This method creates a 2D transform object. A 2D transform object can be used to scale, translate, and rotate the widgets in a two-dimensional space.

Signature

voltmx.ui.makeAffineTransform( )

Input Parameters

None

Return Values

It returns the identity transform.

Exceptions

WidgetError

Remarks

Irrespective of the invocation order of operations, voltmx.ui.makeAffineTransform method applies the transform in the sequence of scale, translate, and rotate operations.

Example

//Sample code of animation 
function animDeftranslate() {
    var transformProp1 = voltmx.ui.makeAffineTransform();
    transformProp1.translate(10, 10);
    var transformProp2 = voltmx.ui.makeAffineTransform();
    transformProp2.translate(20, 20);
    var transformProp3 = voltmx.ui.makeAffineTransform();
    transformProp3.translate(30, 30);
    var animDefinitionOne = {
        0: {
            "anchorPoint": {
                "x": 0.5,
                "y": 0.5
            },
            "transform": transformProp1
        },
        50: {
            "anchorPoint": {
                "x": 0.5,
                "y": 0.5
            },
            "transform": transformProp2
        },
        100: {
            "anchorPoint": {
                "x": 0.5,
                "y": 0.5
            },
            "transform": transformProp3
        }
    }
    animDef = voltmx.ui.createAnimation(animDefinitionOne);
    return animDef;

}

Function getParent() {

    Var result = this.parent;
}  

Availability

• iOS
• Android/Android Tablet
• Windows
• SPA

rotate

This method returns an affine transformation matrix constructed by rotating receivers affine transform. Angle is a number in degrees and always measured from x-axis as shown.

Signature

rotate(angle)

Input Parameters

angle [Number]

A number represents the angle, in degrees, by which this matrix rotates the coordinate system axes. A positive value specifies counterclockwise rotation and a negative value specifies clockwise rotation.

Return Values

Returns an affine transformation matrix constructed by rotating receivers affine transform.

Exceptions

WidgetError

Remarks

Default value is 0, if transform was never applied to the widget. The rotation does not result in any layout changes to parent or peer widgets. This is also applicable for widgets placed inside horizontal or vertical flex containers.

For example, if you want to rotate a widget in 360 degrees, you can follow the below sequence of steps:

step1: Rotate the widget from 0  -   120

step1: Rotate the widget from 120  -   240

step3: Rotate the widget from 240  -  360

Any value greater than 180 degrees may lead to shortest path rotation from its current position. For cross platform values, for example 190 degrees will make the object rotate -170 (190-360) in negative direction, as 170 is shortest path compared to 190.

Example

//Sample code of animation 
function animDeftranslate() {
    var transformProp1 = voltmx.ui.makeAffineTransform();
    transformProp1.translate(100, 100);
    var transformProp2 = voltmx.ui.makeAffineTransform();
    transformProp2.scale(2, 2);
    var transformProp3 = voltmx.ui.makeAffineTransform();
    transformProp3.rotate(90);
    var animDefinitionOne = {
        0: {
            "transform": transformProp1
        },
        50: {

            "transform": transformProp2
        },
        100: {

            "transform": transformProp3
        }
    }
    animDef = voltmx.ui.createAnimation(animDefinitionOne);
    return animDef;

}

Function getParent() {

    var result = this.parent;
}

Availability

• iOS
• Android/Android Tablet
• Windows
• SPA

rotate3D ()

This method rotates the widget by angle on the unit directional vector formed by rx, ry, and rz.

Syntax

rotate3D(  
    angle,  
    rx,  
    ry,  
    rz)

Parameters

angle

Specify the angle, by which a widget to be rotated around rx, ry, and rz axises.

rx

Specify the x-axis value on which rotation to happen.

ry

Specify the y-axis value on which rotation to happen.

rz

Specify the z-axis value on which rotation to happen.

Exceptions

Error Code	Description
100	Invalid input
101	Incomplete input

Remarks

The value of angle should be in degrees and the range should be in between 180o to -180o. Any value greater or lesser than range will result into platform-specific behavior. Positive values of angle will rotate the widget in anti-clockwise direction and vice versa.

The values of rx, ry, and rz should be in the range of 0 - 1. If the (0,0,0) vector is specified, the behavior is platform-specific.

In the Android platform, the values between 0 - 1 are not accepted. Only '0' or '1' is accepted.

All the input parameters need to be specified. If any parameter found missing will result in an exception 101.

Example

var newTransform = voltmx.ui.makeAffineTransform();  
newTransform.rotate3D(45, 1,0,1); //rotates by 45degrees in x and z Axis.  
widget.transform = newTransform;

Availability

Available in the IDE

iOS

Android

SPA

scale

This method returns an affine transformation matrix constructed by scaling receivers affine transform. It is a JSObject with keys sx and sy and allow numbers only.

Signature

scale (  
   sx,   
   sy)

Input Parameters

sx [Number]

The factor by which to scale the x-axis of the widget coordinate system.

sy [Number]

The factor by which to scale the y-axis of the widget coordinate system.

Default values are {"sx":1, "sy":1}, if the transform was never applied to the widget.

Return Values

Returns an affine transformation matrix constructed by scaling receivers affine transform.

Exceptions

WidgetError

Remarks

Scaling does not result in any layout changes to parent or peer widgets. This is applicable to the widgets placed inside horizontal or vertical flex containers. Negative values for sx and sy will make the widget flip in that direction.

Example

//Sample code of animation 
function animDeftranslate() {
    var transformProp1 = voltmx.ui.makeAffineTransform();
    transformProp1.translate(100, 100);
    var transformProp2 = voltmx.ui.makeAffineTransform();
    transformProp2.scale(2, 2);
    var transformProp3 = voltmx.ui.makeAffineTransform();
    transformProp3.rotate(90);
    var animDefinitionOne = {
        0: {
            "transform": transformProp1
        },
        50: {

            "transform": transformProp2
        },
        100: {

            "transform": transformProp3
        }
    }
    animDef = voltmx.ui.createAnimation(animDefinitionOne);
    return animDef;

}

Function getParent() {

    Var result = this.parent;
}

Availability

• iOS
• Android/Android Tablet
• Windows
• SPA

scale3D ()

Scales a widget in three dimensions (x, y, z) coordinate system.

Syntax

scale3D(  
    sx,  
    sy,  
    sz)

Parameters

sx

Specify the value to be scaled in the x direction.

sy

Specify the value to be scaled in the y direction.

sz

Specify the value to be scaled in the z direction.

Exceptions

Error Code	Description
100	Invalid input
101	Incomplete input

Remarks

The default values of the sx, sy, and sz directions are (1, 1, 1). Any value with in the 0 - 1 range scales down the widget and the value greater than '1' scales up in the specified directions. As all the widgets are not 3D meshes, this function may not be applicable for z-axis and may have platform-specific behavior. The scale3D method should not be applied on zero dimension widgets. If applied, the behavior is undefined.

All the input parameters need to be specified. If any parameter found missing will result in an exception 101.

Example

var newTransform = voltmx.ui.makeAffineTransform();  
newTransform.scale3D(2, 0.5, 1);  
//scales by 200% in xDirection, 50% in yDirection and no scale happening in zDirection.  
widget.transform = newTransform;

Availability