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): 

1. 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.
   
   
2. 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).
   
   
3. 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:

1. 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.”
   
   
2. 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:

1. Open the Ruby Console (Window > Ruby Console).
   
   
2. 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.

3. Type the following in the text input field:

UI.messagebox("Hello World")

4. 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. 

1. 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:

• "Programming Ruby" online at http://www.ruby-doc.org/docs/ProgrammingRuby
• "The "Ruby user's guide" online at http://www.ruby-doc.org/docs/UsersGuide/rg/
• "Introduction to Ruby" online at http://www.ruby-doc.org/docs/Tutorial/
• "Learn to Program - A Tutorial for the Future Programmer" on line at http://pine.fm/LearnToProgram/

"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).

2. Take a Ruby course. Ruby courses are beginning to be offered by universities and organizations around the world.
   
   
3. Familiarize yourself with the SketchUp Ruby API by examining the SketchUp Ruby examples and trying Ruby commands within the Ruby console.
   
   
4. Create your own SketchUp Ruby script using any text editor and deploy it within SketchUp.