Ruby Bitmap Methods

[aronb]

Hi,

Other than the Ruby "Bitmap Methods" in the "User Guide", are there any hidden methods / features?
i.e. "getPixel", "setPixel", etc???

How about any hidden features / methods, etc. (in the Ruby Component) at all

Thanks,

Aron

[trogluddite]

There are certainly quite a few undocumented methods in FlowStone's custom Ruby classes. I haven't looked into the Bitmap class specifically, and don't have FlowStone handy right now, but here's a general idea for how to go about finding them, using Ruby code itself.

Ruby has many methods for what is called "reflection" - finding things out about classes and objects. It's probably easiest to ask the Class, as then you don't need to create an instance to play with; for example; typing the following into an empty RubyEdit primitive...

Code: Select all

watch Bitmap.instance_methods

...will show you a list of all instance methods which Bitmaps respond to (the result is actually an Array of Symbols). You'll find that it's quite a long list, as it will include all of the general purpose methods which all Ruby objects have. To narrow the list to only methods which are specific to Bitmaps, pass false as an argument...

Code: Select all

watch Bitmap.instance_methods(false)

To ask an object directly, rather than it's class, you can use the methods method...

Code: Select all

my_string = "Foo"
my_string.methods

And you can ask an object whether it recognises a particular method...

Code: Select all

my_string.respond_to?(:gsub)  # Returns true (don't forget the question mark)

These methods are incredibly useful. Most Ruby method names give a pretty good clue what they do, and for a quick reminder, it can be easier than opening a browser and rummaging through the Ruby API documents. I keep a spare, empty RubyEdit on hand very often, as a scratchpad for just this kind of thing.

However, this still doesn't show you all of the methods, because Classes and objects can have private methods, which are normally hidden, and can't be called directly. But there's a method to look at these, too...

Code: Select all

watch Bitmap.private_instance_methods

And that can take the false argument, too, in the same way.

Code: Select all

watch Bitmap.private_instance_methods(false)

Private methods are usually only for use internally by an object, not by calling them from code. Using them can be very unpredictable because you weren't meant to be calling them at all - but sometimes they do offer a neat hack for a problem that you can't solve any other way. You can't call them in the usual way, by putting the name after a dot. Instead, you must use the method send. The first argument to send is the name of the method you want to call as a String or a Symbol (it works for any method, not just private ones), and you can follow that with any other arguments that you might need. For example, the two lines below do exactly the same thing...

Code: Select all

my_string.gsub("find", "replace")
my_string.send(:gsub, "find", "replace")

Because the first argument is just a regular String or Symbol, this is worth knowing, as it means that you can selectively call different methods by using a variable as the first argument - it's a neat alternative to if-then or case statements sometimes.

The hard part when uncovering undocumented methods is working out what their arguments should be. For methods programmed in Ruby, it is possible to find out how many arguments a method takes, but most of FlowStone's custom methods are compiled C++ add-ons, for which this can't be done - so you'd have to rely on educated guesswork and a bit of trial and error (for example, if there is a GetPixel method, you'd expect it to take either two numbers or an Array of two numbers (co-ordinate), and return a Color object.)

And lastly, a big caveat! Messing with undocumented methods may cause crashes and all sorts of other mayhem, which is sometimes why we haven't been told about them. Be sure to back things up etc. before you start fiddling around!

Have fun - there are lots of interesting things to be discovered about FlowStone Ruby (and Ruby in general) using this kind of detective work, and Ruby has many other built-in methods for peeking under the hood!