Mouse area

In plain words

An invisible layer that lets anything (a picture, a card, a drawing) notice clicks and the mouse.

pz.mouse_area wraps any widget and reports what the mouse does over it: presses (left, right, middle, double click), entering and leaving, moving (on_move(x, y)) and the wheel (on_scroll(dx, dy)); cursor changes the pointer. pz.hover(base, top) shows top over base only while the pointer is over it, and pz.opaque stops clicks from reaching what is under a widget in a stack.

pz.mouse_area · Category: Actions · Full reference →

Preview

Code

pz.mouse_area(
    ui.card(pz.row([pz.icon("folder", size=20), ui.label("Open project…")], spacing=10, align="center"),
            width=280),
    on_press=on_open, on_right_press=on_menu, cursor="pointer",
)

When to use

• To make a card, an image or a custom drawing clickable without turning it into a button.
• For right-click menus (on_right_press), drag gestures (on_move) and zoom with the wheel.
• pz.hover for actions that appear on hover, like the close button of a tab.

Usage

import pyzed as pz

class Board(pz.App):
    def __init__(self):
        self.pointer = (0, 0)
        self.zoom = 1.0

    def view(self):
        return pz.mouse_area(
            self.drawing(),
            on_move=lambda x, y: setattr(self, "pointer", (x, y)),
            on_scroll=lambda dx, dy: setattr(self, "zoom", max(0.1, self.zoom + dy * 0.1)),
            on_double_click=self.reset, cursor="crosshair",
        )

Variants

About these captures

Each capture is recorded by pyzed itself, off-screen at 2x, in One Dark or One Light to match this site’s theme, and cropped to the component so it shows at its real size. The pointer hovers, presses or types into it; a component that does not react to the pointer cycles through a few themes. With reduced motion you see the first frame. Open Code under a capture to see the snippet that draws it; free names such as on_save stand for your own callbacks.

Cursor

The pointer shape is only visible with a real mouse; the shot shows the wrapped widget.

cursor="pointer"

Code

pz.mouse_area(ui.card(ui.label("Click me"), width=180), on_press=on_open, cursor="pointer")

cursor="grab"

Code

pz.mouse_area(ui.card(ui.label("Drag me"), width=180), on_move=on_drag, cursor="grab")

cursor="crosshair"

Code

pz.mouse_area(pz.canvas([draw.circle(60, 40, 24, fill="#74ade8")], width=120, height=80),
              on_press=on_pick, cursor="crosshair")

Hover content

pz.hover only draws its top while the pointer is over it: here, the close button of a row.

At rest

Code

pz.hover(ui.list_item("notes.py", on_open, icon="file-text"),
         pz.container(ui.icon_button("x", on_close, size="xs"), align_x="end", width="fill"))

With the pointer over it

Code

pz.hover(ui.list_item("notes.py", on_open, icon="file-text"),
         pz.container(ui.icon_button("x", on_close, size="xs"), align_x="end", width="fill"))

Events

Mouse area has 10 events of its own, listed below. Like every widget it also has the 18 common events (click, double_click, right_click, mouse_enter, drag, key_down, resize…), attached with .on(...): see Events and Events of every component.

Event	Handler gets	When
on_press	()	Left click (on press).
on_release	()	On releasing the left button.
on_right_press	()	Right click (context menus).
on_double_click	()	Double click.
on_enter	()	The mouse enters.
on_exit	()	The mouse leaves.
on_move	(x, y)	Called with (x, y) when the mouse moves.
on_scroll	(dx, dy)	Callable that receives (dx, dy) in lines when the wheel is used.
on_middle_press	()	Middle-button click.
on_middle_release	()	Middle button released (pan gestures, for example).

Handler gets is what Pyzed passes to your callable: () means nothing. Any handler can also be a message (a value that is not callable), which goes to update().

Handling the events

The same events written three ways. Imperative: methods of the app change self. Declarative: the handlers produce messages and one update() decides. Functional: a pure function draws an immutable state and asks for changes with set_state(...). See Imperative, declarative and functional.

Imperative

class Board(pz.App):
    def __init__(self):
        self.pointer, self.hovering, self.zoom = (0, 0), False, 1.0

    def view(self):
        return pz.mouse_area(
            ui.card(ui.label(f"{self.pointer} · zoom {self.zoom:.1f}"), width=320),
            on_enter=lambda: setattr(self, "hovering", True),
            on_exit=lambda: setattr(self, "hovering", False),
            on_move=lambda x, y: setattr(self, "pointer", (round(x), round(y))),
            on_scroll=lambda dx, dy: setattr(self, "zoom", max(0.1, self.zoom + dy * 0.1)),
            on_double_click=lambda: setattr(self, "zoom", 1.0),
            on_right_press=lambda: print("context menu"),
            cursor="crosshair",
        )

Declarative

from dataclasses import dataclass


@dataclass
class Moved:
    x: float
    y: float


class Board(pz.App):
    pointer = (0, 0)

    def update(self, message):
        match message:
            case Moved(x, y):
                self.pointer = (round(x), round(y))
            case "reset":
                self.pointer = (0, 0)

    def view(self):
        return pz.mouse_area(ui.card(ui.label(str(self.pointer)), width=320),
                             on_move=Moved, on_double_click="reset")

Functional

from dataclasses import dataclass


@dataclass(frozen=True)
class State:
    hovering: bool = False


def view(state, set_state):
    return pz.mouse_area(ui.card(ui.label("Hovering" if state.hovering else "Point at me"), width=320),
                         on_enter=lambda: set_state(hovering=True), on_exit=lambda: set_state(hovering=False))

Tips

Tip

Hover and pointer states only exist with a real mouse, so the previews draw them as they look; see the animated clips in Showcase for the real thing.

Properties and API

pz.mouse_area

mouse_area(
    content,
    *,
    on_press=None,
    on_release=None,
    on_right_press=None,
    on_double_click=None,
    on_enter=None,
    on_exit=None,
    on_move=None,
    on_scroll=None,
    on_middle_press=None,
    on_middle_release=None,
    cursor=None,
)

Detects mouse events over its content.

Property	Default	Description
content	required	Content: a Widget, a string or a number (converted to text).
cursor	None	"pointer", "text", "grab", "grabbing", "crosshair", "not-allowed", "resize-horizontal", "resize-vertical", "move" or "default".

Events: on_press, on_release, on_right_press, on_double_click, on_enter, on_exit, on_move, on_scroll, on_middle_press, on_middle_release (events).

Full reference →

pz.hover

hover(base, top)

Shows top over base only while the mouse is over it (for example, a tab’s close button).

Property	Default	Description
base	required	Widget underneath.
top	required	Widget that appears on hover.

Full reference →

pz.opaque

opaque(content)

Makes a widget block the mouse for whatever is below it in a stack.

Property	Default	Description
content	required	Content: a Widget, a string or a number (converted to text).

Full reference →

Related

ButtonThe themed button: variants, sizes, icons and shortcuts.

PopoverFloating content at a point: context menus, color pickers.

StackLayers children on top of each other; `pin` places one at x, y.