If you recall from the first tutorial – Beginning Ruby 1 – Getting Started – we made a very simple script that looped through the model and found all entities in the model and sorted them into arrays.  That is a perfect starting point for many possible Ruby scripts.

The code below is the final code from the Beginning Ruby 1.  We will be editing and building on this code in this tutorial to make a fully functioning Ruby script that Push/Pulls faces in the model by a user specified distance.

I recommend writing this script in the Web Console. After it is working, we will copy it over to a text editor for some final touches.

This is what we will be changing our starting code to look like. I thought I would let you see it now so you can see how much we are changing. I’ll try to go over all the changes so it is clear what everything does.

So lets move on to the next step and get started!

We are going to be making a plugin that does a push/pull on many faces at once. In the previous tutorial, we search the model for edges, faces, components and groups. We only need to use the faces that we collected. Therefore we need to clean up our previous script so that it is only looking for and organizing faces.

Notice I deleted all the arrays that we used for edges, components and groups.  All that the script is doing now is examining all entities in the model and making an array of all the faces it finds.

To get the script to this state, I took the code from the previous tutorial (also shown in step 1 of this tutorial) and removed lines 5, 7, 8, 11, 13, 14, 16 – 21.

I’ve added lines 6, 12, 13 and 14 here.

Line 6 creates a new variable with a value of 100. This is the distance that we will push/pull each face.  The units are in inches by default (in a later step we will make it work with the user’s default units instead of inches).

Lines 12-14 are very straightforward, and do most of the magic of the script.  The code is taking the “faces” array and is running the pushpull on each face.

Notice the two parameters (called arguments) that are being use with the pushpull method.  The first one is a distance, and we are using our variable “distance”.  So it will pushpull each face 100 inches.  The second argument is a true/false value.  This is the equivalent of hitting ctrl (PC)/option (Mac) during a pushpull action in SketchUp.  Setting this to false will make the pushpull method do a simple pushpull. Setting it to true will make the method create a new face during the pushpull – the same as if you hit ctrl in SketchUp while pushpulling.

If you have tried the script at this point on some geometry, and then tried to undo it, you probably noticed that each pushpull is being treated as a separate action to be undone.  So if you ran the script on a simple box, it has done 6 pushpulls, requiring that you hit undo 6 times to get back to your original box.  Or if you ran the script on a sphere with hundreds of faces….well good luck undoing that!  Lets make the script group all actions together into a single “undo” action.

I’ve added lines 4 and 16 here.  Line 4 opens the undo queue with the start_operation method.  Line 16 commits it with the commit_operation method.  So everything that happens between those lines is treated as a single “undo” action.

We are going to put all our code so far into a method.  To do this, we define the method, end the method, then we add a line of code at the end of the script that will call the method and run our code.  This will all come in very handy later when we add our plugin to SketchUp’s menu system.

I’ve added lines 1, 20 and 22.  On line 1 I named the method “main” because it is the main method.  Well, its the only method in this script, but naming methods wisely is important in scripts that have many methods so you can keep track of what each method is doing.  Line 20 ends the method.  Notice I’ve added a commented out line that repeats the name of the method.  This just helps keep track of all the “end” statements so I can tell which one is actually ending the method. Line 22 calls the method.  The method will not run unless it is called.

Maybe you were already thinking about this, or maybe not.  But when we named our method “main”, we set ourselves up for serious problems.  If any other script has a method simply named “main” like ours, we will probably break eachother’s scripts.  The way to fix this is to wrap our code in a Ruby Module.  There is an entire thread devoted to this topic on the SketchUcation forums here.

I’ve added lines 1 and 24 and tweaked lines 3 and 26.  Line 1 defines the module and line 24 ends the module. Its important to note that now that our method is being declared inside a module, we need to alter how we are defining it. “def main” no longer works. We need to specify that it is being defined as part of the “BR_push_pull” module. On line 26 we also have to adjust how we call the method to include the module name.

Right now, our script is going to find every face and pushpull every face in the model.  Let’s change it so that it first checks if the user has geometry selected.  If they do have something selected, we will only run the script on those entities.  If nothing is selected, then the script should process the entire model.

I’ve added lines 13 – 17.  Line 13 checks to see if the selection is empty.  If it is empty (the user has nothing selected), then we assign all active_entities to our “entities” variable.  But if the user does have a selection, then we assign that selection to the “entities” variable.  Then only the selected entities will be processed later on line 19.

Lets change how the pushpull distance is determined.  Right now, it is just a variable that we are defining in the script.  Lets add an inputbox for the user to input the distance they want.

I added lines 19 – 22.  This is a very basic implementation of the UI.inputbox.  For more information on how to use it, see the API.  But the basic idea is to define an array that holds the input titles and one that holds the default values.  Line 21 triggers the inputbox and whatever the user inputs, is returned to the “results” array.  Since our inputbox only has one input, it is stored at “results[0]“.

The other important thing to note here is that in the default values, I have used “0.to_l”.  to_l is a conversion method that converts the integer 0 to the defrault user unit – 0″, 0′, 0m, 0mm, etc.  This way whatever the users enters, SketchUp will treat it like a measuerment unit.  The user can enter 12″ or 1′ or 3m or 300cm and SketchUp will accurately process that as a length and convert it accordingly.  All because I used the .to_l on the zero in the default value.

We have now added all the functionality to our script that we are going to add.  The only thing left to do is save our script to a file and add it to the menu system.  At this point, I copy the script out of the Web Console and paste it into Notepad++, my text editor. Then save it as any file name you choose, preferably one that describes what the plugin does. multiple_push_pull.rb is logical, but anything along those lines works. “.rb” is the standard filetype for a ruby file. The file should be saved to the sketchup\Plugins folder.

I have added lines 1, and 36 – 41. On line 1 I “require” the sketchup.rb file because it adds a feature that improves the menu system that I want to use (it adds other methods to SketchUp, and I recommend that you open the sketchup.rb file and try to look at its methods). Lines 37 uses the file_loaded method defined in sketchup.rb to determine if this plugin has been loaded yet. If it has not been loaded, then line 38 loads it into the menu system. The method UI.menu () specifies what menu to load the plugin into. And the method add_item() {} specifies the name to use in the menu system and also lets us specify what method to call when the user activates the plugin in the menu . Save the script, open SketchUp and check the “Plugins” folder. Your script will be listed there as “Multiple Push-Pull”. Now we’re all done!