---

Custom Manipulators

If you want to create interactive experiences, you can define your own manipulators.

There are three methods exposed:

• registerTool
• activateTool
• deactivateTool

In the system, manipulators are 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).

Manipulator events are normalized for touch interactions, so click will be called on touch as well as on mouse click.

registerTool

Register a manipulator tool. Pass in an object with handler functions. The object may have the following keys:

• name (String), required
  The name of the tool. This should be unique, and is required to deactivate the tool.

• active (Boolean), default: true
  By default, the tool will be active when registered. If you want to create it, but not immediately activate it, pass {active: false}.

All other keys for the object are event handlers.

• click (Function)

A click handler, that will be called on click. It will be passed the click event, with the following keys:

* `clientX`, `clientY`: x and y coordinates, normalized to the WebGL Canvas
* `which`: Mouse button (1, 2, and 3)
* `originalEvent`: The DOM MouseEvent associated with the click
* `findNode`: A function that will retun the SceneGraph node underneath the click (if one is found).

If you wish to prevent tools further down the stack from receiving this event, return false from this function.

Example:

  $('#clara-embed').clara('registerTool', {
    name: 'myClickHandler',
    click: function(ev) {
      console.log('clicked on?', ev.findNode());
    }
  });

• scroll (Function)

A handler for the ‘wheel’ event. The default manipulator is to zoom the camera.

If you wish to prevent tools further down the stack from receiving this event, return false from this function.

• hover (Function)

Similar to the click handler, but called on mousemove. This will generate a lot of events, and should be handled quickly to prevent slowdowns.

• dblclick (Function)

Similar to the click handler, but called on double click.

• drag (Function)

The drag handler is somewhat unique. Similar to click, it will be passed the click event. The drag handler then must decide whether to handle the drag or not. If it is not to be handled, return false. Otherwise, return an object.

The return object must contain a handle key, with a function that will be called on mousemove until the drag is finished (mouseup). Optionally, a momentum boolean may be passed in. If true, momentum will be applied to the drag, with exponentially decaying movement, similar to how the default tools (rotate, pan, and zoom) behave.

The handle function will be passed an event object similar to the click event. However, it will also contain deltaX, and deltaY, representing the change in x/y coordinates. Note that when momentum is enabled, only deltaX and deltaY will be passed.

Example:

  $('#clara-embed').clara('registerTool', {
    name: 'moveObjectOnX',
    drag: function(ev) {
      var node = ev.findNode();

      // Only move a node if it is a PolyMesh
      if (!node || !node.isPolyMesh()) return false;

      var opCtx = node.ctx().find('#Transform[translation]');

      return {
        momentum: true,
        handle: function(e) {
          var translation = node.transform.getTranslation();
          translation.x = translation.x + (e.deltaX/10);
          opCtx.set({translation: translation});
        },
      }
    }
  });

activateTool

Activates a tool for use.

$('#clara-embed').clara('activateTool', {name: 'moveObjectOnX'});

deactivateTool

De-activates a tool.

$('#clara-embed').clara('deactivateTool', {name: 'moveObjectOnX'});

---