What's New for SketchUp 6
SketchUp contains a Ruby application programming interface (API) for users
who are familiar with (or want to learn) Ruby scripting and want to extend the functionality
of SketchUp. This interface allows users to create macros, such as automated
component generators and additional tools, to be included in the menus within
SketchUp. In addition to the API, SketchUp also includes a Ruby console, which
is an environment where you can experiment with Ruby commands and methods.
What's New for SketchUp 6
The two most substantial addition to the SketchUp 6 Ruby API are the Ruby Observer Mechanism, the Tools class, the WebDialog class, the Styles class, and the Style class.
Ruby Observer Mechanism
The Ruby Observer Mechanism is designed to allow Ruby scripts to be notified when objects change in the SketchUp application or model. For example, you can create an observer class that "listens" to when SketchUp quits and then performs some action.
Create a Ruby class of a specific observer type, such as AppObserver, override the desired methods, such as onQuit, and add an instance of the observer to the applicable objects in your Ruby script (using the add_observer method for that object). Refer to individual observer interfaces for further information.
Tools Class
The Tools class contains methods to manipulate a collection of SketchUp tools. This class is primarily used to switch between tools through the use of key or mouse actions.
WebDialog Class
The Ruby WebDialog class to create and interact with, DHTML dialog boxes, called webdialogs in this documentation, from Ruby code. For example, you can create webdialogs that are invoked from your Ruby code to display a web site, or to accept user input and use the results in your Ruby code.
Styles and Style Classes
The Styles class contains methods for manipulating a collection of styles
in a model. The Style class contains methods for modifying information about a specific style.
Loading Existing Scripts
The following steps are for SketchUp users who simply want to download and
load existing Ruby scripts (such as those distributed by users on the SketchUp Ruby
Forum):
- Ensure that your script has the .rbextension. Any files with the extension .rbthat are in the Plugins folder
are automatically loaded when you start SketchUp.
- Copy the Ruby script into the SketchUp Plugins folder. This folder is located under the SketchUp
installation directory (Windows) or in the Contents\Resources\ directory
within the SketchUp package (OS X).
- Execute SketchUp. Most Ruby scripts
are designed to create a new menu item somewhere within the SketchUp menus. The
location of the menu item depends solely on how the Ruby script was written by
the author (it can be in any of the existing menus or in a newly added menu).
Refer to the Ruby script’s instructions for further details on how to run and
use the script within SketchUp.
SketchUp Ruby API Reference
The SketchUp Ruby API consists of a series of SketchUp-specific Ruby
modules, called classes in the object-oriented programming (OOP) world, and
corresponding commands, called methods in the OOP world, for creating macros
and manipulating geometry in SketchUp. Classes can be thought of as a mechanism
for grouping related SketchUp ruby commands. Click below to reference the
SketchUp Ruby API documentation using either an index of Classes or Methods.
SketchUp
Ruby API Class Index
SketchUp
Ruby API Method Index
SketchUp Ruby API Example Code
This API documentation contains sample code for each SketchUp Ruby method.
There is one sample code file, also called a test file, for each SketchUp Ruby
class file These files end in the word “Tests,” such as “EdgeTests.” All of the
sample code is available in a .zip file on the SketchUp Web site (www.sketchup.com) under the Downloads tab.
Unzip the test files in the Plugins folder within the SketchUp installation
directory. You can examine each test file using a text editor. You can also
execute the tests to see how each API works within SketchUp. To execute these
tests:
- Execute SketchUp. There will be a new menu item, under the
Plugins menu, for each of the script files. Each menu item represents a
different SketchUp Ruby class. For example, ArcCurve APIs are within a menu
item titled “ArcCurve Tests.”
- Select
the menu item representing the SketchUp Ruby class containing the API tests you
want to execute. There are submenu items for each API in each class that you
can click on and execute to test the API. For example, the ArcCurve Tests menu
item contains tests for ArcCurve.center, ArcCurve.end_angle, and so on.
These
tests are not comprehensive in that they do not contain every permutation of
every API.
Ruby Console
The Ruby console is similar in functionality to Ruby's Interactive Ruby (irb)
allowing you to experiment with Ruby commands and methods, specifically most
all methods in the in the standard Ruby API and Sketchup Ruby API. For example,
you can type in simple Ruby syntax from the SketchUp API:
- Open the Ruby Console (Window > Ruby Console).
- Type the following in the text input field at the bottom of
the console:
UI.beep
This command invokes the beep method of the UI
module to play a warning beep.
- Type the following in the text input field:
UI.messagebox("Hello World")- Type the following in the text input field to draw a line in
SketchUp (press the Enter or Return key after each line).
pt1 = [0, 0, 0]
pt2 = [10, 10, 10]
model = Sketchup.active_model
model.entities.add_line(pt1, pt2)
The first line defines a variable called p1 (point one)
and assigns it an array of three values (0,0,0). This is the origin starting
point for the line that will be drawn. The second line defines a variable called p2 (point
two) and assigns it an array of three values (10,10,10). This is the end point
for the line that will be drawn. The third line defines a variable called model which
receives a reference to the currently active model. The fourth line adds a line entity (from pt1 to pt2) to
the currently active model (This statement draws a line in the SketchUp drawing
area).
These examples can be combined with other SketchUp Ruby APIs to create a
SketchUp macro or utility. These files can then be included as a menu item
within SketchUp for use within your models.
Learning Ruby and The SketchUp Ruby API
There is an abundance of ways you can begin to learn Ruby scripting if you
are not already familiar with the language. The following is a list of recommended
ways to learn the Ruby language, including the new SketchUp Ruby API.
- Read a book or tutorial on Ruby. There are many books and
tutorials on Ruby available (some free and some for a fee). Free sources for
Ruby instruction are:
"For fee" resources can be found in your local book store's
computer section or by searching online at www.amazon.com using the keyword
"Ruby." These books and tutorials will help you to become familiar
with both Ruby syntax (the rules of the language) and the standard Ruby API
(the tools you will use).
- Take a Ruby course. Ruby courses are beginning to be offered
by universities and organizations around the world.
- Familiarize yourself with the SketchUp Ruby API by examining
the SketchUp Ruby examples and trying Ruby commands
within the Ruby console.
- Create your own SketchUp Ruby script using any text editor and
deploy it within SketchUp.
Ruby-methods.html
