Exploring hidden features

[tulamide]

One of the things that makes Ruby exciting is that its structure allows you to explore hidden Flowstone features related to Ruby. Features that exist, but were never documented. I made a lot of discoveries over the years, which are now documented in the User Guide. I found out about :setColor for the pens/brushes for example, and a lot more. Sometimes you have to dig really deep to understand how those methods are expected to be used, especially when they expect arguments, of which you know nothing about. It then becomes real detective work to uncover the secret.

I like it a lot. And I encourage you to do the same. Here's a pretty simple example, that I already shared years ago in some thread, but I'm sure it's long forgotten. Also it is still not documented in the User Guide, so it might even be interesting for you. I use it to introduce you to the main tools for your own search.

Create a RubyEdit. You should know by now that this red editor is actually a visual representation of an instance of the RubyEdit class. Every class and every class instance has a method called "methods". So type "methods" in the editor. In the info pane you will see listed all the methods this instance supports. Ignore everything else for now except ":caption" and ":parent".
Those colons btw tell you that they are symbols. A Ruby symbol very roughly is a way to tell Ruby that you plan on using the name after the colon, but for different applications, like a method name, a variable, a hash table name, etc. When you create a variable, a symbol is automatically created as well. For us in this situation it means method names.
So, a RubyEdit has the methods caption() and parent(). We could now just type "caption" in the empty RubyEdit editor, and it would call the method. But, since local variables are written just the same way, we will avoid that to not get confused further on. Instead we use "self", which just points to the current instance. It's somehow redundant, but allows us to differentiate between the method and a local variable.
Remove all code from the editor and type "self.caption". If nothing happened, don't worry. You've done it correctly. But what does "caption" in the real world mean? Headline, Heading, Title, Name. Does our RubyEdit editor have a title (= a caption)? Nope. Click on the boundary of the editor to select it. On the lower right there are now three icons that you are familiar with. The first one deletes the editor and the third one creates a module in which the editor would be placed. But the one in the middle, the capital N, sets a name for our editor. Do that now. Give it any name. I called mine "Check this out".
Now go back into the code section. Update the code to be re-interpreted (quickest way is to enter a new line). Look at the info pane. If you named your editor "Check this out" you will see "check this out in the info pane now. We have access to our tool's name (entered on the Flowstone level) inside of Ruby code!
You could use this to easily differentiate between different instances. if self.caption == "only here" ...somecode... end. Of course, that would only make sense if you created generic code for several instances, for example using a module.
But let's now go a step further. Select the editor in Flowstone again. This time click on the third icon. Click on the newly generated module to select it and click on "N". Give the module any name. I called mine "Watch this". Now double click on the module to go inside. Our RubyEdit editor is ready for us. Remove all code from it and type "self.parent". In the info pane you will see a cryptic line with two words in camel case: "CustomModule". This tells us that the method parent() points us to an instance of a class called CustomModule. Cool, we found a new class! "CustomModule" is non-existent in plain Ruby, so this was added by DSPR. Yeah! Let's investigate.
Clear all code and type "CustomModule.methods". Later, when you are more experienced, you will see immediately that those are just the standard methods inherited, that all classes support. Nothing special in the class definition. Bummer. Replace "CustomModule.methods" by "CustomModule.instance_methods". See the very first name? ":caption" Doesn't that look familiar? Obviously an instance of CustomModule has a method called caption(). Let's try it out.
Remove all code and type "self.parent.caption". If you named your module "Watch this", you will now see "Watch this" in the info pane! Oh My! Not only have we access to the editor's name, we also have access to the name of the module, the editor is placed in!
You could use this to even further differentiate between RubyEdit instances.
if self.parent.caption == "GUI KNOBS" && self.caption == "OUTLINE" ...somecode... end

This is the end of todays' lesson. I hope it was fun for you! Remember, your primary weapons for the hunt after hidden features are the methods :methods and :instance_methods

With just those two you will find 95% of the undocumented treasures.

Happy hunting!

[Spogg]

Thanks tulamide!

I really appreciate you taking the time to make these occasional tutorials.