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