This is a major release with some significant changes! I am very excited for the progress that has been made since the last release.
There are new Py5KeyboardEvent and Py5MouseEvent classes. These can be passed to user defined event functions such as
key_pressed(). Below is a simple example.
def setup(): py5.size(500, 500) def draw(): py5.rect(py5.mouse_x, py5.mouse_y, 10, 10) def mouse_clicked(e: py5.Py5MouseEvent): py5.println('mouse clicked', e.get_millis(), e.get_button(), e.get_modifiers(), e.get_count()) def key_pressed(e: py5.Py5KeyEvent): py5.println('key pressed', e.get_millis(), e.get_key(), e.get_modifiers()) def mouse_enter(): py5.println('mouse entered')
Observe that in this example,
mouse_enter() does not receive an instance of
Py5MouseEvent because it was defined with zero parameters. If the function had been written to accept 1 parameter, it would be passed the instance of
Py5MouseEvent that triggered
mouse_enter(). The parameter is optional. The parameter is optional for all of the user defined keyboard and mouse event functions. Therefore, all of the below signatures are valid:
The type hints are of course optional, and are included here for clarity. Also, the parameter name can be anything you like.
All of this works because py5 will examine each user defined event function (using inspect) to determine how many parameters the function expects. Event functions that require too many parameters (two or more) will be ignored, based on the assumption that they exist for some other purpose than to be called by the py5 Sketch. Similarly, the standard user functions such as
draw() should always take zero parameters and will be ignored if they are defined with more.
Interactive Sketch Portal
The second major change, which required the previously described event class functionality, is that py5 now provides an interactive Jupyter widget that responds to mouse and keyboard events. This is a huge accomplishment and is a feature that has been a user request since I started integrating py5 into Jupyter.
Before continuing, I want to thank Martin Renou for the wonderful Python library ipycanvas. It is because of ipycanvas that I knew that this new py5 feature was possible. I studied the ipycanvas source code to help me understand how a Jupyter widget like this could work, and I referred back to the source code many times as I grappled with various browser bugs. There's also about a dozen lines of typescript code in py5jupyter (more on that in a moment) that were copied from ipycanvas. Bottom line, this py5 feature wouldn't exist had it not been for ipycanvas and an open source community that I can be inspired by and learn from.
Use of the Interactive Sketch Portal is the same as before. When the Sketch is running through a Jupyter Notebook, call
py5_tools.sketch_portal(), like so:
The Sketch portal will appear in the Jupyter Notebook cell's output. You'll need to click on the portal for it to gain focus and start receiving keyboard events.
The Sketch portal can be configured with various parameters; see the documentation for more information.
New py5jupyter Package
The Jupyter-related functionality, including the py5 & py5bot kernels and the Sketch Portal widget, have been split off into a second optional Python library called py5jupyter. Use of py5's Jupyter features without py5jupyter installed is now deprecated and will be removed from py5 shortly.
Existing py5 users will have a few simple tasks to complete. First, install py5jupyter:
Next, remove the py5 & py5bot kernels if they have been installed.
You can always show the installed kernels with the list command:
Finally, reinstall the kernels:
python -m py5jupyter.kernels.py5.install --sys-prefix python -m py5jupyter.kernels.py5bot.install --sys-prefix
New users will start by installing py5 and the optional dependency, like this:
Then install the kernels as above.
Upgrade to Processing 4.0b8
The Processing jars that support py5 have been upgraded to Processing 4.0b8, which works on Apple Silicon (macOS-aarch64) machines. Maybe this release of py5 will also work on Apple Silicon machines? I can't test it myself because I don't have access to such a machine, but I am cautiously optimistic that it will work without me having to do anything. If it doesn't, don't despair: I have a plan to get my hands on an Apple Silicon machine in June. I'll be able to debug and fix any remaining Apple hardware issues then. I'll also do a release shortly after any fixes are made.
New Github Organization
I've created a new organization on Github for py5 called py5coding and invited @villares and @tabreturn to join. All of py5's repositories are now owned by py5coding and not my personal Github account hx2A.
This might be the release that finally works on Apple Silicon (macOS-aarch64) machines. Please test and provide feedback.
Unit tests? I can't keep pushing this off.
More documentation and tutorials.