fix examples, point out error message, and expand on that initbang only gets sent in abstractions i.e. embedded patches

svn path=/trunk/; revision=16801

3 files changed, 78 insertions, 62 deletions

diff --git a/doc/pddp/initbang-help-ex1-loadbang.pd b/doc/pddp/initbang-help-ex1-loadbang.pd
index a8b251c6..b7434d22 100644
--- a/doc/pddp/initbang-help-ex1-loadbang.pd
+++ b/doc/pddp/initbang-help-ex1-loadbang.pd
@@ -1,18 +1,26 @@
-#N canvas 104 284 428 300 10;

-#X obj 0 0 cnv 15 425 20 empty \$0-pddp.cnv.subheading empty 3 12 0

-14 -204280 -1 0;

-#X text 7 1 [initbang] Abstraction Example No 1;

-#X msg 157 203 obj 20 50 outlet;

-#X obj 157 226 s pd-initbang-help-ex1-loadbang.pd;

-#X obj 157 180 loadbang;

-#X text 67 48 This abstraction uses [loadbang] below to create the

-[outlet] seen at left. The [loadbang] object only gets triggered after

-all objects and connections in the parent patch have been created.

-;

-#X text 67 98 This poses a problem if you want to save the patch with

-a connection from this abstraction's outlet in the parent patch to

-the [print from_loadbang] object below it. The next time you open the

-patch \, Pd will attempt to connect those objects BEFORE the [outlet]

-gets created \, and you will get an error.;

-#X connect 2 0 3 0;

-#X connect 4 0 2 0;

+#N canvas 735 240 543 348 10;
+#X obj 10 10 cnv 15 425 20 empty \$0-pddp.cnv.subheading empty 3 12
+0 14 -204280 -1 0;
+#X text 17 11 [initbang] Abstraction Example No 1;
+#X msg 17 285 obj 20 50 outlet;
+#X obj 17 228 loadbang;
+#X text 91 142 This poses a problem if you want to save the patch with
+a connection from this abstraction's outlet in the parent patch to
+the [print from_loadbang] object below it. The next time you open the
+patch \, Pd will attempt to connect those objects BEFORE the [outlet]
+gets created \, and you will get an error.;
+#X obj 17 252 trigger bang bang;
+#X obj 250 308 print [initbang];
+#X text 91 72 This abstraction uses [loadbang] below to create the
+[outlet] seen at left. The [loadbang] object sends its bang after everything
+is done loading \, that means after all objects \, connections \, etc.
+in the parent patch have been created.;
+#X msg 138 265 the error above shows that loadbang creates the outlet
+too late;
+#X text 71 50 <- dynamically created [outlet];
+#X obj 17 308 send pd-initbang-help-ex1-loadbang.pd;
+#X connect 2 0 10 0;
+#X connect 3 0 5 0;
+#X connect 5 0 2 0;
+#X connect 5 1 8 0;
+#X connect 8 0 6 0;
diff --git a/doc/pddp/initbang-help-ex2-initbang.pd b/doc/pddp/initbang-help-ex2-initbang.pd
index 6fb41643..93bb2c47 100644
--- a/doc/pddp/initbang-help-ex2-initbang.pd
+++ b/doc/pddp/initbang-help-ex2-initbang.pd
@@ -1,15 +1,15 @@
-#N canvas 81 215 428 300 10;

-#X obj 0 0 cnv 15 425 20 empty \$0-pddp.cnv.subheading empty 3 12 0

-14 -204280 -1 0;

-#X text 7 1 [initbang] Abstraction Example No 2;

-#X obj 157 191 s pd-initbang-help-ex2-initbang.pd;

-#X obj 157 145 initbang;

-#X text 74 109 <- dynamically created [outlet];

-#X msg 157 168 obj 20 110 outlet;

-#X text 19 36 This abstraction just shows a simple example of how [initbang]

-works. Since [initbang] is used below (instead of [loadbang]) \, the

-outlet gets created before the parent patch initializes. This ensures

-that connections get created properly when the parent patch is opened.

-;

-#X connect 3 0 5 0;

-#X connect 5 0 2 0;

+#N canvas 87 221 428 300 10;
+#X obj 1 9 cnv 15 425 20 empty \$0-pddp.cnv.subheading empty 3 12 0
+14 -204280 -1 0;
+#X text 8 10 [initbang] Abstraction Example No 2;
+#X obj 126 166 initbang;
+#X text 64 129 <- dynamically created [outlet];
+#X text 20 45 This abstraction just shows a simple example of how [initbang]
+works. Since [initbang] is used below (instead of [loadbang]) \, the
+outlet gets created before the parent patch initializes. This ensures
+that connections get created properly when the parent patch is opened.
+;
+#X msg 126 189 obj 20 130 outlet;
+#X obj 126 212 send pd-initbang-help-ex2-initbang.pd;
+#X connect 2 0 5 0;
+#X connect 5 0 6 0;
diff --git a/doc/pddp/initbang-help.pd b/doc/pddp/initbang-help.pd
index e0a2edcf..0363308b 100644
--- a/doc/pddp/initbang-help.pd
+++ b/doc/pddp/initbang-help.pd
@@ -1,11 +1,11 @@
-#N canvas 0 0 555 619 10;
+#N canvas 19 94 556 621 10;
 #X obj 0 595 cnv 15 552 21 empty \$0-pddp.cnv.footer empty 20 12 0
 14 -228856 -66577 0;
 #X obj 0 0 cnv 15 552 40 empty \$0-pddp.cnv.header initbang 3 12 0
 18 -204280 -1 0;
-#X obj 1 412 cnv 3 550 3 empty \$0-pddp.cnv.inlets inlets 8 12 0 13
+#X obj 1 425 cnv 3 550 3 empty \$0-pddp.cnv.inlets inlets 8 12 0 13
 -228856 -1 0;
-#N canvas 50 243 494 344 META 0;
+#N canvas 51 244 494 344 META 0;
 #X text 12 95 LIBRARY internal;
 #X text 12 25 LICENSE SIBSD;
 #X text 12 135 WEBSITE;
@@ -19,50 +19,58 @@ revised the patch to conform to the PDDP template for Pd version 0.42.
 ;
 #X text 12 115 AUTHOR IOhannes m zmoelnig;
 #X restore 502 597 pd META;
-#X obj 1 439 cnv 3 550 3 empty \$0-pddp.cnv.outlets outlets 8 12 0
+#X obj 1 452 cnv 3 550 3 empty \$0-pddp.cnv.outlets outlets 8 12 0
 13 -228856 -1 0;
-#X obj 1 492 cnv 3 550 3 empty \$0-pddp.cnv.argument arguments 8 12
+#X obj 1 505 cnv 3 550 3 empty \$0-pddp.cnv.argument arguments 8 12
 0 13 -228856 -1 0;
-#X obj 1 519 cnv 3 550 3 empty \$0-pddp.cnv.more_info more_info 8 12
+#X obj 1 532 cnv 3 550 3 empty \$0-pddp.cnv.more_info more_info 8 12
 0 13 -228856 -1 0;
-#X text 100 496 (none);
-#N canvas 94 481 428 109 Related_objects 0;
+#X text 100 509 (none);
+#N canvas 95 482 428 109 Related_objects 0;
 #X obj 1 1 cnv 15 425 20 empty \$0-pddp.cnv.subheading empty 3 12 0
 14 -204280 -1 0;
 #X obj 21 42 closebang;
 #X text 7 1 [initbang] Related Objects;
+#X obj 101 42 loadbang;
 #X restore 104 597 pd Related_objects;
-#X obj 80 448 cnv 17 3 17 empty \$0-pddp.cnv.let.0 0 5 9 0 16 -228856
+#X obj 80 461 cnv 17 3 17 empty \$0-pddp.cnv.let.0 0 5 9 0 16 -228856
 -162280 0;
 #X obj 442 22 pddp/pddplink http://wiki.puredata.info/en/initbang -text
 pdpedia: initbang;
 #X obj 468 5 initbang;
-#X text 100 416 (none);
-#X text 100 447 bang;
-#X text 102 556 Pd Documentation Chapter 3.6 - doc/1.manual/x3.htm
-;
-#X obj 95 383 print from_initbang;
-#X obj 95 227 print from_loadbang;
-#X obj 95 115 initbang-help-ex1-loadbang;
-#X obj 95 349 initbang-help-ex2-initbang;
-#X text 102 523 [initbang] is useful if you want to build abstractions
+#X text 100 429 (none);
+#X text 100 460 bang;
+#X obj 95 352 print from_initbang;
+#X obj 95 207 print from_loadbang;
+#X text 102 536 [initbang] is useful if you want to build abstractions
 that have a variable number of inlets or outlets.;
-#X text 112 139 If you connect this outlet to the [print] object below
-and save the patch \, there will be a problem the next time you open
-it. Pd will try to connect the abstraction's outlet to the inlet of
-[print] \, but this will happen before [loadbang] is executed (i.e.
-\, before the outlet exists). The result will be an error \, and no
-connection will be made.;
 #X text 13 21 send "bang" automatically when abstraction starts to
 load;
-#X text 170 447 - a bang message is sent automatically when the containing
-patch is first opened as an embeded object in another patch.;
-#X obj 6 597 pddp/pddplink all_about_help_patches.pd -text Usage Guide;
-#X text 93 71 The abstraction below dynamically creates an outlet using
+#X obj 6 597 pddp/pddplink all_about_help_patches.pd -text Usage Guide
+;
+#X text 93 51 The abstraction below dynamically creates an outlet using
 [loadbang]. The [loadbang] object send a bang after this help patch
 has loaded.;
-#X text 92 261 To solve this problem \, the abstraction below uses
+#X text 92 231 To solve this problem \, the abstraction below uses
 [initbang] instead of [loadbang]. [initbang] will send a bang before
 Pd initializes the parent patch \, so that the [outlet] is created
 before the connection between objects is made. Thus \, you can see
 below that the objects are connected successfully.;
+#X text 112 118 The above outlet is supposed to be connected to [print]
+object below but [loadbang] sends its bang too late. Pd will try to
+connect the abstraction's outlet to the inlet of [print] \, but this
+will happen before [loadbang] is executed (i.e. \, before the outlet
+exists). The result is the an error in the Pd window \, and connection
+fails.;
+#X text 92 372 Careful \, [initbang] sends its bang when the patch
+is starting to load \, so things like GUI objects will not have created
+their visual elements yet.;
+#X text 102 569 Pd Documentation Chapter 3.6 -;
+#X obj 289 569 pddp/pddplink ../1.manual/x3.htm;
+#X obj 95 99 initbang-help-ex1-loadbang;
+#X obj 95 321 initbang-help-ex2-initbang;
+#X text 160 460 - a bang message is sent when the containing parent
+patch first opens the abstraction as an embedded object. If the patch
+is a top-most patch \, no bang will ever be sent.;
+#X connect 25 0 15 0;
+#X connect 26 0 14 0;