Class: Sketchup::Tool Abstract
- Inherits:
-
Object
- Object
- Sketchup::Tool
- Defined in:
- lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb
Overview
Implement the methods described in this class to create a tool. You can not sub-class this class because it is not defined by the API.
Tool is the interface that you implement to create a SketchUp tool. See github.com/SketchUp/sketchup-ruby-api-tutorials/tree/master/examples/02_custom_tool 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
Instance Method Summary collapse
-
#activate ⇒ Object
The #activate method is called by SketchUp when the tool is selected.
-
#deactivate(view) ⇒ Object
The #deactivate method is called when the tool is deactivated because a different tool was selected.
-
#draw(view) ⇒ Object
The #draw method is called by SketchUp whenever the view is refreshed to allow the tool to do its own drawing.
-
#enableVCB? ⇒ Boolean
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).
-
#getExtents ⇒ Geom::BoundingBox
In order to accurately draw things, SketchUp needs to know the extents of what it is drawing.
-
#getInstructorContentDirectory ⇒ String
The #getInstructorContentDirectory method is used to tell SketchUp the directory containing your Tool’s instructor content.
-
#getMenu(menu, flags, x, y, view) ⇒ Object
The #getMenu method is called by SketchUp to let the tool provide its own context menu.
-
#onCancel(reason, view) ⇒ Object
The #onCancel method is called by SketchUp to cancel the current operation of the tool.
-
#onKeyDown(key, repeat, flags, view) ⇒ Boolean
The #onKeyDown method is called by SketchUp when the user presses a key on the keyboard.
-
#onKeyUp(key, repeat, flags, view) ⇒ Boolean
The #onKeyUp method is called by SketchUp when the user releases a key on the keyboard.
-
#onLButtonDoubleClick(flags, x, y, view) ⇒ Object
The #onLButtonDoubleClick is called by SketchUp when the user double clicks with the left mouse button.
-
#onLButtonDown(flags, x, y, view) ⇒ Object
The #onLButtonDown method is called by SketchUp when the left mouse button is pressed.
-
#onLButtonUp(flags, x, y, view) ⇒ Object
The #onLButtonUp method is called by SketchUp when the left mouse button is released.
-
#onMButtonDoubleClick(flags, x, y, view) ⇒ Object
The #onMButtonDoubleClick method is called by SketchUp when the middle mouse button (on a three button mouse) is double-clicked.
-
#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.
-
#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.
-
#onMouseEnter(view) ⇒ Object
The #onMouseEnter method is called by SketchUp when the mouse enters the viewport.
-
#onMouseLeave(view) ⇒ Object
The #onMouseLeave method is called by SketchUp when the mouse leaves the viewport.
-
#onMouseMove(flags, x, y, view) ⇒ Object
The #onMouseMove method is called by SketchUp whenever the mouse is moved.
-
#onMouseWheel(flags, delta, x, y, view) ⇒ Boolean
The #onMouseWheel method is called by SketchUp when the mouse scroll wheel is used.
-
#onRButtonDoubleClick(flags, x, y, view) ⇒ Object
The #onRButtonDoubleClick is called by SketchUp when the user double clicks with the right mouse button.
-
#onRButtonDown(flags, x, y, view) ⇒ Object
The #onRButtonDown method is called by SketchUp when the user presses the right mouse button.
-
#onRButtonUp(flags, x, y, view) ⇒ Object
The #onRButtonUp method is called by SketchUp when the user releases the right mouse button.
-
#onReturn(view) ⇒ nil
The #onReturn method is called by SketchUp when the user hit the Return key to complete an operation in the tool.
-
#onSetCursor ⇒ Boolean
The #onSetCursor method is called by SketchUp when the tool wants to set the cursor.
-
#onUserText(text, view) ⇒ Object
The #onUserText method is called by SketchUp when the user has typed text into the VCB and hit return.
-
#resume(view) ⇒ Object
The #resume method is called by SketchUp when the tool becomes active again after being suspended.
-
#suspend(view) ⇒ Object
The #suspend method is called by SketchUp when the tool temporarily becomes inactive because another tool has been activated.
Instance Method Details
#activate ⇒ Object
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.
53 54 |
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb', line 53 def activate end |
#deactivate(view) ⇒ Object
The #deactivate method is called when the tool is deactivated because a different tool was selected.
67 68 |
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb', line 67 def deactivate(view) end |
#draw(view) ⇒ Object
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.
105 106 |
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb', line 105 def draw(view) end |
#enableVCB? ⇒ Boolean
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.
121 122 |
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb', line 121 def enableVCB? end |
#getExtents ⇒ Geom::BoundingBox
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 Geom::BoundingBox. In a typical implementation, you will create a new Geom::BoundingBox, add points to set the extents of the drawing that the tool will do and then return it.
144 145 |
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb', line 144 def getExtents end |
#getInstructorContentDirectory ⇒ String
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.
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.
168 169 |
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb', line 168 def getInstructorContentDirectory end |
#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.
233 234 |
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb', line 233 def getMenu(, flags, x, y, view) end |
#onCancel(reason, view) ⇒ Object
When something is undone #onCancel is called before the undo is actually executed. If you need to do something with the model after an undo use ModelObserver#onTransactionUndo.
When #onKeyDown is implemented and returns true
, pressing Esc doesn’t trigger #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.
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.
265 266 |
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb', line 265 def onCancel(reason, view) end |
#onKeyDown(key, repeat, flags, view) ⇒ Boolean
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.
326 327 |
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb', line 326 def onKeyDown(key, repeat, flags, view) end |
#onKeyUp(key, repeat, flags, view) ⇒ Boolean
The #onKeyUp method is called by SketchUp when the user releases a key on the keyboard.
358 359 |
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb', line 358 def onKeyUp(key, repeat, flags, view) end |
#onLButtonDoubleClick(flags, x, y, view) ⇒ Object
The #onLButtonDoubleClick is called by SketchUp when the user double clicks with the left mouse button.
385 386 |
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb', line 385 def onLButtonDoubleClick(flags, x, y, view) end |
#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.
412 413 |
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb', line 412 def onLButtonDown(flags, x, y, view) end |
#onLButtonUp(flags, x, y, view) ⇒ Object
The #onLButtonUp method is called by SketchUp when the left mouse button is released.
439 440 |
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb', line 439 def onLButtonUp(flags, x, y, view) end |
#onMButtonDoubleClick(flags, x, y, view) ⇒ Object
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.
474 475 |
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb', line 474 def onMButtonDoubleClick(flags, x, y, view) end |
#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.
505 506 |
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb', line 505 def onMButtonDown(flags, x, y, view) end |
#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.
537 538 |
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb', line 537 def onMButtonUp(flags, x, y, view) end |
#onMouseEnter(view) ⇒ Object
The #onMouseEnter method is called by SketchUp when the mouse enters the viewport.
551 552 |
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb', line 551 def onMouseEnter(view) end |
#onMouseLeave(view) ⇒ Object
The #onMouseLeave method is called by SketchUp when the mouse leaves the viewport.
565 566 |
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb', line 565 def onMouseLeave(view) end |
#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.
595 596 |
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb', line 595 def onMouseMove(flags, x, y, view) end |
#onMouseWheel(flags, delta, x, y, view) ⇒ Boolean
The #onMouseWheel method is called by SketchUp when the mouse scroll wheel is used.
666 667 |
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb', line 666 def onMouseWheel(flags, delta, x, y, view) end |
#onRButtonDoubleClick(flags, x, y, view) ⇒ Object
The #onRButtonDoubleClick is called by SketchUp when the user double clicks with the right mouse button.
693 694 |
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb', line 693 def onRButtonDoubleClick(flags, x, y, view) end |
#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.
722 723 |
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb', line 722 def onRButtonDown(flags, x, y, view) end |
#onRButtonUp(flags, x, y, view) ⇒ Object
The #onRButtonUp method is called by SketchUp when the user releases the right mouse button.
749 750 |
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb', line 749 def onRButtonUp(flags, x, y, view) end |
#onReturn(view) ⇒ nil
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.
766 767 |
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb', line 766 def onReturn(view) end |
#onSetCursor ⇒ Boolean
The #onSetCursor method is called by SketchUp when the tool wants to set the cursor.
782 783 |
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb', line 782 def onSetCursor end |
#onUserText(text, view) ⇒ Object
The #onUserText method is called by SketchUp when the user has typed text into the VCB and hit return.
802 803 |
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb', line 802 def onUserText(text, view) end |
#resume(view) ⇒ Object
The #resume method is called by SketchUp when the tool becomes active again after being suspended.
816 817 |
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb', line 816 def resume(view) end |
#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.
832 833 |
# File 'lib/sketchup-api-stubs/stubs/Sketchup/Tool.rb', line 832 def suspend(view) end |