Widget Level Animation Using Flex Forms

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 kony.ui.createAnimation() API. Refer kony.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

kony.ui.createAnimation (animationDef);

Input Parameters

animationDef [Number]: The sample code below is an example of an animation definition.

{
    <step>: {

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

    stepConfig: {…}
    }
	<step>: {

        <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 = kony.ui.createAnimation(animDefinition);
	return animDef;
}

Availability

• iOS
• Android/ Android Tablet
• Windows
• SPA

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

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 kony.ui.makeAffineTransform.

Syntax

transform

Type

JSObject

Permissions

Read + Write

Example

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

}

Function getParent() {

    var result = this.parent;
}

Availability

• Not available in the IDE.
• iOS
• Android
• Windows
• SPA

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

kony.ui.makeAffineTransform( );

Input Parameters

None

Return Values

It returns the identity transform.

Exceptions

WidgetError

Remarks

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

Example

//Sample code of animation 
function animDeftranslate() {
    var transformProp1 = kony.ui.makeAffineTransform();
    transformProp1.translate(10, 10);
    var transformProp2 = kony.ui.makeAffineTransform();
    transformProp2.translate(20, 20);
    var transformProp3 = kony.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 = kony.ui.createAnimation(animDefinitionOne);
    return animDef;

}

Function getParent() {

    var result = this.parent;
}

Availability

• iOS
• Android/ Android Tablet
• Windows
• SPA

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 = kony.ui.makeAffineTransform();
    transformProp1.translate(100, 100);
    var transformProp2 = kony.ui.makeAffineTransform();
    transformProp2.scale(2, 2);
    var transformProp3 = kony.ui.makeAffineTransform();
    transformProp3.rotate(90);
    var animDefinitionOne = {
        0: {
            "transform": transformProp1
        },
        50: {
            
            "transform": transformProp2
        },
        100: {
           
            "transform": transformProp3
        }
    };
    animDef = kony.ui.createAnimation(animDefinitionOne);
    return animDef;

}

Function getParent() {

    var result = this.parent;
}

Availability

• iOS
• Android/ Android Tablet
• Windows
• SPA

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

Remarks

The value of angle should be in degrees and the range should be in between 180^o to -180^o. 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 = kony.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

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 = kony.ui.makeAffineTransform();
    transformProp1.translate(100, 100);
    var transformProp2 = kony.ui.makeAffineTransform();
    transformProp2.scale(2, 2);
    var transformProp3 = kony.ui.makeAffineTransform();
    transformProp3.rotate(90);
    var animDefinitionOne = {
        0: {
            "transform": transformProp1
        },
        50: {
            
            "transform": transformProp2
        },
        100: {
           
            "transform": transformProp3
        }
    };
    animDef = kony.ui.createAnimation(animDefinitionOne);
    return animDef;

}

Function getParent() {

    var result = this.parent;
}

Availability

• iOS
• Android/ Android Tablet
• Windows
• SPA

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

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 = kony.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

• Available in the IDE
• iOS
• SPA

This method returns an affine transformation matrix constructed by translating receivers affine transform. It is a JavaScript object with keys tx and ty and allow numbers in dp.

Signature

translate (tx, ty);

Input Parameters

tx [Number]: The value by which to move the x-axis of the widget coordinate system.

ty [Number]: The factor by which to move the y-axis of the widget coordinate system.

Default values are {"tx":0, "ty":0} if the transform was never applied to the widget.

Return Values

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

Exceptions

WidgetError

Remarks

Translate 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.

NOTE: Values cannot be specified using percentage and pixels.

Example

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

}

Function getParent() {

    var result = this.parent;
}

Availability

• iOS
• Android/ Android Tablet
• Windows
• SPA

Translate the widget from present location to new location by x, y, z amount.

Syntax

translate3D(tx, ty, tz);

Input Parameters

tx [Number]: Specify the value to be moved in the x direction from present location.

ty [Number]: Specify the value to be moved in the y direction from present location.

tz [Number]: Specify the value to be moved in the z direction from present location.

Exceptions

Remarks

The values of tx, ty, and tz should be floating numbers. If the setPerspective method is not used, the widget moving in the z direction will not have any visual effect.

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

Example

var newTransform = kony.ui.makeAffineTransform();
newTransform.translate3D(223,12,56); //translates by 223 xAxis,12 in yAxis,56 in zAxis
widget.transform = newTransform;

Availability

• Available in the IDE
• iOS
• SPA

This method sets the perspective and sets the vanishing point at the center of the widget.

Syntax

setPerspective(distanceOfViewerToPlane);

Parameters

distanceOfViewerToPlane: The distance between the viewer and object. Always the value of this parameter should be greater than zero. Otherwise results an exception 100.

Exceptions

Remarks

The perspective has to be set in combination with other transforms. The perspective set by itself will not have any effect. If perspective is set to transform in any key frame, the perspective will be applied to that particular key frame itself in the KeyFrameAnimation.

The perspective is platform dependent so that each platform has different perspective of a view for same value. The default perspective on the Android platform is 1280. Any perspective less than 1280 makes the camera perspective closer to the view and greater than 1280 makes perspective far from the view.

In the Android platform, when perspective is not specified, the default perspective is applied.

For the iOS platform, the value of the distanceOfViewerToPlane parameter should be greater than max (width, height) values of the widget view's frame. For example, if the value of (width, height) is (100, 50), the parameter value should be greater than 100. The effect of this parameter vary visually on different platforms for the same value. The units of the distanceOfViewerToPlane parameter is platform-specific.

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

Example

var newTransform = kony.ui.makeAffineTransform();
newTransform.setPerspective(1000.0);
//Sets the perspective as such this will have no effect until it is combined with other transformation matrix.
newTransform.rotate3D(45, 1,0,1);
//rotates by 45degrees in x and z Axis. Now the perspective can be observed
widget.transform = newTransform;

Availability

• Available in the IDE
• iOS
• SPA

Specifies the background color of the widget in hex format.

Syntax

backgroundColor

Type

String

Permissions

Read + Write

Remarks

There is no default value. It accepts 6 dig or 8 digit with alpha position are allowed. For example, ffffff or ffffff00.

When the 4-byte color format (RGBA) string is used, an alpha (A) value of FF specifies that the color is transparent. If the value is 00, the color is opaque. For example, red complete opaque is FF000000. Red complete transparent is FF0000FF. This change is made for backward compatibility.

NOTE: This property has more priority compared to the values coming from the configured skin.The values 0x and # are not allowed in the hex format.

NOTE: Initial value of backgroundColor has to be specified explicitly. If not, platform will not deduce the values from the existing skin and will lead to undefined behavior.

Availability

Not available in the IDE.

• iOS
• Android
• Windows
• SPA

Specifies the opacity of the widget. The value of this property must be in the range 0.0 (transparent) to 1.0 (opaque). Any values outside this range are fixed to the nearest minimum or maximum value.

Syntax

opacity

Type

Number

Permissions

Read + Write

Remarks

This property has more priority compared to the values coming from the configured skin.

Availability

Not available in the IDE.

• iOS
• Android
• Windows
• SPA

This property defines the time in seconds that an animation takes to complete one cycle. This is overall animation level configuration and not the step level configuration.

Possible values include all the positive float numbers with a precision of three and the default value is zero, which indicates that animation is instantaneous. However, there will not be visible animation changes, technically animation occurs and all animation callbacks get triggered.

NOTE: Negative values will be treated as zero or may lead to undefined behavior.

This property specifies the number of times an animation cycle is played. Default value is one (1), meaning the animation will play from beginning to end. A value of zero (0) will cause the animation to repeat forever until the time view is live in the current hierarchy.

NOTE: Possible values include all the positive integer numbers. Any invalid values such as negative values would be ignored or may lead to undefined behavior.

This property defines whether the animation must play in reverse on some or all cycles. If an animation is played in reverse, the timing functions are also reversed. For example, when played in reverse an ease-in animation would appear to be an ease-out animation.

Following are the possible predefined values: 

• kony.anim.DIRECTION_NONE (default)

All iterations of the animation are played as specified.

• kony.anim.DIRECTION_ALTERNATE

The animation cycle iterations that are of odd counts are played in the normal direction, and the animation cycle iterations that are even counts are played in a reverse direction.

Note that this is overall animation level configuration and not the step level configuration.

NOTE: Values will be specified as a string containing one of the above values and any other values will be ignored and default is applied or may lead to undefined behavior.

This property defines when the animation will start. It allows an animation to start executing after it is applied. This is specified in seconds and fractional values are allowed.

Delay value of zero (0) means the animation will execute as soon as it is applied. Otherwise, the value specifies an offset from the moment the animation is applied, and the animation will delay execution by that offset. Default value is zero and any negative or invalid values will default this property to zero.

NOTE: This is overall animation level configuration and not the step level configuration.

This property defines what values are applied to the widget state by the animation outside the time it is executing.

Following are the options:

• kony.anim.FILL_MODE_FORWARDS: The values configured in the last step of animation definition are the final values that are applied to the widget at the end of animation.

• kony.anim.FILL_MODE_BACKWARDS: The values configured in the first step of animation definition are applied to the widget at the beginning of the animation (even before the delay ends). At the end of animation, values are reset to the values, that were there before the start of the animation.

• kony.anim.FILL_MODE_BOTH: The animation is applied twice on the widget. First at the beginning of the animation, before the animation delay with the values configured in the first step of the animation, and second at the end of the animation, with the values configured in the last step of the animation definition.

• kony.anim.FILL_MODE_NONE (default): The values in animation definition are never set to the actual widget. In this case, the widget comes back to original state after the animation is completed.

Following is the table showing the behavior of the animatable properties when queried during or at the end of the animation.

NOTE: This is overall animation level configuration and not the step level configuration. Values will be specified as string containing one of the above values and any other values would be ignored or may lead to undefined behavior.

Example

function animConfig(){
 var config = {
    "duration":1,
    "iterationCount":1,
    "delay":0,
    "fillMode":kony.anim.FILL_MODE_FORWARDS
 };
 return config;
}