com.flagstone.transform.action
Class NewFunction2

java.lang.Object
  com.flagstone.transform.action.NewFunction2

All Implemented Interfaces:

Action, Copyable<Action>, SWFEncodeable

public final class NewFunction2
extends Object
implements Action

The NewFunction2 action is used to create a user-defined function with optimisations to improve performance.

NewFunction2 was added in Flash 7 to improve the performance of function calls by allowing pre-defined variables such as _root, _parent, _global, super, this and the arguments passed to the function to be pre-loaded to a set of up to 256 internal registers.

The optimisation attribute is a compound code, containing a number of flags that control which variables are pre-loaded:

CreateSuper	Create and initialise the super variable with the parent class of the function.
CreateArguments	Create the arguments variable which contains the arguments passed to the function.
CreateThis	Create and initialise the this variable with the object.
LoadThis	Pre-load the this variable into register number 1.
LoadArguments	Pre-load the parent variable into register number 2.
LoadSuper	Pre-load the super variable into register number 3.
LoadRoot	Pre-load the _root variable into register number 4.
LoadParent	Pre-load the _parent variable into register number 5.
LoadGlobal	Pre-load the _global variable into register number 5.

The register numbers that the predefined variables are assigned to are fixed. When specifying which of the functions arguments are also assigned to registers it is important avoid these locations otherwise the variables will be overwritten.

User-defined functions are also used to create methods for user-defined objects. The name of the function is omitted and the function definition is assigned to a variable which allows it to be referenced at a alter time. See the example below.

The arguments supplied to the function can be referenced by the name supplied in the arguments list.

All the action objects added are owned by the function. They will be deleted when the function definition is deleted.

See Also:

NewFunction

Nested Class Summary

static class	NewFunction2.Builder The Builder class is used to generate a new NewFunction2 object using a small set of convenience methods.
static class	NewFunction2.Optimization The set of optimisations that can be used to speed up the execution of functions.

Constructor Summary

NewFunction2(NewFunction2.Builder builder)
Creates and initialises a NewFunction2 object using parameters defined in the Builder.

NewFunction2(NewFunction2 object)
Creates and initialises a NewFunction2 action using the values copied from another NewFunction2 action.

NewFunction2(String aString, int count, Set<NewFunction2.Optimization> opts, Map<String,Integer> map, List<Action> list)
Creates a NewFunction2 with the specified name, argument names and actions to be executed.

NewFunction2(SWFDecoder coder, Context context)
Creates and initialises a NewFunction2 definition using values encoded in the Flash binary format.

Method Summary

NewFunction2	copy() Creates a complete copy of this object.
void	encode(SWFEncoder coder, Context context) Encode an object to the Flash binary format.
List<Action>	getActions() Get the actions executed by the function.
Map<String,Integer>	getArguments() Get the list of RegisterVariables that define the function arguments and whether they are assigned to internal registers or to local variables in memory.
String	getName() Get the name of the function.
Set<NewFunction2.Optimization>	getOptimizations() Get the list of Optimizations that will be used.
int	getRegisterCount() Get the number of registers to allocate for function variables.
int	prepareToEncode(Context context) Prepare an object for encoding, returning the expected size of an object when it is encoded.
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

NewFunction2

public NewFunction2(NewFunction2.Builder builder)

Creates and initialises a NewFunction2 object using parameters defined in the Builder.

Parameters:

builder - a Builder object containing the parameters to generate the function definition.

NewFunction2

public NewFunction2(SWFDecoder coder,
                    Context context)
             throws IOException

Creates and initialises a NewFunction2 definition using values encoded in the Flash binary format.

Parameters:

coder - an SWFDecoder object that contains the encoded Flash data.

context - a Context object used to manage the decoders for different type of object and to pass information on how objects are decoded.

Throws:

IOException - if an error occurs while decoding the data.

NewFunction2

public NewFunction2(String aString,
                    int count,
                    Set<NewFunction2.Optimization> opts,
                    Map<String,Integer> map,
                    List<Action> list)

Creates a NewFunction2 with the specified name, argument names and actions to be executed. The order of the Strings in the argument list indicate the order in which the values will be popped off the stack when the function is executed. The first argument is popped from the stack first.

Parameters:

aString - the name of the function. Can be an empty string if the function is anonymous.

count - the number of registers to allocate for variables.

opts - the set of optimizations that will be applied to boost function performance.

map - the arguments and any register numbers they will be assigned to (zero for no assignment).

list - the list of actions that define the operation performed by the function.

NewFunction2

public NewFunction2(NewFunction2 object)

Creates and initialises a NewFunction2 action using the values copied from another NewFunction2 action.

Parameters:

object - a NewFunction2 action from which the values will be copied. References to immutable objects will be shared.

Method Detail

getName

public String getName()

Get the name of the function. If the function will be used as an object method then the name is an empty string.

Returns:

the name of the function or an empty string.

getRegisterCount

public int getRegisterCount()

Get the number of registers to allocate for function variables.

Returns:

the number of registers to allocate.

getOptimizations

public Set<NewFunction2.Optimization> getOptimizations()

Get the list of Optimizations that will be used.

Returns:

the set of optimizations to increase performance.

getArguments

public Map<String,Integer> getArguments()

Get the list of RegisterVariables that define the function arguments and whether they are assigned to internal registers or to local variables in memory.

Returns:

a copy of the function arguments with optional register assignments.

getActions

public List<Action> getActions()

Get the actions executed by the function.

Returns:

a copy of the list of actions that make up the function body.

copy

public NewFunction2 copy()

Creates a complete copy of this object.

Specified by:

copy in interface Copyable<Action>

Returns:

a deep-copy of this object. New instances of mutable objects are copied and immutable instances are shared.

toString

public String toString()

Overrides:

toString in class Object

prepareToEncode

public int prepareToEncode(Context context)

Prepare an object for encoding, returning the expected size of an object when it is encoded. This method also used to initialise variables, such as offsets and flags that will be used when the object is encoded. Generally the method returns the size in bytes, however when called on objects that use bit fields such as shapes the methods will return the size in bits.

Specified by:

prepareToEncode in interface SWFEncodeable

Parameters:

context - an Context that allows information to be passed between objects to control how they are initialised for encoding.

Returns:

the size of the object when it is encoded.

encode

public void encode(SWFEncoder coder,
                   Context context)
            throws IOException

Encode an object to the Flash binary format.

Specified by:

encode in interface SWFEncodeable

Parameters:

coder - an SWFEncoder object.

context - an Context that allows information to be passed between objects to control how they are initialised for encoding.

Throws:

IOException - if an error occurs while encoding the object.