API_Notes

A class method is a method that is sent to the class itself. For all of the FlowStone custom class, the only entry that you may see here is the method .new. The new method of any class is the method that gets you a new instance of the class - i.e. a new unique object. For example, if this page was about a real class, you might write

@my_new_object = API_Notes.new

Putting the class name first is mandatory, otherwise Ruby won't know what kind of object it is that you want to create!

Other than that, you read the method definition just as you would for an instance method (see below).

Some classes do not show even a new class method - but this doesn't mean that there isn't one, ALL classes have a new method by default. Where a new method is not shown, it means that it is 'private'. These are classes where you would never create your own instance, but FlowStone will provide you with one whenever it is needed.

A good example of a class with no new method is the View class. A new view has to be created whenever a module needs to re-draw its GUI. But the View has to be created in such a way that the connected MGUI primitive can get at it - so FlowStone makes a new View for every redraw, and provides it to you by sending it to your RubyEdit's draw method.

Regular Ruby classes may have more class methods than just new if there is a need to do something with the class as a whole rather than with a particular instance - or sometimes if there are multiple ways to create a new instance (for example File.open to open the data in a file).

Class methods are not always Class methods either. Confusing?! This is because of something called 'Modules'. A Module is a bit like a Class, but you can't make instances of it - its just a container for a bunch of methods. FlowStone doesn't have any custom modules, so I won't elaborate on that here.

# File Flowstone API.rb, line 1334
def self.new
  #DUMMY
end

This is an instance method definition. Calling an instance method sends a message to an object to tell it to do something. The definition doesn't show the object that you are sending the message to - it is just implied that you can only use this method with an object, and the object must be of the same Class as this page is documenting. The object that you send a message to is often referred to as "the receiver", or sometimes 'self'.

If you write a method name all on its own, Ruby will try to make as much sense as it can of what you mean - it will try to find an implied "receiver" for the message. When you are inside a RubyEdit primitive, the implied receiver is usually the RubyEdit instance itself. For example

# This is OK, all RubyEdits have a 'time' method...
time
#=> 5.232532

# This doesn't work, as 'channel' is a method of Midi objects
# not RubyEdits!!
channel
#=> NoMethodError: Unknown method 'channel' for RubyEdit<#12345678>

# Aah, this is better!
@my_midi = Midi.new(176, 2, 20, 125)
@my_midi.channel
#=> 2

So for most of the method definitions except for the RubyEdit ones, remember that the 'receiver' and the 'dot' are always implied.

The arguments that the method requires are given between parentheses straight after the method name. 'Arguments' are the values that you feed to a method so specify precisely what it should do. The same method may be listed several times, each with a different list of arguments. This means that the method has some optional arguments, or there are several different kinds of object that could be used for the same argument. The method descriptions should make clear what defaults are used if you do not give an optional argument. So we can see that for the example_method the third argument is optional.

If an argument in the list has a name beginning with a capital letter, it means that the argument must be of that class. This helps to keep the description nice and short if its fairly obvious what the argument is used for. Lower case names are used if simply giving the class might be confusing (e.g. there are many arguments all of the same class.) The names are just ones I made up - they have no meaning other than being a handy reference to use in the description.

The arrow after the arguments list, pointing to a class name, means "this is what the method will give you back as a result". So for this example method, we'll always get a Float number back. Ruby methods always return something - but I have omitted the return value for any method where the object you get back has no useful meaning.

Note also, that all of the custom Ruby classes have many, many more methods than you see in the doc's. The ones shown are only the ones that are unique to each particular class. There is a huge number of "universal" methods that almost all Ruby objects posess. This is to make coding more simple by ensuring that there is a 'core' of common methods that are available no matter where you are in your code. To see what they are you'll need to look at the official Ruby API documents, under the class 'Object' and the module 'Kernel' - there are far too many for me to list them all here!!!

And finally, why are they called "Public" methods? Well, that is because Classes and instances are allowed to have methods which you can't normally get at - so called "Private" and "Protected" methods. Private and Protected methods can usually only be accessed from within the code that exists inside an object - 'housekeeping' duties, so to speak, that the object looks after for itself, and we don't have to be concerned with.

"Public" methods are the ones that we have access to from outside the object, to tell it to do stuff. The word "Public" is only shown because the document generator can show the hidden stuff too - but only if we have permission. These classes are DSP Robotics code, so we don't have that kind of access to the inner workings!

# File Flowstone API.rb, line 1423
def example_method
  #DUMMY
end