I started to learn Ruby and the SketchUp API as a total Newbie last January shortly after SketchUp announced licensing for extensions. (I was already an expert SketchUp user since version 1.0 almost 15 years ago. And I had programmed in a variety of other non object oriented languages in the past.)
What I’ve been able to accomplished might have taken 2 years without the answers to my newbie questions posted here by many “sages”.
But there were many times when I knew so little that I didn’t know the right questions to ask.
So for the benefit of any new newbies, here’s my personal and idiosyncratic list of the things I wish I knew from the start.
Code editing and testing:
• Download the free NotePad++ and use it for editing.
• Download the free extension SketchUp Ruby Code Editor (SRCE) by Alexander C. Schreyer for use in testing your code.
• I usually put each new method I write in a separate .rb file with the following overall structure:
``
module Mymodule
def self.mymethod(myparam1, myparam2)
# called by myothermethod1 and myothermethod2
# calculates myresult1 and myresult2 given myparam1 and myparam2
mod = Sketchup.active_model # Open model
ent = mod.active.entities # All active entities in model
sel = mod.selection # Current selection
#logic of mymethod goes here
return myresult1, myresult2
end #def
=begin
#test
myparam1 = 22 #plugged value
myparam2 = 45 #plugged value
result = self.mymethod myparam1, myparam2
myresult1 = result[0]
puts "myresult1 = " + myresult1.to_s
myresult2 = result[1]
puts "myresult2 = " + myresult2.to_s
=end
end #module
``
• For testing using the SRCE, I temporarily insert a # in front of =begin and =end.
• If my method calls another one of my methods I must first open and load that method using the SRCE also. That’s because SCRE wraps my module inside its own module so cannot find any methods loaded directly to Sketchup at startup.
The SketchUp Ruby API
• Don’t assume the API covers all data types or operations available to the SketchUp User. There are many holes without warning labels. For me the biggest hole is lack of control over text height and font characteristics of leader and dimension text.
• Don’t assume the specs and samples are error free or are good programming practice.
• Don’t assume Sketchup has no bugs: Read the “technical problems” forum. For me the biggest “bug/feature” is that when user applies the offset tool to an arc, the result is not an arc, so cannot be dimensioned as an arc. This is crucial in site planning and roadway design.
• But there are also many useful methods that might not strike you as useful on first sight. After a few months, go back and reread the API with more experienced eyes.
• When you first submit an extension for the warehouse, it generates and displays a unique 36 character license number code for you to insert into your ruby code using the API licensing methods (Sketchup::Licensing.get_extension_license(ext_id) .licensed?). But you can’t test this because you don’t have yet have a license yourself. And there still is no way for you to download a license for your own extension(??). If you have a typo, the Sketchup review won’t be able to test the extension. Hopefully this catch 22 situation will be remedied.
The Ruby Language:
• Best source for info http://ruby-doc.org/
• I do recommend the book “Automatic SketchUp” by Matthew Scarpino. The sages don’t like it, and it’s far from complete or up to date, but for a newbie who is totally lost, it’s the only reference where Ruby and the SketchUp API are explained together. It’s free at http://rhin.crai.archi.fr/rld/pdf/Automatic_SketchUp.pdf
• Ruby sages often use very terse ruby {blocks} in powerful ways. But I usually avoid them and use simpler control structures where line by line I can insert comments. I want to be able to understand my code 2 months later.
• I started coding without a full appreciation for ruby array methods. Big mistake. Not as good as SQL but what an elegant timesaver!
• The many documentation and forum sites covering Ruby are not directed at the relatively rare situation we have with Sketchup extensions:
o Where code from multiple authors will be run on a single user’s machine under control of a single application. So the SketchUp folks (but not their examples!!) want you to:
segregate your code into uniquely name modules (that hopefully no other author might use).
Never use global variables: ($myvariable) that might interfere with another extension.
o Where authors can write many extensions without ever defining a new Class. Sketchup already has all the classes I usually need. (I have never created a Class except where the API UI Tool forces you to.) If you do create a class of objects, its instances will be ephemeral because they won’t be saved in the skp file format.
o Where all methods are stand alone rather than part of a Class. These must e defined and called using the “self.method (parameter list)” syntax. You could take an entire introductory course on Ruby and never learn about these.
• So I religiously used only a simple set of regular variables (myvariable) which I passed to each of my methods and returned an array of variables from my methods.
• Finally after 5 months I finally discovered that what where called “Class variables” (@@myvariable) weren’t just for classes but could also be used to span an entire Module. Very useful but I use them sparingly.
I could add many observations about quirks of individual situations and methods that happened to be important to my needs. But most of them reveal themselves with a little experimentation. So now I bang away trying this and that. If I still can’t figure something out, only then do I ask my dumb question.
There will always be programmers who can code rings around you. You need to know SketchUp, the API, and Ruby. But the number one priority is always to understand the needs of the end user, even when the user doesn’t fully understand the possibilities.
Barry Milliken, Architect and developer of:
2DXY SlickMoves and 2DXY SiteSurvey.