From f2d25060b88e2dd166667400afd897286be18660 Mon Sep 17 00:00:00 2001 From: Jim Date: Mon, 18 Mar 2024 01:04:49 -0400 Subject: [PATCH 1/2] add comment about pickling with imported mode --- py5_docs/Reference/api_en/Sketch_load_pickle.txt | 2 ++ py5_docs/Reference/api_en/Sketch_save_pickle.txt | 4 +++- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/py5_docs/Reference/api_en/Sketch_load_pickle.txt b/py5_docs/Reference/api_en/Sketch_load_pickle.txt index 01e83f9c..1477a481 100644 --- a/py5_docs/Reference/api_en/Sketch_load_pickle.txt +++ b/py5_docs/Reference/api_en/Sketch_load_pickle.txt @@ -17,6 +17,8 @@ Load a pickled Python object from a file. The path can be in the data directory, There are security risks associated with Python pickle files. A pickle file can contain malicious code, so never load a pickle file from an untrusted source. +When using py5 in [imported mode](content-py5-modes-imported-mode), pickling will not work on objects instantiated from new classes you have defined yourself on the main sketch file. This applies to py5's [](sketch_save_pickle) and `load_pickle()` methods, as well as the Python's standard library pickle module methods they depend upon. If you need to pickle objects from classes you defined, move the class definitions to a different .py file that you import as a module or import the classes from. Otherwise, you could also try using [module mode](content-py5-modes-module-mode) if you want to use pickle with your classes and keep all the sketch code in a single file. + @@ example def setup(): global mouse_x_positions, mouse_y_positions diff --git a/py5_docs/Reference/api_en/Sketch_save_pickle.txt b/py5_docs/Reference/api_en/Sketch_save_pickle.txt index 2580994c..e586f4f4 100644 --- a/py5_docs/Reference/api_en/Sketch_save_pickle.txt +++ b/py5_docs/Reference/api_en/Sketch_save_pickle.txt @@ -16,7 +16,9 @@ obj: Any - any non-py5 Python object @@ description Pickle a Python object to a file. If `filename` is not an absolute path, it will be saved relative to the current working directory ([](sketch_sketch_path)). The saved file can be reloaded with [](sketch_load_pickle). -Object "pickling" is a method for serializing objects and saving them to a file for later retrieval. The recreated objects will be clones of the original objects. Not all Python objects can be saved to a Python pickle file. This limitation prevents any py5 object from being pickled. +Object "pickling" is a technique for serializing objects and saving them to a file for later retrieval. The recreated objects will be clones of the original objects. Not all Python objects can be saved to a Python pickle file. This limitation prevents any py5 object from being pickled. + +When using py5 in [imported mode](content-py5-modes-imported-mode), pickling will not work on objects instantiated from new classes you have defined yourself on the main sketch file. This applies to py5's `save_pickle()` and [](sketch_load_pickle) methods, as well as the Python's standard library pickle module methods they depend upon. If you need to pickle objects from classes you defined, move the class definitions to a different .py file that you import as a module or import the classes from. Otherwise, you could also try using [module mode](content-py5-modes-module-mode) if you want to use pickle with your classes and keep all the sketch code in a single file. @@ example data = dict(mouse_x=[], mouse_y=[]) From c63be10140f769d887ffef26eb03e620127fc84b Mon Sep 17 00:00:00 2001 From: Jim Date: Mon, 18 Mar 2024 01:12:21 -0400 Subject: [PATCH 2/2] use anchors to py5 modes where appropriate --- .../Reference/api_en/Py5Functions_get_current_sketch.txt | 2 +- py5_docs/Reference/api_en/Py5Functions_reset_py5.txt | 2 +- py5_docs/Reference/api_en/Py5Magics_py5bot.txt | 2 +- py5_docs/Reference/api_en/Py5Tools.txt | 2 +- py5_docs/Reference/api_en/Py5Tools_animated_gif.txt | 2 +- py5_docs/Reference/api_en/Py5Tools_capture_frames.txt | 2 +- .../Reference/api_en/Py5Tools_offline_frame_processing.txt | 2 +- py5_docs/Reference/api_en/Py5Tools_save_frames.txt | 2 +- py5_docs/Reference/api_en/Py5Tools_screenshot.txt | 2 +- py5_docs/Reference/api_en/Py5Tools_sketch_portal.txt | 2 +- py5_docs/Reference/api_en/Sketch.txt | 2 +- py5_docs/Reference/api_en/Sketch_full_screen.txt | 2 +- py5_docs/Reference/api_en/Sketch_no_smooth.txt | 2 +- py5_docs/Reference/api_en/Sketch_pixel_density.txt | 2 +- py5_docs/Reference/api_en/Sketch_run_sketch.txt | 6 +++--- py5_docs/Reference/api_en/Sketch_size.txt | 2 +- py5_docs/Reference/api_en/Sketch_smooth.txt | 2 +- 17 files changed, 19 insertions(+), 19 deletions(-) diff --git a/py5_docs/Reference/api_en/Py5Functions_get_current_sketch.txt b/py5_docs/Reference/api_en/Py5Functions_get_current_sketch.txt index b0e09ceb..3c149c35 100644 --- a/py5_docs/Reference/api_en/Py5Functions_get_current_sketch.txt +++ b/py5_docs/Reference/api_en/Py5Functions_get_current_sketch.txt @@ -10,7 +10,7 @@ get_current_sketch() -> Sketch @@ description Get the py5 module's current `Sketch` instance. -When coding py5 in module mode, a Sketch instance is created on your behalf that is referenced within the py5 module itself. That Sketch is called the "current sketch." Use this method to access that Sketch instance directly. +When coding py5 in [module mode](content-py5-modes-module-mode), a Sketch instance is created on your behalf that is referenced within the py5 module itself. That Sketch is called the "current sketch." Use this method to access that Sketch instance directly. @@ example sketch = py5.get_current_sketch() diff --git a/py5_docs/Reference/api_en/Py5Functions_reset_py5.txt b/py5_docs/Reference/api_en/Py5Functions_reset_py5.txt index 82738319..07e22556 100644 --- a/py5_docs/Reference/api_en/Py5Functions_reset_py5.txt +++ b/py5_docs/Reference/api_en/Py5Functions_reset_py5.txt @@ -13,7 +13,7 @@ jclassname: str = None - canonical name of class to instantiate when using py5 i @@ description Reset the py5 module's current `Sketch` instance. -When coding py5 in module mode, a Sketch instance is created on your behalf that is referenced within the py5 module itself. That Sketch is called the "Current Sketch." If the current Sketch exits, it will be in a dead state and cannot be re-run. `reset_py5()` will discard that exited Sketch instance and replace it with a new one in the ready state. +When coding py5 in [module mode](content-py5-modes-module-mode), a Sketch instance is created on your behalf that is referenced within the py5 module itself. That Sketch is called the "Current Sketch." If the current Sketch exits, it will be in a dead state and cannot be re-run. `reset_py5()` will discard that exited Sketch instance and replace it with a new one in the ready state. If `reset_py5()` is called when the current Sketch is in the ready or running states, it will do nothing and return `False`. If `reset_py5()` is called when the current Sketch is in the dead state, `reset_py5()` will replace it and return `True`. diff --git a/py5_docs/Reference/api_en/Py5Magics_py5bot.txt b/py5_docs/Reference/api_en/Py5Magics_py5bot.txt index 7c156681..e8af82ef 100644 --- a/py5_docs/Reference/api_en/Py5Magics_py5bot.txt +++ b/py5_docs/Reference/api_en/Py5Magics_py5bot.txt @@ -18,7 +18,7 @@ This cell magic uses the same rendering mechanism as the py5bot kernel. For user This magic is similar to [](py5magics_py5draw) in that both can be used to create a static Sketch. One key difference is that `%%py5bot` requires the user to begin the code with a call to [](sketch_size), while [](py5magics_py5draw) calls [](sketch_size) for you based on the magic's arguments. -This magic supports the default renderer and the `P2D` and `P3D` renderers. Note that both of the OpenGL renderers will briefly open a window on your screen. This magic is only available when using the py5 kernel and coding in imported mode. The `P2D` and `P3D` renderers are not available when the py5 kernel is hosted on a macOS computer. +This magic supports the default renderer and the `P2D` and `P3D` renderers. Note that both of the OpenGL renderers will briefly open a window on your screen. This magic is only available when using the py5 kernel and coding in [imported mode](content-py5-modes-imported-mode). The `P2D` and `P3D` renderers are not available when the py5 kernel is hosted on a macOS computer. Code used in this cell can reference functions and variables defined in other cells because a copy of the user namespace is provided during execution. Variables and functions created in this cell will be local to only this cell because to do otherwise would be unsafe. Mutable objects in the user namespace, however, can be altered and those changes will persist elsewhere in the notebook. Be aware that using py5 objects in a different notebook cell or reusing them in another Sketch can result in nasty errors and bizzare consequences. diff --git a/py5_docs/Reference/api_en/Py5Tools.txt b/py5_docs/Reference/api_en/Py5Tools.txt index eb48c1a3..9af2135b 100644 --- a/py5_docs/Reference/api_en/Py5Tools.txt +++ b/py5_docs/Reference/api_en/Py5Tools.txt @@ -4,7 +4,7 @@ type = pseudoclass provides_description = functions @@ description -The py5 Tools are extra utility functions not directly related to creating Sketches that help faciliate the use of py5. For example, you can use these to add jar files to the Java classpath before importing py5. All of the py5 Tools are in the Python package `py5_tools`, which are installed alongside py5 but must be explicitly imported before using them. The `py5_tools` package is imported for you when coding in imported mode such as with the py5 Jupyter Notebook kernel. +The py5 Tools are extra utility functions not directly related to creating Sketches that help faciliate the use of py5. For example, you can use these to add jar files to the Java classpath before importing py5. All of the py5 Tools are in the Python package `py5_tools`, which are installed alongside py5 but must be explicitly imported before using them. The `py5_tools` package is imported for you when coding in [imported mode](content-py5-modes-imported-mode) such as with the py5 Jupyter Notebook kernel. @@ example import py5_tools diff --git a/py5_docs/Reference/api_en/Py5Tools_animated_gif.txt b/py5_docs/Reference/api_en/Py5Tools_animated_gif.txt index b03d5a9a..d07c9361 100644 --- a/py5_docs/Reference/api_en/Py5Tools_animated_gif.txt +++ b/py5_docs/Reference/api_en/Py5Tools_animated_gif.txt @@ -28,7 +28,7 @@ Bottom line, you must use either the `count` parameter or the `frame_numbers` pa By default this function will return right away and construct the animated gif in the background while the Sketch is running. The completed gif will be saved to the location specified by the `filename` parameter when it is ready. Set the `block` parameter to `True` to instruct the function to not return until the gif construction is complete. This blocking feature is not available on macOS when the Sketch is executed through an IPython kernel. If the Sketch terminates prematurely, no gif will be created. -By default the Sketch will be the currently running Sketch, as returned by [](py5functions_get_current_sketch). Use the `sketch` parameter to specify a different running Sketch, such as a Sketch created using Class mode. +By default the Sketch will be the currently running Sketch, as returned by [](py5functions_get_current_sketch). Use the `sketch` parameter to specify a different running Sketch, such as a Sketch created using [class mode](content-py5-modes-class-mode). If your Sketch has a `post_draw()` method, use the `hook_post_draw` parameter to make this function run after `post_draw()` instead of `draw()`. This is important when using Processing libraries that support `post_draw()` such as Camera3D or ColorBlindness. diff --git a/py5_docs/Reference/api_en/Py5Tools_capture_frames.txt b/py5_docs/Reference/api_en/Py5Tools_capture_frames.txt index 8546824b..1e9c8369 100644 --- a/py5_docs/Reference/api_en/Py5Tools_capture_frames.txt +++ b/py5_docs/Reference/api_en/Py5Tools_capture_frames.txt @@ -24,7 +24,7 @@ Bottom line, you must use either the `count` parameter or the `frame_numbers` pa By default this function will return right away and will capture frames in the background while the Sketch is running. The returned list of PIL Image objects (`list[PIL.Image]`) will initially be empty, and will be populated all at once when the complete set of frames has been captured. Set the `block` parameter to `True` to instruct this function to capture the frames in the foreground and to not return until the complete list of frames is ready to be returned. To get access to the captured frames as they become available, use the [](py5tools_offline_frame_processing) function instead. If the Sketch is terminated prematurely, the returned list will be empty. -By default the Sketch will be the currently running Sketch, as returned by [](py5functions_get_current_sketch). Use the `sketch` parameter to specify a different running Sketch, such as a Sketch created using Class mode. +By default the Sketch will be the currently running Sketch, as returned by [](py5functions_get_current_sketch). Use the `sketch` parameter to specify a different running Sketch, such as a Sketch created using [class mode](content-py5-modes-class-mode). If your Sketch has a `post_draw()` method, use the `hook_post_draw` parameter to make this function run after `post_draw()` instead of `draw()`. This is important when using Processing libraries that support `post_draw()` such as Camera3D or ColorBlindness. diff --git a/py5_docs/Reference/api_en/Py5Tools_offline_frame_processing.txt b/py5_docs/Reference/api_en/Py5Tools_offline_frame_processing.txt index 0a1d7e9b..fd66bb5a 100644 --- a/py5_docs/Reference/api_en/Py5Tools_offline_frame_processing.txt +++ b/py5_docs/Reference/api_en/Py5Tools_offline_frame_processing.txt @@ -33,7 +33,7 @@ By default this function will return right away and will process frames in the b By default this function will report its progress as frames are processed. If you are using a Jupyter Notebook and happen to be processing tens of thousands of frames, this might cause Jupyter to crash. To avoid that fate, set the `display_progress` parameter to `False`. -Use the `sketch` parameter to specify a different running Sketch, such as a Sketch created using Class mode. If your Sketch has a `post_draw()` method, use the `hook_post_draw` parameter to make this function run after `post_draw()` instead of `draw()`. This is important when using Processing libraries that support `post_draw()` such as Camera3D or ColorBlindness. +Use the `sketch` parameter to specify a different running Sketch, such as a Sketch created using [class mode](content-py5-modes-class-mode). If your Sketch has a `post_draw()` method, use the `hook_post_draw` parameter to make this function run after `post_draw()` instead of `draw()`. This is important when using Processing libraries that support `post_draw()` such as Camera3D or ColorBlindness. @@ example import skvideo.io diff --git a/py5_docs/Reference/api_en/Py5Tools_save_frames.txt b/py5_docs/Reference/api_en/Py5Tools_save_frames.txt index f2646ffb..3f4cf914 100644 --- a/py5_docs/Reference/api_en/Py5Tools_save_frames.txt +++ b/py5_docs/Reference/api_en/Py5Tools_save_frames.txt @@ -23,7 +23,7 @@ Save a running Sketch's frames to a directory. By default this function will return right away and save frames in the background while the Sketch is running. The frames will be saved in the directory specified by the `dirname` parameter. Set the `block` parameter to `True` to instruct the method to not return until the number of frames saved reaches the number specified by the `limit` parameter. This blocking feature is not available on macOS when the Sketch is executed through an IPython kernel. -By default the Sketch will be the currently running Sketch, as returned by [](py5functions_get_current_sketch). Use the `sketch` parameter to specify a different running Sketch, such as a Sketch created using Class mode. +By default the Sketch will be the currently running Sketch, as returned by [](py5functions_get_current_sketch). Use the `sketch` parameter to specify a different running Sketch, such as a Sketch created using [class mode](content-py5-modes-class-mode). If the `limit` parameter is used, this function will wait to return a list of the filenames. If not, it will return right away as the frames are saved in the background. It will keep doing so as long as the Sketch continues to run. diff --git a/py5_docs/Reference/api_en/Py5Tools_screenshot.txt b/py5_docs/Reference/api_en/Py5Tools_screenshot.txt index 53f858b3..cfb9485e 100644 --- a/py5_docs/Reference/api_en/Py5Tools_screenshot.txt +++ b/py5_docs/Reference/api_en/Py5Tools_screenshot.txt @@ -16,7 +16,7 @@ Take a screenshot of a running Sketch. The returned image is a `PIL.Image` object. It can be assigned to a variable or embedded in the notebook. -By default the Sketch will be the currently running Sketch, as returned by [](py5functions_get_current_sketch). Use the `sketch` parameter to specify a different running Sketch, such as a Sketch created using Class mode. +By default the Sketch will be the currently running Sketch, as returned by [](py5functions_get_current_sketch). Use the `sketch` parameter to specify a different running Sketch, such as a Sketch created using [class mode](content-py5-modes-class-mode). This function will not work on a Sketch with no `draw()` function that uses an OpenGL renderer such as `P2D` or `P3D`. Either add a token `draw()` function or switch to the default `JAVA2D` renderer. diff --git a/py5_docs/Reference/api_en/Py5Tools_sketch_portal.txt b/py5_docs/Reference/api_en/Py5Tools_sketch_portal.txt index a95325d6..0cc80a6c 100644 --- a/py5_docs/Reference/api_en/Py5Tools_sketch_portal.txt +++ b/py5_docs/Reference/api_en/Py5Tools_sketch_portal.txt @@ -21,7 +21,7 @@ Creates a portal widget to continuously stream frames from a running Sketch into **Unfortunately, the Sketch Portal feature had to be removed from py5 in release 0.10.0. Changes to Jupyter Lab and Jupyter Widgets somehow broke the code and it was too difficult to figure out why. Rather than fix the code, the Sketch Portal will be re-implemented using the Python library anywidget. This new approach will hopefully be simpler to implement and easier to maintain.** -By default the Sketch will be the currently running Sketch, as returned by [](py5functions_get_current_sketch). Use the `sketch` parameter to specify a different running Sketch, such as a Sketch created using Class mode. +By default the Sketch will be the currently running Sketch, as returned by [](py5functions_get_current_sketch). Use the `sketch` parameter to specify a different running Sketch, such as a Sketch created using [class mode](content-py5-modes-class-mode). The Sketch Portal is a custom Jupyter Widget and can handle keyboard or mouse events just like a native window. You will need to click on the portal for it to gain focus and capture keyboard events. Mouse and keyboard events will be observed by the browser and simulated events will be created for the Sketch. Every effort has been made to make the simulated events identical to real events but some small differences remain. You can also use the Jupyter-provided Widgets such as sliders and text boxes for user input. diff --git a/py5_docs/Reference/api_en/Sketch.txt b/py5_docs/Reference/api_en/Sketch.txt index c6c8eba3..28df50a4 100644 --- a/py5_docs/Reference/api_en/Sketch.txt +++ b/py5_docs/Reference/api_en/Sketch.txt @@ -26,6 +26,6 @@ The core functions to be implemented by the py5 coder are `setup` and `draw`. Th * `post_draw` * `pre_draw` -When coding in class mode, all of the above functions should be instance methods. When coding in module mode or imported mode, the above functions should be stand-alone functions available in the local namespace in which [](sketch_run_sketch) was called. +When coding in [class mode](content-py5-modes-class-mode), all of the above functions should be instance methods. When coding in [module mode](content-py5-modes-module-mode) or [imported mode](content-py5-modes-imported-mode), the above functions should be stand-alone functions available in the local namespace in which [](sketch_run_sketch) was called. For more information, look at the online ["User Functions"](/content/user_functions) documentation. diff --git a/py5_docs/Reference/api_en/Sketch_full_screen.txt b/py5_docs/Reference/api_en/Sketch_full_screen.txt index 84d9bd96..114a2ee5 100644 --- a/py5_docs/Reference/api_en/Sketch_full_screen.txt +++ b/py5_docs/Reference/api_en/Sketch_full_screen.txt @@ -19,7 +19,7 @@ renderer: str - the renderer to use, e.g. P2D, P3D, JAVA2D (default) @@ description Open a Sketch using the full size of the computer's display. This is intended to be called from the `settings()` function. The [](sketch_size) and `full_screen()` functions cannot both be used in the same program. -When programming in module mode and imported mode, py5 will allow calls to `full_screen()` from the `setup()` function if it is called at the beginning of `setup()`. This allows the user to omit the `settings()` function, much like what can be done while programming in the Processing IDE. Py5 does this by inspecting the `setup()` function and attempting to split it into synthetic `settings()` and `setup()` functions if both were not created by the user and the real `setup()` function contains a call to `full_screen()`, or calls to [](sketch_size), [](sketch_smooth), [](sketch_no_smooth), or [](sketch_pixel_density). Calls to those functions must be at the very beginning of `setup()`, before any other Python code (but comments are ok). This feature is not available when programming in class mode. +When programming in [module mode](content-py5-modes-module-mode) and [imported mode](content-py5-modes-imported-mode), py5 will allow calls to `full_screen()` from the `setup()` function if it is called at the beginning of `setup()`. This allows the user to omit the `settings()` function, much like what can be done while programming in the Processing IDE. Py5 does this by inspecting the `setup()` function and attempting to split it into synthetic `settings()` and `setup()` functions if both were not created by the user and the real `setup()` function contains a call to `full_screen()`, or calls to [](sketch_size), [](sketch_smooth), [](sketch_no_smooth), or [](sketch_pixel_density). Calls to those functions must be at the very beginning of `setup()`, before any other Python code (but comments are ok). This feature is not available when programming in [class mode](content-py5-modes-class-mode). When `full_screen()` is used without a parameter on a computer with multiple monitors, it will (probably) draw the Sketch to the primary display. When it is used with a single parameter, this number defines the screen to display to program on (e.g. 1, 2, 3...). When used with two parameters, the first defines the renderer to use (e.g. P2D) and the second defines the screen. The `SPAN` parameter can be used in place of a screen number to draw the Sketch as a full-screen window across all of the attached displays if there are more than one. diff --git a/py5_docs/Reference/api_en/Sketch_no_smooth.txt b/py5_docs/Reference/api_en/Sketch_no_smooth.txt index 2f3f04ce..7f5bf64e 100644 --- a/py5_docs/Reference/api_en/Sketch_no_smooth.txt +++ b/py5_docs/Reference/api_en/Sketch_no_smooth.txt @@ -14,7 +14,7 @@ Draws all geometry and fonts with jagged (aliased) edges and images with hard ed The `no_smooth()` function can only be called once within a Sketch. It is intended to be called from the `settings()` function. The [](sketch_smooth) function follows the same rules. -When programming in module mode and imported mode, py5 will allow calls to `no_smooth()` from the `setup()` function if it is called at the beginning of `setup()`. This allows the user to omit the `settings()` function, much like what can be done while programming in the Processing IDE. Py5 does this by inspecting the `setup()` function and attempting to split it into synthetic `settings()` and `setup()` functions if both were not created by the user and the real `setup()` function contains a call to `no_smooth()`, or calls to [](sketch_size), [](sketch_full_screen), [](sketch_smooth), or [](sketch_pixel_density). Calls to those functions must be at the very beginning of `setup()`, before any other Python code (but comments are ok). This feature is not available when programming in class mode. +When programming in [module mode](content-py5-modes-module-mode) and [imported mode](content-py5-modes-imported-mode), py5 will allow calls to `no_smooth()` from the `setup()` function if it is called at the beginning of `setup()`. This allows the user to omit the `settings()` function, much like what can be done while programming in the Processing IDE. Py5 does this by inspecting the `setup()` function and attempting to split it into synthetic `settings()` and `setup()` functions if both were not created by the user and the real `setup()` function contains a call to `no_smooth()`, or calls to [](sketch_size), [](sketch_full_screen), [](sketch_smooth), or [](sketch_pixel_density). Calls to those functions must be at the very beginning of `setup()`, before any other Python code (but comments are ok). This feature is not available when programming in [class mode](content-py5-modes-class-mode). @@ example def setup(): diff --git a/py5_docs/Reference/api_en/Sketch_pixel_density.txt b/py5_docs/Reference/api_en/Sketch_pixel_density.txt index 3c080d04..07122e6c 100644 --- a/py5_docs/Reference/api_en/Sketch_pixel_density.txt +++ b/py5_docs/Reference/api_en/Sketch_pixel_density.txt @@ -15,7 +15,7 @@ density: int - 1 or 2 @@ description This function makes it possible for py5 to render using all of the pixels on high resolutions screens like Apple Retina displays and Windows High-DPI displays. This function can only be run once within a program. It is intended to be called from the `settings()` function. -When programming in module mode and imported mode, py5 will allow calls to `pixel_density()` from the `setup()` function if it is called at the beginning of `setup()`. This allows the user to omit the `settings()` function, much like what can be done while programming in the Processing IDE. Py5 does this by inspecting the `setup()` function and attempting to split it into synthetic `settings()` and `setup()` functions if both were not created by the user and the real `setup()` function contains a call to `pixel_density()`, or calls to [](sketch_size), [](sketch_full_screen), [](sketch_smooth), or [](sketch_no_smooth). Calls to those functions must be at the very beginning of `setup()`, before any other Python code (but comments are ok). This feature is not available when programming in class mode. +When programming in [module mode](content-py5-modes-module-mode) and [imported mode](content-py5-modes-imported-mode), py5 will allow calls to `pixel_density()` from the `setup()` function if it is called at the beginning of `setup()`. This allows the user to omit the `settings()` function, much like what can be done while programming in the Processing IDE. Py5 does this by inspecting the `setup()` function and attempting to split it into synthetic `settings()` and `setup()` functions if both were not created by the user and the real `setup()` function contains a call to `pixel_density()`, or calls to [](sketch_size), [](sketch_full_screen), [](sketch_smooth), or [](sketch_no_smooth). Calls to those functions must be at the very beginning of `setup()`, before any other Python code (but comments are ok). This feature is not available when programming in [class mode](content-py5-modes-class-mode). The `pixel_density()` should only be used with hardcoded numbers (in almost all cases this number will be 2) or in combination with [](sketch_display_density) as in the second example. diff --git a/py5_docs/Reference/api_en/Sketch_run_sketch.txt b/py5_docs/Reference/api_en/Sketch_run_sketch.txt index 4021154d..8bb04aea 100644 --- a/py5_docs/Reference/api_en/Sketch_run_sketch.txt +++ b/py5_docs/Reference/api_en/Sketch_run_sketch.txt @@ -12,7 +12,7 @@ block: bool = None - method returns immediately (False) or blocks until Sketch e jclassname: str = None - canonical name of class to instantiate when using py5 in processing mode py5_options: list[str] = None - command line arguments to pass to Processing as arguments sketch_args: list[str] = None - command line arguments that become Sketch arguments -sketch_functions: dict[str, Callable] = None - sketch methods when using module mode +sketch_functions: dict[str, Callable] = None - sketch methods when using [module mode](content-py5-modes-module-mode) @@ description Run the Sketch. Code in the `settings()`, `setup()`, and `draw()` functions will be used to actualize your Sketch. @@ -21,9 +21,9 @@ Use the `block` parameter to specify if the call to `run_sketch()` should return A list of strings passed to `py5_options` will be passed to the Processing PApplet class as arguments to specify characteristics such as the window's location on the screen. A list of strings passed to `sketch_args` will be available to a running Sketch using [](sketch_pargs). See the third example for an example of how this can be used. -When calling `run_sketch()` in module mode, py5 will by default search for functions such as `setup()`, `draw()`, etc. in the caller's stack frame and use those in the Sketch. If for some reason that is not what you want or does not work because you are hacking py5 to do something unusual, you can use the `sketch_functions` parameter to pass a dictionary of the desired callable functions. The `sketch_functions` parameter is not available when coding py5 in class mode. Don't forget you can always replace the `draw()` function in a running Sketch using [](sketch_hot_reload_draw). +When calling `run_sketch()` in [module mode](content-py5-modes-module-mode), py5 will by default search for functions such as `setup()`, `draw()`, etc. in the caller's stack frame and use those in the Sketch. If for some reason that is not what you want or does not work because you are hacking py5 to do something unusual, you can use the `sketch_functions` parameter to pass a dictionary of the desired callable functions. The `sketch_functions` parameter is not available when coding py5 in [class mode](content-py5-modes-class-mode). Don't forget you can always replace the `draw()` function in a running Sketch using [](sketch_hot_reload_draw). -When programming in module mode and imported mode, py5 will inspect the `setup()` function and will attempt to split it into synthetic `settings()` and `setup()` functions if both were not created by the user and the real `setup()` function contains calls to [](sketch_size), [](sketch_full_screen), [](sketch_smooth), [](sketch_no_smooth), or [](sketch_pixel_density). Calls to those functions must be at the very beginning of `setup()`, before any other Python code (except for comments). This feature allows the user to omit the `settings()` function, much like what can be done while programming in the Processing IDE. This feature is not available when programming in class mode. +When programming in [module mode](content-py5-modes-module-mode) and [imported mode](content-py5-modes-imported-mode), py5 will inspect the `setup()` function and will attempt to split it into synthetic `settings()` and `setup()` functions if both were not created by the user and the real `setup()` function contains calls to [](sketch_size), [](sketch_full_screen), [](sketch_smooth), [](sketch_no_smooth), or [](sketch_pixel_density). Calls to those functions must be at the very beginning of `setup()`, before any other Python code (except for comments). This feature allows the user to omit the `settings()` function, much like what can be done while programming in the Processing IDE. This feature is not available when programming in [class mode](content-py5-modes-class-mode). When running a Sketch asynchronously through Jupyter Notebook, any `print` statements using Python's builtin function will always appear in the output of the currently active cell. This will rarely be desirable, as the active cell will keep changing as the user executes code elsewhere in the notebook. As an alternative, use py5's [](sketch_println) method, which will place all text in the output of the cell that made the `run_sketch()` call. This will continue to be true if the user moves on to execute code in other Notebook cells. Use [](sketch_set_println_stream) to customize this behavior. All py5 error messages and stack traces are routed through the [](sketch_println) method. Be aware that some error messages and warnings generated inside the Processing Jars cannot be controlled in the same way, and may appear in the output of the active cell or mixed in with the Jupyter Kernel logs. diff --git a/py5_docs/Reference/api_en/Sketch_size.txt b/py5_docs/Reference/api_en/Sketch_size.txt index fc13463a..88c83a9a 100644 --- a/py5_docs/Reference/api_en/Sketch_size.txt +++ b/py5_docs/Reference/api_en/Sketch_size.txt @@ -20,7 +20,7 @@ width: int - width of the display window in units of pixels @@ description Defines the dimension of the display window width and height in units of pixels. This is intended to be called from the `settings()` function. -When programming in module mode and imported mode, py5 will allow calls to `size()` from the `setup()` function if it is called at the beginning of `setup()`. This allows the user to omit the `settings()` function, much like what can be done while programming in the Processing IDE. Py5 does this by inspecting the `setup()` function and attempting to split it into synthetic `settings()` and `setup()` functions if both were not created by the user and the real `setup()` function contains a call to `size()`, or calls to [](sketch_full_screen), [](sketch_smooth), [](sketch_no_smooth), or [](sketch_pixel_density). Calls to those functions must be at the very beginning of `setup()`, before any other Python code (but comments are ok). This feature is not available when programming in class mode. +When programming in [module mode](content-py5-modes-module-mode) and [imported mode](content-py5-modes-imported-mode), py5 will allow calls to `size()` from the `setup()` function if it is called at the beginning of `setup()`. This allows the user to omit the `settings()` function, much like what can be done while programming in the Processing IDE. Py5 does this by inspecting the `setup()` function and attempting to split it into synthetic `settings()` and `setup()` functions if both were not created by the user and the real `setup()` function contains a call to `size()`, or calls to [](sketch_full_screen), [](sketch_smooth), [](sketch_no_smooth), or [](sketch_pixel_density). Calls to those functions must be at the very beginning of `setup()`, before any other Python code (but comments are ok). This feature is not available when programming in [class mode](content-py5-modes-class-mode). The built-in variables [](sketch_width) and [](sketch_height) are set by the parameters passed to this function. For example, running `size(640, 480)` will assign 640 to the [](sketch_width) variable and 480 to the height `variable`. If `size()` is not used, the window will be given a default size of 100 x 100 pixels. diff --git a/py5_docs/Reference/api_en/Sketch_smooth.txt b/py5_docs/Reference/api_en/Sketch_smooth.txt index f160f195..0bbaf0ed 100644 --- a/py5_docs/Reference/api_en/Sketch_smooth.txt +++ b/py5_docs/Reference/api_en/Sketch_smooth.txt @@ -22,7 +22,7 @@ The default renderer uses `smooth(3)` by default. This is bicubic smoothing. The The `smooth()` function can only be set once within a Sketch. It is intended to be called from the `settings()` function. The [](sketch_no_smooth) function follows the same rules. -When programming in module mode and imported mode, py5 will allow calls to `smooth()` from the `setup()` function if it is called at the beginning of `setup()`. This allows the user to omit the `settings()` function, much like what can be done while programming in the Processing IDE. Py5 does this by inspecting the `setup()` function and attempting to split it into synthetic `settings()` and `setup()` functions if both were not created by the user and the real `setup()` function contains a call to `smooth()`, or calls to [](sketch_size), [](sketch_full_screen), [](sketch_no_smooth), or [](sketch_pixel_density). Calls to those functions must be at the very beginning of `setup()`, before any other Python code (but comments are ok). This feature is not available when programming in class mode. +When programming in [module mode](content-py5-modes-module-mode) and [imported mode](content-py5-modes-imported-mode), py5 will allow calls to `smooth()` from the `setup()` function if it is called at the beginning of `setup()`. This allows the user to omit the `settings()` function, much like what can be done while programming in the Processing IDE. Py5 does this by inspecting the `setup()` function and attempting to split it into synthetic `settings()` and `setup()` functions if both were not created by the user and the real `setup()` function contains a call to `smooth()`, or calls to [](sketch_size), [](sketch_full_screen), [](sketch_no_smooth), or [](sketch_pixel_density). Calls to those functions must be at the very beginning of `setup()`, before any other Python code (but comments are ok). This feature is not available when programming in [class mode](content-py5-modes-class-mode). @@ example def setup():