new Snap! API: programmatically broadcast messages and optionally wait from outside Snap!

HISTORY.md

@@ -5,6 +5,7 @@
     * log pen vectors
     * export pen trails as SVG
     * access pen trails as SVG_Costume: new "pen vectors" reporter variant of "pen trails"
+    * new Snap! API: programmatically broadcast messages and optionally wait from outside Snap!
 * **Notable Changes:**
     * when creating a costume from pen trails (raster or vector) make its rotation center the position of the sprite
 * **Notable Fixes:**
@@ -13,6 +14,9 @@
     * NEW Slovak translation, thanks, Peter Lukacovic
     * German
 
+### 2019-12-15
+* gui, threads:  new Snap! API: programmatically broadcast messages and optionally wait from outside Snap!
+
 ### 2019-12-13
 * added direct relabelling option to pen trails blocks' context menus
 

snap.html

@@ -7,9 +7,9 @@
         <script type="text/javascript" src="src/morphic.js?version=2019-11-12"></script>
         <script type="text/javascript" src="src/widgets.js?version=2019-10-16"></script>
         <script type="text/javascript" src="src/blocks.js?version=2019-12-13"></script>
-        <script type="text/javascript" src="src/threads.js?version=2019-12-05"></script>
+        <script type="text/javascript" src="src/threads.js?version=2019-12-15"></script>
         <script type="text/javascript" src="src/objects.js?version=2019-12-13"></script>
-        <script type="text/javascript" src="src/gui.js?version=2019-12-07"></script>
+        <script type="text/javascript" src="src/gui.js?version=2019-12-15"></script>
         <script type="text/javascript" src="src/paint.js?version=2019-06-27"></script>
         <script type="text/javascript" src="src/lists.js?version=2019-12-08"></script>
         <script type="text/javascript" src="src/byob.js?version=2019-07-12"></script>

src/gui.js

@@ -68,8 +68,8 @@ ToggleButtonMorph, contains, ScrollFrameMorph, StageMorph, PushButtonMorph, sb,
 InputFieldMorph, FrameMorph, Process, nop, SnapSerializer, ListMorph, detect,
 AlignmentMorph, TabMorph, Costume, MorphicPreferences, Sound, BlockMorph,
 ToggleMorph, InputSlotDialogMorph, ScriptsMorph, isNil, SymbolMorph, fontHeight,
-BlockExportDialogMorph, BlockImportDialogMorph, SnapTranslator, localize,
+BlockExportDialogMorph, BlockImportDialogMorph, SnapTranslator, localize, List,
-List, ArgMorph, Uint8Array, HandleMorph, SVG_Costume, TableDialogMorph,
+ArgMorph, Uint8Array, HandleMorph, SVG_Costume, TableDialogMorph, isString,
 CommentMorph, CommandBlockMorph, BooleanSlotMorph, RingReporterSlotMorph,
 BlockLabelPlaceHolderMorph, Audio, SpeechBubbleMorph, ScriptFocusMorph,
 XML_Element, WatcherMorph, BlockRemovalDialogMorph, saveAs, TableMorph,
@@ -79,7 +79,7 @@ BlockEditorMorph, BlockDialogMorph*/
 
 // Global stuff ////////////////////////////////////////////////////////
 
-modules.gui = '2019-December-07';
+modules.gui = '2019-December-15';
 
 // Declarations
 
@@ -6058,6 +6058,50 @@ IDE_Morph.prototype.isIE = function () {
     return ua.indexOf("MSIE ") > -1 || ua.indexOf("Trident/") > -1;
 };
 
+// IDE_Morph external communication API - experimental
+/*
+    programmatically trigger scripts from outside of Snap!
+*/
+
+IDE_Morph.prototype.broadcast = function(message, callback) {
+    // same as using the broadcast block - launch all scripts
+    // in the current project reacting to the specified message,
+    // if a callback is supplied wait for all processes to terminate
+    // then call the callback, same as using the "broadcast and wait" block
+
+    var rcvrs = this.stage.children.concat(this.stage),
+        myself = this,
+        procs = [];
+
+    function wait() {
+        if (procs.some(function (any) {return any.isRunning(); })) {
+            return;
+        }
+        if (callback instanceof Function) {
+            myself.onNextStep = function () {
+                callback();
+                callback = null;
+            };
+        }
+    }
+
+    if (!isString(message)) {
+        throw new Error('message must be a String');
+    }
+    this.stage.lastMessage = message;
+    rcvrs.forEach(function (sprite) {
+        sprite.allHatBlocksFor(message).forEach(function (block) {
+            procs.push(myself.stage.threads.startProcess(
+                block,
+                sprite,
+                myself.stage.isThreadSafe,
+                false,
+                callback instanceof Function ? wait : null
+            ));
+        });
+    });
+};
+
 // ProjectDialogMorph ////////////////////////////////////////////////////
 
 // ProjectDialogMorph inherits from DialogBoxMorph:

src/threads.js

@@ -61,7 +61,7 @@ StageMorph, SpriteMorph, StagePrompterMorph, Note, modules, isString, copy,
 isNil, WatcherMorph, List, ListWatcherMorph, alert, console, TableMorph, Color,
 TableFrameMorph, ColorSlotMorph, isSnapObject, newCanvas, Symbol, SVG_Costume*/
 
-modules.threads = '2019-December-05';
+modules.threads = '2019-December-15';
 
 var ThreadManager;
 var Process;
@@ -398,6 +398,8 @@ ThreadManager.prototype.removeTerminatedProcesses = function () {
                         );
                     }
                 }
+            } else if (proc.onComplete instanceof Function) {
+                proc.onComplete();
             }
         } else {
             remaining.push(proc);