New py5 Release: 0.8.0a0

Event Classes

There are new Py5KeyboardEvent and Py5MouseEvent classes. These can be passed to user defined event functions such as mouse_clicked() or 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:

• key_pressed() or key_pressed(e: py5.Py5KeyEvent)

• key_typed() or key_typed(e: py5.Py5KeyEvent)

• key_released() or key_released(e: py5.Py5KeyEvent)

• mouse_clicked() or mouse_clicked(e: py5.Py5MouseEvent)

• mouse_dragged() or mouse_dragged(e: py5.Py5MouseEvent)

• mouse_moved() or mouse_moved(e: py5.Py5MouseEvent)

• mouse_entered() or mouse_entered(e: py5.Py5MouseEvent)

• mouse_exited() or mouse_exited(e: py5.Py5MouseEvent)

• mouse_pressed() or mouse_pressed(e: py5.Py5MouseEvent)

• mouse_released() or mouse_released(e: py5.Py5MouseEvent)

• mouse_wheel() or mouse_wheel(e: py5.Py5MouseEvent)

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 setup() and 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:

py5_tools.sketch_portal()

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.

This feature works because the widget uses JavaScript callbacks to send event information to the Jupyter Kernel. This in turn is used to create simulated keyboard and mouse events for the py5 Sketch to react to. Although every effort has been made to get the simulated events to match the real native events, I was not able to test on all permutations of operating systems, browsers, and py5 renderers (Java AWT vs OpenGL). There are a few edge cases that keep it from being exactly the same. Keep in mind that native Processing events and therefore native py5 events already differ slightly across operating systems, so any differences here should be in line with the differences users already deal with.

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:

pip install py5jupyter

Next, remove the py5 & py5bot kernels if they have been installed.

jupyter kernelspec remove py5
jupyter kernelspec remove py5bot

You can always show the installed kernels with the list command:

jupyter kernelspec list

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:

pip install py5[jupyter]

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.