Tool

interface Tool

Parent: Object | Class Index
Methods: activate, deactivate, draw, getExtents, getMenu, onCancel, onKeyDown, onKeyUp, onLButtonDoubleClick, onLButtonDown, onLButtonup, onMButtonDoubleClick, onMButtonDown, onMButtonUp, onMouseEnter, onMouseLeave, onMouseMove, onRButtonDoubleClick, onRButtonDown, onRButtonUp, onReturn, onSetCursor, onUserText, resume, suspend |
Sample Code: linetool.rb, tooltests.rb |

Tool is the interface that you implement to create a SketchUp tool.
See the example file examples/linetool.rb for an example of how to create a custom tool in Ruby.
The linetool.rb Ruby script uses a constant, CONSTRAIN_MODIFIER_KEY when verifying that the Shift key is pressed. The following table contains several constants you can use when check for a certain key press.

Ruby Constant | Key
CONSTRAIN_MODIFIER_KEY | Shift Key (Mac and PC)
CONSTRAIN_MODIFIER_MASK | Shift Key (Mac and PC)
COPY_MODIFIER_KEY | Menu (Mac) / Ctrl (PC)
COPY_MODIFIER_MASK | Alt (Mac) / Ctrl (PC)
ALT_MODIFIER_KEY | Command (Mac) / Menu (PC)
ALT_MODIFIER_MASK | Command (Mac) / Alt (PC)

Instance Methods

activate
The activate method is called by SketchUp when the tool is first activated.
Syntax:
tool.activate
Arguments:
Return Value:
Comments:
Example:
N/A

deactivate
The deactivate method is called when the tool is deactivated because a different tool was selected
Syntax:
tool.deactivate view
Arguments:
view - a View object where the method was invoked
Return Value:
Comments:
Example:
N/A

draw
The draw method is called by SketchUp 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.
Syntax:
tool.draw view
Arguments:
view - a View object where the method was invoked
Return Value:
Comments:
Example:
N/A

getExtents

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.

Syntax:
BoundingBox = tool.getExtents
Arguments:
Return Value:
BoundingBox - a BoundingBox object
Comments:
Example:
N/A

getMenu
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.
Syntax:
tool.getMenu menu
Arguments:
menu - a Menu object
Return Value:
Comments:
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.
Example:
N/A

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.
Syntax:
tool.onCancel reason, view
Arguments:
reason - a reason value (see comments) view - a View object where the method was invoked
Return Value:
Comments:
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:
N/A

onKeyDown
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.
Syntax:
tool.onKeyDown key, repeat, flags, view
Arguments:
key - the key that was pressed repeat - 1 for repeat 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
Return Value:
Comments:
This method is normally used for special keys such as the Shift key, Ctrl key, and so on. This method is actually called for all keys that are pressed.
Example:
N/A

onKeyUp
The onKeyUp method is called by SketchUp when the user releases a key on the keyboard.
Syntax:
tool.onKeyUp key, repeat, flags, view
Arguments:
key - the key that was pressed repeat - 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
Return Value:
Comments:
Example:
N/A

onLButtonDoubleClick
The onLButtonDoubleClick method is called by SketchUp when the user double-clicks with the left mouse button.
Syntax:
tool.onLButtonDoubleClick flags, x, y, view
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
Return Value:
Comments:
Example:
N/A

onLButtonDown
The onLButtonDown method is called by SketchUp when the left mouse button is pressed. Most tools will implement this method.
Syntax:
tool.onLButtonDown flags, x, y, view
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
Return Value:
Comments:
Example:
N/A

onLButtonUp
The onLButtonUp method is called by SketchUp when the left mouse button is released.
Syntax:
tool.onLButtonUp flags, x, y, view
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
Return Value:
Comments:
Example:
N/A

onMButtonDoubleClick
The onMButtonDoubleClick method is called by SketchUp when the middle mouse button (on a three button mouse) is double-clicked.
Syntax:
tool.onMButtonDoubleClick flags, x, y, view
Arguments:
Return Value:
Comments:
Only implement this method if you want SketchUp to react to a middle mouse button being double-clicked.
Example:
N/A

onMButtonDown
The onMButtonDown method is called by SketchUp when the middle mouse button (on a three button mouse) is down.
Syntax:
tool.onMButtonDown flags, x, y, view
Arguments:
Return Value:
Comments:
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:

onMButtonUp
The onMButtonUp method is called by SketchUp when the middle mouse button (on a three button mouse) is released.
Syntax:
tool.onMButtonUp flags, x, y, view
Arguments:
Return Value:
Comments:
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:

onMouseEnter
The onMouseEnter method is called by SketchUp when the mouse enters the View object.
Syntax:
tool.onMouseEnter view
Arguments:
view - a View object where the method was invoked
Return Value:
Comments:
Example:
N/A

onMouseLeave
The onMouseLeave method is called by SketchUp when the mouse leaves the View object.
Syntax:
tool.onMouseLeave view
Arguments:
view - a View object where the method was invoked
Return Value:
Comments:
Example:
N/A

onMouseMove
The onMouseMove method is called by SketchUp whenever the mouse is moved. You will often want to implement this method.
Syntax:
tool.onMouseMove flags, x, y, view
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
Return Value:
Comments:
Try to make this method as efficient as possible because this method is called often.
Example:
N/A

onRButtonDoubleClick
The onRButtonDoubleClick is called by SketchUp when the user double clicks with the right mouse button.
Syntax:
tool.onRButtonDoubleClick flags, x, y, view
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
Return Value:
Comments:
Example:
N/A

onRButtonDown
The onRButtonDown method is called by SketchUp when the user presses the right mouse button. Implement this method when want your tool to do something other than display the context menu when the right mouse button is clicked.
Syntax:
tool.onRButtonDown flags, x, y, view
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
Return Value:
Comments:
Example:
N/A

onRButtonUp
The onRButtonUp method is called by SketchUp when the user releases the right mouse button.
Syntax:
tool.onRButtonUp flags, x, y, view
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
Return Value:
Comments:
Example:
N/A

onReturn
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.
Syntax:
tool.onReturn view
Arguments:
view - a View object where the method was invoked
Return Value:
Comments:
Example:
N/A

onSetCursor
The onSetCursor method is called by SketchUp when the tool wants to set the cursor.
Syntax:
tool.suspend view
Arguments:
view - a View object where the method was invoked
Return Value:
Comments:
Example:

class CursorTool
@@nCursor = 0

def initialize
if(@@nCursor == 0)
mydir = File.dirname(__FILE__)
@@nCursor = UI::create_cursor(mydir + "/SomeFile.tiff",11,10)
end
end #initialize

def onSetCursor()
cursor = UI::set_cursor(@@nCursor)
end

end

def test_cursor
Sketchup.active_model.select_tool CursorTool.new
end

onUserText
The onUserText method is called by SketchUp when the user has typed text into the VCB and hit return.
Syntax:
tool.onUserText text, view
Arguments:
text - the text string that was typed into the VCB view - a View object where the method was invoked
Return Value:
Comments:
Example:
N/A

resume
The resume method is called by SketchUp when the tool becomes active again after being suspended.
Syntax:
tool.resume view
Arguments:
view - a View object where the method was invoked
Return Value:
Comments:
Example:
N/A

suspend
The suspend method is called by SketchUp when the tool temporarily becomes inactive because another tool was activated. This typically happens when a viewing tool is activated, for example when orbiting with the middle mouse button.
Syntax:
tool.suspend view
Arguments:
view - a View object where the method was invoked
Return Value:
Comments:
Example:
N/A