|
SketchUp Ruby API Examples |
Examples |
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) |
Parent: Object
Methods: activate, deactivate, draw, getExtents, getInstructorContentDirectory, getMenu, onCancel, onKeyDown, onKeyUp, onLButtonDown, onLButtonUp, onLButtonDoubleClick, onMButtonDoubleClick, onMButtonDown, onMButtonUp, onMouseEnter, onMouseLeave, onMouseMove, onRButtonDoubleClick, onRButtonDown , onRButtonUp, onReturn, onSetCursor, onUserText, resume, suspend
Example
Code: linetool.rb, tooltests.rb
The activate method is called by SketchUp when the tool is first activated.
tool.activate
The deactivate method is called when the tool is deactivated because a different tool was selected
tool.deactivate view
view - a View object where the method was invoked
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.
tool.draw view
view - a View object where the method was invoked
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.
BoundingBox = tool.getExtents
BoundingBox - a BoundingBox object
The getInstructorContentDirectory method is used to returns the directory containing the instructor content (index.html).
directory = tool.getInstructorContentDirectory
directory - the string directory where the Instructor content exists.
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.
tool.getMenu menu
menu - a Menu object
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.
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.
tool.onCancel reason, view
reason - a reason value (see comments)
view - a View object where the method was invoked
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
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.
tool.onKeyDown key, repeat, flags, view
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
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.
The onKeyUp method is called by SketchUp when the user releases a key on the keyboard.
tool.onKeyUp key, repeat, flags, view
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
onLButtonDoubleClick
The onLButtonDoubleClick method is called by SketchUp when the user double-clicks with the left mouse button.
tool.onLButtonDoubleClick flags, x, y, view 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
The onLButtonDown method is called by SketchUp when the left mouse button is pressed. Most tools will implement this method.
tool.onLButtonDown flags, x, y, view
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
The onLButtonUp method is called by SketchUp when the left mouse button is released.
tool.onLButtonUp flags, x, y, view
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
The onMButtonDoubleClick method is called by SketchUp when the middle mouse button (on a three button mouse) is double-clicked.
tool.onMButtonDoubleClick flags, x, y, view Only implement this method if you want SketchUp to react to a middle mouse button being double-clicked.
The onMButtonDown method is called by SketchUp when the middle mouse button (on a three button mouse) is down.
tool.onMButtonDown flags, x, y, view 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.
The onMButtonUp method is called by SketchUp when the middle mouse button (on a three button mouse) is released.
tool.onMButtonUp flags, x, y, view
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.
The onMouseEnter method is called by SketchUp when the mouse enters the View object.
tool.onMouseEnter view
view - a View object where the method was invoked
The onMouseLeave method is called by SketchUp when the mouse leaves the View object.
tool.onMouseLeave view
view - a View object where the method was invoked
The onMouseMove method is called by SketchUp whenever the mouse is moved. You will often want to implement this method.
tool.onMouseMove flags, x, y, view
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
Try to make this method as efficient as possible because this method is called often.
The onRButtonDoubleClick is called by SketchUp when the user double clicks with the right mouse button.
tool.onRButtonDoubleClick flags, x, y, view
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
The onRButtonDown method is called by SketchUp when the user presses the right mouse button. Implement this method, along with the tool.getMenu(menu) method, when you want your tool to do something other than display the default context menu when the right mouse button is clicked.
tool.onRButtonDown flags, x, y, view
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
The onRButtonUp method is called by SketchUp when the user releases the right mouse button.
tool.onRButtonUp flags, x, y, view
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
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.
tool.onReturn view
view - a View object where the method was invoked
The onSetCursor method is called by SketchUp when the tool wants to set the cursor.
tool.suspend view
view - a View object where the method was invoked
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
The onUserText method is called by SketchUp when the user has typed text into the VCB and hit return.
tool.onUserText text, view
text - the text string that was typed into the VCB
view - a View object where the method was invoked
The resume method is called by SketchUp when the tool becomes active again after being suspended.
tool.resume view
view - a View object where the method was invoked
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.
tool.suspend view
view - a View object where the method was invoked