Custom Events v1.0.0

Last updated: Apr 21th, 2018

Scripts

Register event

Name

chomlin_events_register

Description

Registers an event. You must call this script before you can dispatch or listen to an event.

Arguments
Name Type Description
event_name String Name of an event to register
Returns

Event handle you use to dispatch or unregister the event.

The event handle is just event's name, but it might change in the future. Use this handle to dispatch the event instead of the name. Hard-coding is terrible anyway, and your code will not suddenly stop working after the asset is updated.

Listen to event

Name

chomlin_events_listen

Description

Creates an event listener script which called after you dispatch the event. Each event listener may receive up to 10 arguments that the dispatcher may send. Those arguments are available in listener script as argument0, argument1, ..., argument9

Keep in mind

This script sores self to use when calling listener script later on. In other words, listener script is called inside the with (self) {} block where self is going to point to the object that created the listener. It means that listeners have access to properties of objects that register them.

Arguments
Name Type Description
event_name String Name of an event to listen to
listening_script Script A script that's called after the event dispatch.
Returns

Event listener handle used to stop listening.

Dispatch event

Name

chomlin_events_dispatch

Description

Dispatches an event.

Arguments
Name Type Description
event_name String Name of an event to dispatch
event_arguments array Array of up to 10 arguments to pass to the listener. While this argument is an array, the listener receives them as argument0, argument1, ..., argument9
Returns

No return

Unregister event

Name

chomlin_events_unregister

Description

Removes event and all its active listeners, freeing memory. You do not have to remove listeners before calling this script.

Arguments
Name Type Description
event_name String Name of an event to unregister
Returns

No return

Remove listener

Name

chomlin_events_stop_listening

Description

Stops listener from listening to an event.

Arguments
Name Type Description
event_listener Event listener handle returned by chomlin_events_listen
arg0..9 Any You may pass up to 10 arguments to event listener which will be available in the listener as argument0, argument1, .. argument9.
Returns

No return

Clear all events and listeners

Name

chomlin_events_clear

Description

Equivalent of calling chomlin_events_unregister on all registered events.

Arguments

No arguments

Returns

No return

Best Practices

Prevent "memory leaks"

Listeners and events are in no way linked to objects that create them. It means that there is no way to automatically removed them from memory upon objects' destruction. If you do not unregister an event, or remove the listener, but lose their handles, you will not be able to free the memory they occupy unless you use the chomlin_events_clear script.

Keep in mind that it is not a memory leak because you still have a way of freeing the memory. This effect may stack resulting in higher memory usage though, so remember to clear events and listeners