Events

docs/events/blur.md

@@ -0,0 +1,9 @@
+# Blur
+
+The `Blur` event is sent to a widget when it loses focus.
+
+- [ ] Bubbles
+
+## Attributes
+
+_No other attributes_

docs/events/descendant_blur.md

@@ -0,0 +1,9 @@
+# DescendantBlur
+
+The `DescendantBlur` event is sent to a widget when one of its children loses focus.
+
+- [x] Bubbles
+
+## Attributes
+
+_No other attributes_

docs/events/descendant_focus.md

@@ -0,0 +1,9 @@
+# DescendantFocus
+
+The `DescendantFocus` event is sent to a widget when one of its children receives input focus.
+
+- [x] Bubbles
+
+## Attributes
+
+_No other attributes_

docs/events/enter.md

@@ -0,0 +1,9 @@
+# Enter
+
+The `Enter` event is sent to a widget when the mouse pointer first moves over a widget.
+
+- [ ] Bubbles
+
+## Attributes
+
+_No other attributes_

docs/events/focus.md

@@ -0,0 +1,9 @@
+# Focus
+
+The `Focus` event is sent to a widget when it receives input focus.
+
+- [ ] Bubbles
+
+## Attributes
+
+_No other attributes_

docs/events/hide.md

@@ -0,0 +1,9 @@
+# Show
+
+The `Hide` event is sent to a widget when it is hidden from view.
+
+- [ ] Bubbles
+
+## Attributes
+
+_No additional attributes_

docs/events/key.md

@@ -0,0 +1,11 @@
+# Key
+
+The `Key` event is sent to a widget when the user presses key on the keyboard.
+
+- [x] Bubbles
+
+## Attributes
+
+| attribute | type | purpose                  |
+| --------- | ---- | ------------------------ |
+| `key`     | str  | The key that was pressed |

docs/events/leave.md

@@ -0,0 +1,9 @@
+# Leave
+
+The `Leave` event is sent to a widget when the mouse pointer moves off a widget.
+
+- [ ] Bubbles
+
+## Attributes
+
+_No other attributes_

docs/events/load.md

@@ -0,0 +1,11 @@
+# Mount
+
+The `Load` event is sent to the app prior to switching the terminal in to application mode.
+
+The load event is typically used to do any setup actions required by the app, that don't change the display.
+
+- [ ] Bubbles
+
+## Attributes
+
+_No additional attributes_

docs/events/mount.md

@@ -6,12 +6,6 @@ The mount event is typically used to set the initial state of a widget or to add
 
 - [ ] Bubbles
 
-## Parameters
+## Attributes
 
-`sender`
+_No additional attributes_
-
-: The sender of the widget
-
-## Code
-
-::: textual.events.Mount

docs/events/mouse_capture.md

@@ -0,0 +1,11 @@
+# MouseCapture
+
+The `MouseCapture` event is sent to a widget when it is capturing mouse events from outside of its borders on the screen.
+
+- [ ] Bubbles
+
+## Attributes
+
+| attribute        | type   | purpose                                       |
+| ---------------- | ------ | --------------------------------------------- |
+| `mouse_position` | Offset | Mouse coordinates when the mouse was captured |

docs/events/mouse_click.md

@@ -0,0 +1,20 @@
+# Click
+
+The `Click` event is sent to a widget when the user clicks a mouse button.
+
+- [x] Bubbles
+
+## Attributes
+
+| attribute  | type | purpose                                   |
+| ---------- | ---- | ----------------------------------------- |
+| `x`        | int  | Mouse x coordinate, relative to Widget    |
+| `y`        | int  | Mouse y coordinate, relative to Widget    |
+| `delta_x`  | int  | Change in x since last mouse event        |
+| `delta_y`  | int  | Change in x since last mouse event        |
+| `button`   | int  | Index of mouse button                     |
+| `shift`    | bool | Shift key pressed if True                 |
+| `meta`     | bool | Meta key pressed if True                  |
+| `ctrl`     | bool | Shift key pressed if True                 |
+| `screen_x` | int  | Mouse x coordinate relative to the screen |
+| `screen_y` | int  | Mouse y coordinate relative to the screen |

docs/events/mouse_down.md

@@ -0,0 +1,20 @@
+# MouseDown
+
+The `MouseDown` event is sent to a widget when a mouse button is pressed.
+
+- [x] Bubbles
+
+## Attributes
+
+| attribute  | type | purpose                                   |
+| ---------- | ---- | ----------------------------------------- |
+| `x`        | int  | Mouse x coordinate, relative to Widget    |
+| `y`        | int  | Mouse y coordinate, relative to Widget    |
+| `delta_x`  | int  | Change in x since last mouse event        |
+| `delta_y`  | int  | Change in x since last mouse event        |
+| `button`   | int  | Index of mouse button                     |
+| `shift`    | bool | Shift key pressed if True                 |
+| `meta`     | bool | Meta key pressed if True                  |
+| `ctrl`     | bool | Shift key pressed if True                 |
+| `screen_x` | int  | Mouse x coordinate relative to the screen |
+| `screen_y` | int  | Mouse y coordinate relative to the screen |

docs/events/mouse_move.md

@@ -0,0 +1,20 @@
+# MouseMove
+
+The `MouseMove` event is sent to a widget when the mouse pointer is moved over a widget.
+
+- [x] Bubbles
+
+## Attributes
+
+| attribute  | type | purpose                                   |
+| ---------- | ---- | ----------------------------------------- |
+| `x`        | int  | Mouse x coordinate, relative to Widget    |
+| `y`        | int  | Mouse y coordinate, relative to Widget    |
+| `delta_x`  | int  | Change in x since last mouse event        |
+| `delta_y`  | int  | Change in x since last mouse event        |
+| `button`   | int  | Index of mouse button                     |
+| `shift`    | bool | Shift key pressed if True                 |
+| `meta`     | bool | Meta key pressed if True                  |
+| `ctrl`     | bool | Shift key pressed if True                 |
+| `screen_x` | int  | Mouse x coordinate relative to the screen |
+| `screen_y` | int  | Mouse y coordinate relative to the screen |

docs/events/mouse_release.md

@@ -0,0 +1,11 @@
+# MouseRelease
+
+The `MouseRelease` event is sent to a widget it is no longer receiving mouse events outside of its borders.
+
+- [ ] Bubbles
+
+## Attributes
+
+| attribute        | type   | purpose                                      |
+| ---------------- | ------ | -------------------------------------------- |
+| `mouse_position` | Offset | Mouse coordinates when the mouse was release |

docs/events/mouse_scroll_down.md

@@ -0,0 +1,12 @@
+# MouseScrollDown
+
+The `MouseScrollDown` event is sent to a widget when scroll wheel (or trackpad equivalent) is moved _down_.
+
+- [x] Bubbles
+
+## Attributes
+
+| attribute | type | purpose                                |
+| --------- | ---- | -------------------------------------- |
+| `x`       | int  | Mouse x coordinate, relative to Widget |
+| `y`       | int  | Mouse y coordinate, relative to Widget |

docs/events/mouse_scroll_up.md

@@ -0,0 +1,12 @@
+# MouseScrollUp
+
+The `MouseScrollUp` event is sent to a widget when scroll wheel (or trackpad equivalent) is moved _up_.
+
+- [x] Bubbles
+
+## Attributes
+
+| attribute | type | purpose                                |
+| --------- | ---- | -------------------------------------- |
+| `x`       | int  | Mouse x coordinate, relative to Widget |
+| `y`       | int  | Mouse y coordinate, relative to Widget |

docs/events/mouse_up.md

@@ -0,0 +1,20 @@
+# MouseUp
+
+The `MouseUp` event is sent to a widget when the user releases a mouse button.
+
+- [x] Bubbles
+
+## Attributes
+
+| attribute  | type | purpose                                   |
+| ---------- | ---- | ----------------------------------------- |
+| `x`        | int  | Mouse x coordinate, relative to Widget    |
+| `y`        | int  | Mouse y coordinate, relative to Widget    |
+| `delta_x`  | int  | Change in x since last mouse event        |
+| `delta_y`  | int  | Change in x since last mouse event        |
+| `button`   | int  | Index of mouse button                     |
+| `shift`    | bool | Shift key pressed if True                 |
+| `meta`     | bool | Meta key pressed if True                  |
+| `ctrl`     | bool | Shift key pressed if True                 |
+| `screen_x` | int  | Mouse x coordinate relative to the screen |
+| `screen_y` | int  | Mouse y coordinate relative to the screen |

docs/events/paste.md

@@ -0,0 +1,11 @@
+# Paste
+
+The `Paste` event is sent to a widget when the user pastes text.
+
+- [ ] Bubbles
+
+## Attributes
+
+| attribute | type | purpose                  |
+| --------- | ---- | ------------------------ |
+| `text`    | str  | The text that was pasted |

docs/events/resize.md

@@ -4,20 +4,10 @@ The `Resize` event is sent to a widget when its size changes and when it is firs
 
 - [x] Bubbles
 
-## Parameters
+## Attributes
 
-`event.size`
+| attribute        | type | purpose                                           |
-
+| ---------------- | ---- | ------------------------------------------------- |
-: The new size of the Widget.
+| `size`           | Size | The new size of the Widget.                       |
-
+| `virtual_size`   | Size | The virtual size (scrollable area) of the Widget. |
-`event.virtual_size`
+| `container_size` | Size | The size of the container (parent widget).        |
-
-: The virtual size (scrollable area) of the Widget.
-
-`event.container_size`
-
-: The size of the widget's container.
-
-## Code
-
-::: textual.events.Mount

docs/events/screen_resume.md

@@ -0,0 +1,9 @@
+# ScreenResume
+
+The `ScreenResume` event is sent to a **Screen** when it becomes current.
+
+- [ ] Bubbles
+
+## Attributes
+
+_No other attributes_

docs/events/screen_suspend.md

@@ -0,0 +1,9 @@
+# ScreenSuspend
+
+The `ScreenSuspend` event is sent to a **Screen** when it is replaced by another screen.
+
+- [ ] Bubbles
+
+## Attributes
+
+_No other attributes_

docs/events/show.md

@@ -0,0 +1,9 @@
+# Show
+
+The `Show` event is sent to a widget when it becomes visible.
+
+- [ ] Bubbles
+
+## Attributes
+
+_No additional attributes_

docs/examples/basic.css

@@ -29,7 +29,7 @@ App > Screen {
 #tree-container {
   overflow-y: auto;
   height: 20; 
-  margin: 1 2;
+  margin: 1 3;
   background: $panel;
   padding: 1 2;
 }
@@ -97,7 +97,7 @@ DataTable {
 Tweet {
   height:12;
   width: 100%;
- 
+  margin: 0 2; 
   
   background: $panel;
   color: $text-panel;

docs/styles/background.md

@@ -2,6 +2,12 @@
 
 The `background` rule sets the background color of the widget.
 
+## Syntax
+
+```
+background: COLOR [PERCENTAGE]
+```
+
 ## Example
 
 This example creates three widgets and applies a different background to each.

docs/styles/border.md

@@ -24,6 +24,16 @@ For example `heavy white` would display a heavy white line around a widget.
 
 Borders may also be set individually for the four edges of a widget with the `border-top`, `border-right`, `border-bottom` and `border-left` rules.
 
+## Syntax
+
+```
+border: [<COLOR>] [<BORDER VALUE>];
+border-top: <COLOR>] [<BORDER VALUE>];
+border-right: <COLOR>] [<BORDER VALUE>];
+border-bottom: <COLOR>] [<BORDER VALUE>];
+border-left: <COLOR>] [<BORDER VALUE>];
+```
+
 ## Border command
 
 The `textual` CLI has a subcommand which will let you explore the various border types:

docs/styles/box_sizing.md

@@ -6,6 +6,12 @@ The default value is `border-box` which means that padding and border are includ
 
 You can set `box-sizing` to `content-box` which tells Textual that padding and border should increase the size of the widget, leaving the content area unaffected.
 
+## Syntax
+
+```
+box-sizing: [border-box|content-box];
+```
+
 ## Example
 
 Both widgets in this example have the same height (5). The top widget has `box-sizing: border-box` which means that padding and border reduces the space for content. The bottom widget has `box-sizing: content-box` which increases the size of the widget to compensate for padding and border.

docs/styles/color.md

@@ -2,6 +2,12 @@
 
 The `color` rule sets the text color of a Widget.
 
+## Syntax
+
+```
+color: <COLOR> [<PERCENTAGE>];
+```
+
 ## Example
 
 This example sets a different text color to three different widgets.

docs/styles/display.md

@@ -2,6 +2,12 @@
 
 The `display` property defines if a Widget is displayed or not. The default value is `"block"` which will display the widget as normal. Setting the property to `"none"` will effectively make it invisible.
 
+## Syntax
+
+```
+display: [none|block];
+```
+
 ## Example
 
 Note that the second widget is hidden by adding the "hidden" class which sets the display style to None.

docs/styles/height.md

@@ -2,6 +2,12 @@
 
 The `height` rule sets a widget's height. By default, it sets the height of the content area, but if `box-sizing` is set to `border-box` it sets the height of the border area.
 
+## Syntax
+
+```
+height: <SCALAR>;
+```
+
 ## Example
 
 This examples applies a widget with a height of 50% of the screen.

docs/styles/margin.md

@@ -10,6 +10,14 @@ The `margin` rule adds space around the entire widget. Margin may be specified w
 
 Margin may also be set individually by setting `margin-top`, `margin-right`, `margin-bottom`, or `margin-left` to an single value.
 
+## Syntax
+
+```
+margin: <INTEGER>;
+margin: <INTEGER> <INTEGER>;
+margin: <INTEGER> <INTEGER> <INTEGER> <INTEGER>;
+```
+
 ## Example
 
 In this example we add a large margin to a some static text.

docs/styles/max_height.md

@@ -2,6 +2,12 @@
 
 The `max-height` rule sets a maximum width for a widget.
 
+## Syntax
+
+```
+max-height: <SCALAR>;
+```
+
 ## CSS
 
 ```sass

docs/styles/max_width.md

@@ -2,6 +2,12 @@
 
 The `max-width` rule sets a maximum width for a widget.
 
+## Syntax
+
+```
+max-width: <SCALAR>;
+```
+
 ## CSS
 
 ```sass

docs/styles/min_height.md

@@ -2,6 +2,12 @@
 
 The `min-height` rule sets a minimum height for a widget.
 
+## Syntax
+
+```
+min-height: <SCALAR>;
+```
+
 ## CSS
 
 ```sass

docs/styles/min_width.md

@@ -2,6 +2,12 @@
 
 The `min-width` rules sets a minimum width for a widget.
 
+## Syntax
+
+```
+min-width: <SCALAR>;
+```
+
 ## CSS
 
 ```sass

docs/styles/offset.md

@@ -1,6 +1,14 @@
 # Offset
 
-The `offset` rule adds an offset to the widget's position.
+The `offset` rule adds an offset to the widget's position. The offset is given as two values.
+
+Coordinates may be specified individually with `offset-x` and `offset-y`.
+
+## Syntax
+
+```
+offset: <SCALAR> <SCALAR>;
+```
 
 ## Example
 

docs/styles/outline.md

@@ -26,6 +26,16 @@ For example `heavy white` would display a heavy white line around a widget.
 
 Outlines may also be set individually with the `outline-top`, `outline-right`, `outline-bottom` and `outline-left` rules.
 
+## Syntax
+
+```
+outline: [<COLOR>] [<BORDER VALUE>];
+outline-top: <COLOR>] [<BORDER VALUE>];
+outline-right: <COLOR>] [<BORDER VALUE>];
+outline-bottom: <COLOR>] [<BORDER VALUE>];
+outline-left: <COLOR>] [<BORDER VALUE>];
+```
+
 ## Example
 
 This examples shows a widget with an outline. Note how the outline occludes the text area.

docs/styles/overflow.md

@@ -12,6 +12,14 @@ The default value for overflow is `"auto auto"` which will show scrollbars autom
 
 Overflow may also be set independently by setting the `overflow-x` rule for the horizontal bar, and `overflow-y` for the vertical bar.
 
+## Syntax
+
+```
+overflow: [auto|hidden|scroll];
+overflow-x: [auto|hidden|scroll];
+overflow-y: [auto|hidden|scroll];
+```
+
 ## Example
 
 Here we split the screen in to left and right sections, each with three vertically scrolling widgets that do not fit in to the height of the terminal.

docs/styles/padding.md

@@ -10,6 +10,14 @@ The padding rule adds space around the content of a widget. You can specify padd
 
 Padding may also be set individually by setting `padding-top`, `padding-right`, `padding-bottom`, or `padding-left` to an single value.
 
+## Syntax
+
+```
+padding: <INTEGER>;
+padding: <INTEGER> <INTEGER>;
+padding: <INTEGER> <INTEGER> <INTEGER> <INTEGER>;
+```
+
 ## Example
 
 This example adds padding around static text.

docs/styles/scrollbar.md

@@ -3,7 +3,7 @@
 There are a number of rules to set the colors used in Textual scrollbars. You won't typically need to do this, as the default themes have carefully chosen colors, but you can if you want to.
 
 | Rule                          | Color                                                   |
-|-------------------------------|---------------------------------------------------------|
+| ----------------------------- | ------------------------------------------------------- |
 | `scrollbar-color`             | Scrollbar "thumb" (movable part)                        |
 | `scrollbar-color-hover`       | Scrollbar thumb when the mouse is hovering over it      |
 | `scrollbar-color-active`      | Scrollbar thumb when it is active (being dragged)       |
@@ -12,6 +12,17 @@ There are a number of rules to set the colors used in Textual scrollbars. You wo
 | `scrollbar-background-active` | Scrollbar background when the thumb is being dragged    |
 | `scrollbar-corner-color`      | The gap between the horizontal and vertical scrollbars  |
 
+## Example:
+
+```
+scrollbar-color: <COLOR>;
+scrollbar-color-hover: <COLOR>;
+scrollbar-color-active: <COLOR>;
+scrollbar-background: <COLOR>;
+scrollbar-background-hover: <COLOR>;
+scrollbar-background-active: <COLOR>;
+scrollbar-corner-color: <COLOR>;
+```
 
 ## Example
 

docs/styles/scrollbar_size.md

@@ -4,6 +4,12 @@ The `scrollbar-size` rule changes the size of the scrollbars. It takes 2 integer
 
 The scrollbar dimensions may also be set individually with `scrollbar-size-horizontal` and `scrollbar-size-vertical`.
 
+# Syntax
+
+```
+scrollbar-size: <INTEGER> <INTEGER>;
+```
+
 ## Example
 
 In this example we modify the size of the widgets scrollbar to be _much_ larger than usual.

docs/styles/text_style.md

@@ -12,6 +12,12 @@ The `text-style` rule enables a number of different ways of displaying text. The
 
 Text styles may be set in combination. For example "bold underline" or "reverse underline strike".
 
+## Syntax
+
+```
+text-style: <TEXT STYLE> ...
+```
+
 ## Example
 
 Each of the three text panels has a different text style.

docs/styles/tint.md

@@ -2,6 +2,12 @@
 
 The tint rule blends a color with the widget. The color should likely have an _alpha_ component, or the end result would obscure the widget content.
 
+## Syntax
+
+```
+tint: <COLOR> [<PERCENTAGE>];
+```
+
 ## Example
 
 This examples shows a green tint with gradually increasing alpha.

docs/styles/visibility.md

@@ -2,6 +2,12 @@
 
 The `visibility` rule may be used to make a widget invisible while still reserving spacing for it. The default value is `"visible"` which will cause the Widget to be displayed as normal. Setting the value to `"hidden"` will cause the Widget to become invisible.
 
+## Syntax
+
+```
+visibility: [hidden|visible];
+```
+
 ## Example
 
 Note that the second widget is hidden, while leaving a space where it would have been rendered.

docs/styles/width.md

@@ -2,6 +2,12 @@
 
 The `width` rule sets a widget's width. By default, it sets the width of the content area, but if `box-sizing` is set to `border-box` it sets the width of the border area.
 
+## Syntax
+
+```
+width: <SCALAR>;
+```
+
 ## Example
 
 This example adds a widget with 50% width of the screen.

mkdocs.yml

@@ -12,8 +12,28 @@ nav:
  
   - "actions.md"
   - Events:
+    - "events/blur.md"
+    - "events/descendant_blur.md"
+    - "events/descendant_focus.md"
+    - "events/enter.md"
+    - "events/enter.md"
+    - "events/focus.md"
+    - "events/hide.md"
+    - "events/key.md"
+    - "events/leave.md"
+    - "events/load.md"
     - "events/mount.md"
+    - "events/mouse_capture.md"
+    - "events/mouse_down.md"
+    - "events/mouse_move.md"
+    - "events/mouse_release.md"
+    - "events/mouse_scroll_down.md"
+    - "events/mouse_scroll_up.md"
+    - "events/mouse_up.md"
     - "events/resize.md"
+    - "events/screen_resume.md"
+    - "events/screen_suspend.md"
+    - "events/show.md"
   - Styles:    
     - "styles/background.md"
     - "styles/border.md"

src/textual/events.py

@@ -366,10 +366,6 @@ class Click(MouseEvent, bubble=True):
     pass
 
 
-class DoubleClick(MouseEvent, bubble=True):
-    pass
-
-
 @rich.repr.auto
 class Timer(Event, verbosity=3, bubble=False):
     __slots__ = ["time", "count", "callback"]