In this tutorial we are going to learn about the different events that occur in a Voxelent application and how we can use them.

JavaScript is not multi-threaded

First of all, it is important to have in mind that JavaScript is not a multi-threaded language. Nonetheless, there are some initiatives towards providing threads in JavaScript. For the moment being, we can count with one single thread per page.

Voxelent Events

Voxelent defines its own set of events. You can see the list of events in the API docs, under the vxl.events namespace. Here is a list of some of them:

event description
vxl.events.MODELS_LOADED Fired when all the models listed in a vxl.api.load or vxl.go.modelManager.load instruction have been loaded
vxl.events.DEFAULT_LUT_LOADED Fired when the default lookup table has been loaded. The publisher of this event is vxlLookupTableManager
vxl.events.SCENE_NEW Fired by the vxlScene constructor
vxl.events.SCENE_UPDATED Fired by vxlScene when a new actor is added to the scene
vxl.events.ACTOR_MOVED Fired by vxlActor
vxl.events.ACTOR_SCALED Fired by vxlActor
vxl.events.ACTOR_CHANGED_COLOR Fired by vxlActor
vxl.events.ACTOR_CHANGED_SHADING Fired by vxlActor
vxl.events.VIEW_NEW Fired by the vxlView constructor

In Voxelent, events are triggered when changes occur in any Actor, Scene, View, and during model loading among others.

Regardless of the type of event, all the classes in Voxelent use the vxlNotifier object, and more specifically its global instance vxl.go.notifier.

The following diagram shows the events that the vxlView, vxlScene and vxlActor publish and subscribe to. The notifier acts as a mediator decoupling the publishers from the subscribers.

The vxlNotifier class

The vxlNotifier offers the methods publish, subscribe, and fire:

Publishing events

Any object that wants to fire Voxelent events needs to register first with the vxlNotifier. This is done by invoking its publish method.

Method signature:

vxlNotifier.publish(events, publisher);

Invoked by the publisher, the first parameter contains the event or list of the events that the publisher is committing to deliver

Example (taken from the vxlScene constructor):

var e = vxl.events; //alias
vxl.go.notifier.publish([
e.SCENE_NEW,
e.SCENE_UPDATED],this); //this = scene instance

Subscribing to events

Method signature:

vxlNotifier.subscribe(events, subscriber);

Invoked by the subscriber, the first parameter contains the event, or list of events that the subscriber wants to be notified about

Example (taken from the vxlScene constructor):

var e = vxl.events; //alias
vxl.go.notifier.subscribe([e.MODELS_LOADED,e.DEFAULT_LUT_LOADED], this); //this = scene instance

Firing events

Method signature:

vxlNotifier.fire(event, publisher);

This method is invoked by the publisher of the event. The publisher has the responsibility of determining when to fire any of the events that it has agreed to publish. The second parameter is usually the this keyword, which refers to the publisher instance that is firing the event.

For example, let’s take a look at vxlModelManager. This class is responsible for loading geometric models into a Voxelent application. In its constructor, vxlModelManager publishes the vxl.event.MODELS_LOADED. This event is fired by vxlModelManager upon a successful invocation of its load method. This method can be invoked directly or through the Public API as shown in the following diagram:

Here, the global instance of vxlNotifier (vxl.go.notifier), notifies all the subscribers that a vxl.events.MODEL_LOADED event has been fired, passing along the source of the event.

Handling Events

To be notified of an event, the subscriber needs to implement the handleEvent(event, source) method.

Example 1:

In demo-heart.html we subscribe to the vxl.events.MODEL_LOADED event from the source page and upon receiving this event in the handleEvent method, we proceed to set up the camera position and to start the animation.

 

 

 

Example 2:

In demo-brain.html, we subscribe to the vxl.events.MODEL_LOADED event from the source page and as this is the only event that we subscribe to, we know that when handleEvent is invoked, that mens that the vxl.events.MODEL_LOADED event has been fired. At this point, we enable the bounding box in the image and call vxlCamera.longShot to visualize all the objects in the scene.