Rework the dial example, which was overly complicated.

pdlua/tutorial/examples/dial.pd

@@ -1,40 +1,36 @@
-#N canvas 433 315 876 306 12;
+#N canvas 542 350 734 300 12;
 #X obj 40 50 dial;
 #X floatatom 40 10 5 0 0 0 - phase -, f 5;
 #X obj 200 70 tgl 15 0 empty empty empty 17 7 0 10 #fcfcfc #000000
 #000000 0 1;
 #X text 200 40 clock;
 #X obj 200 94 metro 1000;
 #X floatatom 200 152 5 0 0 0 - - -, f 5;
-#X msg 200 210 0;
-#X obj 200 180 s phase;
-#X text 400 40 random speedometer;
-#X obj 400 70 tgl 15 0 empty empty empty 17 7 0 10 #fcfcfc #000000
+#X msg 150 210 0;
+#X obj 200 260 s phase;
+#X text 350 40 random speedometer;
+#X obj 350 70 tgl 15 0 empty empty empty 17 7 0 10 #fcfcfc #000000
 #000000 0 1;
-#X floatatom 400 152 5 0 0 0 - - -, f 5;
-#X obj 400 239 line;
-#X obj 400 274 s phase;
-#X obj 400 123 expr phase = random(-100 \, 100)/300.;
-#X msg 400 210 \$1 100;
-#X obj 400 94 metro 100;
-#X obj 200 123 expr phase = phase + 1/60.;
-#X obj 200 240 t f f;
+#X floatatom 350 152 5 0 0 0 - - -, f 5;
+#X obj 350 219 line;
+#X obj 350 264 s phase;
+#X msg 350 190 \$1 100;
+#X obj 350 94 metro 100;
 #X obj 20 12 bng 15 250 50 0 empty empty empty 17 7 0 10 #fcfcfc #000000
 #000000;
 #X floatatom 40 210 5 0 0 0 - - -, f 5;
-#X obj 40 274 v phase;
-#X obj 40 238 change;
-#X obj 680 70 adc~;
-#X obj 740 70 tgl 15 0 empty empty empty 17 7 0 10 #fcfcfc #000000
+#X obj 40 264 v phase;
+#X obj 570 70 adc~;
+#X obj 630 70 tgl 15 0 empty empty empty 17 7 0 10 #fcfcfc #000000
 #000000 0 1;
-#X obj 680 274 s phase;
-#X text 680 40 dB meter;
-#X obj 680 123 env~;
-#X obj 680 99 *~ 0.5;
-#X obj 680 186 expr ($f1-50)/100;
-#X floatatom 680 152 5 0 0 0 - - -, f 5;
-#X text 700 206 0..100 dB -> -0.5..+0.5 phase, f 16;
-#X msg 740 94 \; pd dsp \$1;
+#X obj 570 264 s phase;
+#X text 570 40 dB meter;
+#X obj 570 123 env~;
+#X obj 570 99 *~ 0.5;
+#X obj 570 186 expr ($f1-50)/100;
+#X floatatom 570 152 5 0 0 0 - - -, f 5;
+#X text 590 206 0..100 dB -> -0.5..+0.5 phase, f 16;
+#X msg 630 94 \; pd dsp \$1;
 #N canvas 767 395 479 405 colors-and-size 0;
 #X text 120 70 black on white;
 #X text 120 100 white on black;
@@ -74,29 +70,28 @@ color (face), f 40;
 #X connect 22 0 9 0;
 #X restore 90 10 pd colors-and-size;
 #X text 230 10 <--- click to open;
-#X connect 0 0 19 0;
+#X obj 200 123 expr phase + 1/60.;
+#X obj 350 123 expr random(-100 \, 100)/300.;
+#X connect 0 0 16 0;
 #X connect 1 0 0 0;
 #X connect 2 0 4 0;
-#X connect 4 0 16 0;
+#X connect 4 0 30 0;
 #X connect 5 0 7 0;
-#X connect 6 0 17 0;
-#X connect 9 0 15 0;
-#X connect 10 0 14 0;
+#X connect 6 0 7 0;
+#X connect 9 0 14 0;
+#X connect 10 0 13 0;
 #X connect 11 0 12 0;
-#X connect 13 0 10 0;
-#X connect 14 0 11 0;
-#X connect 15 0 13 0;
-#X connect 16 0 5 0;
-#X connect 17 0 20 0;
-#X connect 17 1 12 0;
-#X connect 18 0 0 0;
-#X connect 19 0 21 0;
-#X connect 21 0 20 0;
-#X connect 22 0 27 0;
-#X connect 22 1 27 0;
-#X connect 23 0 31 0;
-#X connect 26 0 29 0;
-#X connect 27 0 26 0;
-#X connect 28 0 24 0;
-#X connect 29 0 28 0;
-#X connect 32 0 0 0;
+#X connect 13 0 11 0;
+#X connect 14 0 31 0;
+#X connect 15 0 0 0;
+#X connect 16 0 17 0;
+#X connect 18 0 23 0;
+#X connect 18 1 23 0;
+#X connect 19 0 27 0;
+#X connect 22 0 25 0;
+#X connect 23 0 22 0;
+#X connect 24 0 20 0;
+#X connect 25 0 24 0;
+#X connect 28 0 0 0;
+#X connect 30 0 5 0;
+#X connect 31 0 10 0;

tutorial/pd-lua-intro.md

@@ -1038,7 +1038,7 @@ end
 
 The existence of the  `paint` method tells Pd-Lua that this is a graphical object. As mentioned before, this method receives a graphics context `g` as argument. The graphics context is an internal data structure keeping track of the graphics state of the object, which is used to invoke all the graphics operations. The `set_color` method of the graphics context is used to set the color for all drawing operations; in the case of `fill` operations it fills the graphical element with the color, while in the case of `stroke` operations it draws its border. There's just one color value, so we need to set the desired fill color in case of `fill`, and the desired stroke color in case of `stroke` operations. The color values 0 and 1 we use in this example are predefined, and indicate the default background color (usually white) and default foreground color (usually black), respectively.
 
-It is possible to choose other colors by calling `g:set_color(r, g, b)` with rgb color values instead, with each r, g, b value ranging from 0 to 255 (i.e., a byte value). For instance, the color "teal" would be specified as 0, 128, 128, the color "orange" as 255, 165, 0, "black" as 0, 0, 0, "white" as 255, 255, 255, etc. It's also possible to add a fourth *alpha* a.k.a. opacity value a, which is a floating point number in the range 0-1. 0 means fully transparent, 1 fully opaque, any value in between will blend in whatever is behind the graphical element to varying degrees. The alpha values are only supported in both plugdata and purr-data (as of Pd-Lua 0.12.7), in vanilla Pd they are simply ignored at present. So in vanilla Pd all graphical objects will be opaque no matter what alpha value you specify.
+It is possible to choose other colors by calling `g:set_color(r, g, b)` with rgb color values instead, with each r, g, b value ranging from 0 to 255 (i.e., a byte value). For instance, the color "teal" would be specified as 0, 128, 128, the color "orange" as 255, 165, 0, "black" as 0, 0, 0, "white" as 255, 255, 255, etc. It's also possible to add a fourth *alpha* a.k.a. opacity value a, which is a floating point number in the range 0-1, where 0 means fully transparent, 1 fully opaque, and any value in between will blend in whatever is behind the graphical element to varying degrees. As of Pd-Lua 0.12.7, alpha values are fully supported in both plugdata and purr-data. In vanilla Pd they are simply ignored at present, so all graphical objects will be opaque no matter what alpha value you specify.
 
 Let's now take a closer look at the drawing operations themselves. We start out by filling the entire object rectangle, which is our drawing surface, with the default background color 0, using `g:fill_all()`. This operation is special in that it not only fills the entire object rectangle, but also creates a standard border rectangle around it. If you skip this, you'll get an object without border, which may be useful at times.
 
@@ -1187,7 +1187,7 @@ Now that our dial object is basically finished, let's do something interesting w
 
 ![18-graphics4](18-graphics4.png)
 
-In the patch, we store the current phase angle in the `phase` variable, so that it can be updated easily using the `expr` object by just assigning to the variable. Note that we also update the variable whenever the dial outputs a new value, so you can also drag around the hand to determine its starting phase.
+Pd lets us store the phase angle in a named variable (`v phase`) which can be recalled in an `expr` object doing the necessary calculations. The `expr` object sends the computed value to the `phase` receiver, which updates both the variable and the upper numbox, and the numbox then updates the dial. Note that we also set the variable whenever the dial outputs a new value, so you can also drag around the hand to determine the starting phase. And we added a `0` message to reset the hand to the 12 o'clock home position when needed.
 
 Here's another little example, rather useless but fun, simulating a speedometer which just randomly moves the needle left and right: