added optional color-csv parameter to flashScripts() api

HISTORY.md

@@ -2,6 +2,9 @@
 
 ## in development:
 
+2024-01-22
+* api: added optional color-csv parameter to flashScripts() api 
+
 2024-01-21
 * new dev version for v9.2.3
 

docs/API.md

@@ -1,6 +1,6 @@
 # The Snap! API
 
-Jens Mönig, Bernat Romagosa, July 17, 2023
+Jens Mönig, Bernat Romagosa, January 22, 2024
 
 This document describes how Snap! can be accessed from an outside program to start scripts, send and retrieve information. The model use case is embedding interactive Snap! projects in other websites such as MOOCs or other adaptive learning platforms.
 
@@ -401,15 +401,17 @@ an XML String
 the flashSpriteScripts() method highlights the blocks of the scripts of the sprite indicated by name - or the current sprite or stage if none - that correspond to the portion of the text between the start- and end lines when using the current codification mapping
 
 #### syntax
-    flashSpriteScripts(fromLOC, toLOC[, spriteName]);
+    flashSpriteScripts(fromLOC, toLOC[, spriteName[, colorCSV]]);
 
 #### parameters
 * fromLOC
-    * integer representing the first line of mapped code to be signalled, starting at 1
+    * integer representing the first line of mapped code to be signaled, starting at 1
 * toLOC
-    * integer representing the last line of mapped code to be signalled
+    * integer representing the last line of mapped code to be signaled
 * spriteName
     * name of sprite or stage whose scripts to fetch, or none, in which case the currently edited object will be taken
+* colorCSV
+    * string with comma-separated integer values representing a color in the form "r,g,b[,a]", or none, in which case the default highlight color will be used
 
 #### return value
 undefined

pyret/inline.html

@@ -75,7 +75,9 @@
                     if (this.selectionStart < this.selectionEnd) {
                         ide.flashSpriteScripts(
                             ln(this.selectionStart),
-                            ln(this.selectionEnd)
+                            ln(this.selectionEnd),
+                            null, // sprite name
+                            '200,100,130' // rgb(a) color csv
                         );
                     }
                 };

snap.html

@@ -16,7 +16,7 @@
         <script src="src/morphic.js?version=2023-11-07"></script>
         <script src="src/symbols.js?version=2024-01-24"></script>
         <script src="src/widgets.js?version=2023-05-24"></script>
-        <script src="src/blocks.js?version=2023-11-24"></script>
+        <script src="src/blocks.js?version=2024-01-22"></script>
         <script src="src/threads.js?version=2024-01-15"></script>
         <script src="src/objects.js?version=2024-01-15"></script>
         <script src="src/scenes.js?version=2022-10-29"></script>
@@ -33,7 +33,7 @@
         <script src="src/store.js?version=2023-07-27"></script>
         <script src="src/locale.js?version=2024-01-19"></script>
         <script src="src/cloud.js?version=2023-04-12"></script>
-        <script src="src/api.js?version=2022-11-28"></script>
+        <script src="src/api.js?version=2024-01-22"></script>
         <script src="src/sha512.js?version=2019-06-27"></script>
         <script src="src/FileSaver.min.js?version=2019-06-27"></script>
         <script>

src/api.js

@@ -7,7 +7,7 @@
     written by Jens Mönig
     [email protected]
 
-    Copyright (C) 2023 by Jens Mönig
+    Copyright (C) 2024 by Jens Mönig
 
     This file is part of Snap!.
 
@@ -46,7 +46,7 @@ detect, isSnapObject, VariableFrame*/
 
 // Global stuff ////////////////////////////////////////////////////////
 
-modules.api = '2023-January-30';
+modules.api = '2024-January-22';
 
 // IDE_Morph external communication API
 /*
@@ -278,14 +278,17 @@ IDE_Morph.prototype.loadSpriteScriptsXML = function (scriptsXML) {
     return this.spriteNamed(name).synchScriptsFrom(scriptsXML);
 };
 
-IDE_Morph.prototype.flashSpriteScripts = function (fromLOC, toLOC, name) {
+IDE_Morph.prototype.flashSpriteScripts = function (fromLOC, toLOC, name, clr) {
     // highlight the blocks of the scripts of the sprite indicated by name or
     // the current sprite or stage if none that correspond to the portion of the
     // text between the start- and end lines when using the current codification
-    // mapping
+    // mapping.
+    // Optionally a string of comma-separated "r,g,b[a]" values can be passed
+    // in to specify a specific highlight color. Of none is supplied the default
+    // flash color is used.
     var scripts = this.spriteNamed(name).scripts;
     scripts.unflash();
-    scripts.flashLOC(fromLOC, toLOC);
+    scripts.flashLOC(fromLOC, toLOC, clr);
 };
 
 IDE_Morph.prototype.unflashSpriteScripts = function (name) {

src/blocks.js

@@ -9,7 +9,7 @@
     written by Jens Mönig
     [email protected]
 
-    Copyright (C) 2023 by Jens Mönig
+    Copyright (C) 2024 by Jens Mönig
 
     This file is part of Snap!.
 
@@ -161,7 +161,7 @@ SVG_Costume, embedMetadataPNG, ThreadManager, snapEquals*/
 
 // Global stuff ////////////////////////////////////////////////////////
 
-modules.blocks = '2023-November-24';
+modules.blocks = '2024-January-22';
 
 var SyntaxElementMorph;
 var BlockMorph;
@@ -9216,14 +9216,17 @@ ScriptsMorph.prototype.elementsAtLOC = function () {
     return loc;
 };
 
-ScriptsMorph.prototype.flashLOC = function (start, end = start) {
+ScriptsMorph.prototype.flashLOC = function (start, end = start, color = null) {
     // highlight all syntax elements located in the textual code indicated
-    // by start and end line numbers. End is optional.
+    // by start and end line numbers. End is optional, as is a color string of
+    // the form "r,g,b[,a]".
     var loc = this.elementsAtLOC(),
+        clr = color ? Color.fromString(color) : null,
+        flash = (idx) => loc[idx - 1].forEach(elem => elem.flash(clr)),
         i;
     this.unflash();
     for (i = start; i <= end; i += 1) {
-        loc[i - 1].forEach(elem => elem.flash());
+        flash(i);
     }
 };