Tools and Events

Tools allow you to intercept mouse and touch events. The default set of tools installed will handle scene navigation (orbit, pan, zoom) for both mice and touch interfaces. You can override or disable the default tools for custom behavior.

Each event has a stack of tools. Some events will look for the first tool that is able to handle the event (ex drag), whereas other events will continue through the entire stack of tools unless explicitly stopped (ex click, hover). Events are normalized for touch interactions, so click will be called on touch as well as on mouse click.

There are two methods exposed:

A Tool is an object with keys corresponding to the events it handles. There are two classes of events:

1. Simple events

These include:

mousedown - Will be called for both mousedown, and touchstart
mouseup - Will be called for both mouseup and touchend
dblclick - Double click
click - This event will be called on mouseup, if it is within 300ms of the mousedown event, and the mouse has not moved.
hover - This event will be fired for any mousemove event while no button is pressed. This will be called extremely frequently, so any handlers must be fast.
scroll - Normalized handler that maps the mouse wheel. Is called with a delta value.
pinch - For touch interfaces, will be called with two finger touch that is moving together, or apart.
swipe - For touch interfaces, will be called with two finger touch that are moving in the same direction.
nodeenter - For mouse and touch interface, will be called when mouse enters or touch inside the bounding box of the node. For VR mode, will be called when view or controller direction enter the bounding box.
nodeleave - Similar with nodeenter but will be fired when leave the bounding box.
controllerupdate - For VR mode, will be called every single frame when VR mode is activated and at lease one controller are connected.

These events can be handled by passing in a function for the appropriate key. For example, to log to the console every time a click event is triggered, use:

addTool({
  click: function(ev) {
    console.log('Click occurred at', ev.clientX, ev.clientY);
  }
}, 'Log Clicks');

The event passed in to the handler functions is a synthetic event. You may access the original event that triggered the action with the originalEvent property.

By default, these events will keep going down the stack, calling each handler function. However, if you return false from your handler function, the propagation will be stopped.

2. Compound events

This is the drag event, which is a compound event composed of mousemove events between a mousedown and mouseup event (and the corresponding touchstart, touchmove, and touchend).

The interface for the drag event is slightly different, since we must indicate if we would like to handle this event when the drag is started.

We must provide a function that will either return false, indicating that we will not handle this drag event, or return an Object, with a handle function attached. This handle function will be what is called while dragging. We may also provide an optional momentum key, which if set to true, will provide a decaying momentum stream of events after the drag event has ended.

For example:

addTool({
  drag: function(ev) {
    // handle drags originating only from the top left corner.
    if (ev.clientX > 50 || ev.clientY > 50) {
      return false;
    }

    return {
      momentum: true,

      handle: function(ev) {
        console.log('This is the drag event handler');
      }
    }
  }
}, 'Top Left Drag');

For detail information of event, please check Events section.

Now learn how to query and manipulate the scene graph.