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.

Default Tools	3D player	2D player
`select`	Yes	No
`orbit`	Yes	Yes (only if the stage has the Turntable or Panorama Effect added)
`pan`	Yes	No
`zoom`	Yes	Yes

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

parameter	type
tool	`string \

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

parameter	type
tools	`array \

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

setTool(key, attrs)

Updates an existing tool.
Kind: inner method of Tools

parameter	type
key	`string`
attrs	`Tool`

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

setTools(tools)

Updates existing tools.
Kind: inner method of Tools

parameter	type
tools	`object l string, Tool`

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

removeTool(toolName)

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

parameter	type
toolName	`string`

player.tools.removeTool('orbit')

removeTools(toolNames)

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

parameter	type
toolNames	`Array \

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

parameter	type
toolName	`string`

player.tools.setPrimary('zoom')

getPrimaryTool()

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

player.tools.getPrimaryTool()