Object to Object Events

Introduction

Object to Object Events (oto events) allows any object to listen to events raised by any other object. This functionality is built into the SimObject class in the engine from which all classes derive so it works equally well with ScriptObjects, Scenes, and GuiControls. There's very little setup and it's extremely simple to use.

Basic Example

To show you how this works, let's set up a basic example.

new ScriptObject(ObjA);
new ScriptObject(ObjB);
new ScriptObject(ObjC);

Here we have 3 creatively name objects. Let's play a game of Marco Polo with them! First we'll need to set the object to respond to a Marco event like so:

function ObjA:onMarco(%this)
{
    echo("A: Polo!");
}
function ObjB:onMarco(%this)
{
    echo("B: Polo!");
}
function ObjC:onMarco(%this)
{
    echo("C: Polo!");
}

Now, let's have B and C listen to A. There are two ways to do this so I'll demonstrate both:

ObjA.addListener(ObjB); //B now listens to A's events
ObjC.startListening(ObjA); //C now listens to A's events also

The last step is to have A yell Marco.

ObjA.postEvent("Marco");

This will cause B and C to both yell Polo!

Passing Data

It's possible to pass a little data along with the event. This is done simply by including the data after the event name:

ObjA.postEvent("Marco", "I'm hungry!");

Listeners can pick up this data simply by adding another variable to the function.

function ObjC:onMarco(%this, %stomachState)
{
    echo("C: Polo!");
    if(%stomachState !$= "")
    {
        echo("Let's go eat!");
    }
}

If you need to pass more than one piece of data then simply wrap it in a ScriptObject.

Unbreakable!

Although Oto Events seem simple, they're also hard to break! For example, you can delete objects in the middle of posting an event. So if B's callback deleted C then C's callback will safely never happen. It's important to note here that the callbacks occur in the order that the listeners start listening. Listeners can also safely stop listening at any time, objects can actually listen to their own events, and circular events are prevented.

API

Here's a full list of methods that can be used to control Object to Object Events.

StartListening(object)

The calling object starts listening to the given object.

StopListening(object)

The calling object stop listening to the given object.

AddListener(object)

The given object will start listening to the calling object.

RemoveListener(object)

The given object will stop listening to the calling object.

RemoveAllListeners()

Removes all listeners from the object.

PostEvent(eventName, data)

Calls the script function onEventName for all listening objects. So an event like Jump will call onJump for all listeners if such a function exists. Optional data can be included that will be passed to the listener. If a listener does not have a matching function for an event, then it will be safely skipped.