Fix #549

py5_docs/Reference/api_en/Sketch_intercept_escape.txt

@@ -0,0 +1,33 @@
+@@ meta
+name = intercept_escape()
+type = method
+pclass = Sketch
+category = structure
+subcategory = None
+
+@@ signatures
+intercept_escape() -> None
+
+@@ description
+Prevent the Escape key from causing the Sketch to exit. Normally hitting the Escape key (`ESC`) will cause the Sketch to exit. In Processing, one can write code to change the Escape key's behavior by changing the [](sketch_key) value to something else, perhaps with code similar to `py5.key = 'x'`. That code won't work in py5 because py5 does not allow the user to alter the value of [](sketch_key) like Processing does. The `intercept_escape()` method was created to allow users to achieve the same goal of preventing the Escape key from causing the Sketch to exit.
+
+The `intercept_escape()` method will only do something when [](sketch_key) already equals `ESC`. This function should only be called from the user event functions `key_pressed()`, `key_typed()`, and `key_released()`.
+
+This method will not alter the value of [](sketch_key). This method cannot prevent a Sketch from exiting when the exit is triggered by any other means, such as a call to [](sketch_exit_sketch) or the user closes the window.
+
+@@ example
+def setup():
+    py5.size(200, 200)
+
+def draw():
+    py5.rect(py5.mouse_x, py5.mouse_y, 10, 10)
+
+def key_pressed():
+    if py5.key == py5.ESC:
+        # this code will not work:
+        # py5.key = 'x'
+
+        py5.intercept_escape()
+
+    # verify py5.key has not changed
+    assert py5.key == py5.ESC

py5_docs/scripts/create_missing_documentation_files.py

@@ -103,7 +103,7 @@
     print(f"creating {new_docfile}")
     with open(new_docfile, "w") as f:
         extra = (
-            f"pclass = {pclass}\nprocessing_name = {java_name}  # remove if not a part of Processing\n"
+            f"pclass = {pclass}\nprocessing_name = {java_name}  # **REMOVE IF NOT A PART OF PROCESSING**\n"
             if java_name
             else ""
         )

py5_jar/src/main/java/py5/core/Sketch.java

@@ -494,6 +494,18 @@ public void fakeKeyEvent(int action, int modifiers, String input, boolean isAuto
     postEvent(new KeyEvent(null, System.currentTimeMillis(), action, modifiers, key, keyCode, isAutoRepeat));
   }
 
+  public void interceptEscape() {
+    if (key == ESC) {
+      interceptEscape = true;
+    }
+  }
+
+  @Override
+  protected void handleKeyEvent(KeyEvent event) {
+    super.handleKeyEvent(event);
+    interceptEscape = false;
+  }
+
   @Override
   public void postWindowMoved(int newX, int newY) {
     if (!sketchFullScreen()) {

py5_jar/src/main/java/py5/core/SketchBase.java

@@ -48,13 +48,15 @@ public class SketchBase extends PApplet {
   protected boolean disposeCalled;
   protected boolean inIPythonSession;
   protected boolean inJupyterZMQShell;
+  protected boolean interceptEscape;
 
   public SketchBase() {
     py5Bridge = null;
     this.py5RegisteredEvents = new HashSet<String>();
     this.py5RegisteredEventParamCounts = new HashMap<String, Integer>();
     this.exitActualCallCount = 0;
     disposeCalled = false;
+    interceptEscape = false;
   }
 
   public static void setJOGLProperties(String py5Path) {
@@ -97,10 +99,12 @@ public void py5Println(String text, boolean stderr) {
 
   @Override
   public void exit() {
-    if (platform == MACOS && g.isGL() && !isLooping()) {
-      loop();
+    if (!interceptEscape) {
+      if (platform == MACOS && g.isGL() && !isLooping()) {
+        loop();
+      }
+      super.exit();
     }
-    super.exit();
   }
 
   @Override

py5_resources/data/sketch.csv

@@ -231,6 +231,7 @@ println,println,,method,output,text_area,PYTHON,override to provide special prin
 set_println_stream,,,method,output,text_area,PYTHON,special print tools for managing print output from a running sketch
 main,main,,method,,,SKIP,public methods that shouldn't be available to users
 exit_sketch,exit,,method,structure,,JAVA,renamed because of conflict with builtin python function
+intercept_escape,interceptEscape,,method,structure,,JAVA,
 get_pixels,get,@_return_py5image,method,image,pixels,JAVA,
 method,method,,method,,,SKIP,
 append,append,,method,data,array_functions,SKIP,user should use python instead