Class: Sketchup::Tool

Inherits:
Object
  • Object
show all

Overview

Tool is the interface that you implement to create a SketchUp tool. See the file Plugins/Examples/linetool.rb (in your SketchUp install directory) 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 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 Method Summary # collapse

Instance Method Details

#activateObject

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

Returns:

  • nil

Version:

  • SketchUp 6.0

#deactivate(view) ⇒ Object

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

Returns nil

Parameters:

  • view

    A View object where the method was invoked.

Returns:

  • nil

Version:

  • SketchUp 6.0

#draw(view) ⇒ Object

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

Returns nil

Parameters:

  • view (Sketchup::View)

    A View object where the method was invoked.

Returns:

  • nil

See Also:

Version:

  • SketchUp 6.0

#enableVCB?Object

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:

  • enable - true if you want the VCB enabled

  • (Boolean)

Version:

  • SketchUp 6.0

#getExtentsObject

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 BoundingBox. In a typical implementation, you will create a new 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

Returns:

  • BoundingBox - a BoundingBox object

Version:

  • SketchUp 6.0

#getInstructorContentDirectoryObject

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.

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.

Examples:

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

Returns:

  • directory - the string directory where the Instructor content exists.

Version:

  • SketchUp 6.0

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

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.

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

Returns nil

Parameters:

  • menu

    A Menu object.

  • flags (optional)

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

  • x (optional)

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

  • y (optional)

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

  • view (optional)

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

Returns:

  • nil

Version:

  • SketchUp 6.0

#onCancel(reason, view) ⇒ Object

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

Returns nil

Parameters:

  • reason

    A reason value (see comments).

  • view

    A View object where the method was invoked.

Returns:

  • nil

Version:

  • SketchUp 6.0

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

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

Returns nil

Parameters:

  • key

    The key that was pressed.

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

  • flags

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

  • view

    A View object where the method was invoked.

Returns:

  • nil

Version:

  • SketchUp 6.0

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

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

Returns nil

Parameters:

  • key

    The key that was pressed.

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

  • flags

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

  • view

    A View object where the method was invoked.

Returns:

  • nil

Version:

  • SketchUp 6.0

#onLButtonDoubleClick(flags, x, y, view) ⇒ Object

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

Returns nil

Parameters:

  • flags

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

  • x

    The X coordinate on the screen where the event occurred.

  • y

    The Y coordinate on the screen where the event occurred.

  • view

    A View object where the method was invoked.

Returns:

  • nil

Version:

  • SketchUp 6.0

#onLButtonDown(flags, x, y, view) ⇒ Object

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

Returns nil

Parameters:

  • flags

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

  • x

    The X coordinate on the screen where the event occurred.

  • y

    The Y coordinate on the screen where the event occurred.

  • view

    A View object where the method was invoked.

Returns:

  • nil

Version:

  • SketchUp 6.0

#onLButtonUp(flags, x, y, view) ⇒ Object

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

Returns nil

Parameters:

  • flags

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

  • x

    The X coordinate on the screen where the event occurred.

  • y

    The Y coordinate on the screen where the event occurred.

  • view

    A View object where the method was invoked.

Returns:

  • nil

Version:

  • SketchUp 6.0

#onMButtonDoubleClick(flags, x, y, view) ⇒ Object

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

Returns nil

Parameters:

  • flags

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

  • x

    The X coordinate on the screen where the event occurred.

  • y

    The Y coordinate on the screen where the event occurred.

  • view

    A View object where the method was invoked.

Returns:

  • nil

Version:

  • SketchUp 6.0

#onMButtonDown(flags, x, y, view) ⇒ Object

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

Returns nil

Parameters:

  • flags

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

  • x

    The X coordinate on the screen where the event occurred.

  • y

    The Y coordinate on the screen where the event occurred.

  • view

    A View object where the method was invoked.

Returns:

  • nil

Version:

  • SketchUp 6.0

#onMButtonUp(flags, x, y, view) ⇒ Object

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

Returns nil

Parameters:

  • flags

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

  • x

    The X coordinate on the screen where the event occurred.

  • y

    The Y coordinate on the screen where the event occurred.

  • view

    A View object where the method was invoked.

Returns:

  • nil

Version:

  • SketchUp 6.0

#onMouseEnter(view) ⇒ Object

The onMouseEnter method is called by SketchUp when the mouse enters the View object.

Examples:

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

Returns nil

Parameters:

  • view

    A View object where the method was invoked.

Returns:

  • nil

Version:

  • SketchUp 6.0

#onMouseLeave(view) ⇒ Object

The onMouseLeave method is called by SketchUp when the mouse leaves the View object.

Examples:

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

Returns nil

Parameters:

  • view

    A View object where the method was invoked.

Returns:

  • nil

Version:

  • SketchUp 6.0

#onMouseMove(flags, x, y, view) ⇒ Object

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

Returns nil

Parameters:

  • flags

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

  • x

    The X coordinate on the screen where the event occurred.

  • y

    The Y coordinate on the screen where the event occurred.

  • view

    A View object where the method was invoked.

Returns:

  • nil

Version:

  • SketchUp 6.0

#onRButtonDoubleClock(flags, x, y, view) ⇒ Object

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

Returns nil

Parameters:

  • flags

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

  • x

    The X coordinate on the screen where the event occurred.

  • y

    The Y coordinate on the screen where the event occurred.

  • view

    A View object where the method was invoked.

Returns:

  • nil

Version:

  • SketchUp 6.0

#onRButtonDown(flags, x, y, view) ⇒ Object

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

Returns nil

Parameters:

  • flags

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

  • x

    The X coordinate on the screen where the event occurred.

  • y

    The Y coordinate on the screen where the event occurred.

  • view

    A View object where the method was invoked.

Returns:

  • nil

Version:

  • SketchUp 6.0

#onRButtonUp(flags, x, y, view) ⇒ Object

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

Returns nil

Parameters:

  • flags

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

  • x

    The X coordinate on the screen where the event occurred.

  • y

    The Y coordinate on the screen where the event occurred.

  • view

    A View object where the method was invoked.

Returns:

  • nil

Version:

  • SketchUp 6.0

#onReturn(view) ⇒ Object

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 onMouseLeave(view)
  puts "onMouseLeave: view = #{view}"
end

Returns nil

Parameters:

  • view

    A View object where the method was invoked.

Returns:

  • nil

Version:

  • SketchUp 6.0

#onSetCursorObject

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

Returns:

  • nil

Version:

  • SketchUp 6.0

#onUserText(text, view) ⇒ Object

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

Examples:

def onUserText(text, view)
  puts "onSetCursor: text = #{text}, view = #{view}"
end

Returns nil

Parameters:

  • text

    The text string that was typed into the VCB.

  • view

    A View object where the method was invoked.

Returns:

  • nil

Version:

  • SketchUp 6.0

#resume(view) ⇒ Object

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

Returns nil

Parameters:

  • view

    A View object where the method was invoked.

Returns:

  • nil

Version:

  • SketchUp 6.0

#suspend(view) ⇒ Object

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

Returns nil

Parameters:

  • view

    A View object where the method was invoked.

Returns:

  • nil

Version:

  • SketchUp 6.0