Using the Ruby Console

(Available in Platinum and Professional)

Default UI Menu: Ruby.Net Scripts/Toggle Ruby Console

Ribbon UI Menu:

img

You can use the Ruby console to run functions, load ruby scripts, or even define new functions.

The top portion of the Ruby console is the Output Panel. This is where Ruby scripts will put text output, and where the Ruby engine will notify you of any errors that it has encountered, or provide other notifications. It is possible to copy text from the Output Panel to the clipboard for reuse in the Input Panel or elsewhere. The bottom panel of the Ruby console is the Input Panel. Here you can type in any functions that you want to call, or define new values or even functions. The Load… button allows you to open a ruby script using a standard "Open" dialog box. The Save… button allows you to save the contents of the input panel as a ruby script using a standard "Save As" dialog box. The Evaluate button tells Ruby to evaluate the text that you have typed into the Input Panel. The Close button closes the Ruby Console. After you close the Ruby console you can re-open it at any time from the Scripts/Toggle Ruby Console menu command. The Multiline checkbox allows you to turn Multiline input off or on.

  • When Multiline is unchecked (the default), only a single line of input in the input panel is evaluated. This mode is convenient for running already-defined functions or defining and setting variable values on the fly. In this mode, pressing the Enter key is the same as pressing the Evaluate button.
  • When Multiline is checked, you are allowed to enter as many different lines of text as you want. In this mode, the Enter key works to end the current line and move the cursor to a new line, instead of performing the Evaluate function. Multiline mode can be useful if you want to quickly define a simple function right in the Ruby console. After you are done entering lines, be sure to uncheck Multiline before pressing Evaluate.

Loading a script with the Load… button

To load a ruby script, click on the Load… button in the Ruby Console. This opens a dialog box that lets you browse to a ruby script and load its functions and other definitions into memory.

Note, however, that loading a script in this way will not automatically execute any of the methods in the script – you'll have to do that from the Ruby console as well. For example, if you want to execute a function draw_stuff which is contained in the ruby script ConsoleLoadSample.rb you would do the following:

  • Click on the "Load…" button.
  • Using the "Open" dialog, browse to the folder containing ConsoleLoadSample.rb.
  • Highlight ConsoleLoadSample.rb in the file list, and click "Open". The Output Panel adds a line "true" to indicate the script was opened successfully, but nothing else visibly happens.
  • Type "draw_stuff" in the Input Panel, and click Evaluate or press Enter. Now the function draw_stuff will perform whatever tasks it is supposed to.

Once the script has been loaded, it remains in memory for the duration of the TurboCAD session – you won't have to reload the script each time you want to run the draw_stuff function; simply enter "draw_stuff" in the input panel and press Enter to run the function again.

Loading a script using the load command

You can also load a script by using the load command in the Input Panel. In this case, you must specify the full path to the script, and use double backslashes as path separators. For example: load("C: MyRubyScripts draw_plus.rb") If the script is loaded successfully, the Output Panel will print a "true" response. If not, the Output Panel will print out one or more error messages. As when you use the Load... button, loading a script in this fashion does not automatically run any of the functions in the script.

Defining a function in the Input Panel

To create a new function definition in the Ruby Console is straightforward. Let us walk you through a simple example:

  • Open the Ruby Console, if it's not already open.
  • Place a check mark in the Enable Multiline checkbox.
  • Type the following lines into the input panel, using the Enter key to end each line:

def sayit puts "There, I said it!" end

  • Click Execute. (Note: Don't press Enter. Use the Executebutton.) The Output Panel should echo all the lines of the function, followed by "nil".
  • Uncheck Enable Multiline.
  • Type "sayit" in the Input Panel, and hit Enter or press Evaluate. The Output Panel should produce "There, I said it," followed by "nil".

Setting variables in the Input Panel

To set a single variable using the Input Panel, disable Multiline entry, and simply enter the variable's definition, and press Enter or click Evaluate. a = 5 press Enter To set a series of variables, enable Multiline entry and enter the variables, then disable Multiline entry and click Evaluate. a = 6 b = 4 c = 5 puts a puts a*b puts b+c click Executer.

Clearing the Output Panel

Any time you want to clear the accumulated text in the console's Output Panel, use the cls command in the Input Panel: cls press Enter

More Ruby

Examples of Ruby scripts can be found in the RubyScripts folder within the Programs folder where you installed TurboCAD. Looking at these examples is the best way to familiarize yourself with Ruby in TurboCAD. For more advanced information there are several online sights dedicated to programming in Ruby, and there are many books available. You will also want to familiarize yourself with the TurboCAD SDK for a better grasp of TurboCAD's functions. Some of the Ruby functions available emulate the functions of Ruby as used in Google SketchUp. Therefore it is advisable to look at the documentation of Ruby scripting in SketchUp as well.

TurboCAD 26

With this version of TurboCAD we have moved all the sample Ruby scripts to this RubyScripts subfolder of your "User Data" folder, in order to give you better access to them. Previously they were stored in a sub-folder of Program Files; restricted permissions on that folder made adding new scripts difficult for many users. The original goal with Ruby scripting for TurboCAD was to match as closely as possible the SketchUp Ruby function set; ultimately we had to abandond this goal due to significant differences in the two programs' feature sets. We have instead made the TurboCAD .NET API available via Ruby, and encourage you to use TC's native .NET API for calling TurboCAD functions. All the sample scripts that begin with "TC" use this API; all scripts beginning with "SU" utilize the older, incomplete SketchUp-like API.

ABOUT THIS FOLDER

Note that ALL Ruby scripts placed in this folder will be automatically loaded by TurboCAD upon startup. If you don't want a script to be executed as TurboCAD starts, store that script in a different folder; either a subfolder of this one or a folder parallel to this one should work equally well. When you have tested a script to your satisfaction, and you want to make that script's function(s) available in the Ruby console when TurboCAD starts, add a line similar to the following to the end of your script: UI.menu("Console").add_item("Name_on_menu"){function_name} For example, a very simple script might say "Hello world!"; the contents of your ruby file would look something like this: # MyHelloScript.rb def say_hello MessageBox.Show("Hello world!") end UI.menu("Console").add_item("Hello"){say_hello} When you save the script above to this folder, then close and restart TurboCAD, a new item "Hello" will be added to the droplist of available functions in the Ruby Console's pre-loads button. REFERENCING XAML-BASED FORMS TurboCAD's Ruby engine allows you to use WPF to create XAML-based dialog boxes for user input and other interactions with your script. By default, the Ruby engine will look in your default Drawings folder for such XAML files; if the XAML file cannot be found in that location, the Ruby engine will also attempt to find a non-pathed XAML file here. Otherwise, the reference to the XAML file in your script must point to the full path and filename of the XAML file, or use a path relative to this folder or the Drawings folder.

Some Examples:

window = UI.LoadXaml("MyXamlForm.xaml") No path given — Ruby will first look for MyXamlForm.xaml in the default Drawings folder, then in this RubyScripts folder. window = UI.LoadXaml("./MyXamlForm.xaml") Self-referencing relative path – Just as in the example above, Ruby will first look for this file in the Drawings folder, then in this RubyScripts folder. window = UI.LoadXaml("../XAML/MyXamlForm.xaml") Relative path to parallel folder – In this example, Ruby goes up to the parent folder, then back down into a folder named "XAML" to look for MyXamlForm. window = UI.LoadXaml("C:\MyScripts\MyXamlForm.xaml") Absolute path – Ruby looks for the xaml file in the exact location specified.

Note: IF YOU CHANGE YOUR DEFAULT DRAWINGS LOCATION, THE DEFAULT PATH WHERE RUBY LOOKS FOR XAML FILES WILL CHANGE ACCORDINGLY WHEN TURBOCAD RESTARTS. So if you change the default drawings path in TurboCAD's Options/File Locations dialog, you must update any relative paths to the XAML files in your scripts as well. In such a case, it may be easiest to move your entire RubyScripts folder into the parent folder that contains your new default drawings folder.