# Events of every component

> Every event of every Pyzed component: what each one reports, what the handler gets, and how many events each component can have.

Source: https://albakore.github.io/pyzed/library/events/

Pyzed widgets react to events in two layers:

- **Their own events**: the `on_*` parameters of each component, such as `on_press` of a button or
  `on_select` of 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. A `pz.Component` also raises `on_mount` and `on_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.

```python
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

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`

| 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

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

**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](https://albakore.github.io/pyzed/library/mouse-area/#events) | 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](https://albakore.github.io/pyzed/library/console/#events) | 8 | 26 | `on_query`, `on_toggle_level`, `on_clear`, `on_copy`, `on_context`, `on_open`, `on_source`, `on_write` |
| [Tab bar](https://albakore.github.io/pyzed/library/tab-bar/#events) | 7 | 25 | `on_select`, `on_close`, `on_drag`, `on_drop`, `on_drag_over`, `on_context`, `on_new` |
| [Editor](https://albakore.github.io/pyzed/library/editor/#events) | 6 | 24 | `on_change`, `on_cursor`, `on_scroll`, `on_zoom`, `on_action`, `on_hover` |
| [Canvas](https://albakore.github.io/pyzed/library/canvas/#events) | 5 | 23 | `on_press`, `on_release`, `on_right_press`, `on_move`, `on_scroll` |
| [Drop zone](https://albakore.github.io/pyzed/library/drop-zone/#events) | 5 | 25 | `on_drop`, `on_files`, `on_reject`, `on_enter`, `on_leave` |
| [Edits bar](https://albakore.github.io/pyzed/library/edits-bar/#events) | 5 | 25 | `on_keep`, `on_reject`, `on_keep_file`, `on_reject_file`, `on_open` |
| [Window frame](https://albakore.github.io/pyzed/library/window-frame/#events) | 5 | 23 | `on_drag`, `on_minimize`, `on_maximize`, `on_close`, `on_menu` |
| [Date picker](https://albakore.github.io/pyzed/library/date-picker/#events) | 4 | 24 | `on_change`, `on_open`, `on_close`, `on_dismiss` |
| [Sign-in prompt](https://albakore.github.io/pyzed/library/auth-prompt/#events) | 4 | 24 | `on_pick`, `on_cancel`, `on_open_url`, `on_copy` |
| [Table](https://albakore.github.io/pyzed/library/table/#events) | 4 | 22 | `on_sort`, `on_row_press`, `on_row_double_press`, `on_row_context` |
| [Tree](https://albakore.github.io/pyzed/library/tree/#events) | 4 | 22 | `on_toggle`, `on_select`, `on_open`, `on_context` |
| [Command palette](https://albakore.github.io/pyzed/library/command-palette/#events) | 3 | 21 | `on_query`, `on_submit`, `on_press` |
| [Date range picker](https://albakore.github.io/pyzed/library/date-range-picker/#events) | 3 | 23 | `on_change`, `on_open`, `on_close` |
| [Error dialog](https://albakore.github.io/pyzed/library/error-dialog/#events) | 3 | 21 | `on_close`, `on_go_to`, `on_logs` |
| [Icon picker](https://albakore.github.io/pyzed/library/icon-picker/#events) | 3 | 23 | `on_change`, `on_pick`, `on_close` |
| [Input](https://albakore.github.io/pyzed/library/input/#events) | 3 | 21 | `on_input`, `on_submit`, `on_clear` |
| [List item](https://albakore.github.io/pyzed/library/list-item/#events) | 3 | 21 | `on_press`, `on_right_press`, `on_double_press` |
| [Prompt](https://albakore.github.io/pyzed/library/prompt/#events) | 3 | 21 | `on_input`, `on_submit`, `on_cancel` |
| [Select](https://albakore.github.io/pyzed/library/select/#events) | 3 | 21 | `on_select`, `on_open`, `on_close` |
| [Time picker](https://albakore.github.io/pyzed/library/time-picker/#events) | 3 | 23 | `on_change`, `on_open`, `on_close` |
| [Tool call](https://albakore.github.io/pyzed/library/tool-call/#events) | 3 | 23 | `on_allow`, `on_allow_always`, `on_deny` |
| [Unsaved changes](https://albakore.github.io/pyzed/library/unsaved-changes/#events) | 3 | 21 | `on_save`, `on_discard`, `on_cancel` |
| [Breadcrumbs](https://albakore.github.io/pyzed/library/breadcrumbs/#events) | 2 | 20 | `on_press`, `on_more` |
| [Calendar](https://albakore.github.io/pyzed/library/calendar/#events) | 2 | 22 | `on_change`, `on_month` |
| [Chip](https://albakore.github.io/pyzed/library/chip/#events) | 2 | 20 | `on_press`, `on_remove` |
| [Color picker](https://albakore.github.io/pyzed/library/color-picker/#events) | 2 | 22 | `on_change`, `on_press` |
| [Confirm](https://albakore.github.io/pyzed/library/confirm/#events) | 2 | 20 | `on_confirm`, `on_cancel` |
| [Error boundary](https://albakore.github.io/pyzed/library/error-boundary/#events) | 2 | 20 | `on_error`, `on_details` |
| [Number field](https://albakore.github.io/pyzed/library/number-field/#events) | 2 | 20 | `on_change`, `on_submit` |
| [Picker](https://albakore.github.io/pyzed/library/picker/#events) | 2 | 20 | `on_query`, `on_submit` |
| [Service row](https://albakore.github.io/pyzed/library/service-row/#events) | 2 | 22 | `on_toggle`, `on_primary` |
| [Slider](https://albakore.github.io/pyzed/library/slider/#events) | 2 | 20 | `on_change`, `on_release` |
| [Split button](https://albakore.github.io/pyzed/library/split-button/#events) | 2 | 20 | `on_press`, `on_menu` |
| [Thread history](https://albakore.github.io/pyzed/library/thread-history/#events) | 2 | 22 | `on_open`, `on_delete` |
| [Toast](https://albakore.github.io/pyzed/library/toast/#events) | 2 | 20 | `on_dismiss`, `on_press` |
| [Accordion](https://albakore.github.io/pyzed/library/accordion/#events) | 1 | 19 | `on_toggle` |
| [Alert](https://albakore.github.io/pyzed/library/alert/#events) | 1 | 19 | `on_close` |
| [Badge](https://albakore.github.io/pyzed/library/badge/#events) | 1 | 19 | `on_press` |
| [Button](https://albakore.github.io/pyzed/library/button/#events) | 1 | 19 | `on_press` |
| [Callout](https://albakore.github.io/pyzed/library/callout/#events) | 1 | 19 | `on_dismiss` |
| [Card](https://albakore.github.io/pyzed/library/card/#events) | 1 | 19 | `on_press` |
| [Catalog](https://albakore.github.io/pyzed/library/catalog/#events) | 1 | 21 | `on_install` |
| [Checkbox](https://albakore.github.io/pyzed/library/checkbox/#events) | 1 | 19 | `on_toggle` |
| [Choice](https://albakore.github.io/pyzed/library/choice/#events) | 1 | 19 | `on_cancel` |
| [Dialog layer](https://albakore.github.io/pyzed/library/dialog-layer/#events) | 1 | 19 | `on_dismiss` |
| [Disclosure](https://albakore.github.io/pyzed/library/disclosure/#events) | 1 | 19 | `on_toggle` |
| [File picker](https://albakore.github.io/pyzed/library/file-input/#events) | 1 | 19 | `on_change` |
| [Icon button](https://albakore.github.io/pyzed/library/icon-button/#events) | 1 | 19 | `on_press` |
| [Layer](https://albakore.github.io/pyzed/library/layer/#events) | 1 | 19 | `on_dismiss` |
| [Markdown](https://albakore.github.io/pyzed/library/markdown/#events) | 1 | 19 | `on_link` |
| [Menu](https://albakore.github.io/pyzed/library/menu/#events) | 1 | 19 | `on_press` |
| [Modal](https://albakore.github.io/pyzed/library/modal/#events) | 1 | 19 | `on_close` |
| [Panel](https://albakore.github.io/pyzed/library/panel/#events) | 1 | 19 | `on_resize` |
| [Popover](https://albakore.github.io/pyzed/library/popover/#events) | 1 | 19 | `on_dismiss` |
| [Radio group](https://albakore.github.io/pyzed/library/radio-group/#events) | 1 | 19 | `on_select` |
| [Reference browser](https://albakore.github.io/pyzed/library/reference-browser/#events) | 1 | 19 | `on_open_url` |
| [Resizable](https://albakore.github.io/pyzed/library/resizable/#events) | 1 | 19 | `on_resize` |
| [Scrollable](https://albakore.github.io/pyzed/library/scrollable/#events) | 1 | 19 | `on_scroll` |
| [Search input](https://albakore.github.io/pyzed/library/search-input/#events) | 1 | 19 | `on_input` |
| [Segmented](https://albakore.github.io/pyzed/library/segmented/#events) | 1 | 19 | `on_select` |
| [Shortcuts](https://albakore.github.io/pyzed/library/shortcuts/#events) | 1 | 19 | `on_query` |
| [Split](https://albakore.github.io/pyzed/library/split/#events) | 1 | 19 | `on_resize` |
| [Stat](https://albakore.github.io/pyzed/library/stat/#events) | 1 | 19 | `on_press` |
| [Status bar](https://albakore.github.io/pyzed/library/status-bar/#events) | 1 | 19 | `on_press` |
| [Switch](https://albakore.github.io/pyzed/library/switch/#events) | 1 | 19 | `on_toggle` |
| [Title bar](https://albakore.github.io/pyzed/library/title-bar/#events) | 1 | 19 | `on_press` |
| [Toggle group](https://albakore.github.io/pyzed/library/toggle-group/#events) | 1 | 19 | `on_select` |
| [Virtual list](https://albakore.github.io/pyzed/library/virtual-list/#events) | 1 | 19 | `on_scroll` |
| [Workspace](https://albakore.github.io/pyzed/library/workspace/#events) | 1 | 19 | `on_resize` |
| [About](https://albakore.github.io/pyzed/library/about/#events) | 0 | 18 | — |
| [Anchor layout](https://albakore.github.io/pyzed/library/anchor-layout/#events) | 0 | 18 | — |
| [Animation](https://albakore.github.io/pyzed/library/animation/#events) | 0 | 18 | — |
| [Avatar](https://albakore.github.io/pyzed/library/avatar/#events) | 0 | 18 | — |
| [Bar chart](https://albakore.github.io/pyzed/library/bar-chart/#events) | 0 | 18 | — |
| [Column](https://albakore.github.io/pyzed/library/column/#events) | 0 | 18 | — |
| [Container](https://albakore.github.io/pyzed/library/container/#events) | 0 | 18 | — |
| [Context meter](https://albakore.github.io/pyzed/library/context-meter/#events) | 0 | 18 | — |
| [Count badge](https://albakore.github.io/pyzed/library/count-badge/#events) | 0 | 18 | — |
| [Diff stat](https://albakore.github.io/pyzed/library/diff-stat/#events) | 0 | 18 | — |
| [Diff view](https://albakore.github.io/pyzed/library/diff-view/#events) | 0 | 18 | — |
| [Divider](https://albakore.github.io/pyzed/library/divider/#events) | 0 | 18 | — |
| [Donut](https://albakore.github.io/pyzed/library/donut/#events) | 0 | 18 | — |
| [Effects](https://albakore.github.io/pyzed/library/effects/#events) | 0 | 18 | — |
| [Empty state](https://albakore.github.io/pyzed/library/empty-state/#events) | 0 | 18 | — |
| [Facepile](https://albakore.github.io/pyzed/library/facepile/#events) | 0 | 18 | — |
| [Field](https://albakore.github.io/pyzed/library/field/#events) | 0 | 18 | — |
| [Flex](https://albakore.github.io/pyzed/library/flex/#events) | 0 | 18 | — |
| [Grid](https://albakore.github.io/pyzed/library/grid/#events) | 0 | 18 | — |
| [Heading](https://albakore.github.io/pyzed/library/heading/#events) | 0 | 18 | — |
| [Icon](https://albakore.github.io/pyzed/library/icon/#events) | 0 | 18 | — |
| [Image](https://albakore.github.io/pyzed/library/image/#events) | 0 | 18 | — |
| [Indicator](https://albakore.github.io/pyzed/library/indicator/#events) | 0 | 18 | — |
| [Kbd](https://albakore.github.io/pyzed/library/kbd/#events) | 0 | 18 | — |
| [Keybinding hint](https://albakore.github.io/pyzed/library/keybinding-hint/#events) | 0 | 18 | — |
| [Label](https://albakore.github.io/pyzed/library/label/#events) | 0 | 18 | — |
| [List header](https://albakore.github.io/pyzed/library/list-header/#events) | 0 | 18 | — |
| [Panel header](https://albakore.github.io/pyzed/library/panel-header/#events) | 0 | 18 | — |
| [Plan](https://albakore.github.io/pyzed/library/plan/#events) | 0 | 20 | — |
| [Progress](https://albakore.github.io/pyzed/library/progress/#events) | 0 | 18 | — |
| [QR code](https://albakore.github.io/pyzed/library/qr-code/#events) | 0 | 18 | — |
| [Responsive](https://albakore.github.io/pyzed/library/responsive/#events) | 0 | 18 | — |
| [Rich text](https://albakore.github.io/pyzed/library/rich-text/#events) | 0 | 18 | — |
| [Row](https://albakore.github.io/pyzed/library/row/#events) | 0 | 18 | — |
| [Settings group](https://albakore.github.io/pyzed/library/settings-group/#events) | 0 | 18 | — |
| [Shader](https://albakore.github.io/pyzed/library/shader/#events) | 0 | 18 | — |
| [Space](https://albakore.github.io/pyzed/library/spacing/#events) | 0 | 18 | — |
| [Sparkline](https://albakore.github.io/pyzed/library/sparkline/#events) | 0 | 18 | — |
| [Spinner](https://albakore.github.io/pyzed/library/spinner/#events) | 0 | 18 | — |
| [Stack](https://albakore.github.io/pyzed/library/stack/#events) | 0 | 18 | — |
| [Terminal](https://albakore.github.io/pyzed/library/terminal/#events) | 0 | 18 | — |
| [Text](https://albakore.github.io/pyzed/library/text/#events) | 0 | 18 | — |
| [Toolbar](https://albakore.github.io/pyzed/library/toolbar/#events) | 0 | 18 | — |
| [Tooltip](https://albakore.github.io/pyzed/library/tooltip/#events) | 0 | 18 | — |

Next: [App, windows, forms and components](https://albakore.github.io/pyzed/guides/classes/) explains how to create your own events, and [Imperative, declarative and functional](https://albakore.github.io/pyzed/guides/code-styles/) shows the three ways of handling them.