The Custom Object
By Matt Galanto

Index

• Disclaimer
• The Basics
• Functions
• Conditions
  - On Creation of an Instance
  - On Function
  - On Destruction of an Instance
  - On Error
• Actions
  - Create Instance
  - Destroy Instance
  - Destroy All Instances
  - Set Default Instance
  - Specify an Instance
  -> Call a Function
  -> Set an Integer Variable
  -> Set a Float Variable
  -> Set a String Variable
  - Current Instance
  -> Call a Function
  -> Set an Integer Variable
  -> Set a Float Variable
  -> Set a String Variable
  - Returns and Loops
  -> Return
  -> Return an Integer
  -> Return a Float
  -> Return a String
  -> Set Function to Loop
  - Global Variables
  -> Create a Global Variable
  -> Set an Integer Variable
  -> Set a Float Variable
  -> Set a String Variable
  - Local Variables
  -> Create a Local Variable
  -> Set an Integer Variable
  -> Set a Float Variable
  -> Set a String Variable
  - Errors
  -> Generate an Error
  -> Clear Expression Error Code
• Expressions
  - Slot Data
  -> Get an Integer from a Slot
  -> Get a Float from a Slot
  -> Get a String from a Slot
  - Specify an Instance
  -> Get an Integer Variable
  -> Get a Float Variable
  -> Get a String Variable
  - Current Instance
  -> Get Name of Instance
  -> Get an Integer VariableI
  -> Get a Float Variable
  -> Get a String Variable
  - Global Variables
  -> Get an Integer Variable
  -> Get a Float Variable
  -> Get a String Variable
  - Local Variables
  -> Get an Integer Variable
  -> Get a Float Variable
  -> Get a String Variable
  - Errors
  -> Get Current Error Code
  -> Get Current Expression Error Code
  - Miscellaneous
  -> Get Loop Index of Current Function
  -> Get Number of Parameters of Current Function
  -> Get Return Type of Current Function
  -> Format a String
  -> Unformat a String
  -> Get Number of Selected Objects

Disclaimer

The author of this extension makes no claims concerning the fitness of this extension for any purpose whatsoever, and makes no gurantees, written or implied, of its level of security and safety to authors or to end users in any respect. You agree to use this extension at your own risk and to hold the author harmless in any event.

The Basics

The Custom Object may seem like it's overwhelming and complicated at first, but I think the time needed to learn the object may just be worth it. The first thing I want to do is define some terms:
- Instance: An instance is a lot like an object in MMF. In fact, I chose instance instead of object simply so that things wouldn't be so confusing. Creating an instance is just like creating an object in MMF. You can create multiple instances of a particular Custom Object just like you can create multiple duplicate objects of a particular Active Object.
- Default Instance: The default instance can be set with the Set Default Instance action. Once set, whenever an action, condition, or expression asks for an instance, you can use "" to specify the default instance. The exception is the "Create Instance" action for obvious reasons.
- Function: A function doesn't really have an MMF analogy. Basically, when you call or evaluate a function, the object executes events corresponding to the particular function that has been called. The object continues executing these events until a Return action is executed.
- Variable: A variable is just like an Alterable Value, Global Value, or Alterable String in MMF. Unlike in MMF, avariable in the Custom Object stores three separate values: an integer, a float (an integer will a decimal), and a string. There are three types of variables.
- Global Variable: A global variable is a variable that is accessible by all Custom Objects (including clones) and at all times. Global variables do not keep their data over frames.
- Local Variable: A local variable is the most complicated type of variable to explain. A local variable is accessible by all instances of a particular Custom Object and is not shared with other Custom Objects. Local variables are subject to function scope. Basically, what happens is that everytime a function is called or when an instance is created or destroyed, a fresh set of local variables, consisting of the parameters passed to the function, is created. The old local variables are left inaccessible until the function returns, at which time, the old local variables become accessible again.
- Member Variable: A member variable is associated to a particular instance. Each instance has its own unique set of member variables. These variables are accessible at all times

Functions

Basically, when you call or evaluate a function, the object executes events corresponding to the particular function that has been called. The object continues executing these events until a proper Return action is executed. There are 2 actions and 6 expressions that call functions. Each has two basic components: a function name and a parameter list. I want to take you step-by-step through what happens when you call a function:

1. If the "Verify Function" option is selected. The object checks to make sure that the function exists. If it does not, an error is generated.
2. The object sets the current instance to the specified instance.
3. The object creates a fresh set off local variables for the newly called function. This set of local variables is empty at this time.
4. The object parses the parameter list and creates local variables named p1, p2, p3, etc. to store each of the parameters. Each variable created from a parameter stores an integer, a float, a string created from the parameter. Each string is then unformatted automatically using the Unformat a String expression. Because of this, all string parameters should be formatted by the Format a String expression (this is NOT done automatically).
5. The object now starts testing the conditions of events with the On Function condition. If all conditions are true, the event is executed.
6. If the "Automatically Loop Functions" option is selected, the object continues cycling through the events until a proper Return action is executed. At this point the current event is finished being executed, the On Function condition is set to return false, and the object finishes its current loop, which should not have anymore events being executed.
7. If the "Automatically Loop Functions" option is notselected, the object cycles through the events until a proper Return action is executed as earlier or until the end of the events at which point an error is generated. The Set Function to Loop action can be used to have the function loop itself at the end of the events.
8. Once the last loop finishes, the local variables of that function are destroyed and the old data (the old local variables and the old current instance) are restored.
9. If an action called the function, execution returns to the event that called the function.
10. If an expression called the function, execution returns to that expression, which returns the value specified in the Return action.

A word about Patrameter Lists: Parameter lists are comma delimited lists. They should not contain spaces unless you want a space in your string. Also, you should use the Format a String expression on any strings that you want to pass. Otherwise, any backslahes or commas in your string will mess things up. String parameters are unformatted automatically by the object. Here are some sample parameter lists:

• "0,0.23,2435,0.3232,Hi I'm Matt,90,Yo"
• "3232,234.5,"+FomatString$("Custom Object", "I'm using commas,,,,,,, in this string.")
• "Hi,0.2342"
• "0"
• "23.45,Word,3232"
• FomatString$("Custom Object", string$("FileName"))

Conditions

On Creation of an Instance
This condition is used to denote an event that will be executed when an instance is created. They are executed right after the instance is created. The created instance will be the current instance.

On Function
This condition is used to denote an event that will be executed when the specified function is called.

On Destruction of an Instance
This condition is used to denote an event that will be executed when an instance is destroyed. They are executed just before the instance is destroyed. The instance to be destroyed will be the current instance.

On Error
This condition will return true if an error has occured in an action or in a condition. Events with this condition will be executed as soon as an error occurs in the object. The error code for the error will only be available to events with this condition. For getting errors in expressions, use the 'Get Current Expression Error Code' expression.

Actions

Create Instance
This action creates an instance with the specified name. After the instance is created, events with the On Creation of an Instance condition are executed with the specified parameters. A fresh set of local variables are created for the execution of these events. You should not use a Return with these events.

Destroy Instance
This action destroys the specified instance. Before the instance is destroyed, events with the On Destruction of an Instance condition are executed. A fresh set of local variables are created for the execution of these events. You should not use a Return with these events. If an instance is in use, it cannot be destroyed. An error will be generated, and the instance will be left alone.

Destroy All Instances
This action destroys all instances. Before the instance is destroyed, events with the On Destruction of an Instance condition are executed. A fresh set of local variables are created for the execution of these events. You should not use a Return with these events. If an instance is in use, it cannot be destroyed. An error will be generated, and the instance will be left alone.

Set Default Instance
This action sets the default instance that is used in place of "" when an instance is requested. See the Basics section for more details.

Specify an Instance
The actions under this menu heading ask you to enter a specific instance to be used.

Current Instance
The actions under this menu heading use the current instance. For the next four actions, I will refer to this as the specified instance. The current instance is only applicable when inside a function, creation, or destruction. For whatever instance the function, creation, or destruction has been called, that is the current instance.

Call a Function
This action executes events with the On Function condition and with the specified function name with the specified parameters. The current instance is set to the specified instance and a fresh set of local variables is created. The returned value is converted to the specified type and stored in the specified slot. Slots range from 0 to 10 inclusive. If the return type is 0, the return value is ignored and nothing is stored in a slot. Return types: 0 = void, 1 = integer, 2 = float, 3 = string.

Set an Integer Variable (Member Variable)
This action sets the specified member integer of the specified instance to the specified value.

Set a Float Variable (Member Variable)
This action sets the specified member float of the specified instance to the specified value.

Set a String Variable (Member Variable)
This action sets the specified member string of the specified instance to the specified string.

Return
This action halts the current function and returns to the event that called the function. The function will literally return at the end of the current event!

Return an Integer
This action halts the current function and returns the specified integer to the expression that called the function. The function will literally return at the end of the current event!

Return a Float
This action halts the current function and returns the specified float to the expression that called the function. The function will literally return at the end of the current event!

Return a String
This action halts the current function and returns the specified string to the expression that called the function. The function will literally return at the end of the current event!

Set Function to Loop
This action sets the function to repeat itself when it finishes with its current iteration. The function will not repeat if it returns.

Create a Global Variable
This action creates a global variable of the specified name. The default integer is 0, the default float is 0.0, and the default string is "".

Set an Integer Variable (Global Variable)
This action sets the specified global integer to the specified value.

Set a Float Variable (Global Variable)
This action sets the specified global float to the specified value.

Set a String Variable (Global Variable)
This action sets the specified global string to the specified string.

Create a Local Variable
This action creates a local variable of the specified name. The default integer is 0, the default float is 0.0, and the default string is "".

Set an Integer Variable (Local Variable)
This action sets the specified local integer to the specified value.

Set a Float Variable (Local Variable)
This action sets the specified local float to the specified value.

Set a String Variable (Local Variable)
This action sets the specified local string to the specified string.

Generate an Error
This action generates an error with the specified code as if the error had occured in a condition or in an action.

Clear Expression Error Code
This action sets the current expression error code to 0.

Expressions

Get an Integer from a Slot
IntegerSlot("Custom Object", Slot)
This expression returns the integer stored in the specified slot. Slot values range from 0 to 10 inclusive. If an invalid slot is entered, the return values is 0. There is a separate set of slots for each data type, so having a function store a string in slot 1 will not overwrite the integer and float stored in slot 1.

Get a Float from a Slot
FloatSlot("Custom Object", Slot)
This expression returns the float stored in the specified slot. Slot values range from 0 to 10 inclusive. If an invalid slot is entered, the return values is 0.0. There is a separate set of slots for each data type, so having a function store a string in slot 1 will not overwrite the integer and float stored in slot 1.

Get a String from a Slot
StringSlot$("Custom Object", Slot)
This expression returns the string stored in the specified slot. Slot values range from 0 to 10 inclusive. If an invalid slot is entered, the return values is "". There is a separate set of slots for each data type, so having a function store a string in slot 1 will not overwrite the integer and float stored in slot 1.

Get an Integer Variable (Specify an Instance) (Member Variable)
IntOfInstance("Custom Object", Instance Name, Variable Name)
This expression returns the specified integer of the specified instance.

Get a Float Variable (Specify an Instance) (Member Variable)
FloatOfInstance("Custom Object", Instance Name, Variable Name)
This expression returns the specified float of the specified instance.

Get a String Variable (Specify an Instance) (Member Variable)
StringOfInstance$("Custom Object", Instance Name, Variable Name)
This expression returns the specified string of the specified instance.

Get Name of Instance (Current Instance)
GetInstanceName$("Custom Object")
This expression returns the name of the current instance.

Get an Integer Variable (Current Instance) (Member Variable)
IntOfCurrInstance("Custom Object", Variable Name)
This expression returns the specified integer of the current instance.

Get a Float Variable (Current Instance) (Member Variable)
FloatOfCurrInstance("Custom Object", Variable Name)
This expression returns the specified float of the current instance.

Get a String Variable (Current Instance) (Member Variable)
StringOfCurrInstance$("Custom Object", Variable Name)
This expression returns the specified string of the current instance.

Get an Integer Variable (Global Variable)
GlobalInt("Custom Object", Variable Name)
This expression returns the specified global integer.

Get a Float Variable (Global Variable)
GlobalFloat("Custom Object", Variable Name)
This expression returns the specified global float.

Get a String Variable (Global Variable)
GlobalString$("Custom Object", Variable Name)
This expression returns the specified global string.

Get an Integer Variable (Local Variable)
LocalInt("Custom Object", Variable Name)
This expression returns the specified local integer.

Get a Float Variable (Local Variable)
LocalFloat("Custom Object", Variable Name)
This expression returns the specified local float.

Get a String Variable (Local Variable)
LocalString$("Custom Object", Variable Name)
This expression returns the specified local string.

Get Current Error Code
Error("Custom Object")
This expression returns the current error code resulting from an error in an action or condition, which is only meaningful when the event has an On Error condition.
Error Codes:
0: No errors
1: Instance does not exists
2: Functions does not exist
3: Variable does not exist
4: Cannot call another function after current function has returned
5: Cannot destroy an instance that is in use
6: Instance already exists
7: Variable already exist
8: Invalid slot number
9: Cannot return when not in a function or during a creation or destruction
10: Alrady returned from function
11: Function did not return
12: Cannot Loop a Function that Has Returned
13: Cannot have an instance named ""
14: Cannot refer to current instance when not in a function or during a creation or destruction
15: Invalid fixed value

Get Current Expression Error Code
ExpressionError("Custom Object")
This expression returns the current error code resulting from an error in an expression. The same codes apply here as above.

Get Loop Index of Current Function
FunctionLoopNumber("Custom Object")
This expression returns the loop index of the current function. The loop index is the number of times the current function has repeated itself. The loop index of the first loop is 0.

Get Number of Parameters of Current Function
NumberOfParameters("Custom Object")
This expression returns the number of parameters of the current function.

Get Return Type of Current Function
GetReturnType("Custom Object")
This expression returns the return type of the current function:
-> -1 indicates that there is are currently no active functions or that an On Creation or On Destruction event is currently in progress.
-> 0 indicates that no return value is expected.
-> 1 indicates that an integer is expected.
-> 2 indicates that a float is expected.
-> 3 indicates that a string is expected.

Format a String
FormatString$("Custom Object", String)
This expression takes a string and places escape characters before backslashes (\) and commas (,). Doing this allows you to use strings with these characters in them as parameters to a function. When converting parameters to variables, all parameters are Unformatted automatically whether you formatted them or not.

Unformat a String
UnformatString$("Custom Object", String)
This expression takes a string and removes escape characters. When converting parameters to variables, all parameters are Unformatted automatically whether you formatted them or not.

Get Number of Selected Objects
CountSelected("Custom Object", Fixed Value)
This expression counts the number of objects of the specified type for which the current conditions are true. The type of object is specified by the fixed value if one of those objects.