Writing Classes

SuperCollider follows a pure object-oriented paradigm. It is not built on data types, but on objects, which respond to messages. A class is an object that holds information about how its objects (instances) respond to such messages. Writing a class gives a definition of this behavior.

This is an overview of idioms used in writing classes. It is not a tutorial on writing a system of interrelated classes. It gives an overview of some typical expressions. See also: Introduction to Objects, Messages, and Classes.

NOTE: Class definitions are statically compiled when you launch SuperCollider or "recompile the library." This means that class definitions must be saved into a file with the extension .sc, in a disk location where SuperCollider looks for classes. Saving into the main class library (SCClassLibrary) is generally not recommended. It's preferable to use either the user or system extension directories.

It is not possible to enter a class definition into an interpreter window and execute it.

Each object instance responds to its instance methods. Instance methods are called in the local context of the object. Within instance methods, the keyword this refers to the instance itself.

This could then be used as follows:

To return from the method use ^ (caret). Multiple exit points also possible. If no ^ is specified, the method will return the instance (and in the case of Class methods, will return the class). There is no such thing as returning void in SuperCollider.

An object's class methods are defined alongside its instance methods. They are specified with an asterisk (*) before the method name.

A Class is itself an object. It is what all instances of it have in common. Class methods are the instance methods of the object's class. That's why within class methods, the keyword this refers to the class.

To change the behaviour inherited from the superclass, methods can be overridden. Note that an object looks always for the method it has defined first and then looks in the superclass. Here MyClass.value(2) will return 6, not 4:

Object.new will return a new object. When overriding the class method .new you must call the superclass, which in turn calls its superclass, up until Object.new is called and an object is actually created and its memory allocated.

In this case note that super.new called the method new on the superclass and returned a new object. Subsequently we are calling the .init method on that object, which is an instance method.

WARNING: If the superclass also happened to call super.new.init it will have expected to call the .init method defined in that class (the superclass), but instead the message .init will find the implementation of the class that the object actually is, which is our new subclass. In such cases, a unique method name like myclassInit should be used.

One easy way to copy the arguments passed to the instance variables when creating a class is to use Object: *newCopyArgs. This method will copy the arguments to the instance variables in the order that the variables were defined in the class, starting from the parent classes and working it's way down to the current class.

Class variables are accessible within class methods and in any instance methods.

Initializations on class level (e.g. to set up classvars) can be implemented by overloading the Class: *initClass method.

Overreliance on inheritance is usually a design flaw. Inheritance is mainly a way to organise code, and shouldn't be mistaken for a categorisation of objects. Two objects may respond to a message in different ways (polymorphism), and objects delegate control to ther objects they hold in their instance variables (object composition).

Two completely unrelated objects can respond to the same messages and therefore be used together in the same code. For example, Function and Event have no common superclass apart from the general class Object. But both respond to the message play. Instead of inheriting all methods, you can simply implement some of the same methods in your class.

Often, an object passes control to one of the objects it has in its instance variables. Because these objects can be of any kind, this is a very flexible way to achieve a wide range of functionalities. For example, a Button has an action instance variable, which may hold anything that responds to the message value.

Often, variables like action above are filled with custom objects that belong to MyClass. Thus, one will write many small classes that can be well combined in such a way. This is called "pluggable behavior".

In a variable declaration, variables can be directly initialized. Only Literals may be used to initialize variables this way. This means that it is not possible to chain assignments (e.g. var x = 9; var y = x + 1).

An instance variable is accessible from all instance methods of this class and its subclasses. A class variable, by contrast, is accessible from all class and instance methods of this class and its subclasses. Instance variables will shadow class variables of the same name.

Subclasses can override class variable declarations (but not instance variables). Then the class variables of the superclass are not accessible in the subclass anymore.

SuperCollider demands that variables are not accessible outside of the class or instance. A method must be added to explicitly give access:

These are referred to as getter and setter methods. SuperCollider allows these methods to be easily added by adding < or >.

This provides the following methods:

And it also allows us to say:

A getter or setter method created in this fashion may be overridden in a subclass by explicitly defining the method. Setter methods should take only one argument to support both ways of expression consistently. eg.

A setter method should always return the receiver. This allows us to be sure that several setters can chained up.

Methods may be added to Classes in separate files. This is equivalent to Categories in Objective-C. By convention, the file name starts with a lower case letter: the name of the method or feature that the methods are supporting.

By default when postln is called on an class instance the name of the class is printed in a post window. When postln or asString is called on a class instance, the class then calls printOn which by default returns just the object's class name. This should be overridden to obtain more useful information.

A call to asCompileString should return a string which when evaluated creates the exact same instance of the class. To define a custom behaviour one should either override storeOn or storeArgs. The method storeOn should return the string that evaluated creates the instance of the current object. The method storeArgs should return an array with the arguments to be passed to TheClass.new. In most cases this method can be used instead of storeOn.

Private methods are marked by a prefix pr, e.g. prBundleSize. This is just a naming convention; the message can still be called from anywhere. It is recommended to stick to convention and only call private methods from within the class that defines them.

When a message is received that is undefined, the receiver calls the method doesNotUnderstand. Normally this throws an error. By overriding doesNotUnderstand, it is possible to catch those calls and use them. For an example, see the class definition of IdentityDictionary.