SuperCollider GUIDES

Writing Classes

Writing SuperCollider Classes

For a basic tutorial on how standard object-orientated classes are composed, look elsewhere http://www.google.com/search?q=oop+class+tutorial

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.
Platform.userExtensionDir;   // Extensions available only to your user account
Platform.systemExtensionDir; // Extensions available to all users on the machine

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

Inheriting

MyClass : SomeSuperclass {

}

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

MyClass { // :Object is implied

}

Methods

class methods are specified with the asterisk within the class method, the keyword this refers to the class. A class in SuperCollider is itself an object. It is an instance of Class. Instance methods are specified within the instance method, the keyword this refers to the instance.

MyClass {
    *classMethod { arg argument;

    }

    instanceMethod { arg argument;

    }
}

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.

MyClass {
    someMethod {
        ^returnObject
    }

    someOtherMethod { arg aBoolean;
        if(aBoolean,{
            ^someObject
        },{
            ^someOtherObject
        })
    }

}

New Instance creation

Object.new will return to you 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.

MyClass {
    // this example adds no new functionality
    *new {
        ^super.new
    }

    // this is a normal constructor method
    *new1 { arg arga,argb,argc;
        ^super.new.init(arga,argb,argc)
    }
    init { arg arga,argb,argc;
        // do initiation here
    }
}

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. So you should use a unique method name like myclassinit if this is likely to be a problem.

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

MyClass {
    var <a,b,c;

    *new { arg a,b,c;
        ^super.newCopyArgs(a,b,c)
    }
}

MyChildClass : MyClass{
    var <d;

    *new { arg a,b,c,d;
        ^super.newCopyArgs(a,b,c,d)
    }
}

Over reliance on inheritance is usually a design flaw. Explore "object composition" rather than trying to obtain all your powers through inheritance. Is your "subclass" really some kind of "superclass" or are you just trying to swipe all of daddy's methods? Do a websearch for Design Patterns.

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

MyClass {
    classvar myClassvar;
    var myInstanceVar;
}

For class initialization check initClass.

Overriding Methods (Overloading)

In order to change the behaviour of the superclass, often methods are 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:

Superclass {
    calculate { arg in; in * 2 }
    value { arg in; ^this.calculate(in) }
}

MyClass : Superclass {
    calculate { arg in; in * 3 }
}

If the method of the superclass is needed, it can be called by super.

Superclass {
    var x;

    init {
        x = 5;
    }
}

MyClass : Superclass {
    var y;
    init {
        super.init;
        y = 6;
    }
}

Getter Setter

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

MyClass : Superclass {
    var myVariable;

    variable {
        ^myVariable
    }

    variable_ { arg newValue;
        myVariable = newValue;
    }
}

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

MyClass {
    var <getMe, >setMe, <>getMeOrSetMe;
}

you now have the methods:

someObject.getMe;
someObject.setMe_(value);

this also allows us to say:

someObject.setMe = value;

someObject.getMeOrSetMe_(5);
someObject.getMeOrSetMe.postln;

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

MyClass {
    variable_ { arg newValue;
        variable = newValue.clip(minval,maxval);
    }
}

A setter method should always return the receiver. This is standard OOP practice (outside of SuperCollider as well). Do not return the new value from your setter.

MyClass {
    variable_ { arg newValue;
        myVariable = newValue;
        ^newValue       // DO NOT DO THIS
    }
}

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.

+ Class {
    newMethod {
    }

    *newClassMethod {
    }
}

Slotted classes

Classes defined with [slot] can use the syntax myClass[i] which will call myClass.at(i). This is useful when defining classes that inherit from a Collection type class.

MyClass[slot] {
    *new {
         ^super.new
    }

    at {|i|
        ("Index "++i).postln
    }
}
a = MyClass();
a[3];

Defining a custom array of Points:

MyPointArray[slot] : RawArray {
    center { ^Point(*this.asArray.flop.collect{ |item| item.sum / item.size } ) }
    asArray{ ^this.collect{ |elem| elem.asArray } }
}

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 can be overridden to obtain more useful information.

MyTestPoint {
    var <x, <y;

    *new{ |x,y| ^super.newCopyArgs(x,y) }

    printOn { arg stream;
        stream << "MyTestPoint( " << x << ", " << y << " )";
    }
}
a = MyTestPoint(2,3);

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.

// either
MyTestPoint {
    var <x, <y;

    *new{ |x,y| ^super.newCopyArgs(x,y) }

    storeOn { arg stream;
        stream << "MyTestPoint.new(" << x << ", " << y << ")";
    }
}

// or
MyTestPoint {
    var <x, <y;

    *new{ |x,y| ^super.newCopyArgs(x,y) }

    storeArgs { arg stream;
        ^[x,y]
    }
}
MyTestPoint(2,3).asCompileString;

Catching methods that are not explicitly defined

It is possible to catch calls to methods that are not explicitly defined in a Class by overriding doesNotUnderstand.

MyClass {
    *new { ^super.new }

    doesNotUnderstand { arg selector...args;
        (this.class++" does not understand method "++selector);

        If(UGen.findRespondingMethodFor(selector).notNil){
            "But UGen understands this method".postln
        };
    }
}
a = MyClass();
a.someMethodThatDoesNotExist

Tricks and Traps

"Superclass not found..."
In one given code file, you can only put classes that inherit from each Object, each other, and one external class. In other words, you can't inherit from two separate classes that are defined in separate files.

If you should happen to declare a variable in a subclass and use the same name as a variable declared in a superclass, you will find that both variables exist, but only the one in the object's actual class is accessible. You should not do that. This will at some point become an error worthy of compilation failure.