Events

Canvas instances can specify event handlers — regular Python callables invoked by the IDE on certain UI events like mouse movements or key presses.

Broadly, there are two steps involved in using event handlers:

Setting the event handlers on the Canvas instance.
Monitoring for events by calling the interact method.

For example:

from scripton.canvas import Canvas

canvas = Canvas(width=640, height=480)

def draw_on_canvas(event):
    canvas.draw_circle(
        x=event.x,
        y=event.y,
        radius=5,
        fill='rgba(61, 121, 255, 0.7)'
    )

# Set the on_hover event handler
canvas.on_hover = draw_on_canvas

# Monitor events from the UI
canvas.interact()

The example above allows "painting" on the canvas by drawing circles as the mouse moves.

API

For any of the event handlers below, None may be assigned to unregister any previously assigned handlers.

`Canvas.on_hover`

The on_hover handler is invoked when the pointer moves over the canvas.

The callback will receive a PointerEvent instance describing the pointer's state (position, any pressed buttons, etc.).

Example: painting on the canvas

from scripton.canvas import Canvas

canvas = Canvas(width=640, height=480)

def draw_on_canvas(event):
    canvas.draw_circle(
        x=event.x,
        y=event.y,
        radius=5,
        fill='rgba(61, 121, 255, 0.7)'
    )

canvas.on_hover = draw_on_canvas

canvas.interact()

`Canvas.on_key_down`

The on_key_down callback is invoked when a key is pressed while the canvas is focused. The callback will receive a KeyboardEvent instance containing the key and any modifiers.

Moving a circle with the arrow keys

from scripton.canvas import Canvas
from functools import partial

canvas = Canvas(width=640, height=480)
position = [420, 240]


def redraw():
    with canvas.sync():
        canvas.clear()
        canvas.draw_circle(
            x=position[0],
            y=position[1],
            radius=20,
            fill='rgba(61, 121, 255)'
        )


def move_circle(event, delta=5):
    match event.key:
        case 'ArrowLeft':
            position[0] -= delta
        case 'ArrowRight':
            position[0] += delta
        case 'ArrowUp':
            position[1] -= delta
        case 'ArrowDown':
            position[1] += delta

    redraw()


canvas.on_key_down = move_circle
redraw()
canvas.interact()

`Canvas.on_key_up`

The on_key_up callback is invoked when a key is released while the canvas is focused. The callback will receive a KeyboardEvent instance containing the key and any modifiers.

Moving a circle with the arrow keys

from scripton.canvas import Canvas
from functools import partial

canvas = Canvas(width=640, height=480)
position = [420, 240]


def redraw():
    with canvas.sync():
        canvas.clear()
        canvas.draw_circle(
            x=position[0],
            y=position[1],
            radius=20,
            fill='rgba(61, 121, 255)'
        )


def move_circle(event, delta=5):
    match event.key:
        case 'ArrowLeft':
            position[0] -= delta
        case 'ArrowRight':
            position[0] += delta
        case 'ArrowUp':
            position[1] -= delta
        case 'ArrowDown':
            position[1] += delta

    redraw()


canvas.on_key_up = move_circle
redraw()
canvas.interact()

`PointerEvent`

Represents a pointer event (mouse, touchpad, ...) from the UI relative to a target (eg: canvas).

class PointerEvent(Event):

    # The x coordinate (in pixels) relative to the target.
    # Ranges from 0 to the width of the target (increasing to the right).
    x: int

    # The y coordinate (in pixels) relative to the target.
    # Ranges from 0 to the height of the target (increasing downwards).
    y: int

    # The normalized x and y coordinates (in the range [0, 1]) relative to
    # the target. This is equal to the x and y coordinates divided by
    # the width and height of the target.
    normalized: Point2D

    # True if the SHIFT key was pressed during the event.
    shift: bool

    # True if the CONTROL key was pressed during the event.
    ctrl: bool

    # True if the ALT (Option on macOS) key was pressed during the event.
    alt: bool

    # True if the META (Command on macOS) key was pressed during the event.
    meta: bool

    # True if the left (primary) mouse button was pressed during the event.
    left_button: bool

    # True if the right (secondary) mouse button was pressed during the event.
    right_button: bool

    # True if the middle (wheel/auxiliary) mouse button was pressed during the event.
    middle_button: bool

    # True if the back (fourth) mouse button was pressed during the event.
    back_button: bool

    # True if the forward (fifth) mouse button was pressed during the event.
    forward_button: bool

`KeyboardEvent`

Represents a keyboard event from the UI.

class KeyboardEvent(Event):
    # The key that was pressed (eg: 'a', 'Enter', ...) or released.
    # A full list of key values can be found at:
    # https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values
    key: str

    # True if the SHIFT key was pressed during the event.
    shift: bool

    # True if the CONTROL key was pressed during the event.
    ctrl: bool

    # True if the ALT (Option on macOS) key was pressed during the event.
    alt: bool

    # True if the META (Command on macOS) key was pressed during the event.
    meta: bool