LavishScript:Events

From Lavish Software Wiki
Jump to: navigation, search

Overview

LavishScript events provide a way to hook functionality in either a script or module (or subsequently an extension or plugin for LavishScript applications such as Inner Space or Fury). Each event is referred to by name, and any number of atoms or C functions can be attached to the event. Every atom and C function will be executed in arbitrary order immediately when the event is executed. Events may be executed with any number of parameters, which will be passed to the atoms or C functions.

Using events in scripts

Registering an event

The lavishscript object type provides a method called RegisterEvent. All you need is a name, preferrably one that is fairly unique and describes what the event is for. For example, "Alias Added" is a LavishScript event that executes when an alias is created with the alias command.

LavishScript:RegisterEvent["Alias Added"]
LavishScript:RegisterEvent[My Event]

There are no restrictions on event names, so long as you follow LavishScript syntax rules. Registering an event twice will have no further effect.

Attaching to an existing event

To attach to an event, the event object type provides a method called AttachAtom. All you need is the name of an atom to attach to the event, and your atom will be executed the next time the event is executed. There is no limit to the number of atoms that can be attached to the same event. Your atom should be tailored to the event -- for example, "Alias Added" will pass the name of the alias that was added as a parameter, and therefore an atom to attach to this event should have a parameter to take that.

Event[Alias Added]:AttachAtom[OMGAnAliasWasAdded]
Event[My Event]:AttachAtom[MyEventExecuted]

Executing an event

The event object type provides two methods for execution: Execute and ThisExecute. ThisExecute is for when the event requires a special object, to be accessed with This, and the methods are otherwise identical. Any parameters given to the methods will be given to the event -- note that with ThisExecute, the first parameter will become This (use the name of an object currently in scope).

Event[My Event]:ThisExecute[SomeObject,"Hello this is a parameter to My Event"]
Event[Alias Added]:Execute[Kwyjibo]
Note
Kwyjibo is a Simpsons reference. See [1]

Detaching from an event

The event object type provides a method called DetachAtom. This is used in exactly the same way as AttachAtom, so the explanation stops here (see Attaching to an event).

Event[Alias Added]:DetachAtom[OMGAnAliasWasAdded]
Event[My Event]:DetachAtom[MyEventExecuted]

Unregistering an event

The event object type provides a method called Unregister. You do NOT need to unregister the event, as doing so may introduce synchronization issues with the event targets. For example, scripts or extensions that use your event will not be aware of its disappearance, and will not know they have been forcefully detached from the event. You should only unregister an event if you want to forcefully detach all targets from an event.

Event["Alias Added"]:Unregister
Event[My Event]:Unregister

Alternate way to register and unregister an event

Alternatively, LavishScript allows you to create a variable of the event object type to automatically register and later unregister an event. Simply declare the variable in the scope you want the event to be available. The variable may be used as the event object for execution and such as well.

declare MyEvent event "My Event"
MyEvent:ThisExecute[SomeObject,"Hello this is a parameter to My Event"]

Using Events in C

Note: This portion will be explained with LavishScript module API, but applies equally to APIs that expose LavishScript event API.

Registering an event

Use the RegisterEvent function to register an event. The return value of the function is the EventID, which is then used to attach or detach event targets, or unregister the event.

 unsigned long MyEvent=pLSInterface->RegisterEvent("My Event");

Retrieving the Event ID of an existing event

Retrieving the event ID is done exactly the same as registering an event. There is no functional or logical difference, and it is not harmful to register the event before the module that actually intends to register the event.

 unsigned long MyEvent=pLSInterface->RegisterEvent("My Event");

Attaching to an existing event

TODO

Executing an event

Use the ExecuteEvent function to execute an event. The function requires an event ID, and optionally accepts parameters to pass, as well as an object to use as the event's context. Parameters are given in argc,argv form and, as is customary in LavishScript API, uses an inclusive begin and exclusive end in the argument list.

pLSInterface->ExecuteEvent(MyEvent);  // executes the event with NO parameters

pLSInterface->ExecuteEvent(MyEvent,1,argc,argv); // executes the event with 1-argc parameters from argv

char *Parameter1="Parameter 1";
char *Parameter2="Parameter 2";
char *argv[]={
  Parameter1,
  Parameter2,
};
pLSInterface->ExecuteEvent(MyEvent,0,2,argv); // executes the event with some custom parameters

LSOBJECT This;
This.Ptr="I am a string object";
This.Type=pStringType;
pLSInterface->ExecuteEvent(MyEvent,0,0,0,&This); // executes the event with no parameters, in the context of a given string object

Detaching from an existing event

TODO

Unregistering an event

You do NOT need to unregister the event, as doing so may introduce synchronization issues with the event targets. For example, scripts or extensions that use your event will not be aware of its disappearance, and will not know they have been forcefully detached from the event. You should only unregister an event if you want to forcefully detach all targets from an event.

pLSInterface->UnregisterEvent(MyEvent);

See Also