My favorites | English | Sign in

Google SketchUp Ruby API

Tool

interface

Parent: Object

Introduction

SketchUp 6.0+

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 passsing it to Sketchup.active_model.select_tool. For example:

     def 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 = Menu on Mac, Ctrl on PC
  • COPY_MODIFIER_MASK = Alt on Mac, Ctrl on PC
  • ALT_MODIFIER_KEY = Command on Mac, Menu on PC
  • ALT_MODIFIER_MASK = Command on Mac, Alt on PC

Methods

Tool.activateSketchUp 6.0+

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.

Returns:

nil
 def activate
   puts "Your tool has been activated."
 end

Tool.deactivateSketchUp 6.0+

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

Arguments:

view
A View object where the method was invoked.

Returns:

nil
 def deactivate(view)
   puts "Your tool has been deactivated in view: " + view.to_s
 end

Tool.drawSketchUp 6.0+

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.

Arguments:

view
A View object where the method was invoked.

Returns:

nil
 def draw(view)
   puts "Your tool can draw into view: " + view.to_s
 end

Tool.enableVCB?SketchUp 6.0+

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.

Returns:

enable
true if you want the VCB enabled
 # For this tool, allow vcb text entry while the tool is active.
 def enableVCB?
   return true
 end

Tool.getExtentsSketchUp 6.0+

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.

Returns:

BoundingBox
a BoundingBox object
 def getExtents
   bb = Sketchup.active_model.bounds
   return bb
 end

Tool.getInstructorContentDirectorySketchUp 6.0+

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.

Returns:

directory
the string directory where the Instructor content exists.
 def getInstructorContentDirectory
   return "c:\\Program Files\\SketchUp 7\\Plugins\\MyToolInstructor\\"
 end

Tool.getMenuSketchUp 6.0+

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.

Arguments:

menu
A Menu object.

Returns:

nil
 def getMenu(menu)
   menu.add_item("Say Hello") {
     UI.messagebox("Hello")
   } 
 end

Tool.onCancelSketchUp 6.0+

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.

    • Arguments:

    reason
    A reason value (see comments).
    view
    A View object where the method was invoked.

    Returns:

    nil
     def onCancel(reason, view)
   puts "MyTool was cancelled for reason #" + reason.to_s +
     " in view:" + view.to_s
 end

Tool.onKeyDownSketchUp 6.0+

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.

Arguments:

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
 def onKeyDown(key, repeat, flags, view)
   puts "onKeyDown: key = " + key.to_s
   puts "        repeat = " + repeat.to_s
   puts "         flags = " + flags.to_s
   puts "          view = " + view.to_s
 end

Tool.onKeyUpSketchUp 6.0+

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

Arguments:

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
 def onKeyUp(key, repeat, flags, view)
   puts "onKeyUp:   key = " + key.to_s
   puts "        repeat = " + repeat.to_s
   puts "         flags = " + flags.to_s
   puts "          view = " + view.to_s
 end

Tool.onLButtonDoubleClickSketchUp 6.0+

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

Arguments:

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
 def onLButtonDoubleClick(flags, x, y, view)
   puts "onLButtonDoubleClick: flags = " + key.to_s
   puts "                 x = " + x.to_s
   puts "                 y = " + y.to_s
   puts "              view = " + view.to_s
 end

Tool.onLButtonDownSketchUp 6.0+

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

Arguments:

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
 def onLButtonDown(flags, x, y, view)
   puts "onLButtonDown: flags = " + key.to_s
   puts "                   x = " + x.to_s
   puts "                   y = " + y.to_s
   puts "                view = " + view.to_s
 end

Tool.onLButtonUpSketchUp 6.0+

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

Arguments:

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
 def onLButtonUp(flags, x, y, view)
   puts "onLButtonUp: flags = " + key.to_s
   puts "                 x = " + x.to_s
   puts "                 y = " + y.to_s
   puts "              view = " + view.to_s
 end

Tool.onMButtonDoubleClickSketchUp 6.0+

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.

Arguments:

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
 def onMButtonDoubleClick(flags, x, y, view)
   puts "onMButtonDoubleClick: flags = " + key.to_s
   puts "                 x = " + x.to_s
   puts "                 y = " + y.to_s
   puts "              view = " + view.to_s
 end

Tool.onMButtonDownSketchUp 6.0+

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.

Arguments:

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
 def onMButtonDown(flags, x, y, view)
   puts "onMButtonDown: flags = " + key.to_s
   puts "                 x = " + x.to_s
   puts "                 y = " + y.to_s
   puts "              view = " + view.to_s
 end

Tool.onMButtonUpSketchUp 6.0+

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.

Arguments:

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
 def onMButtonUp(flags, x, y, view)
   puts "onMButtonUp: flags = " + key.to_s
   puts "                 x = " + x.to_s
   puts "                 y = " + y.to_s
   puts "              view = " + view.to_s
 end

Tool.onMouseEnterSketchUp 6.0+

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

Arguments:

view
A View object where the method was invoked.

Returns:

nil
 def onMouseEnter(view)
   puts "onMouseEnter: view = " + view.to_s
 end

Tool.onMouseLeaveSketchUp 6.0+

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

Arguments:

view
A View object where the method was invoked.

Returns:

nil
 def onMouseLeave(view)
   puts "onMouseLeave: view = " + view.to_s
 end

Tool.onMouseMoveSketchUp 6.0+

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.

Arguments:

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
 def onMouseMove(flags, x, y, view)
   puts "onMouseMove: flags = " + flags.to_s
   puts "                 x = " + x.to_s
   puts "                 y = " + y.to_s
   puts "              view = " + view.to_s
 end

Tool.onRButtonDoubleClickSketchUp 6.0+

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

Arguments:

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
 def onRButtonDoubleClick(flags, x, y, view)
   puts "onRButtonDoubleClick: flags = " + key.to_s
   puts "                 x = " + x.to_s
   puts "                 y = " + y.to_s
   puts "              view = " + view.to_s
 end

Tool.onRButtonDownSketchUp 6.0+

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

Arguments:

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
 def onRButtonDown(flags, x, y, view)
   puts "onRButtonDown: flags = " + key.to_s
   puts "                 x = " + x.to_s
   puts "                 y = " + y.to_s
   puts "              view = " + view.to_s
 end

Tool.onRButtonUpSketchUp 6.0+

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

Arguments:

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
 def onRButtonDown(flags, x, y, view)
   puts "onRButtonDown: flags = " + key.to_s
   puts "                 x = " + x.to_s
   puts "                 y = " + y.to_s
   puts "              view = " + view.to_s
 end

Tool.onReturnSketchUp 6.0+

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.

Arguments:

view
A View object where the method was invoked.

Returns:

nil
 def onMouseLeave(view)
   puts "onMouseLeave: view = " + view.to_s
 end

Tool.onSetCursorSketchUp 6.0+

The onSetCursor method is called by SketchUp when the tool wants to set the cursor. If your tool needs to have more than one cursor, then you will need to implement this method, but if it only has one you can set the cursor in the activate method.

Arguments:

view
A View object where the method was invoked.

Returns:

nil
 def onSetCursor(view)
   puts "onSetCursor: view = " + view.to_s
   # You would set your cursor here. See UI.set_cursor method.
 end

Tool.onUserTextSketchUp 6.0+

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

Arguments:

text
The text string that was typed into the VCB.
view
A View object where the method was invoked.

Returns:

nil
 def onUserText(text, view)
   puts "onSetCursor: text = " + text.to_s + ", view = " + view.to_s
 end

Tool.resumeSketchUp 6.0+

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

Arguments:

view
A View object where the method was invoked.

Returns:

nil
 def resume(view)
   puts "resume: view = " + view.to_s
 end

Tool.suspendSketchUp 6.0+

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.

Arguments:

view
A View object where the method was invoked.

Returns:

nil
 def suspend(view)
   puts "suspend: view = " + view.to_s
 end