Tools

Access to SketchUp’s active tool — read it, watch for changes, and trigger component placement.

Get this object from model.tools. Use it to detect which tool the user has active, react when they switch tools, or programmatically activate the component placement tool.

Example

let model = await SketchUpApi.getActiveModel();

// Watch for tool activations
let handle = model.tools.observeToolChanges(
  change => {
    if (change.event === 'Activation') {
      console.log(change.tool.name);
      // => 'PaintTool', 'RectangleTool', etc.
    }
  }
);

// Stop observing when done
handle.stop();

See

Since

SDK 1.19.0 protocol 1.16.0

Methods

clearActiveTool()

clearActiveTool(): Promise<Tool>

Deactivates any active tool and returns the user to Select mode.

Returns

Promise<Tool>

Since

SDK 1.19.0 protocol 1.16.0

getActive()

getActive(): Promise<Tool>

Returns the currently active tool, if any.

Returns

Promise<Tool>

Since

SDK 1.19.0 protocol 1.16.0

observeToolChanges()

observeToolChanges(callback): ObserverHandle

Calls callback on every tool lifecycle event — initial state, activation, and state changes. Returns a handle to stop observing.

Parameters

Parameter	Type	Description
`callback`	(`change`) => `void`	invoked with each `ToolEvent`

Returns

ObserverHandle

Since

SDK 2.30.0 protocol 1.16.0

placeComponentOnce()

placeComponentOnce(component): Promise<ComponentInstance | undefined>

Activates the place-component tool and waits for the user to click to place it, then resolves with the placed ComponentInstance. Resolves with undefined if the user cancels. If the user deletes the component definition before placing, the snapshot is invalidated.

Parameters

Parameter	Type	Description
`component`	`ComponentDefinition` \| `ComponentDefinitionRef`	the component definition to place

Returns

Promise<ComponentInstance | undefined>

the placed instance, or undefined if cancelled

placeComponentRepeatedly()

placeComponentRepeatedly(component, callback?): Promise<ComponentInstance[]>

Activates the place-component tool in multi-place mode, letting the user stamp multiple instances. Each time the user places an instance the optional callback is called. Resolves with the full array of placed instances when the user cancels or switches to another tool.

Parameters

Parameter	Type	Description
`component`	`ComponentDefinition` \| `ComponentDefinitionRef`	the component definition to place
`callback`	(`instances`) => `void`	invoked after each placement with the new instances

Returns

Promise<ComponentInstance[]>

toString()

toString(): string

Returns

string

Show Deprecated

Deprecated

streamToolChanges()

streamToolChanges(callback): ObserverHandle

Streams changes to the current active tool

Parameters

Parameter	Type	Description
`callback`	(`change`) => `void`	invoked on every tool change

Returns

ObserverHandle

Since

SDK 1.19.0 protocol 1.16.0