From 28d395f7749c36dd64dd5c4e985cb1aac3725064 Mon Sep 17 00:00:00 2001 From: Will McGugan Date: Mon, 26 Sep 2022 10:41:36 +0100 Subject: [PATCH] code in events --- docs/events/blur.md | 4 ++++ docs/events/click.md | 4 ++++ docs/events/descendant_blur.md | 4 ++++ docs/events/descendant_focus.md | 4 ++++ docs/events/enter.md | 4 ++++ docs/events/focus.md | 4 ++++ docs/events/hide.md | 4 ++++ docs/events/key.md | 4 ++++ docs/events/leave.md | 4 ++++ docs/events/load.md | 4 ++++ docs/events/mount.md | 4 ++++ docs/events/mouse_capture.md | 4 ++++ docs/events/mouse_down.md | 4 ++++ docs/events/mouse_move.md | 4 ++++ docs/events/mouse_release.md | 8 ++++++-- docs/events/mouse_scroll_down.md | 6 +++++- docs/events/mouse_scroll_up.md | 4 ++++ docs/events/mouse_up.md | 4 ++++ docs/events/paste.md | 4 ++++ docs/events/resize.md | 8 ++++++-- docs/events/screen_resume.md | 4 ++++ docs/events/screen_suspend.md | 4 ++++ docs/events/show.md | 4 ++++ docs/examples/guide/input/mouse01.py | 3 +-- docs/guide/input.md | 18 +++++++++++------- src/textual/events.py | 20 +++++++++++++++++--- 26 files changed, 126 insertions(+), 17 deletions(-) diff --git a/docs/events/blur.md b/docs/events/blur.md index a9046e3a6..067e7bde9 100644 --- a/docs/events/blur.md +++ b/docs/events/blur.md @@ -8,3 +8,7 @@ The `Blur` event is sent to a widget when it loses focus. ## Attributes _No other attributes_ + +## Code + +::: textual.events.Blur diff --git a/docs/events/click.md b/docs/events/click.md index 3d09b1f75..5d1c80c68 100644 --- a/docs/events/click.md +++ b/docs/events/click.md @@ -19,3 +19,7 @@ The `Click` event is sent to a widget when the user clicks a mouse button. | `ctrl` | bool | Ctrl key pressed if True | | `screen_x` | int | Mouse x coordinate relative to the screen | | `screen_y` | int | Mouse y coordinate relative to the screen | + +## Code + +::: textual.events.Click diff --git a/docs/events/descendant_blur.md b/docs/events/descendant_blur.md index e58e575ab..bfe0799f6 100644 --- a/docs/events/descendant_blur.md +++ b/docs/events/descendant_blur.md @@ -8,3 +8,7 @@ The `DescendantBlur` event is sent to a widget when one of its children loses fo ## Attributes _No other attributes_ + +## Code + +::: textual.events.DescendantBlur diff --git a/docs/events/descendant_focus.md b/docs/events/descendant_focus.md index 6c5c75b9e..9090cd65d 100644 --- a/docs/events/descendant_focus.md +++ b/docs/events/descendant_focus.md @@ -8,3 +8,7 @@ The `DescendantFocus` event is sent to a widget when one of its descendants rece ## Attributes _No other attributes_ + +## Code + +::: textual.events.DescendantFocus diff --git a/docs/events/enter.md b/docs/events/enter.md index ded210cfa..5fbcda727 100644 --- a/docs/events/enter.md +++ b/docs/events/enter.md @@ -8,3 +8,7 @@ The `Enter` event is sent to a widget when the mouse pointer first moves over a ## Attributes _No other attributes_ + +## Code + +::: textual.events.Enter diff --git a/docs/events/focus.md b/docs/events/focus.md index 0a9ae1900..54f4b2a48 100644 --- a/docs/events/focus.md +++ b/docs/events/focus.md @@ -8,3 +8,7 @@ The `Focus` event is sent to a widget when it receives input focus. ## Attributes _No other attributes_ + +## Code + +::: textual.events.Focus diff --git a/docs/events/hide.md b/docs/events/hide.md index 81cc2a3b7..e4b4d9108 100644 --- a/docs/events/hide.md +++ b/docs/events/hide.md @@ -8,3 +8,7 @@ The `Hide` event is sent to a widget when it is hidden from view. ## Attributes _No additional attributes_ + +## Code + +::: textual.events.Hide diff --git a/docs/events/key.md b/docs/events/key.md index 95fef1168..ae7e33250 100644 --- a/docs/events/key.md +++ b/docs/events/key.md @@ -11,3 +11,7 @@ The `Key` event is sent to a widget when the user presses a key on the keyboard. | --------- | ----------- | ----------------------------------------------------------- | | `key` | str | Name of the key that was pressed. | | `char` | str or None | The character that was pressed, or None it isn't printable. | + +## Code + +::: textual.events.Key diff --git a/docs/events/leave.md b/docs/events/leave.md index 0759a7468..5a72463a9 100644 --- a/docs/events/leave.md +++ b/docs/events/leave.md @@ -8,3 +8,7 @@ The `Leave` event is sent to a widget when the mouse pointer moves off a widget. ## Attributes _No other attributes_ + +## Code + +::: textual.events.Leave diff --git a/docs/events/load.md b/docs/events/load.md index 07b74eda5..2702a7906 100644 --- a/docs/events/load.md +++ b/docs/events/load.md @@ -10,3 +10,7 @@ The load event is typically used to do any setup actions required by the app tha ## Attributes _No additional attributes_ + +## Code + +::: textual.events.Load diff --git a/docs/events/mount.md b/docs/events/mount.md index ce664a1aa..1b2377b77 100644 --- a/docs/events/mount.md +++ b/docs/events/mount.md @@ -10,3 +10,7 @@ The mount event is typically used to set the initial state of a widget or to add ## Attributes _No additional attributes_ + +## Code + +::: textual.events.Mount diff --git a/docs/events/mouse_capture.md b/docs/events/mouse_capture.md index 56c8b718a..167478636 100644 --- a/docs/events/mouse_capture.md +++ b/docs/events/mouse_capture.md @@ -10,3 +10,7 @@ The `MouseCapture` event is sent to a widget when it is capturing mouse events f | attribute | type | purpose | | ---------------- | ------ | --------------------------------------------- | | `mouse_position` | Offset | Mouse coordinates when the mouse was captured | + +## Code + +::: textual.events.MouseCapture diff --git a/docs/events/mouse_down.md b/docs/events/mouse_down.md index eac4585ed..69ed3ca2f 100644 --- a/docs/events/mouse_down.md +++ b/docs/events/mouse_down.md @@ -19,3 +19,7 @@ The `MouseDown` event is sent to a widget when a mouse button is pressed. | `ctrl` | bool | Ctrl key pressed if True | | `screen_x` | int | Mouse x coordinate relative to the screen | | `screen_y` | int | Mouse y coordinate relative to the screen | + +## Code + +::: textual.events.MouseDown diff --git a/docs/events/mouse_move.md b/docs/events/mouse_move.md index ac69a4dc9..42fb61389 100644 --- a/docs/events/mouse_move.md +++ b/docs/events/mouse_move.md @@ -19,3 +19,7 @@ The `MouseMove` event is sent to a widget when the mouse pointer is moved over a | `ctrl` | bool | Ctrl key pressed if True | | `screen_x` | int | Mouse x coordinate relative to the screen | | `screen_y` | int | Mouse y coordinate relative to the screen | + +## Code + +::: textual.events.MouseMove diff --git a/docs/events/mouse_release.md b/docs/events/mouse_release.md index efe6b02fd..5d0fb1eba 100644 --- a/docs/events/mouse_release.md +++ b/docs/events/mouse_release.md @@ -7,6 +7,10 @@ The `MouseRelease` event is sent to a widget when it is no longer receiving mous ## Attributes -| attribute | type | purpose | -| ---------------- | ------ | -------------------------------------------- | +| attribute | type | purpose | +| ---------------- | ------ | --------------------------------------------- | | `mouse_position` | Offset | Mouse coordinates when the mouse was released | + +## Code + +::: textual.events.MouseRelease diff --git a/docs/events/mouse_scroll_down.md b/docs/events/mouse_scroll_down.md index d0e756fbe..2808cbf24 100644 --- a/docs/events/mouse_scroll_down.md +++ b/docs/events/mouse_scroll_down.md @@ -8,6 +8,10 @@ The `MouseScrollDown` event is sent to a widget when the scroll wheel (or trackp ## Attributes | attribute | type | purpose | -|-----------|------|----------------------------------------| +| --------- | ---- | -------------------------------------- | | `x` | int | Mouse x coordinate, relative to Widget | | `y` | int | Mouse y coordinate, relative to Widget | + +## Code + +::: textual.events.MouseScrollDown diff --git a/docs/events/mouse_scroll_up.md b/docs/events/mouse_scroll_up.md index 4d98eea9a..8fbe19c78 100644 --- a/docs/events/mouse_scroll_up.md +++ b/docs/events/mouse_scroll_up.md @@ -11,3 +11,7 @@ The `MouseScrollUp` event is sent to a widget when the scroll wheel (or trackpad | --------- | ---- | -------------------------------------- | | `x` | int | Mouse x coordinate, relative to Widget | | `y` | int | Mouse y coordinate, relative to Widget | + +## Code + +::: textual.events.MouseScrollUp diff --git a/docs/events/mouse_up.md b/docs/events/mouse_up.md index 5e855e2c9..9536089ed 100644 --- a/docs/events/mouse_up.md +++ b/docs/events/mouse_up.md @@ -19,3 +19,7 @@ The `MouseUp` event is sent to a widget when the user releases a mouse button. | `ctrl` | bool | Ctrl key pressed if True | | `screen_x` | int | Mouse x coordinate relative to the screen | | `screen_y` | int | Mouse y coordinate relative to the screen | + +## Code + +::: textual.events.MouseUp diff --git a/docs/events/paste.md b/docs/events/paste.md index 019463c8f..c9e051271 100644 --- a/docs/events/paste.md +++ b/docs/events/paste.md @@ -10,3 +10,7 @@ The `Paste` event is sent to a widget when the user pastes text. | attribute | type | purpose | | --------- | ---- | ------------------------ | | `text` | str | The text that was pasted | + +## Code + +::: textual.events.Paste diff --git a/docs/events/resize.md b/docs/events/resize.md index be57261df..87e0ae8ac 100644 --- a/docs/events/resize.md +++ b/docs/events/resize.md @@ -7,8 +7,12 @@ The `Resize` event is sent to a widget when its size changes and when it is firs ## Attributes -| attribute | type | purpose | -| ---------------- | ---- | ------------------------------------------------- | +| attribute | type | purpose | +| ---------------- | ---- | ------------------------------------------------ | | `size` | Size | The new size of the Widget | | `virtual_size` | Size | The virtual size (scrollable area) of the Widget | | `container_size` | Size | The size of the container (parent widget) | + +## Code + +::: textual.events.Resize diff --git a/docs/events/screen_resume.md b/docs/events/screen_resume.md index 13f603d82..4852149a1 100644 --- a/docs/events/screen_resume.md +++ b/docs/events/screen_resume.md @@ -8,3 +8,7 @@ The `ScreenResume` event is sent to a **Screen** when it becomes current. ## Attributes _No other attributes_ + +## Code + +::: textual.events.ScreenResume diff --git a/docs/events/screen_suspend.md b/docs/events/screen_suspend.md index b5a6d3f4b..b716832ed 100644 --- a/docs/events/screen_suspend.md +++ b/docs/events/screen_suspend.md @@ -8,3 +8,7 @@ The `ScreenSuspend` event is sent to a **Screen** when it is replaced by another ## Attributes _No other attributes_ + +## Code + +::: textual.events.ScreenSuspend diff --git a/docs/events/show.md b/docs/events/show.md index 755757459..b669430cc 100644 --- a/docs/events/show.md +++ b/docs/events/show.md @@ -8,3 +8,7 @@ The `Show` event is sent to a widget when it becomes visible. ## Attributes _No additional attributes_ + +## Code + +::: textual.events.Show diff --git a/docs/examples/guide/input/mouse01.py b/docs/examples/guide/input/mouse01.py index 4c9fb9543..7c0de3f27 100644 --- a/docs/examples/guide/input/mouse01.py +++ b/docs/examples/guide/input/mouse01.py @@ -1,6 +1,5 @@ -from textual.app import App, ComposeResult - from textual import events +from textual.app import App, ComposeResult from textual.layout import Container from textual.widgets import Static, TextLog diff --git a/docs/guide/input.md b/docs/guide/input.md index 1a49c8337..1d24da5f3 100644 --- a/docs/guide/input.md +++ b/docs/guide/input.md @@ -29,15 +29,15 @@ Note the key event handler on the app which logs all key events. if you press an There are two main attributes on a key event. The `key` attribute is the _name_ of the key which may be a single character, or a longer identifier. Textual insures that the `key` attribute could always be used in a method name. -Key events also contain a `char` attribute which contains a printable character. +Key events also contain a `char` attribute which contains single character if it is printable, or ``None`` if it is not printable (like a function key which has no corresponding character). -To illustrate the difference, try `key01.py` with the space key. You should see something like the following: +To illustrate the difference between `key` ad `char`, try `key01.py` with the space key. You should see something like the following: ```{.textual path="docs/examples/guide/input/key01.py", press="space,_"} ``` -The `key` attribute contains the word "space" while the `char` attribute contains a literal space. +Note that he `key` attribute contains the word "space" while the `char` attribute contains a literal space. ### Key methods @@ -53,7 +53,7 @@ Note the addition of a `key_space` method which is called in response to the spa !!! note - Consider key methods to be a convenience for experimenting with Textual features. In nearly all cases, key [bindings](#bindings) and actions are referable. + Consider key methods to be a convenience for experimenting with Textual features. In nearly all cases, key [bindings](#bindings) and [actions](../guide/actions.md) are preferable. ## Input focus @@ -84,7 +84,7 @@ The app splits the screen in to quarters, with a TextLog widget in each quarter. the `:focus` CSS pseudo-selector can be used to apply a style to the focused widget. -You can also move focus by pressing the ++tab++ key which moves the focus to the next widget. Pressing ++shift+tab++ moves the focus in the opposite direction. +You can move focus by pressing the ++tab++ key to focus the next widget. Pressing ++shift+tab++ moves the focus in the opposite direction. ### Controlling focus @@ -119,7 +119,7 @@ The following example binds the keys ++r++, ++g++, and ++b++ to an action which ```{.textual path="docs/examples/guide/input/binding01.py", press="r,g,b,b"} ``` -Note how the footer displays bindings and makes them clickable, as an alternative to pressing the key. +Note how the footer displays bindings and makes them clickable. ### Binding class @@ -156,7 +156,7 @@ The following example shows mouse movements being used to _attach_ a widget to t === "mouse01.py" - ```python title="mouse01.py" hl_lines="12-14" + ```python title="mouse01.py" hl_lines="11-13" --8<-- "docs/examples/guide/input/mouse01.py" ``` @@ -182,6 +182,10 @@ Call [release_mouse][textual.widget.Widget.release_mouse] to restore the default Textual will send a [MouseCapture](../events/mouse_capture.md) event when the mouse is captured, and a [MouseRelease](../events/mouse_release.md) event when it is released. +### Enter and Leave events + +Textual will send a [Enter](../events/enter.md) event to a widget when the mouse cursor first moves over it, and a [Leave](../events/leave) event when the cursor moves off a widget. + ### Click events There are three events associated with clicking a button on your mouse. When the button is initially pressed, Textual sends a [MouseDown](../events/mouse_down.md) event, followed by [MouseUp](../events/mouse_up.md) when the button is released. Textual then sends a final [Click](../events/mouse_click.md) event. diff --git a/src/textual/events.py b/src/textual/events.py index 988629978..f1cb1232f 100644 --- a/src/textual/events.py +++ b/src/textual/events.py @@ -318,17 +318,31 @@ class MouseEvent(InputEvent, bubble=True): @property def offset(self) -> Offset: - """The mouse coordinate as an offset.""" + """The mouse coordinate as an offset. + + Returns: + Offset: Mouse coordinate. + + """ return Offset(self.x, self.y) @property def screen_offset(self) -> Offset: - """Mouse coordinate relative to the screen.""" + """Mouse coordinate relative to the screen. + + Returns: + Offset: Mouse coordinate. + """ return Offset(self.screen_x, self.screen_y) @property def delta(self) -> Offset: - """Mouse coordinate delta (change since last event).""" + """Mouse coordinate delta (change since last event). + + Returns: + Offset: Mouse coordinate. + + """ return Offset(self.delta_x, self.delta_y) @property