HelpSource/Classes/UserView.schelp

   1 CLASS:: UserView
   2 redirect:: implClass
   3 summary:: A custom drawn view using Pen
   4 categories:: GUI>Views
   5 related:: Classes/Pen
   6
   7 DESCRIPTION::
   8 An empty view on which you can draw using the link::Classes/Pen:: class.
   9
  10 This view displays and does nothing by itself, but allows you to define how it will be drawn, and expects you to define its entire mode of interaction using mouse, key, and drag and drop actions.
  11
  12 To define how the view is drawn you set the link::#-drawFunc:: variable to a link::Classes/Function:: within which you can use the link::Classes/Pen:: class to draw graphical primitives, such as lines, rectangles, elipses, curves, and also text.
  13
  14 This class offers convenient mechanisms for creating animations, that is, to automatically redraw itself in regular time intervals. See the link::#animation#Animation:: section of this document.
  15
  16 For a guide to using this view, see the link::Guides/GUI-Introduction.html#custom_views#Custom Views:: section of the 'Introduction to GUI'. For a tutorial on how to write a emphasis::subclass:: of UserView to make your own custom view classes, see the link::Guides/UserView-Subclassing:: guide.
  17
  18
  19
  20 CLASSMETHODS::
  21
  22 PRIVATE:: key
  23
  24
  25
  26 INSTANCEMETHODS::
  27
  28 SUBSECTION:: Drawing
  29
  30 METHOD:: drawFunc
  31
  32         Sets the Function to evalute whenever the view is asked to redraw itself. This may be, for example, due to being hidden and shown again, being resized, another view moving on top of it, or after the link::Classes/View#-refresh:: method has been called.
  33
  34         Within that Function you are allowed to use the link::Classes/Pen:: class to draw withing the bounds of the view. All the coordinates given to methods of Pen are relative to the top-left corner of the view. Usage of Pen is not allowed outside of that Function.
  35
  36         The Function will be passed this view as the argument when evaluated.
  37
  38 argument::
  39         A Function.
  40
  41
  42 METHOD:: background
  43         Sets the color used to fill the whole area occupied by the view below the drawing done in link::#-drawFunc::. You can set the background at any moment, even within the code::drawFunc::, but any drawing done in that Function will always be displayed on top of the background.
  44
  45         argument::
  46                 A Color.
  47
  48 METHOD:: drawingEnabled
  49         Whether the link::#-drawFunc:: will be called when the view is redrawing itself. Note that link::#-background:: will be painted regardless of this variable.
  50
  51         The default value is code::true::.
  52
  53         argument::
  54                 A Boolean.
  55
  56 METHOD:: clearOnRefresh
  57         Whether the view shall clear the last drawing done in link::#-drawFunc:: before being redrawn.
  58
  59         If this is code::false::, the view will continuously draw on top of all the previous drawing whenever it is redrawn, until link::#-clearDrawing:: is called.
  60
  61         The default value is code::true::.
  62
  63         note:: On OSX this functionality is only available for the version >= 10.4. ::
  64
  65         argument::
  66                 A Boolean.
  67
  68 METHOD:: clearDrawing
  69         If link::#-clearOnRefresh:: is code::false::, you can call this method to manually clear any drawing done in link::#-drawFunc:: so far.
  70
  71
  72
  73 SUBSECTION:: Animation
  74
  75 METHOD:: animate
  76         Whether the view shall redraw itself internally at a regular time interval (frame rate). See link::#-frameRate:: for the way to adjust that interval.
  77
  78         note:: This method is strong::not:: available in strong:: SwingOSC GUI ::. ::
  79
  80         The default value is code::false::.
  81
  82         argument::
  83                 A Boolean.
  84
  85 METHOD:: frameRate
  86         The interval at which the view regularily redraws itself, if link::#-animate:: is code::true::.
  87
  88         In strong:: Qt GUI :: you can change the desired frame rate by setting this variable.
  89
  90         In strong:: Cocoa GUI :: this variable is not settable. Instead, use code::thisProcess.setDeferredTaskInterval(1/fps):: to change the global interval used for animation frame rate.
  91
  92         The default frame rate is 60fps.
  93
  94         note:: Getting the value of this variable will return the average actual frame rate. If it is lower than the desired frame rate set as described above, that implies that the view tries but does not manage to redraw itself at that frame rate. The reason may typically be that the drawing defined in link::#-drawFunc:: is computationally too demanding for the system.
  95         ::
  96
  97 argument:: fps
  98         A Float defining the interval between frames of animation, in frames per second.
  99
 100 METHOD:: frame
 101
 102         The count of frames drawn while link::#-animate:: is code::true::; it will increase by 1 every time the view is redrawn.
 103
 104         If animation is stopped and started again (by setting code::animate:: to code::false:: and then code::true:: again), the frame count is restarted.
 105
 106         returns:: An Integer.
 107
 108
 109
 110 SUBSECTION:: Actions
 111
 112         The UserView by itself does not respond to any interaction by the user. You can define the modes of interaction entirely on your own using mouse and keyboard actions. See link::Guides/GUI-Introduction#actions_and_hooks:_make_that_button_do_something!#Actions and Hooks:: section of the 'Introduction to GUI' for detailed explanation.
 113
 114         Note that there is no default mode of interaction with the UserView, so link::Classes/View#-action:: will never be triggered, if you don't implement that yourself.
 115
 116 EXAMPLES::
 117
 118 'Introduction to GUI' contains an link::Guides/GUI-Introduction#custom_views#example:: with elaborate explanation on how to use UserView. Below are further examples.
 119
 120 For a tutorial on how to write a emphasis::subclass:: of UserView to make your own custom view classes, see the link::Guides/UserView-Subclassing:: guide.
 121
 122 SUBSECTION:: Basic Usage
 123
 124 Resize the window or click on the UserView to refresh the drawing:
 125
 126 code::
 127 (
 128 w=Window.new;
 129 v=UserView(w, w.view.bounds.insetBy(50,50));
 130 v.resize = 5;
 131 v.background_(Color.rand);
 132 v.drawFunc={|uview|
 133                 Pen.moveTo(0@uview.bounds.height.rand);
 134                 Pen.lineTo(uview.bounds.width@uview.bounds.height.rand);
 135                 Pen.stroke;
 136         };
 137 v.mouseDownAction={v.refresh};
 138 w.front;
 139 )
 140 ::
 141
 142 Coordinates are relative to the UserView. Try resizing the window:
 143
 144 code::
 145 (
 146 var func;
 147
 148 func = {|me|
 149         Pen.use{
 150                 10.do{
 151                         Color.red(rrand(0.0, 1), rrand(0.0, 0.5)).set;
 152                         Pen.addArc((400.exprand(2))@(100.rand), rrand(10, 100), 2pi.rand, pi);
 153                         Pen.perform([\stroke, \fill].choose);
 154                 }
 155         }
 156 };
 157
 158 w = Window.new("DrawFunc Examples").front;
 159 w.view.background_(Color.white);
 160
 161 3.do{|i|
 162         v = UserView(w, Rect(20+(i*120), 100, 100, 100))
 163                 .drawFunc_(func);
 164         v.resize=3; // the func coordinates ar valid even though the view move on resize
 165         v.background_(Color.rand);
 166 };
 167
 168 w.refresh;
 169 )
 170 ::
 171
 172 SUBSECTION:: Responding to mouse clicks and movement
 173
 174 Using the link:: Classes/View#mouse_actions#mouse actions :: you can make UserView change the way it is drawn in response to mouse interaction. The sequence of examples below will guide you through the various possibilities.
 175
 176 Clicking and moving the mouse on each of the painted squares in the following example will redraw them differently. See interpreter output for posted information that you can use in the mouse actions.
 177
 178 code::
 179 (
 180 var drawFunc, mouseDownFunc, mouseUpFunc, mouseMoveFunc, sat = 0, startX;
 181
 182 drawFunc = {|me|
 183         Pen.use{
 184                 10.do{
 185                         Color.red(rrand(0.0, 1), rrand(0.3, 0.8)).set;
 186                         Pen.addArc((400.exprand(2))@(100.rand), rrand(10, 50), 2pi.rand, pi);
 187                         Pen.perform([\stroke, \fill].choose);
 188                 }
 189         }
 190 };
 191
 192 mouseDownFunc = {|me, x, y, mod|
 193         startX = x;
 194         postf("begin path: x=% realtive mouse coordinates:%\n",startX, x@y);
 195 };
 196
 197 mouseUpFunc = {|me, x, y, mod|
 198         postf("end path: (startX-x)==% mouse coordinates:%\n",(startX-x), x@y);
 199 };
 200
 201 mouseMoveFunc = {|me, x, y, mod|
 202         sat = ((startX-x)/100);
 203         (x@y).postln;
 204         me.refresh;
 205 };
 206
 207 w = Window.new.front;
 208 w.view.background_(Color.white);
 209 3.do{|i|
 210         v = UserView(w, Rect(20+(i*120), 100, 100, 100));
 211         v.background_(Color.rand);
 212         v.drawFunc = drawFunc;
 213         v.mouseDownAction = mouseDownFunc;
 214         v.mouseUpAction = mouseUpFunc;
 215         v.mouseMoveAction = mouseMoveFunc;
 216 };
 217 w.refresh;
 218 )
 219 ::
 220
 221 The following example uses the link::#-clearOnRefresh:: option to prevent the UserView from clearing its contents when redrawn. Clicking and moving the mouse within each square will draw ever more arcs on top of each other.
 222
 223 code::
 224 (
 225 var func, views;
 226
 227 func = {|me|
 228         Pen.use{
 229                 1.do{
 230                         Color(
 231                                 rrand(0.0, 1),
 232                                 rrand(0.0,0.2),
 233                                 rrand(0.0, 0.8),
 234                                 rrand(0.4, 0.8)
 235                         ).set;
 236                         Pen.addArc((400.exprand(2))@(100.rand), rrand(10, 50), 2pi.rand, pi);
 237                         Pen.perform([\stroke, \fill].choose);
 238                 }
 239         }
 240 };
 241
 242 w = Window.new("DrawFunc Examples").front;
 243 w.view.background_(Color.white);
 244 views = {|i|
 245         v = UserView(w, Rect(20+(i*120), 100, 100, 100));
 246         v.background = Color.rand;
 247         v.drawFunc = func;
 248         v.mouseMoveAction = {|me| me.refresh };
 249         v.clearOnRefresh_(false);
 250 } ! 3;
 251 w.refresh;
 252 )
 253 ::
 254
 255 The following example uses the link::#-clearOnRefresh:: option to keep the old contents when redrawn, allowing you to draw a line which follows the mouse cursor by clicking and draging on the view.
 256
 257 It also uses the mouse position to compute the color of the line.
 258
 259 code::
 260 (
 261 var w, txt, lines, points, drawLine;
 262
 263 drawLine = { |points, bounds|
 264         var p0;
 265         points.do { |p,i|
 266                 if(i == 0){
 267                         p0 = p;
 268                 }{
 269                         Pen.moveTo(p0);
 270                         Pen.lineTo(p);
 271                         Color(
 272                                 (p.x/bounds.width).clip(0,1),
 273                                 1.0-(p.x/bounds.width).clip(0,1),
 274                                 (p.y/bounds.height).clip(0,1)
 275                         ).set;
 276                         Pen.stroke;
 277                         p0 = p;
 278                 }
 279         };
 280 };
 281
 282 w = Window("draw on me", Rect(128, 64, 340, 360));
 283
 284 v = UserView(w,w.view.bounds)
 285         .clearOnRefresh_(false)
 286         .mouseDownAction_({|v,x,y|
 287                 points = [x@y];
 288         })
 289         .mouseMoveAction_({|v,x,y|
 290                 points = points.add(x@y);
 291                 v.refresh;
 292         })
 293         .mouseUpAction_({|v,x,y|
 294                 points = points.add(x@y);
 295                 lines = lines.add(points);
 296                 points = nil;
 297                 v.refresh;
 298         })
 299         .background_(Color.white)
 300         .drawFunc_{|me|
 301                 var r = me.bounds;
 302
 303                 Pen.use {
 304                         Pen.width = 1;
 305                         Color.black.set;
 306
 307                         lines.do { |linePoints|
 308                                 drawLine.value(linePoints, r);
 309                         };
 310                         lines = nil;
 311
 312                         drawLine.value(points, r);
 313                         if( points.size > 0 ) { points = [points.last] };
 314                 };
 315         };
 316
 317 w.front;
 318 )
 319 ::
 320
 321 SUBSECTION:: Animation
 322
 323 The following is an animation with mouse interaction. Click and drag in the view to move the center of the rotating object.
 324
 325 code::
 326 (
 327 var width = 400, height = 400, mx = 0, my = 0, pt, r;
 328
 329 w = Window("animation and mouse interaction", Rect(100, 200, width, height), false);
 330
 331 u = UserView(w, Rect(0, 0, width, height));
 332 u.background = Color.black;
 333 u.animate = true; //animate this view
 334
 335 // allocate data in advance, for optimization:
 336 pt = Point();
 337 r = Rect();
 338
 339 u.drawFunc = {
 340         Pen.fillColor = Color.green;
 341         Pen.stringAtPoint(u.frameRate.asString, Point(10, 10)); // display frame rate
 342         Pen.stringAtPoint(u.frame.asString, Point(10, 30)); // display frame counter
 343         Pen.color = Color.white;
 344         pt.x=mx;
 345         pt.y=my;
 346         100.do{|i|
 347                 Pen.moveTo(pt);
 348                 pt.x = sin(u.frame*0.04.neg+i)*(5*i)+mx; //use .frame to drive animation
 349                 pt.y = cos(u.frame*0.05+i)*(5*i)+my;
 350                 r.left=pt.x;
 351                 r.top=pt.y;
 352                 r.width=i;
 353                 r.height=i;
 354                 Pen.lineTo(pt);
 355                 Pen.fillStroke;
 356                 Pen.addOval(r);
 357                 Pen.fillStroke;
 358         };
 359 };
 360 u.mouseDownAction = {|v, x, y|
 361         mx = x;
 362         my = y;
 363 };
 364 u.mouseMoveAction = u.mouseDownAction;
 365 w.front;
 366 )
 367
 368 u.animate = false; //animation can be paused and resumed
 369 u.animate = true;
 370 w.close; //stops animation
 371 ::
 372
 373 A simple ball animation:
 374
 375 code::
 376 (
 377 var width = 400, height = 400, xspeed = 3, yspeed = 2, x = width*0.5, y = height*0.5;
 378 w = Window("ball", Rect(100, 200, width, height));
 379 u = UserView(w, Rect(0, 0, width, height));
 380 u.background = Color.black;
 381 u.animate = true;
 382 u.drawFunc = {
 383         if(x<0 or:{x>width}, {xspeed = 0-xspeed});
 384         if(y<0 or:{y>height}, {yspeed = 0-yspeed});
 385         x = x+xspeed;
 386         y = y+yspeed;
 387         Pen.fillColor = Color.white;
 388         Pen.fillOval(Rect.aboutPoint(Point(x, y), 8, 8));
 389 };
 390 w.front;
 391 )
 392
 393 ( //replace the drawFunc above while running
 394 u.drawFunc = {
 395         Pen.fillColor = Color.red;
 396         Pen.fillOval(Rect(200, 200, sin(u.frame*0.031)*200, sin(u.frame*0.044)*200));
 397         Pen.fillOval(Rect(200, 200, sin(u.frame*0.052)*200, sin(u.frame*0.065)*200));
 398         Pen.fillOval(Rect(200, 200, sin(u.frame*0.073)*200, sin(u.frame*0.086)*200));
 399 }
 400 )
 401
 402 //close the window to stop
 403 w.close;
 404 ::
 405
 406 An animation that makes a good use of the link::#-clearOnRefresh:: option to keep the old contents when redrawing.
 407
 408 note:: In strong::Cocoa GUI:: this functionality is only available on Mac OS X version >= 10.4. ::
 409
 410 code::
 411 (
 412 var width = 640, height = 480, w, theta = 0, drawFunc;
 413 w = Window( "trails", Rect( 128, 64, width, height ), false );
 414 drawFunc = { arg view;
 415         var x = 20 * sin( theta ), y = 42 * cos( theta );
 416         theta = theta + 0.01;
 417         //draw a semitransparent rect filling the screen:
 418         Pen.fillColor_( Color.red( 0.2, 0.1 ));
 419         Pen.fillRect( Rect( 0, 0, width, height ));
 420         Pen.strokeColor_( Color.white );
 421         Pen.translate( width * 0.5, height * 0.5 );
 422         6.do { arg i;
 423                 Pen.rotate( theta * (1 - (i / 6)) );
 424                 Pen.scale( 0.7 + (i * 0.4), 0.4 + (i * 0.5) );
 425                 Pen.strokeOval( Rect.aboutPoint( Point( x, y ), 60, 40 ));
 426         };
 427 };
 428 x = UserView( w, Rect( 10, 10, width - 20, height - 20 ))
 429         .canFocus_( false )
 430         .drawFunc_( drawFunc )
 431         .clearOnRefresh_( false );
 432
 433 w.front;
 434 x.animate = true
 435 )
 436 ::
 437
 438 SUBSECTION:: Usage of refreshInRect(aRect)
 439
 440 note:: This functionality is only available in strong::Cocoa GUI:: ::
 441
 442 The code::refreshInRect:: method constrains the receiver's refresh area to the rectangle passed in aRect. You may use Quartz Debug's flash screen updates to see the refresh area of the view
 443
 444 code::
 445 (
 446 var userView, win, blob = Rect(0, 0, 50, 50), trackblob=false, pmouse;
 447
 448 a = SCImage.new("/Library/Desktop Pictures/Ripples Blue.jpg");
 449
 450 win = SCWindow.new("refreshInRect Test", Rect(400, 400, 600, 200), scroll:true).front;
 451 win.onClose_({ a.free; });
 452
 453 userView = SCUserView(win, Rect(10,10,2000,800))
 454         .backgroundImage_(a, 5)
 455         .drawFunc_({|me|
 456                 Color.blue.setFill;
 457                 Pen.fillRect(blob);
 458         })
 459         .mouseDownAction_({|v, x, y, mod|
 460                 pmouse = x@y;
 461                 trackblob = blob.containsPoint(pmouse);
 462         })
 463         .mouseUpAction_({|v, x, y, mod|
 464                 trackblob = false;
 465         })
 466         .mouseMoveAction_({|v, x, y, mod|
 467                 var refresh, mouse, delta;
 468                 mouse = x@y;
 469
 470                 if(trackblob, {
 471                         refresh = blob.copy;
 472                         delta = mouse-pmouse;
 473                         blob = blob.moveBy(delta.x, delta.y);
 474                         refresh = refresh.union(blob);
 475                         v.refreshInRect(refresh);
 476                 });
 477                 pmouse = mouse;
 478         });
 479
 480 blob = blob.moveBy(userView.bounds.left, userView.bounds.top);
 481 userView.bounds.postln;
 482 )
 483 ::