HelpSource/Guides/UserView-Subclassing.schelp

   1 title:: Custom Views
   2 summary:: A guide to creating custom views by subclassing UserView
   3 categories:: GUI
   4 related:: Classes/UserView, Guides/WritingClasses, Guides/GUI-Introduction
   5
   6 note:: This document only applies to strong:: Cocoa GUI ::. Subclassing a view is specific to a GUI kit, at least because you have to subclass from the kit-specific class, i.e. SCUserView, QUserView or JSCUserView, instead of the generic UserView class.
   7
   8 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 code::*new:: class method instead of the code::init:: instance method.
   9
  10 Nonetheless, you may find this tutorial helpful for other GUI kits than Cocoa, as most information in it is correct for all the kits.
  11 ::
  12
  13 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 link::Guides/WritingClasses::.
  14
  15 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.
  16
  17 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.
  18
  19 SECTION:: Tutorial
  20
  21 The following narrates the code in the template:
  22
  23 SUBSECTION:: 1. Setup instance vars appropriate to your widget
  24
  25 You inherit all of the instance variables from SCUserView and SCView, of course, but many gui widgets need their own variables.
  26
  27 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.
  28
  29
  30 SUBSECTION:: 2. Define the *viewClass method
  31
  32 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.
  33
  34
  35 SUBSECTION:: 3. Set up your view
  36
  37 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.
  38
  39 Finally, you should set code::this.drawFunc (SCUserView's drawing function):: to the method this.draw, which you will define below.
  40
  41 SUBSECTION:: 4. Define a drawing function for SCPen
  42
  43 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 link::Classes/Pen:: for drawing methods.
  44
  45
  46 SUBSECTION:: 5. Define typical widget methods
  47
  48 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).
  49
  50 SUBSECTION:: 6. Override mouseActions
  51
  52 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 link::Classes/View#subclassing#View: Subclassing::.
  53
  54
  55 SUBSECTION:: 7. Define default key actions
  56
  57 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 link::Classes/View#subclassing#View: Subclassing::.
  58
  59
  60 SUBSECTION:: 8. Define default drag and drop actions
  61
  62 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 link::Classes/View#subclassing#View: Subclassing::.
  63
  64
  65 That's it. Now recompile, only to find your first syntax errors. ;-)
  66
  67 Happy subclassing.
  68
  69 SECTION:: Custom view template
  70
  71 code::
  72 // How to subclass SCUserView to make custom GUI interfaces. Jost Muxfeldt, 2008.
  73 // For many purposes you can use this as a template, and simply adjust the methods
  74
  75 MyWidget : SCUserView {
  76
  77         // (1) Setup instance vars appropriate to your widget. Make sure to define value.
  78         var <>step, <value=0, <>leftColor, <>rightColor, <>thumbWidth=7;
  79
  80         // (2) Set the viewClass to SCUserView
  81         *viewClass { ^SCUserView } // this ensures that SCUserView's primitive is called
  82
  83
  84         // (3) Set up your view
  85         init { |argParent, argBounds|
  86
  87                 super.init(argParent, argBounds);
  88
  89                 // set defaults of your instance variables
  90                 rightColor=Color.grey(0.8);
  91                 leftColor=Color.grey(0.2);
  92                 step=this.pixelStep;
  93
  94                 // set the draw function of the SCUserView
  95                 this.drawFunc={ this.draw};
  96         }
  97
  98
  99         // (4) define a drawing function for SCPen
 100         draw{
 101                 // Draw the fill
 102                 SCPen.fillColor = Color.grey;
 103                 Pen.addRect(Rect(0,0, this.bounds.width*value,this.bounds.height));
 104                 Pen.fill;
 105                 // Draw the triangle
 106                 SCPen.fillColor = Color.red;
 107                 Pen.moveTo(((this.bounds.width*value)-5) @ this.bounds.height);
 108                 Pen.lineTo(((this.bounds.width*value)+5) @ this.bounds.height);
 109                 Pen.lineTo(((this.bounds.width*value)) @ (this.bounds.height/2));
 110                 Pen.lineTo(((this.bounds.width*value)-5) @ this.bounds.height);
 111                 Pen.fill;
 112                 // Draw the frame
 113                 SCPen.strokeColor = Color.black;
 114                 Pen.addRect(Rect(0,0, this.bounds.width,this.bounds.height));
 115                 Pen.stroke;
 116         }
 117
 118
 119         // (5) define typical widget methods  (only those you need or adjust as needed)
 120         valueAction_{ arg val; // most widgets have this
 121                 this.value=val;
 122                 this.doAction;
 123         }
 124         value_{ |val|    // in many widgets, you can change the
 125                                          // value and refresh the view , but not do the action.
 126                 value=val;
 127                 this.refresh;
 128         }
 129                         // these are like in SCSlider
 130         increment { |zoom=1| ^this.valueAction = this.value + (max(this.step, this.pixelStep) * zoom) }
 131         decrement { |zoom=1| ^this.valueAction = this.value - (max(this.step, this.pixelStep) * zoom) }
 132
 133         pixelStep {  // like in SCSlider
 134                 var bounds = this.bounds;
 135                 ^(bounds.width-1).reciprocal
 136         }
 137
 138
 139         // (6) override mouseActions
 140         mouseDown{ arg x, y, modifiers, buttonNumber, clickCount;
 141                 var newVal;
 142                 // this allows for user defined mouseDownAction
 143                 mouseDownAction.value(this, x, y, modifiers, buttonNumber, clickCount);
 144
 145                 // set the value and do the action
 146                 ([256, 0].includes(modifiers)).if{ // restrict to no modifier
 147
 148                         newVal= x.linlin(0,this.bounds.width,0,1);
 149                         // translates the relative mouse position in pixels to a value between 0 and 1
 150
 151                         if (newVal != value) {this.valueAction_(newVal)}; // only do something if the value changed
 152                 };
 153         }
 154
 155         mouseMove{ arg x, y, modifiers, buttonNumber, clickCount;
 156                 var newVal;
 157                 // this allows for user defined mouseMoveAction
 158                 mouseMoveAction.value(this, x, y, modifiers, buttonNumber, clickCount);
 159
 160                 // set the value and do the action
 161                 ([256, 0].includes(modifiers)).if{ // restrict to no modifier
 162
 163                         newVal= x.linlin(0,this.bounds.width,0,1);
 164                         // translates the  relative mouse position in pixels to a value between 0 and 1
 165
 166                         if (newVal != value) {this.valueAction_(newVal)}; // only do something if the value changed
 167                 };
 168
 169         }
 170
 171         // (7) define default key actions
 172         // make sure to return "this", if successful, and nil if not successful
 173         defaultKeyDownAction { arg char, modifiers, unicode,keycode;
 174                 if (unicode == 16rF700, { this.increment; ^this });
 175                 if (unicode == 16rF703, { this.increment; ^this });
 176                 if (unicode == 16rF701, { this.decrement; ^this });
 177                 if (unicode == 16rF702, { this.decrement; ^this });
 178
 179                 ^nil            // bubble if it's an invalid key
 180         }
 181
 182         // (8) define drag and drop
 183         defaultGetDrag {^value} // what to drag
 184         defaultCanReceiveDrag  {^currentDrag.isNumber} // when to receive
 185         defaultReceiveDrag { this.valueAction = currentDrag;} // what to do on receiving
 186 }
 187 ::
 188
 189 Try this after you have added the class to the class library:
 190
 191 code::
 192 (
 193         GUI.cocoa;
 194         w=Window.new.front;
 195         v=MyWidget(w, Rect(10,20,200,20)).valueAction_(0.5);
 196         q=MyWidget(w, Rect(10,60,200,20)).valueAction_(0.3);
 197 )
 198 ::