registerSpecialProperty()

Availability

AS2 and AS3.

Usage

Tweener.registerSpecialProperty(name:String, getFunction:Function, setFunction:Function [, parameters:Array]);

Parameters

name:Number — The name of the new special property you want to create. This name cannot conflict with the name of any existing tweening parameter, and it's recommended that you do not use the name of any special property already existing as this would overwrite them.

getFunction:Function — The function used to read the property or value corresponding to this special property. Must receive a parameter, which is the target object that must be read.

setFunction:Function — The function used to set the value of the property corresponding to this special property. Must receive two parameters: the target object, which is the object that will be changed, and the desired value, which is a Number.

parameters:Array — An optional parameter containing an array of properties of any kind. This parameter is passed to the getFunction and setFunction functions when updating the values of special properties; that way, you can have the same function work for a number of different special properties, but doing different things to them based on the parameters received.

Description

Creates and registers a new special property, which is like a normal property, but with additional functionality. From an Object Oriented Programming point of view, this is like a getter/setter - meaning you create a function that reads a property of an object, and another function that sets the value of this same property, then tie them both to a special name.

A feature like this shouldn't be needed most of the times, as changing the value of a given property is all that's needed to create a transition of some kind. Some objects or classes don't have exposted properties, or some properties might need additional code for a propert tweening, and that's where the need for special properties arise.

Almost all special properties used on Tweener are created and registered with this method; check the SpecialPropertiesDefault.as file to check what they do. Some special properties, however, are grouping of other properties. This is the case of _color and _colorTransform, for example, which are related to a number of different properties, and as such don't really fit into the whole getter/setter architecture. Cases like these are created with the registerSpecialPropertySplitter method instead.

Returns

Nothing.

Examples

Suppose you want to create a new special property, called _autoAlpha, that immediately sets the _alpha of a MovieClip and, in case it is 0, also makes the object invisible by setting its _visible property to false so it can really be hidden from mouse events. This is not needed since such a special property already exists by default, but it's used on this example.

In this case, one could register this new _autoAlpha property this way:

_autoAlpha_get = function(p_obj:Object):Number {
    return p_obj._alpha;
};
_autoAlpha_set = function(p_obj:Object, p_value:Number):Void {
    p_obj._alpha = p_value;
    p_obj._visible = (p_value != 0);
};
Tweener.registerSpecialProperty("_autoAlpha", _autoAlpha_get, _autoAlpha_set);

First the get and set functions are created, and then, a new special property is registered. This new special property would be available and be accepted by Tweener from that point on, regardless of Class or Object referred to.

For example, to do a fade out with that new special property, it works like this:

Tweener.addTween(myMC, {_autoAlpha:0, time:1});

After fading out, myMC would automatically be set to invisible.

As a comparison, the alternative - without using a new special property, and using events to synchronize the visibility change to the tweening start or end, regardless of initial delays - would look like this:

// Fade in
Tweener.addTween(myMC, {_alpha:100, time:1, onStart:function() { this._visible = true; }});

// Or fade out
Tweener.addTween(myMC, {_alpha:0, time:1, onComplete:function() { this._visible = false; }});

Also, the additional parameters can be used to create more powerful functions, instead of being forced to duplicate very similar functions and assigning them to specific special properties. For example, let's suppose you have an object with functions getValueX(), getValueY(), and getValueZ(), and their equivalents, setValueX(), setValueY(), and setValueZ(), and you want to create special properties to update those values. With normal special properties, you could write this:

_valueX_get = function(p_obj:Object):Number {
    return p_obj.getValueX();
};
_valueX_set = function(p_obj:Object, p_value:Number):Void {
    p_obj.setValueX(p_value);
};
_valueY_get = function(p_obj:Object):Number {
    return p_obj.getValueY();
};
_valueY_set = function(p_obj:Object, p_value:Number):Void {
    p_obj.setValueY(p_value);
};
_valueZ_get = function(p_obj:Object):Number {
    return p_obj.getValueZ();
};
_valueZ_set = function(p_obj:Object, p_value:Number):Void {
    p_obj.setValueZ(p_value);
};
Tweener.registerSpecialProperty("_valueX", _valueX_get, _valueX_set);
Tweener.registerSpecialProperty("_valueY", _valueY_get, _valueY_set);
Tweener.registerSpecialProperty("_valueZ", _valueZ_get, _valueZ_set);

This works well, but with parameters, you can write something like so, using only one two functions:

_valueAny_get = function(p_obj:Object, p_parameters:Array):Number {
    return p_obj[p_parameters[0]]();
};
_valueAny_set = function(p_obj:Object, p_value:Number, p_parameters:Array):Void {
    p_obj[p_parameters[1]](p_value);
};
Tweener.registerSpecialProperty("_valueX", _valueAny_get, _valueAny_set, ["getValueX", "setValueX"]);
Tweener.registerSpecialProperty("_valueY", _valueAny_get, _valueAny_set, ["getValueY", "setValueZ"]);
Tweener.registerSpecialProperty("_valueZ", _valueAny_get, _valueAny_set, ["getValueZ", "setValueZ"]);

See also

registerSpecialPropertySplitter, Special Properties