class Sketchup::Tool

Tool is the interface that you implement to create a SketchUp tool. See github.com/SketchUp/sketchup-ruby-api-tutorials/tree/master/examples/02_custom_tool for an example of how to create a custom tool in Ruby.

To create a new tool in Ruby, you must define a new class that implements the methods for the events that you want to respond to. You do not have to implement methods for every possible event that a Tool can respond to.

Once you have defined a tool class, you select that tool by creating an instance of it and passing it to {Sketchup::Model#select_tool}. For example:

class MyTool
  def activate
    puts 'Your tool has been activated.'
  end
end

my_tool = MyTool.new
Sketchup.active_model.select_tool(my_tool)

The following table contains several constants you can use when check for certain key presses inside the keyboard handling callbacks:

@abstract Implement the methods described in this class to create a tool.

You can not sub-class this class because it is not defined by the API.

@version SketchUp 6.0

Public Instance Methods

activate() click to toggle source

The {#activate} method is called by SketchUp when the tool is selected. It is a good place to put most of your initialization, such as instance variables to track the state of the tool.

@example

def activate
  puts 'Your tool has been activated.'
end

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb, line 53
def activate
end
deactivate(view) click to toggle source

The {#deactivate} method is called when the tool is deactivated because a different tool was selected.

@example

def deactivate(view)
  puts "Your tool has been deactivated in view: #{view}"
end

@param [Sketchup::View] view

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb, line 67
def deactivate(view)
end
draw(view) click to toggle source

The {#draw} method is called by SketchUp whenever the view is refreshed to allow the tool to do its own drawing. If the tool has some temporary graphics that it wants displayed while it is active, it should implement this method and draw to the {Sketchup::View}.

@example

def draw(view)
  # Draw a square.
  points = [
    Geom::Point3d.new(0, 0, 0),
    Geom::Point3d.new(9, 0, 0),
    Geom::Point3d.new(9, 9, 0),
    Geom::Point3d.new(0, 9, 0)
  ]
  # Fill
  view.drawing_color = Sketchup::Color.new(255, 128, 128)
  view.draw(GL_QUADS, points)
  # Outline
  view.line_stipple = '' # Solid line
  view.drawing_color = Sketchup::Color.new(64, 0, 0)
  view.draw(GL_LINE_LOOP, points)
end

@note If you draw outside the model bounds you need to implement

{Tool#getExtents} which return a bounding box large enough to include the
points you draw. Otherwise your drawing will be clipped.

@param [Sketchup::View] view

A View object where the method was invoked.

@see getExtents

@see Sketchup::View#draw

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb, line 105
def draw(view)
end
enableVCB?() click to toggle source

The {#enableVCB?} method is used to tell SketchUp whether to allow the user to enter text into the VCB (value control box, aka the “measurements” panel). If you do not implement this method, then the vcb is disabled by default.

@example

# For this tool, allow vcb text entry while the tool is active.
def enableVCB?
  return true
end

@return [Boolean] Return true if you want the VCB enabled

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb, line 121
def enableVCB?
end
getExtents() click to toggle source

In order to accurately draw things, SketchUp needs to know the extents of what it is drawing. If the tool is doing its own drawing, it may need to implement this method to tell SketchUp the extents of what it will be drawing. If you don't implement this method, you may find that part of what the tool is drawing gets clipped to the extents of the rest of the model.

This must return a {Geom::BoundingBox}. In a typical implementation, you will create a new {Geom::BoundingBox}, add points to set the extents of the drawing that the tool will do and then return it.

@example

def getExtents
  bb = Sketchup.active_model.bounds
  return bb
end

@return [Geom::BoundingBox]

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb, line 144
def getExtents
end
getInstructorContentDirectory() click to toggle source

The {#getInstructorContentDirectory} method is used to tell SketchUp the directory containing your Tool's instructor content. To use this, create a custom instructor directory, put an index.html file inside of it, and then return that path via this method. If the SketchUp user has the Instructor window open when they activate your tool, they will see your html file.

@example

def getInstructorContentDirectory
  extension_path = Sketchup.extensions['MyExtension].extension_path
  instructor_path = File.join(extension_path, 'MyExtension', 'instructor')
  return instructor_path
end

@note Prior to SketchUp 2014 this method would assume the path was relative

to the SketchUp resource folder. From 2014 and onwards you can specify the
absolute path to an HTML file or the absolute path to a directory
containing an index.html file.

@return [String] the directory path where the Instructor content exists.

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb, line 168
def getInstructorContentDirectory
end
getMenu(menu, flags, x, y, view) click to toggle source

The {#getMenu} method is called by SketchUp to let the tool provide its own context menu. Most tools will not want to implement this method and, instead, use the normal context menu found on all entities.

If you do implement this method, the argument is a Menu. You should use the add_item method to build the context menu.

Your tool will use a standard context menu by default if you do not implement this method. Implement this method if you want a context-click to display something other than this default context menu.

In SketchUp 2015 the flags, x, y and view parameters were added. They are needed if you need to pick the entities under the mouse position. The new parameters are optional, but if you need to use one you must include them all.

@example

if Sketchup.version.to_i < 15
  # Compatible with SketchUp 2014 and older:
  def getMenu(menu)
    menu.add_item('Say Hello') {
      UI.messagebox('Hello')
    }
  end
else
  # Only works with SketchUp 2015 and newer:
  def getMenu(menu, flags, x, y, view)
    ph = view.pick_helper(x, y)
    entity = ph.best_picked
    if entity
      view.model.selection.clear
      view.model.selection.add(entity)
      menu.add_item("Erase #{entity.typename}") {
        entity.erase!
      }
   end
 end
end

@param menu

A Menu object.

@param [optional] flags

A bit mask that tells the state of the
modifier keys and other mouse buttons at the time.
Added in SU2015.

@param [optional] x

The X coordinate on the screen where the
event occurred. Added in SU2015.

@param [optional] y

The Y coordinate on the screen where the
event occurred. Added in SU2015.

@param [optional] view

A View object where the method was invoked.
Added in SU2015.

@return nil

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb, line 233
def getMenu(menu, flags, x, y, view)
end
onCancel(reason, view) click to toggle source

The {#onCancel} method is called by SketchUp to cancel the current operation of the tool. The typical response will be to reset the tool to its initial state.

The reason identifies the action that triggered the call. The reason can be one of the following values:

  • 0: the user canceled the current operation by hitting the escape key.

  • 1: the user re-selected the same tool from the toolbar or menu.

  • 2: the user did an undo while the tool was active.

@example

def onCancel(reason, view)
  puts "MyTool was canceled for reason ##{reason} in view: #{view}"
end

@note When something is undone {#onCancel} is called before the undo is

actually executed. If you need to do something with the model after an undo
use {Sketchup::ModelObserver#onTransactionUndo}.

@note When {#onKeyDown} is implemented and returns true, pressing Esc

doesn't trigger {#onCancel}.

@param [Integer] reason

A reason value (see comments).

@param [Sketchup::View] view

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb, line 265
def onCancel(reason, view)
end
onKeyDown(key, repeat, flags, view) click to toggle source

The {#onKeyDown} method is called by SketchUp when the user presses a key on the keyboard. If you want to get input from the VCB, you should implement onUserText rather than this method.

This method is can be used for special keys such as the Shift key, Ctrl key, and so on, or for just determining which key a user pressed. This method is actually called for all keys that are pressed.

There are several “virtual keys” defined as constants you can use. Their use is cross platform. They are:

  • VK_ALT

  • VK_COMMAND

  • VK_CONTROL

  • VK_DELETE

  • VK_DOWN

  • VK_END

  • VK_HOME

  • VK_INSERT

  • VK_LEFT

  • VK_MENU

  • VK_NEXT

  • VK_PRIOR

  • VK_RIGHT

  • VK_SHIFT

  • VK_SPACE

  • VK_UP

V6: There is a bug on Windows where the typematic effect does not work. Typematic effects work fine on a Mac.

@example

def onKeyDown(key, repeat, flags, view)
  puts "onKeyDown: key = #{key}"
  puts "        repeat = #{repeat}"
  puts "         flags = #{flags}"
  puts "          view = #{view}"
end

@param [Integer] key

The key that was pressed.

@param [Integer] repeat

A value of 1 for a single press of a key.  A value
of 2 if the user has pressed a key and is holding
it down.

@param [Integer] flags

A bit mask that tells the state of the modifier
keys at the time of the event.

@param [Sketchup::View] view

@return [Boolean] Return true to prevent SketchUp from processing the

event.

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb, line 326
def onKeyDown(key, repeat, flags, view)
end
onKeyUp(key, repeat, flags, view) click to toggle source

The {#onKeyUp} method is called by SketchUp when the user releases a key on the keyboard.

@example

def onKeyUp(key, repeat, flags, view)
  puts "onKeyUp: key = #{key}"
  puts "      repeat = #{repeat}"
  puts "       flags = #{flags}"
  puts "        view = #{view}"
end

@param [Integer] key

The key that was pressed.

@param [Integer] repeat

A value of 1 for a single press of a key.  A value
of 2 if the user has pressed a key and is holding
it down.

@param [Integer] flags

A bit mask that tells the state of the modifier
keys at the time of the event.

@param [Sketchup::View] view

@return [Boolean] Return true to prevent SketchUp from processing the

event.

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb, line 358
def onKeyUp(key, repeat, flags, view)
end
onLButtonDoubleClick(flags, x, y, view) click to toggle source

The {#onLButtonDoubleClick} is called by SketchUp when the user double clicks with the left mouse button.

@example

def onLButtonDoubleClick(flags, x, y, view)
  puts "onLButtonDoubleClick: flags = #{flags}"
  puts "                          x = #{x}"
  puts "                          y = #{y}"
  puts "                       view = #{view}"
end

@param [Integer] flags

A bit mask that tells the state of the modifier
keys and other mouse buttons at the time.

@param [Integer] x

The X coordinate on the screen where the event occurred.

@param [Integer] y

The Y coordinate on the screen where the event occurred.

@param [Sketchup::View] view

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb, line 385
def onLButtonDoubleClick(flags, x, y, view)
end
onLButtonDown(flags, x, y, view) click to toggle source

The {#onLButtonDown} method is called by SketchUp when the left mouse button is pressed. Most tools will implement this method.

@example

def onLButtonDown(flags, x, y, view)
  puts "onLButtonDown: flags = #{flags}"
  puts "                   x = #{x}"
  puts "                   y = #{y}"
  puts "                view = #{view}"
end

@param [Integer] flags

A bit mask that tells the state of the modifier
keys and other mouse buttons at the time.

@param [Integer] x

The X coordinate on the screen where the event occurred.

@param [Integer] y

The Y coordinate on the screen where the event occurred.

@param [Sketchup::View] view

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb, line 412
def onLButtonDown(flags, x, y, view)
end
onLButtonUp(flags, x, y, view) click to toggle source

The {#onLButtonUp} method is called by SketchUp when the left mouse button is released.

@example

def onLButtonUp(flags, x, y, view)
  puts "onLButtonUp: flags = #{flags}"
  puts "                 x = #{x}"
  puts "                 y = #{y}"
  puts "              view = #{view}"
end

@param [Integer] flags

A bit mask that tells the state of the modifier
keys and other mouse buttons at the time.

@param [Integer] x

The X coordinate on the screen where the event occurred.

@param [Integer] y

The Y coordinate on the screen where the event occurred.

@param [Sketchup::View] view

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb, line 439
def onLButtonUp(flags, x, y, view)
end
onMButtonDoubleClick(flags, x, y, view) click to toggle source

The {#onMButtonDoubleClick} method is called by SketchUp when the middle mouse button (on a three button mouse) is double-clicked.

Only implement this method if you want SketchUp to react to a middle mouse button being double-clicked.

@example

def onMButtonDoubleClick(flags, x, y, view)
  puts "onMButtonDoubleClick: flags = #{flags}"
  puts "                          x = #{x}"
  puts "                          y = #{y}"
  puts "                       view = #{view}"
end

@note Though this method has been documented in the Ruby API for many years,

it has never worked properly. We are leaving this documentation in place
for now in the hopes of fixing the implementation, but you won't have any
luck trying to use it in SU7 and earlier.

@param [Integer] flags

A bit mask that tells the state of the modifier
keys and other mouse buttons at the time.

@param [Integer] x

The X coordinate on the screen where the event occurred.

@param [Integer] y

The Y coordinate on the screen where the event occurred.

@param [Sketchup::View] view

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb, line 474
def onMButtonDoubleClick(flags, x, y, view)
end
onMButtonDown(flags, x, y, view) click to toggle source

The {#onMButtonDown} method is called by SketchUp when the middle mouse button (on a three button mouse) is down.

The Orbit tool is activated by default when the middle mouse button is down. Implement this method if you want a middle mouse button to do something other than invoke the Orbit tool.

@example

def onMButtonDown(flags, x, y, view)
  puts "onMButtonDown: flags = #{flags}"
  puts "                    x = #{x}"
  puts "                    y = #{y}"
  puts "                 view = #{view}"
end

@param [Integer] flags

A bit mask that tells the state of the modifier
keys and other mouse buttons at the time.

@param [Integer] x

The X coordinate on the screen where the event occurred.

@param [Integer] y

The Y coordinate on the screen where the event occurred.

@param [Sketchup::View] view

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb, line 505
def onMButtonDown(flags, x, y, view)
end
onMButtonUp(flags, x, y, view) click to toggle source

The {#onMButtonUp} method is called by SketchUp when the middle mouse button (on a three button mouse) is released.

SketchUp returns to the previous tool from the Orbit tool when the middle mouse button is released. Implement this method if you want a middle mouse button to do something other than return to the previous tool when in the Orbit tool.

@example

def onMButtonUp(flags, x, y, view)
  puts "onMButtonUp: flags = #{flags}"
  puts "                  x = #{x}"
  puts "                  y = #{y}"
  puts "               view = #{view}"
end

@param [Integer] flags

A bit mask that tells the state of the modifier
keys and other mouse buttons at the time.

@param [Integer] x

The X coordinate on the screen where the event occurred.

@param [Integer] y

The Y coordinate on the screen where the event occurred.

@param [Sketchup::View] view

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb, line 537
def onMButtonUp(flags, x, y, view)
end
onMouseEnter(view) click to toggle source

The {#onMouseEnter} method is called by SketchUp when the mouse enters the viewport.

@example

def onMouseEnter(view)
  puts "onMouseEnter: view = #{view}"
end

@param [Sketchup::View] view

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb, line 551
def onMouseEnter(view)
end
onMouseLeave(view) click to toggle source

The {#onMouseLeave} method is called by SketchUp when the mouse leaves the viewport.

@example

def onMouseLeave(view)
  puts "onMouseLeave: view = #{view}"
end

@param [Sketchup::View] view

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb, line 565
def onMouseLeave(view)
end
onMouseMove(flags, x, y, view) click to toggle source

The {#onMouseMove} method is called by SketchUp whenever the mouse is moved. You will often want to implement this method.

Try to make this method as efficient as possible because this method is called often.

@example

def onMouseMove(flags, x, y, view)
  puts "onMouseMove: flags = #{flags}"
  puts "                  x = #{x}"
  puts "                  y = #{y}"
  puts "               view = #{view}"
end

@param [Integer] flags

A bit mask that tells the state of the modifier
keys and other mouse buttons at the time.

@param [Integer] x

The X coordinate on the screen where the event occurred.

@param [Integer] y

The Y coordinate on the screen where the event occurred.

@param [Sketchup::View] view

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb, line 595
def onMouseMove(flags, x, y, view)
end
onMouseWheel(flags, delta, x, y, view) click to toggle source

The {#onMouseWheel} method is called by SketchUp when the mouse scroll wheel is used.

@example

class ExampleTool

  def initialize
    @property_value = 0
    @rect = [
      Geom::Point3d.new(100, 150, 0),
      Geom::Point3d.new(300, 150, 0),
      Geom::Point3d.new(300, 250, 0),
      Geom::Point3d.new(100, 250, 0),
    ]
  end

  def onMouseMove(flags, x, y, view)
    view.invalidate
  end

  def onMouseWheel(flags, delta, x, y, view)
    # If the cursor is not within the bounds of the rectangle, return false
    # to let SketchUp do its default action (zoom).
    point = Geom::Point3d.new(x, y)
    return false unless Geom.point_in_polygon_2D(point, @rect, true)

    # If cursor is within the bounds of the rectangle, update the value
    # and prevent the default zoom.
    @property_value += delta
    view.invalidate
    true
  end

  def draw(view)
    view.line_width = 2
    view.line_stipple = ''
    view.drawing_color = 'red'
    view.draw2d(GL_QUADS, @rect)

    point = Geom::Point3d.new(120, 170)
    view.draw_text(point, "Value: #{@property_value}",
       size: 20, bold: true, color: 'black')
  end

end

Sketchup.active_model.select_tool(ExampleTool.new)

@param [Integer] flags

A bit mask that tells the state of the modifier
keys and other mouse buttons at the time.

@param [Integer] delta

Either +1+ or +-1+ depending on which direction the
mouse wheel scrolled.

@param [Float] x

The X coordinate on the screen where the event occurred.

@param [Float] y

The Y coordinate on the screen where the event occurred.

@param [Sketchup::View] view

@return [Boolean] Return true to prevent SketchUp from performing default

zoom action.

@version SketchUp 2019.2

# File lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb, line 666
def onMouseWheel(flags, delta, x, y, view)
end
onRButtonDoubleClick(flags, x, y, view) click to toggle source

The {#onRButtonDoubleClick} is called by SketchUp when the user double clicks with the right mouse button.

@example

def onRButtonDoubleClick(flags, x, y, view)
  puts "onRButtonDoubleClick: flags = #{flags}"
  puts "                          x = #{x}"
  puts "                          y = #{y}"
  puts "                       view = #{view}"
end

@param [Integer] flags

A bit mask that tells the state of the modifier
keys and other mouse buttons at the time.

@param [Integer] x

The X coordinate on the screen where the event occurred.

@param [Integer] y

The Y coordinate on the screen where the event occurred.

@param [Sketchup::View] view

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb, line 693
def onRButtonDoubleClick(flags, x, y, view)
end
onRButtonDown(flags, x, y, view) click to toggle source

The {#onRButtonDown} method is called by SketchUp when the user presses the right mouse button. Implement this method, along with the tool.getMenu method, when you want your tool to do something other than display the default context menu when the right mouse button is clicked.

@example

def onRButtonDown(flags, x, y, view)
  puts "onRButtonDown: flags = #{flags}"
  puts "                   x = #{x}"
  puts "                   y = #{y}"
  puts "                view = #{view}"
end

@param [Integer] flags

A bit mask that tells the state of the modifier
keys and other mouse buttons at the time.

@param [Integer] x

The X coordinate on the screen where the event occurred.

@param [Integer] y

The Y coordinate on the screen where the event occurred.

@param [Sketchup::View] view

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb, line 722
def onRButtonDown(flags, x, y, view)
end
onRButtonUp(flags, x, y, view) click to toggle source

The {#onRButtonUp} method is called by SketchUp when the user releases the right mouse button.

@example

def onRButtonUp(flags, x, y, view)
  puts "onRButtonUp: flags = #{flags}"
  puts "                 x = #{x}"
  puts "                 y = #{y}"
  puts "              view = #{view}"
end

@param [Integer] flags

A bit mask that tells the state of the modifier
keys and other mouse buttons at the time.

@param [Integer] x

The X coordinate on the screen where the event occurred.

@param [Integer] y

The Y coordinate on the screen where the event occurred.

@param [Sketchup::View] view

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb, line 749
def onRButtonUp(flags, x, y, view)
end
onReturn(view) click to toggle source

The {#onReturn} method is called by SketchUp when the user hit the Return key to complete an operation in the tool. This method will rarely need to be implemented.

@example

def onReturn(view)
  puts "onReturn(#{view})"
end

@param [Sketchup::View] view

@return [nil]

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb, line 766
def onReturn(view)
end
onSetCursor() click to toggle source

The {#onSetCursor} method is called by SketchUp when the tool wants to set the cursor.

@example

def onSetCursor
  puts "onSetCursor: view = #{view}"
  # You would set your cursor here. See UI.set_cursor method.
  UI.set_cursor(@cursor_id) # UI.set_cursor return true
end

@return [Boolean] Return true to prevent SketchUp using the default cursor.

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb, line 782
def onSetCursor
end
onUserText(text, view) click to toggle source

The {#onUserText} method is called by SketchUp when the user has typed text into the VCB and hit return.

@example

def onUserText(text, view)
  @distance = text.to_l
rescue ArgumentError
  view.tooltip = 'Invalid length'
end

@param [String] text

The text string that was typed into the VCB.

@param [Sketchup::View] view

A view object where the method was invoked.

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb, line 802
def onUserText(text, view)
end
resume(view) click to toggle source

The {#resume} method is called by SketchUp when the tool becomes active again after being suspended.

@example

def resume(view)
  puts "resume: view = #{view}"
end

@param [Sketchup::View] view

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb, line 816
def resume(view)
end
suspend(view) click to toggle source

The {#suspend} method is called by SketchUp when the tool temporarily becomes inactive because another tool has been activated. This typically happens when a viewing tool is activated, such as when orbit is active due to the middle mouse button.

@example

def suspend(view)
  puts "suspend: view = #{view}"
end

@param [Sketchup::View] view

@version SketchUp 6.0

# File lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb, line 832
def suspend(view)
end