Introduction

The tools module is for interacting with player tools, which are responsible for updating the scene based on keyboard, mouse, and touch interfaces. The default set of tools will handle scene navigation (orbit, pan, and zoom).

These tools are used for both the 3D and the 2D player. The default tools and their behavior depend on the player mode.

Event Handlers

The Interaction Events section within the Events page lists all potential event handlers that can be used with these tools.

Tools

addTool(tool)

Adds a tool to the player. These can be custom new tools based on the event handlers listed here.
Kind: inner method of Tools

player.tools.addTool({
 key: string,
 label: string,
 active: boolean,
 enabled: boolean,
 handlers: {
  // event handlers can be added here, such as the following
  click: (ev) => console.log(ev),
  hover: (ev) => console.log(ev),
 }
})

Example

Example where we add one of the default tools.

player.tools.addTool('orbit')

Example where we add a custom tool.

player.tools.addTool({
 key: 'partSelect',
 label: 'Part Select Tool',
 active: true,
 enabled: true,
 handlers: {
  click: (ev) => {
  	// event handler code can be added here to determine what to do on a click
  }
 }
})

addTools(tools)

Adds an array of tools to the player.
Kind: inner method of Tools

player.tools.addTools(['pan', 'orbit', 'zoom'])

setTool(key, attrs)

Updates an existing tool.
Kind: inner method of Tools

player.tools.setTool('orbit', { enabled: false })

setTools(tools)

Updates existing tools.
Kind: inner method of Tools

player.tools.setTools({ 'orbit', { enabled: false }, 'pan': { enabled: true } })

removeTool(toolName)

Removes a tool from the player.
Kind: inner method of Tools

player.tools.removeTool('orbit')

removeTools(toolNames)

Removes an array of tools from the player.
Kind: inner method of Tools

player.tools.removeTools(['pan', 'orbit', 'zoom'])

setPrimary(toolName)

Sets a tool as Primary tool.

This option allows you to define what tool should be prioritized by the primary event trigger, which is the "click and drag" behaviour drag.
For example, if you set the primary tool on the 3D player to zoom, you will see that the click + drag behavior becomes zoom instead of orbit.

Kind: inner method of Tools

player.tools.setPrimary('zoom')

getPrimaryTool()

Gets the current primary tool.
Kind: inner method of Tools
Returns: string -

player.tools.getPrimaryTool()