UIZE JavaScript Framework

MODULES Uize.Fade

SEARCHEXAMPLESSOURCETO DODEPSTEST

1. Introduction

The Uize.Fade class is the foundation for animation in the UIZE JavaScript Framework, supporting quantization, curves, compound value fades, and more.

DEVELOPERS: Chris van Rensburg

The Uize.Fade class implements automated interpolation of a simple or compound value, between specified start and end values, and with qualities of the fade - such as duration, curve, quantization, etc. - being configurable through the state properties of the class.

BACKGROUND READING

For an in-depth discussion on animation in the UIZE JavaScript Framework, and for a discussion on how this module fits into the larger picture, consult the guide JavaScript Animation and Effects and read through the section The Engine.

1.1. Examples

The following example pages are good showcases for the Uize.Fade module...

Fade As a Color Chart - See how acceleration and deceleration affect fades in this visual representation using color gradients, where fades are blending between two colors.
Fade As a Graph - Visualize how different acceleration / deceleration curves affect a fade with this graphical representation using bar widgets.
Fade Quantization Chart - See how different values for the quantization property affect a fade with this visualization using color gradients for different quantization values.
Fading an Object - Animate complex data objects with ease. UIZE supports compound value interpolation. See how an array of two RGB color objects can be faded over time.

SEARCH FOR EXAMPLES

Use the link below to search for example pages on the UIZE Web site that reference the Uize.Fade module...

SEARCH

1.2. Implementation Info

The Uize.Fade module defines the Uize.Fade class, which is a subclass of Uize.Class.

INHERITANCE CHAIN

Uize.Class −> Uize.Fade

1.2.1. Features Introduced in This Module

The features listed in this section have been introduced in this module.

INSTANCE METHODS

start | stop

STATE PROPERTIES

acceleration | curve | deceleration | duration | endValue | inProgress | progress | quantization | reverse | startValue | value

STATIC METHODS

Uize.Fade.blendValues | Uize.Fade.celeration | Uize.Fade.fade | Uize.Fade.fadeMethod | Uize.Fade.fadeProperties | Uize.Fade.fadeProperty

1.2.2. Features Overridden in This Module

The features listed in this section have been overridden in this module.

The module that an overridden feature was initially introduced in will be noted in the IMPLEMENTATION INFO notes for the feature.

INSTANCE METHODS

valueOf

STATIC PROPERTIES

Uize.Fade.moduleName | Uize.Fade.nonInheritableStatics

1.2.3. Features Inherited From Other Modules

The features listed in this section have been inherited from other modules.

The module that an inherited feature was initially introduced in will be noted in the IMPLEMENTATION INFO notes for the feature.

INSTANCE METHODS

fire | get | is | isMet | kill | met | onChange | once | set | toggle | unmet | unwire | whenever | wire

STATIC METHODS

Uize.Fade.alphastructor | Uize.Fade.declare | Uize.Fade.doMy | Uize.Fade.dualContextMethods | Uize.Fade.dualContextProperties | Uize.Fade.fire | Uize.Fade.get | Uize.Fade.instanceMethods | Uize.Fade.instanceProperties | Uize.Fade.mixins | Uize.Fade.omegastructor | Uize.Fade.set | Uize.Fade.singleton | Uize.Fade.stateProperties | Uize.Fade.staticMethods | Uize.Fade.staticProperties | Uize.Fade.subclass | Uize.Fade.toggle | Uize.Fade.unwire | Uize.Fade.wire

STATIC PROPERTIES

Uize.Fade.pathToResources

1.2.4. Modules Directly Under This Namespace

Uize.Fade.Factory | Uize.Fade.mSeries | Uize.Fade.xFactory

1.2.5. Unit Tests

There is no dedicated unit tests module for the Uize.Fade module.

2. Instance Events

2.1. Done

Fired each time the fade ends.

NOTES

see also the Start instance event.

2.2. Start

Fired each time the fade starts.

NOTES

see also the Done instance event.

3. Instance Methods

3.1. fire

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.2. get

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.3. is

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.4. isMet

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.5. kill

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.6. met

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.7. onChange

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.8. once

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.9. set

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.10. start

Starts the fade automation.

SYNTAX

myInstance.start ();

VARIATION

myInstance.start (fadePropertiesOBJ);

When the optional fadePropertiesOBJ parameter is specified, the state properties specified in the fadePropertiesOBJ object will be set before the fade is started. This is a convenience offered because one often might want to start a fade immediately after setting its startValue and endValue properties (and sometimes other properties, such as curve, quantization, etc.).

EXAMPLE

The following statement...

myFade.start ({startValue:0,endValue:50,duration:2500);

...is equivalent to...

myFade.stop ();
myFade.set ({startValue:0,endValue:50,duration:2500);
myFade.start ();

NOTES

Before the automation is started, it is stopped. So, if automation is in progress when this method is called, it will be reset and started over.
each time that automation is started using this method, the Start instance event is fired
this method has no return value
see also the stop instance method

IMPLEMENTATION INFO

this feature was introduced in this module

3.11. stop

Stops the fade automation.

SYNTAX

myInstance.stop ();

NOTES

if the fade automation is not in progress, then this method has no effect
this method has no return value
see also the start instance method

IMPLEMENTATION INFO

this feature was introduced in this module

3.12. toggle

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.13. unmet

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.14. unwire

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.15. valueOf

this is an override of an inherited feature (implementation is in this module, first introduced in Uize.Class)

IMPLEMENTATION INFO

3.16. whenever

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

3.17. wire

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

4. Static Methods

4.1. Uize.Fade.alphastructor

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.2. Uize.Fade.blendValues

IMPLEMENTATION INFO

this feature was introduced in this module
this static feature is not inherited by subclasses

4.3. Uize.Fade.celeration

Produces a curve function that may contain an acceleration phase, deceleration phase, or both acceleration and deceleration phases.

SYNTAX

curveFUNC = Uize.Fade.celeration (acceleration0to1FLOAT,deceleration0to1FLOAT);

4.3.1. Parameters

4.3.1.1. acceleration0to1FLOAT

A floating point value in the range of 0 to 1, specifying the fraction of the curve function that should should be an acceleration phase.

When the value 0 is specified, the resulting curve function will contain no acceleration phase. When the value 1 is specified, the acceleration phase will occupy the entire curve. When the value .5 is specified, the acceleration phase will occupy the first half of the curve. The default value for this parameter is 0.

4.3.1.2. deceleration0to1FLOAT

A floating point value in the range of 0 to 1, specifying the fraction of the curve function that should should be a deceleration phase.

When the value 0 is specified, the resulting curve function will contain no deceleration phase. When the value 1 is specified, the deceleration phase will occupy the entire curve. When the value .5 is specified, the deceleration phase will occupy the second half of the curve. The default value for this parameter is 0.

4.3.2. Sustain Phase

The values of the acceleration0to1FLOAT and deceleration0to1FLOAT parameters do not need to add up to 1, but their sum should not exceed 1.

If the values of acceleration0to1FLOAT and deceleration0to1FLOAT do not add up to 1, then there will be a sustain phase between the acceleration and deceleration phases. During the sustain phase, the rate of change will remain constant.

4.3.3. Variations

VARIATION 1

curveFUNC = Uize.Fade.celeration (acceleration0to1FLOAT);

When the optional deceleration0to1FLOAT parameter is not specified, its value will be defaulted to 0 and the resulting curve function will contain no deceleration phase.

VARIATION 2

curveFUNC = Uize.Fade.celeration ();

When no parameters are specified, then a reference to Uize.Curve.linear (a linear curve function) will be returned - the resulting curve function will contain no acceleration or deceleration phases. The same linear curve function will be produced if the value 0 is specified for both the acceleration0to1FLOAT and deceleration0to1FLOAT parameters.

NOTES

see also the curve state property

IMPLEMENTATION INFO

this feature was introduced in this module
this static feature is not inherited by subclasses

4.4. Uize.Fade.declare

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.5. Uize.Fade.doMy

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.6. Uize.Fade.dualContextMethods

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.7. Uize.Fade.dualContextProperties

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.8. Uize.Fade.fade

IMPLEMENTATION INFO

this feature was introduced in this module
this static feature is inherited by subclasses

4.9. Uize.Fade.fadeMethod

IMPLEMENTATION INFO

this feature was introduced in this module
this static feature is inherited by subclasses

4.10. Uize.Fade.fadeProperties

IMPLEMENTATION INFO

this feature was introduced in this module
this static feature is inherited by subclasses

4.11. Uize.Fade.fadeProperty

IMPLEMENTATION INFO

this feature was introduced in this module
this static feature is inherited by subclasses

4.12. Uize.Fade.fire

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.13. Uize.Fade.get

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.14. Uize.Fade.instanceMethods

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.15. Uize.Fade.instanceProperties

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.16. Uize.Fade.mixins

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.17. Uize.Fade.omegastructor

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.18. Uize.Fade.set

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.19. Uize.Fade.singleton

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.20. Uize.Fade.stateProperties

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.21. Uize.Fade.staticMethods

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.22. Uize.Fade.staticProperties

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.23. Uize.Fade.subclass

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.24. Uize.Fade.toggle

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.25. Uize.Fade.unwire

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

4.26. Uize.Fade.wire

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

5. State Properties

5.1. acceleration

IMPLEMENTATION INFO

this feature was introduced in this module

5.2. curve

A function reference, being a curve function that will be used to control value interpolation for a fade process.

This property lets you specify a curve function in order to achieve a wide variety of different kinds of non-linear fade effects, including motion effects like bounce, springiness, wobble, elasticity. etc.

When setting a value for the curve property, you can provide your own hand-rolled curve function, or you can pick from the many convenient curve function generators provided in the Uize.Curve and Uize.Curve.Rubber modules. Even more complex curve functions can be generated using the versatile curve function modifiers provided in the Uize.Curve.Mod module.

5.2.1. Implemented in the Uize.Math.Blend Module

Supported for curves in the Uize.Fade class is based on support for curves in the Uize.Math.Blend module.

This module provides the underlying value blending engine that is used in fades. For an in-depth discussion of curves and such topics as compound (hierarchical) quantization objects, consult the reference for the Uize.Math.Blend module.

NOTES

the initial value is undefined
when this property is set to null, value interpolation will be linear

IMPLEMENTATION INFO

this feature was introduced in this module

5.3. deceleration

IMPLEMENTATION INFO

this feature was introduced in this module

5.4. duration

An integer, representing the time (in milliseconds) that the fade process should take to complete.

NOTES

the initial value is 2000 (i.e. two seconds)
the actual duration of the fade process is not affected by the value of the curve state property

IMPLEMENTATION INFO

this feature was introduced in this module

5.5. endValue

The value (or set of values) that should be reached at the end of the fade process.

NOTES

the initial value is 100
see also the startValue state property

IMPLEMENTATION INFO

this feature was introduced in this module

5.6. inProgress

A boolean value, indicating whether or not the fade operation is in progress.

To monitor when a fade is in progress, one can register an event handler on the Changed.inProgress instance event.

NOTES

the initial value is undefined
this property is read-only

IMPLEMENTATION INFO

this feature was introduced in this module

5.7. progress

A floating point value in the range of 0 to 1, specifying the fraction of the full fade process that is complete. A value of 0 indicates that the fade is at the start, a value of 1 indicates that the fade is at the end, and a value of .5 indicates that the fade is halfway through.

NOTES

the initial value is 0

IMPLEMENTATION INFO

this feature was introduced in this module

5.8. quantization

A number or array or object, allowing one to control the quantization for the interpolated values of a fade.

When the value 0, undefined, or null is specified for this property, then the fade's interpolated value can be a floating point number (or contain floating point numbers, if it's a compound value). This can be a problem for fading values in certain applications where an integer value is desirable, and where a floating point number may be inappropriate. In such cases, a value of 1 can be specified for the quantization state property, thereby directing the fade to interpolate its value in increments of one.

5.8.1. Implemented in the Uize.Math.Blend Module

Supported for quantization in the Uize.Fade class is based on support for quantization in the Uize.Math.Blend module.

This module provides the underlying value blending engine that is used in fades. For an in-depth discussion of quantization and such topics as compound (hierarchical) quantization objects, consult the reference for the Uize.Math.Blend module.

NOTES

the initial value is undefined

IMPLEMENTATION INFO

this feature was introduced in this module

5.9. reverse

A boolean value, specifying whether or not the fade process should operate in reverse.

Because this flag complements the value of the progress state property, the progress property will have a value of 1 when the fade starts and 0 when the fade is done. This may also mean that the nature of the fade will not be exactly reversed and may actually be different if there is asymmetry resulting from the specific value of the curve state property.

NOTES

the initial value is undefined

IMPLEMENTATION INFO

this feature was introduced in this module

5.10. startValue

The value (or set of values) at which the fade process should start.

NOTES

the initial value is 0
see also the endValue state property

IMPLEMENTATION INFO

this feature was introduced in this module

5.11. value

The value (or set of values) at the current point in a fade that is in progress, as interpolated between the values of the startValue and endValue state properties.

NOTES

the initial value is 0

IMPLEMENTATION INFO

this feature was introduced in this module

6. Deprecated Features

6.1. Uize.Fade.blendValues Static Methods (DEPRECATED 2011-11-24)

Uize.Fade.blendValues  >> BECOMES >> Uize.Math.Blend.blend

6.2. acceleration State Property (DEPRECATED 2009-07-10)

A floating point value in the range of 0 to 1, specifying the fraction of the fade should be an acceleration phase.

This state property has been deprecated in favor of the more versatile curve state property and the Uize.Fade.celeration static method.

INSTEAD OF...

myInstance.set ({acceleration:.25,deceleration:.5});

USE...

myInstance.set ({curve:Uize.Fade.celeration (.25,.5)});

Setting a value for acceleration will have the effect of creating a curve function using the Uize.Fade.celeration static method and then setting the curve function created as the value of the curve property.

The curve state property is much more versatile than the acceleration State Property (DEPRECATED 2009-07-10) and deceleration State Property (DEPRECATED 2009-07-10), and lets you specify a curve function in order to achieve a wide variety of different kinds of non-linear fade effects, including effects like bounce, springiness, wobble, elasticity. etc. When setting a value for the curve property, you can provide your own hand-rolled curve function, or you can pick from the many convenient curve function generators provided in the Uize.Curve and Uize.Curve.Rubber modules. Even more complex curve functions can be generated using the versatile curve function modifiers provided in the Uize.Curve.Mod module.

NOTES

the initial value is undefined
the sum of the acceleration State Property (DEPRECATED 2009-07-10) and deceleration State Property (DEPRECATED 2009-07-10) must not exceed 1
see also the deceleration State Property (DEPRECATED 2009-07-10)
see the curve state property and the Uize.Fade.celeration static method

6.3. deceleration State Property (DEPRECATED 2009-07-10)

A floating point value in the range of 0 to 1, specifying the fraction of the fade should be a deceleration phase.

This state property has been deprecated in favor of the more versatile curve state property and the Uize.Fade.celeration static method.

INSTEAD OF...

myInstance.set ({acceleration:.25,deceleration:.5});

USE...

myInstance.set ({curve:Uize.Fade.celeration (.25,.5)});

Setting a value for deceleration will have the effect of creating a curve function using the Uize.Fade.celeration static method and then setting the curve function created as the value of the curve property.

The curve state property is much more versatile than the deprecated acceleration State Property (DEPRECATED 2009-07-10) and deceleration State Property (DEPRECATED 2009-07-10), and lets you specify a curve function in order to achieve a wide variety of different kinds of non-linear fade effects, including effects like bounce, springiness, wobble, elasticity. etc. When setting a value for the curve property, you can provide your own hand-rolled curve function, or you can pick from the many convenient curve function generators provided in the Uize.Curve and Uize.Curve.Rubber modules. Even more complex curve functions can be generated using the versatile curve function modifiers provided in the Uize.Curve.Mod module.

NOTES

the initial value is undefined
the sum of the acceleration State Property (DEPRECATED 2009-07-10) and deceleration State Property (DEPRECATED 2009-07-10) must not exceed 1
see also the acceleration State Property (DEPRECATED 2009-07-10)
see the curve state property and the Uize.Fade.celeration static method

7. Static Properties

7.1. Uize.Fade.moduleName

IMPLEMENTATION INFO

this is an override of an inherited feature (implementation is in this module, first introduced in Uize.Class)
this static feature is inherited by subclasses

7.2. Uize.Fade.nonInheritableStatics

IMPLEMENTATION INFO

this is an override of an inherited feature (implementation is in this module, first introduced in Uize.Class)
this static feature is not inherited by subclasses

7.3. Uize.Fade.pathToResources

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses