123456789_123456789_123456789_123456789_123456789_

Class: Sketchup::Tool Abstract

Relationships
Inherits: Object

Overview

This class is 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.

Tool is the interface that you implement to create a SketchUp tool. See our code example for 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 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:

  • CONSTRAIN_MODIFIER_KEY = Shift Key

  • CONSTRAIN_MODIFIER_MASK = Shift Key

  • COPY_MODIFIER_KEY = Alt/Option on Mac, Ctrl on PC

  • COPY_MODIFIER_MASK = Alt/Option on Mac, Ctrl on PC

  • ALT_MODIFIER_KEY = Command on Mac, Alt on PC

  • ALT_MODIFIER_MASK = Command on Mac, Alt on PC

Version:

  • SketchUp 6.0

Instance Attribute Summary

  • #enableVCB? ⇒ Boolean readonly

    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).

Instance Method Summary

Instance Attribute Details

#enableVCB? ⇒ Boolean (readonly)

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.

Examples:

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

Returns:

  • (Boolean) —

    Return true if you want the VCB enabled

Version:

  • SketchUp 6.0

Instance Method Details

#activate

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.

Examples:

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

Version:

  • SketchUp 6.0

#deactivate(view)

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

Examples:

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

Parameters:

Version:

  • SketchUp 6.0

#draw(view)

Note:

If you draw outside the model bounds you need to implement #getExtents which return a bounding box large enough to include the points you draw. Otherwise your drawing will be clipped.

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 View.

Examples:

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

Parameters:

  • view (Sketchup::View) —

    A View object where the method was invoked.

See Also:

Version:

  • SketchUp 6.0

#getExtents ⇒ Geom::BoundingBox

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.

Examples:

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

Version:

  • SketchUp 6.0

#getInstructorContentDirectory ⇒ String

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.

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.

Examples:

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

Returns:

  • (String) —

    the directory path where the Instructor content exists.

Version:

  • SketchUp 6.0

#getMenu(menu) ⇒ nil #getMenu(menu, flags, x, y, view) ⇒ nil

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 Menu#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.

Examples:

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

Overloads:

  • #getMenu(menu) ⇒ nil

    Parameters:

  • #getMenu(menu, flags, x, y, view) ⇒ nil

    Parameters:

    • menu (Sketchup::Menu)
    • flags (Integer) —

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

    • x (Integer) —

      The X coordinate on the screen where the event occurred.

    • y (Integer) —

      The Y coordinate on the screen where the event occurred.

    • view (Sketchup::View)

    Version:

    • SketchUp 2015

Version:

  • SketchUp 6.0

#onCancel(reason, view)

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 ModelObserver#onTransactionUndo.

Note:

When #onKeyDown is implemented and returns true, pressing Esc doesn’t trigger #onCancel.

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.

Examples:

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

Parameters:

  • reason (Integer) —

    A reason value (see comments).

  • view (Sketchup::View)

Version:

  • SketchUp 6.0

#onKeyDown(key, repeat, flags, view) ⇒ Boolean

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.

Examples:

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

Parameters:

  • key (Integer) —

    The key that was pressed.

  • repeat (Integer) —

    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.

  • flags (Integer) —

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

  • view (Sketchup::View)

Returns:

  • (Boolean) —

    Return true to prevent SketchUp from processing the event.

Version:

  • SketchUp 6.0

#onKeyUp(key, repeat, flags, view) ⇒ Boolean

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

Examples:

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

Parameters:

  • key (Integer) —

    The key that was pressed.

  • repeat (Integer) —

    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.

  • flags (Integer) —

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

  • view (Sketchup::View)

Returns:

  • (Boolean) —

    Return true to prevent SketchUp from processing the event.

Version:

  • SketchUp 6.0

#onLButtonDoubleClick(flags, x, y, view)

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

Examples:

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

Parameters:

  • flags (Integer) —

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

  • x (Integer) —

    The X coordinate on the screen where the event occurred.

  • y (Integer) —

    The Y coordinate on the screen where the event occurred.

  • view (Sketchup::View)

Version:

  • SketchUp 6.0

#onLButtonDown(flags, x, y, view)

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

Examples:

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

Parameters:

  • flags (Integer) —

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

  • x (Integer) —

    The X coordinate on the screen where the event occurred.

  • y (Integer) —

    The Y coordinate on the screen where the event occurred.

  • view (Sketchup::View)

Version:

  • SketchUp 6.0

#onLButtonUp(flags, x, y, view)

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

Examples:

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

Parameters:

  • flags (Integer) —

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

  • x (Integer) —

    The X coordinate on the screen where the event occurred.

  • y (Integer) —

    The Y coordinate on the screen where the event occurred.

  • view (Sketchup::View)

Version:

  • SketchUp 6.0

#onMButtonDoubleClick(flags, x, y, view)

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.

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.

Examples:

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

Parameters:

  • flags (Integer) —

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

  • x (Integer) —

    The X coordinate on the screen where the event occurred.

  • y (Integer) —

    The Y coordinate on the screen where the event occurred.

  • view (Sketchup::View)

Version:

  • SketchUp 6.0

#onMButtonDown(flags, x, y, view)

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.

Examples:

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

Parameters:

  • flags (Integer) —

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

  • x (Integer) —

    The X coordinate on the screen where the event occurred.

  • y (Integer) —

    The Y coordinate on the screen where the event occurred.

  • view (Sketchup::View)

Version:

  • SketchUp 6.0

#onMButtonUp(flags, x, y, view)

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.

Examples:

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

Parameters:

  • flags (Integer) —

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

  • x (Integer) —

    The X coordinate on the screen where the event occurred.

  • y (Integer) —

    The Y coordinate on the screen where the event occurred.

  • view (Sketchup::View)

Version:

  • SketchUp 6.0

#onMouseEnter(view)

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

Examples:

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

Parameters:

Version:

  • SketchUp 6.0

#onMouseLeave(view)

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

Examples:

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

Parameters:

Version:

  • SketchUp 6.0

#onMouseMove(flags, x, y, view)

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.

Examples:

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

Parameters:

  • flags (Integer) —

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

  • x (Integer) —

    The X coordinate on the screen where the event occurred.

  • y (Integer) —

    The Y coordinate on the screen where the event occurred.

  • view (Sketchup::View)

Version:

  • SketchUp 6.0

#onMouseWheel(flags, delta, x, y, view) ⇒ Boolean

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

Examples:

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)

Parameters:

  • flags (Integer) —

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

  • delta (Integer) —

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

  • x (Float) —

    The X coordinate on the screen where the event occurred.

  • y (Float) —

    The Y coordinate on the screen where the event occurred.

  • view (Sketchup::View)

Returns:

  • (Boolean) —

    Return true to prevent SketchUp from performing default zoom action.

Version:

  • SketchUp 2019.2

#onRButtonDoubleClick(flags, x, y, view)

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

Examples:

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

Parameters:

  • flags (Integer) —

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

  • x (Integer) —

    The X coordinate on the screen where the event occurred.

  • y (Integer) —

    The Y coordinate on the screen where the event occurred.

  • view (Sketchup::View)

Version:

  • SketchUp 6.0

#onRButtonDown(flags, x, y, view)

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.

Examples:

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

Parameters:

  • flags (Integer) —

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

  • x (Integer) —

    The X coordinate on the screen where the event occurred.

  • y (Integer) —

    The Y coordinate on the screen where the event occurred.

  • view (Sketchup::View)

Version:

  • SketchUp 6.0

#onRButtonUp(flags, x, y, view)

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

Examples:

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

Parameters:

  • flags (Integer) —

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

  • x (Integer) —

    The X coordinate on the screen where the event occurred.

  • y (Integer) —

    The Y coordinate on the screen where the event occurred.

  • view (Sketchup::View)

Version:

  • SketchUp 6.0

#onReturn(view) ⇒ nil

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.

Examples:

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

Parameters:

Version:

  • SketchUp 6.0

#onSetCursor ⇒ Boolean

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

Examples:

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

Returns:

  • (Boolean) —

    Return true to prevent SketchUp using the default cursor.

Version:

  • SketchUp 6.0

#onUserText(text, view)

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

Examples:

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

Parameters:

  • text (String) —

    The text string that was typed into the VCB.

  • view (Sketchup::View) —

    A view object where the method was invoked.

Version:

  • SketchUp 6.0

#resume(view)

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

Examples:

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

Parameters:

Version:

  • SketchUp 6.0

#suspend(view)

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.

Examples:

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

Parameters:

Version:

  • SketchUp 6.0