Events of every component
Pyzed widgets react to events in two layers:
- Their own events: the
on_*parameters of each component, such ason_pressof a button oron_selectof a tree. They report what the component means (a tab was closed, a row was opened) and usually pass a value (the text, the item, the new state). - The common events: 18 events every widget has, whatever it is, attached with
.on(...): clicks, hover, drag, focus, keys and size. Apz.Componentalso raiseson_mountandon_unmount.
So a component can have up to its own events plus 18 common ones. Across the 114 components of the library there are 160 own events; the ones with the most are listed first in the table at the end.
ui.list_item("main.py", self.open, icon="file").on( # on_press is its own event right_click=self.show_menu, # the common ones: any widget mouse_enter=lambda: setattr(self, "hovered", "main.py"), drag=lambda e: self.move(e.dx, e.dy), # takes the pz.Event)The common events
Section titled “The common events”Every widget has them. A handler without arguments is called with nothing; one with an argument gets a pz.Event.
| Group | Event | When |
|---|---|---|
| Mouse | click |
The widget was clicked (pressed and released with the left button). |
| Mouse | double_click |
Two clicks in quick succession. |
| Mouse | right_click |
The right button was pressed (use it for context menus). |
| Mouse | middle_click |
The middle button (wheel) was pressed. |
| Mouse | mouse_down |
Any button was pressed over the widget (event.button). |
| Mouse | mouse_up |
Any button was released over the widget (event.button). |
| Mouse | mouse_enter |
The pointer moved onto the widget. |
| Mouse | mouse_leave |
The pointer left the widget. |
| Mouse | mouse_move |
The pointer moved over the widget (event.x, event.y). |
| Mouse | scroll |
The wheel turned over the widget (event.dx, event.dy in lines). |
| Drag | drag_start |
The left button was pressed and the pointer moved a few pixels. |
| Drag | drag |
The pointer moved while dragging (event.dx, event.dy since the last one). |
| Drag | drag_end |
The button was released after a drag. |
| Focus | focus |
The widget was clicked and now receives key events. |
| Focus | blur |
A click elsewhere took the focus away. |
| Keyboard | key_down |
A key was pressed while focused (event.key, e.g. "ctrl-s"). |
| Keyboard | key_up |
A key was released while focused (event.key). |
| Layout | resize |
The widget got a new size, including its first one (event.width, event.height). |
Fields of pz.Event
Section titled “Fields of pz.Event”| Property | Description |
|---|---|
type |
The event name ("click", or a component’s own event). |
x, y |
Pointer position relative to the widget (position gives both). |
window_x, window_y |
Pointer position in the window. |
screen_x, screen_y |
On the screen (None where the system does not say, such as Wayland). |
dx, dy |
Scroll amount, or drag movement since the previous drag. |
width, height |
The widget’s size (size gives both). |
button |
"left", "right", "middle"… |
key |
The key combo, such as "ctrl-s". |
shift, ctrl, alt, logo |
Modifiers held. |
value, source |
For a component’s own events: the data and the component. |
What handlers get
Section titled “What handlers get”Controls that produce a value call your callable with it. The most common shapes:
| Handler | Description | Events |
|---|---|---|
() |
Nothing: the event is the news (a press, a close, Enter). | ui.alert(on_close=), ui.badge(on_press=), ui.breadcrumbs(on_more=), ui.button(on_press=)… |
(event) |
A pz.Event: its value holds the data, source the component. |
ui.Calendar(on_change=), ui.Calendar(on_month=), ui.Catalog(on_install=), ui.ColorPicker(on_change=)… |
(text) |
The new text, on every keystroke. | ui.command_palette(on_query=), ui.console(on_query=), ui.editor(on_change=), ui.input(on_input=)… |
(x, y) |
The pointer position, relative to the widget. | pz.canvas(on_press=), pz.canvas(on_release=), pz.canvas(on_right_press=), pz.canvas(on_move=)… |
(info) |
A dict (scroll offset and sizes) or a ui.ErrorInfo. |
ui.editor(on_scroll=), ui.error_boundary(on_error=), ui.error_boundary(on_details=), pz.scrollable(on_scroll=)… |
(value) |
The new value: a number, a color, an option… | ui.file_input(on_change=), ui.number_field(on_change=), ui.radio_group(on_select=), ui.slider(on_change=)… |
(tab_id) |
The id of the tab. | ui.tab_bar(on_select=), ui.tab_bar(on_close=), ui.tab_bar(on_drag=), ui.tab_bar(on_context=) |
(id) |
The id of the row or tab (for a tree, its path). | ui.tree(on_toggle=), ui.tree(on_select=), ui.tree(on_open=), ui.tree(on_context=) |
(row) |
The row (the dict or object you passed in rows). |
ui.table(on_row_press=), ui.table(on_row_double_press=), ui.table(on_row_context=) |
(dx, dy) |
How far the wheel turned, in lines. | pz.canvas(on_scroll=), pz.mouse_area(on_scroll=) |
(checked) |
The new state, True or False. |
ui.checkbox(on_toggle=), ui.switch(on_toggle=) |
(line) |
The log line (a ui.LogEntry). |
ui.console(on_context=), ui.console(on_open=) |
(name) |
A name: of the icon, or of the editor action. | ui.editor(on_action=), ui.icon_picker_dialog(on_pick=) |
(url) |
The URL of the link. | ui.markdown(on_link=), ui.reference_browser(on_open_url=) |
(size) |
The new size in pixels, when a drag ends. | ui.panel(on_resize=), pz.resizable(on_resize=) |
(item) |
The option that was chosen. | ui.segmented(on_select=), ui.select(on_select=) |
Events of each component
Section titled “Events of each component”Own counts the component’s on_* events; Total adds the 18 common ones (and mount / unmount for pz.Component classes).
| Component | Own | Total | Its events |
|---|---|---|---|
| Mouse area | 10 | 28 | on_press, on_release, on_right_press, on_double_click, on_enter, on_exit, on_move, on_scroll, on_middle_press, on_middle_release |
| Console | 8 | 26 | on_query, on_toggle_level, on_clear, on_copy, on_context, on_open, on_source, on_write |
| Tab bar | 7 | 25 | on_select, on_close, on_drag, on_drop, on_drag_over, on_context, on_new |
| Editor | 6 | 24 | on_change, on_cursor, on_scroll, on_zoom, on_action, on_hover |
| Canvas | 5 | 23 | on_press, on_release, on_right_press, on_move, on_scroll |
| Drop zone | 5 | 25 | on_drop, on_files, on_reject, on_enter, on_leave |
| Edits bar | 5 | 25 | on_keep, on_reject, on_keep_file, on_reject_file, on_open |
| Window frame | 5 | 23 | on_drag, on_minimize, on_maximize, on_close, on_menu |
| Date picker | 4 | 24 | on_change, on_open, on_close, on_dismiss |
| Sign-in prompt | 4 | 24 | on_pick, on_cancel, on_open_url, on_copy |
| Table | 4 | 22 | on_sort, on_row_press, on_row_double_press, on_row_context |
| Tree | 4 | 22 | on_toggle, on_select, on_open, on_context |
| Command palette | 3 | 21 | on_query, on_submit, on_press |
| Date range picker | 3 | 23 | on_change, on_open, on_close |
| Error dialog | 3 | 21 | on_close, on_go_to, on_logs |
| Icon picker | 3 | 23 | on_change, on_pick, on_close |
| Input | 3 | 21 | on_input, on_submit, on_clear |
| List item | 3 | 21 | on_press, on_right_press, on_double_press |
| Prompt | 3 | 21 | on_input, on_submit, on_cancel |
| Select | 3 | 21 | on_select, on_open, on_close |
| Time picker | 3 | 23 | on_change, on_open, on_close |
| Tool call | 3 | 23 | on_allow, on_allow_always, on_deny |
| Unsaved changes | 3 | 21 | on_save, on_discard, on_cancel |
| Breadcrumbs | 2 | 20 | on_press, on_more |
| Calendar | 2 | 22 | on_change, on_month |
| Chip | 2 | 20 | on_press, on_remove |
| Color picker | 2 | 22 | on_change, on_press |
| Confirm | 2 | 20 | on_confirm, on_cancel |
| Error boundary | 2 | 20 | on_error, on_details |
| Number field | 2 | 20 | on_change, on_submit |
| Picker | 2 | 20 | on_query, on_submit |
| Service row | 2 | 22 | on_toggle, on_primary |
| Slider | 2 | 20 | on_change, on_release |
| Split button | 2 | 20 | on_press, on_menu |
| Thread history | 2 | 22 | on_open, on_delete |
| Toast | 2 | 20 | on_dismiss, on_press |
| Accordion | 1 | 19 | on_toggle |
| Alert | 1 | 19 | on_close |
| Badge | 1 | 19 | on_press |
| Button | 1 | 19 | on_press |
| Callout | 1 | 19 | on_dismiss |
| Card | 1 | 19 | on_press |
| Catalog | 1 | 21 | on_install |
| Checkbox | 1 | 19 | on_toggle |
| Choice | 1 | 19 | on_cancel |
| Dialog layer | 1 | 19 | on_dismiss |
| Disclosure | 1 | 19 | on_toggle |
| File picker | 1 | 19 | on_change |
| Icon button | 1 | 19 | on_press |
| Layer | 1 | 19 | on_dismiss |
| Markdown | 1 | 19 | on_link |
| Menu | 1 | 19 | on_press |
| Modal | 1 | 19 | on_close |
| Panel | 1 | 19 | on_resize |
| Popover | 1 | 19 | on_dismiss |
| Radio group | 1 | 19 | on_select |
| Reference browser | 1 | 19 | on_open_url |
| Resizable | 1 | 19 | on_resize |
| Scrollable | 1 | 19 | on_scroll |
| Search input | 1 | 19 | on_input |
| Segmented | 1 | 19 | on_select |
| Shortcuts | 1 | 19 | on_query |
| Split | 1 | 19 | on_resize |
| Stat | 1 | 19 | on_press |
| Status bar | 1 | 19 | on_press |
| Switch | 1 | 19 | on_toggle |
| Title bar | 1 | 19 | on_press |
| Toggle group | 1 | 19 | on_select |
| Virtual list | 1 | 19 | on_scroll |
| Workspace | 1 | 19 | on_resize |
| About | 0 | 18 | — |
| Anchor layout | 0 | 18 | — |
| Animation | 0 | 18 | — |
| Avatar | 0 | 18 | — |
| Bar chart | 0 | 18 | — |
| Column | 0 | 18 | — |
| Container | 0 | 18 | — |
| Context meter | 0 | 18 | — |
| Count badge | 0 | 18 | — |
| Diff stat | 0 | 18 | — |
| Diff view | 0 | 18 | — |
| Divider | 0 | 18 | — |
| Donut | 0 | 18 | — |
| Effects | 0 | 18 | — |
| Empty state | 0 | 18 | — |
| Facepile | 0 | 18 | — |
| Field | 0 | 18 | — |
| Flex | 0 | 18 | — |
| Grid | 0 | 18 | — |
| Heading | 0 | 18 | — |
| Icon | 0 | 18 | — |
| Image | 0 | 18 | — |
| Indicator | 0 | 18 | — |
| Kbd | 0 | 18 | — |
| Keybinding hint | 0 | 18 | — |
| Label | 0 | 18 | — |
| List header | 0 | 18 | — |
| Panel header | 0 | 18 | — |
| Plan | 0 | 20 | — |
| Progress | 0 | 18 | — |
| QR code | 0 | 18 | — |
| Responsive | 0 | 18 | — |
| Rich text | 0 | 18 | — |
| Row | 0 | 18 | — |
| Settings group | 0 | 18 | — |
| Shader | 0 | 18 | — |
| Space | 0 | 18 | — |
| Sparkline | 0 | 18 | — |
| Spinner | 0 | 18 | — |
| Stack | 0 | 18 | — |
| Terminal | 0 | 18 | — |
| Text | 0 | 18 | — |
| Toolbar | 0 | 18 | — |
| Tooltip | 0 | 18 | — |
Next: App, windows, forms and components explains how to create your own events, and Imperative, declarative and functional shows the three ways of handling them.