tut_hello_cube.rb | SketchUp Developer

Source Code tut_hello_cube.rb

This is the contents of the tut_hello_cube.rb file with the comments stripped out of it that we will be examining in this part of the tutorial.

require 'sketchup.rb'
require 'extensions.rb'

module Examples
  module HelloCube

    unless file_loaded?(__FILE__)
      ex = SketchupExtension.new('Hello Cube', 'tut_hello_cube/main')
      ex.description = 'SketchUp Ruby API example creating a cube.'
      ex.version     = '1.0.0'
      ex.copyright   = 'Trimble Navigations © 2016'
      ex.creator     = 'SketchUp'
      Sketchup.register_extension(ex, true)
      file_loaded(__FILE__)
    end

  end # module HelloCube
end # module Examples

Registering Our Extension

Create a blank text file in your SketchUp Plugins folder. Name it tut_hello_cube.rb. Use your favorite Ruby editor to edit the file.

This file is what call the "root" ruby file, or sometimes the "registration" file because it sits in your root plugins folder, it also registers your extension with SketchUp. We're pretty clever, 'eh?!

Don't use the root file to do any other code tasks.

We expect that this file sets up everything needed to regsiter the extension with SketchUp and nothing else.

The first thing we need to do for our Extension is require a few ruby files provided by SketchUp. Both of these add functionailty that we'll use in the following lines of code. Add these lines to the top of your file:

require 'sketchup.rb'
require 'extensions.rb'

Next we need to properly namespace your code. In SketchUp Ruby, all code is loaded into a single space. If you don't wrap your own code into your own module names, there is a very real chance that you will break someone else's code, or that they will break yours.

To Namespace your extension, we recommend a pattern similar to:

module PublisherName
module ExtensionName
# ...
end
end

module Examples
  module HelloCube

Next we'll guard against the Extension being loaded by SketchUp multiple times. We'll use the method `file_loaded?` for this. Multiple loading can happen for various reasons - either by development debugging or extension updates etc.

The __FILE__ constant is a "magic" Ruby constant that returns a string with the path to the current file. You don't have to use this constant with file_loaded? - you can use any unique string to represent this file. But __FILE__ is very convenient for this.

unless file_loaded?(__FILE__)

Next we define the extension. The two arguments are the extension name and the file that should be loaded when the extension is enabled.

Note that the file loaded (tut_hello_world/main) must be in a folder named with the same base name as this root file.

Another thing to notice is that we omitted the .rb file extension and wrote `tut_hello_world/main` instead of `tut_hello_world/main.rb`. SketchUp is smart enough to find the file regardless and this is required if you decide to later encrypt the extension.

ex = SketchupExtension.new('Hello Cube', 'tut_hello_cube/main')

Next we add some information to the extension. This isn't required, but highly recommended as it helps the user when managing it's installed extensions.

      ex.description = 'SketchUp Ruby API example creating a cube.'
      ex.version     = '1.0.0'
      ex.copyright   = 'Trimble Navigations © 2016'
      ex.creator     = 'SketchUp'

Finally we tell SketchUp to register this extension. Remember to always set the second argument to true - this tells SketchUp to load the extension by default. Otherwise the user have to manually enable it after installing.

Sketchup.register_extension(ex, true)

This is needed for the load guard to prevent the extension being registered multiple times.

      file_loaded(__FILE__)
    end

  end # module HelloCube
end # module Examples