updated api documentation

API.md

@@ -1,6 +1,6 @@
 # The Snap! API
 
-Jens Mönig, Bernat Romagosa, January 07, 2021
+Jens Mönig, Bernat Romagosa, November 16, 2021
 
 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.
 
@@ -8,6 +8,17 @@ This experimental Snap! API is a set of methods for an IDE_Morph containing a Sn
 
 Currently the API consists of the following methods:
 
+#### Navigate Scenes
+
+* IDE_Morph.prototype.getScenes()
+* IDE_Morph.prototype.getCurrentScene()
+* IDE_Morph.prototype.switchTo()
+
+#### Control Processes
+
+* IDE_Morph.prototype.processes()
+* IDE_Morph.prototype.stop()
+
 #### Broadcast Messages (and optionally wait)
 
 * IDE_Morph.prototype.broadcast()
@@ -94,6 +105,60 @@ request, while `e.data.response` carries the return value of the API method call
 
 ## Interacting with the IDE
 
+### IDE_Morph.prototype.getScenes()
+The getScenes() method returns an array with the names of all scenes in the projects. The minimum number of elements is 1, since there is always at least one scene per project. The scene names are unique strings within the array. Note that the empty string ('') is a valid scene identifier.
+
+#### syntax
+    ide.getScenes();
+
+#### return value
+an Array of Strings, minimum length 1
+
+
+### IDE_Morph.prototype.getCurrentScene()
+The getCurrentScene() method returns a string representing the name of the currently active scene in the project. If the scene is unnamed and empty string is returned.
+
+#### syntax
+    ide.getCurrentScene();
+
+#### return value
+a String, can be an empty String
+
+
+### IDE_Morph.prototype.switchTo()
+The switchTo() method displays the specified scene. It suspends all processes and clones of the previously active scene and passes control to the new scene.
+
+#### syntax
+    ide.switchTo(sceneName);
+
+#### parameters
+* sceneName
+    - string, the name of the scene to be activated
+
+#### return value
+undefined
+
+
+### IDE_Morph.prototype.processes()
+The processes() method returns the number of running threads in the currently active scene. If the return value is zero the scene is idle.
+
+#### syntax
+    ide.processes();
+
+#### return value
+a Number
+
+
+### IDE_Morph.prototype.stop()
+The stop() method immediately terminates all currently running threads in the active scene and removes all temporary clones. It does not trigger a "When I am stopped" event.
+
+#### syntax
+    ide.stop();
+
+#### return value
+undefined
+
+
 ### IDE_Morph.prototype.broadcast()
 The broadcast() method triggers all scripts whose hat block listens to the specified message. An optional callback can be added to be run after all triggered scripts have terminated.
 
@@ -209,7 +274,7 @@ the loadProjectXML() method replaces the current project of the IDE with another
 #### parameters
 * projectData
     * XML string representing a serialized project
-    
+
 #### return value
 unefined
 
@@ -219,7 +284,7 @@ the unsavedChanges() method return a Boolean value indicating whether the curren
 
 #### syntax
     ide.unsavedChanges();
-    
+
 #### return value
 a Boolean
 

HISTORY.md

@@ -35,6 +35,7 @@
     * made scrollbars thinner by default and slightly transparent in flat design mode
     * blocked xhr requests to from Snap! to s.b.e
     * the "message" reporter and watcher in the control category has been deprecated and moved to dev mode for backwards compatibility
+    * updated the Snap! API and documentation with methods to navigate among scenes and control processes
     * removed old hidden "prefer smooth animations" setting (no longer used, old projects will continue to work just fine)
     * removed old hidden "virtual keyboard" setting (was no longer used for the last years)
     * removed old hidden "project urls" setting
@@ -63,6 +64,7 @@
 ### 2021-11-16
 * store, gui: updated serializer app tag to v7
 * api: removed incomplete api documentation from the source code
+* updated api documentation
 
 ### 2021-11-15
 * German translation update