Writing Classes:
Filter:
Guides | Language > OOP

Writing Classes

Writing SuperCollider 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.

There is also an overview of the current full Class Tree.

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.

Inheriting

To avoid having to write the same code several times, classes can inherit implementations from their superclasses.

Without specifying a superclass, Object is assumed as the default superclass.

This is why in the above example, the message new can be called without being explicitly defined in the class.

Methods

Instance Methods

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.

Class Methods

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.

This could then be used as follows:

Overriding methods (overloading)

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:

The keyword super can be used to call methods on the superclass

Instances

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 calls the method new on the superclass and returns a new object.

Instance Variables and Initialisation Logic

Instance can have variables associated with them — known as members is other languages.

These can be assigned in two ways. Through newCopyArgs or through an init method. The former is recommend and discussed first.

Rather than calling the method new a call to Object: *newCopyArgs can be used to initialise members.

The code below allows the call–site to decide the initial value of c and defaults a to 10 and b to 20.

If initialisation logic that prepares the arguments before assignment is required, ideally, it should go before the call to super.newCopyArgs. This way the final object never exists in an invalid state — an alternative is the use of an init method and shall be shown shortly.

However, when there is a hierarchy of classes, newCopyArgs requires that all the base class arguments be passed in the order they are defined. This makes changing the base class difficult. Here is one way to mitigate this issue using variable keyword arguments Functions: Variable Arguments and Object: -superPerformArgs.

Calling Derived(1, 2, 3) will set a to 1, b to 2, and c to 3. Here are some more examples:

Although this approach might seem complex, the benefit is that the new instance variables can be added to either class and it will always be clear which one you meant to assign to.

Should it be desirable to remove instance variables of the base class in the future, it is good to require that only keyword arguments be used. This can be achieved by removing the named arguments and throwing an error if args is not empty. One disadvantage here is that autocomplete in the IDE will not work.

Another benefit is that the instance is never in an incomplete state: either all the instance members have been assigned to, or the object does not exist.

The disadvantages come when you have complex initialisation logic where the arguments in Derived require knowledge of the arguments in Base. Traditionally in SuperCollider this has been solved with an init method as seen below, although a 'builder' pattern might be considered for complex cases.

This works but becomes more complex in inheritance chains.

WARNING: If both the Base and Derived class define an init method, the Derived class will override the Base's implementation, meaning it will no longer be possible to call that implementation. In such cases, a unique method name like myclassInit should be used, or better yet, a specialised name that indicates what kind of initialization is performed.

While the init pattern is the most flexible, care must be taken as inside the init functions, the instance is in an incomplete state and other methods might not work as expected; for example, this may become confusing when combined with threads and asynchronous execution, for example, when interacting with the server.

Class instances

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.

Alternatives to inheritance

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).

Polymorphism

See also: Polymorphism

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.

Object Composition

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".

Variables

Initializing variables directly

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).

Variable Scope

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.

Getters and Setters

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.

Constants

Constants are variables, that, well, don't vary. They can only be assigned initially.

External method files

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.

Slotted classes

Classes defined with [slot] can use the syntax myClass[...] which will call myClass.new and then this.add(each) for each item in the square brackets.

Printing to string

Printing custom messages to post window

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.

Defining custom asCompileString behaviour

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

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.

Catching undefined method calls

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.