There are also subtle differences between kits when it comes to subclassing. In particular, in Qt GUI, step 2 of this tutorial is redundant, and step 3 consists of overriding the *new class method instead of the init instance method.
Nonetheless, you may find this tutorial helpful for other GUI kits than Cocoa, as most information in it is correct for all the kits.
This is a short tutorial on how to make a custom view class by subclassing SCUserView. It is assumed that you know how to write classes in SuperCollider. See Writing Classes.
At the bottom of this document there is a template class code that you can refer to as an example of the steps taken in the tutorial. To test it simply copy it into a file ending with '.sc' and place the file into your SC Extensions folder. If you are already running SuperCollider, recompile the class library in order for the new class to become available.
You may also find the template useful when creating your own custom view classes. Rename the class MyWidget to whatever you want to call your class, and adjust the variables and methods to fit your design.
The following narrates the code in the template:
You inherit all of the instance variables from SCUserView and SCView, of course, but many gui widgets need their own variables.
In particular, you need to overide value, to return whatever you want your view to return. The instance variable, step, is also often used to allow value to be quantized. thumbSize is used for both width and height of a slider handle, while thumbWidth or thumbHeight are typically used for only one dimension. x and y are used for mouse clicks. Take a look at a similar widget to see what the standard instance variables are.
It is mandatory to define the *viewClass class method to return the SCUserView class. You must do this so that your class calls the primitive of SCUserView on init.
You will want to override init to customize your subclass. Here you will set the defaults of some of your instant variables and anything else you want to do on creating the view.
Finally, you should set this.drawFunc (SCUserView's drawing function) to the method this.draw, which you will define below.
This is where you will define how the view appears. How you draw will typically be dependent on instance variables which you defined, such as value, states (for buttons), x and y (for mouse clicks), or anything else you might need for your design. See Pen for drawing methods.
Here you define various methods according to your own design. You should look at similar gui objects to see what they have. The setter, valueAction_ is defined by practically any gui widget, for example. It sets the value and performs the action (already defined in SCView).
SCView defines mouseDown, mouseMove and mouseUp, as methods, and the corresponding user definable methods, mouseDownAction, mouseMoveAction and mouseUpAction. You should override mouseDown, mouseMove or mouseUp as needed, and make sure your method calls the corresponding action as well, so your user can later add user actions, just like in the template. See also the View: Subclassing.
Here you define your default key responses in defaultKeyDownAction or defaultKeyUpAction. Differently than with mouse actions, you do not call the keyAction in your method, since this mechanism is handled by SCView. If the user defines a keyDownAction, or keyUpAction, SCView makes it override your default action. See the template, and View: Subclassing.
Here you define your drag responses in defaultGetDrag, defaultCanReceiveDrag, and defaultReceiveDrag. Differently than with mouse actions, you do not call the dragAction in your method, since this mechanism is handled by SCView. If your user defines a beginDragAction, canReceiveDragHandler, or receiveDragHandler, SCView makes it override your default action. See the template, and View: Subclassing.
That's it. Now recompile, only to find your first syntax errors. ;-)
Happy subclassing.
// How to subclass SCUserView to make custom GUI interfaces. Jost Muxfeldt, 2008.
// For many purposes you can use this as a template, and simply adjust the methods
MyWidget : SCUserView {
// (1) Setup instance vars appropriate to your widget. Make sure to define value.
var <>step, <value=0, <>leftColor, <>rightColor, <>thumbWidth=7;
// (2) Set the viewClass to SCUserView
*viewClass { ^SCUserView } // this ensures that SCUserView's primitive is called
// (3) Set up your view
init { |argParent, argBounds|
super.init(argParent, argBounds);
// set defaults of your instance variables
rightColor=Color.grey(0.8);
leftColor=Color.grey(0.2);
step=this.pixelStep;
// set the draw function of the SCUserView
this.drawFunc={ this.draw};
}
// (4) define a drawing function for SCPen
draw{
// Draw the fill
SCPen.fillColor = Color.grey;
Pen.addRect(Rect(0,0, this.bounds.width*value,this.bounds.height));
Pen.fill;
// Draw the triangle
SCPen.fillColor = Color.red;
Pen.moveTo(((this.bounds.width*value)-5) @ this.bounds.height);
Pen.lineTo(((this.bounds.width*value)+5) @ this.bounds.height);
Pen.lineTo(((this.bounds.width*value)) @ (this.bounds.height/2));
Pen.lineTo(((this.bounds.width*value)-5) @ this.bounds.height);
Pen.fill;
// Draw the frame
SCPen.strokeColor = Color.black;
Pen.addRect(Rect(0,0, this.bounds.width,this.bounds.height));
Pen.stroke;
}
// (5) define typical widget methods (only those you need or adjust as needed)
valueAction_{ arg val; // most widgets have this
this.value=val;
this.doAction;
}
value_{ |val| // in many widgets, you can change the
// value and refresh the view , but not do the action.
value=val;
this.refresh;
}
// these are like in SCSlider
increment { |zoom=1| ^this.valueAction = this.value + (max(this.step, this.pixelStep) * zoom) }
decrement { |zoom=1| ^this.valueAction = this.value - (max(this.step, this.pixelStep) * zoom) }
pixelStep { // like in SCSlider
var bounds = this.bounds;
^(bounds.width-1).reciprocal
}
// (6) override mouseActions
mouseDown{ arg x, y, modifiers, buttonNumber, clickCount;
var newVal;
// this allows for user defined mouseDownAction
mouseDownAction.value(this, x, y, modifiers, buttonNumber, clickCount);
// set the value and do the action
([256, 0].includes(modifiers)).if{ // restrict to no modifier
newVal= x.linlin(0,this.bounds.width,0,1);
// translates the relative mouse position in pixels to a value between 0 and 1
if (newVal != value) {this.valueAction_(newVal)}; // only do something if the value changed
};
}
mouseMove{ arg x, y, modifiers, buttonNumber, clickCount;
var newVal;
// this allows for user defined mouseMoveAction
mouseMoveAction.value(this, x, y, modifiers, buttonNumber, clickCount);
// set the value and do the action
([256, 0].includes(modifiers)).if{ // restrict to no modifier
newVal= x.linlin(0,this.bounds.width,0,1);
// translates the relative mouse position in pixels to a value between 0 and 1
if (newVal != value) {this.valueAction_(newVal)}; // only do something if the value changed
};
}
// (7) define default key actions
// make sure to return "this", if successful, and nil if not successful
defaultKeyDownAction { arg char, modifiers, unicode,keycode;
if (unicode == 16rF700, { this.increment; ^this });
if (unicode == 16rF703, { this.increment; ^this });
if (unicode == 16rF701, { this.decrement; ^this });
if (unicode == 16rF702, { this.decrement; ^this });
^nil // bubble if it's an invalid key
}
// (8) define drag and drop
defaultGetDrag {^value} // what to drag
defaultCanReceiveDrag {^currentDrag.isNumber} // when to receive
defaultReceiveDrag { this.valueAction = currentDrag;} // what to do on receiving
}
Try this after you have added the class to the class library:
(
GUI.cocoa;
w=Window.new.front;
v=MyWidget(w, Rect(10,20,200,20)).valueAction_(0.5);
q=MyWidget(w, Rect(10,60,200,20)).valueAction_(0.3);
)