registerSpecialPropertySplitter()

Availability

AS2 and AS3.

Usage

Tweener.registerSpecialPropertySplitter(name:String, splitterFunction: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 new value you want to assign to that property; and it must return an Array of objects, each object containing a name property (with the name of the property, or special property, that need to be tweened) and a value property (with the value the property should be tweened to).

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

Description

Creates and registers a new special property splitter, which is a special property that actually splits itself into several other property or special property tweenings. This is useful if you want to create a special property that acts on several different properties at the same time, instead of just wrapping some kind of functionality of other method.

Some special properties used on Tweener are created and registered with this method; check the SpecialPropertiesDefault.as file to check what they do.

Returns

Nothing.

Examples

Suppose you want to create a new special property, called _scale, that immediately sets the _xscale and _yscale of a MovieClip in one go. 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 _scale property this way (AS2):

_scale_splitter = function(p_value:Number, p_parameters:Array):Array {
	var nArray:Array = new Array();
	nArray.push({name:"_xscale", value: p_value});
	nArray.push({name:"_yscale", value: p_value});
	return nArray;
}
Tweener.registerSpecialPropertySplitter("_scale", _scale_splitter);

That is, you tell the splitter function the value you want the split properties to have, and the function returns a list of the corresponding property values, and their target values. After that is done, you can use this new special property natively, as in:

Tweener.addTween(myMC, {_scale:200, time:1});

This will automatically scale myMC to 200% of scale, regardless of its individual horizontal and vertical scales.

Special property splitters can also return the name of special properties themselves as part of the list of properties to be tweened. For example, this is part of the special property that adds the _color special property to Tweener, as defined by SpecialPropertiesDefault.as:

public static function _color_splitter (p_value):Array {
	var nArray:Array = new Array();
	if (p_value == null) {
		// No parameter passed, so just resets the color
		nArray.push({name:"_color_ra", value:100});
		nArray.push({name:"_color_rb", value:0});
		nArray.push({name:"_color_ga", value:100});
		nArray.push({name:"_color_gb", value:0});
		nArray.push({name:"_color_ba", value:100});
		nArray.push({name:"_color_bb", value:0});
	} else {
		// A color tinting is passed, so converts it to the object values
		nArray.push({name:"_color_ra", value:0});
		nArray.push({name:"_color_rb", value:AuxFunctions.numberToR(p_value)});
		nArray.push({name:"_color_ga", value:0});
		nArray.push({name:"_color_gb", value:AuxFunctions.numberToG(p_value)});
		nArray.push({name:"_color_ba", value:0});
		nArray.push({name:"_color_bb", value:AuxFunctions.numberToB(p_value)});
	}
	return nArray;
}

This special property receives a numeric color value (such as 0xff56a1) and converts it into specific color channel twewnings, to tint a MovieClip by way of a tweening. Notice that _color_ra (and others) are also special properties themselves.

See also

registerSpecialProperty, Special Properties