input docs an exampels

docs/events/key.md

@@ -7,6 +7,7 @@ The `Key` event is sent to a widget when the user presses a key on the keyboard.
 
 ## Attributes
 
-| attribute | type | purpose                  |
-| --------- | ---- | ------------------------ |
-| `key`     | str  | The key that was pressed |
+| attribute | type        | purpose                                                     |
+| --------- | ----------- | ----------------------------------------------------------- |
+| `key`     | str         | Name of the key that was pressed.                           |
+| `char`    | str or None | The character that was pressed, or None it isn't printable. |

docs/events/mouse_move.md

@@ -2,7 +2,7 @@
 
 The `MouseMove` event is sent to a widget when the mouse pointer is moved over a widget.
 
-- [x] Bubbles
+- [ ] Bubbles
 - [x] Verbose
 
 ## Attributes

docs/examples/guide/input/key01.py

@@ -0,0 +1,21 @@
+from textual.app import App, ComposeResult
+from textual.widgets import TextLog
+from textual import events
+
+
+class InputApp(App):
+    """App to display key events."""
+
+    def compose(self) -> ComposeResult:
+        yield TextLog()
+
+    def on_key(self, event: events.Key) -> None:
+        self.query_one(TextLog).write(event)
+
+    def key_space(self) -> None:
+        self.bell()
+
+
+if __name__ == "__main__":
+    app = InputApp()
+    app.run()

docs/examples/guide/input/key02.css

@@ -0,0 +1,12 @@
+Screen {
+    layout: horizontal;
+}
+
+KeyLogger {
+    width: 1fr;
+    border: blank;
+}
+
+KeyLogger:focus {
+    border: wide $accent;
+}

docs/examples/guide/input/key02.py

@@ -0,0 +1,23 @@
+from textual.app import App, ComposeResult
+from textual.widgets import TextLog
+from textual import events
+
+
+class KeyLogger(TextLog):
+    def on_key(self, event: events.Key) -> None:
+        self.write(event)
+
+
+class InputApp(App):
+    """App to display key events."""
+
+    CSS_PATH = "input02.css"
+
+    def compose(self) -> ComposeResult:
+        yield KeyLogger()
+        yield KeyLogger()
+
+
+if __name__ == "__main__":
+    app = InputApp()
+    app.run()

docs/examples/guide/input/mouse01.css

@@ -0,0 +1,24 @@
+Screen {
+    layers: log ball;
+}
+
+TextLog {
+    layer: log;
+}
+
+PlayArea { 
+    background: transparent;
+    layer: ball;
+    
+}
+Ball {
+    layer: ball;
+    width: auto;
+    height: 1;
+    background: $secondary;
+    border: tall $secondary;    
+    color: $background;
+    box-sizing: content-box;
+    text-style: bold;
+    padding: 0 4;
+}

docs/examples/guide/input/mouse01.py

@@ -0,0 +1,31 @@
+from textual.app import App, ComposeResult
+
+from textual import events
+from textual.layout import Container
+from textual.widgets import Static, TextLog
+
+
+class PlayArea(Container):
+    def on_mount(self) -> None:
+        self.capture_mouse()
+
+    def on_mouse_move(self, event: events.MouseMove) -> None:
+        self.screen.query_one(TextLog).write(event)
+        self.query_one(Ball).offset = event.offset - (8, 2)
+
+
+class Ball(Static):
+    pass
+
+
+class MouseApp(App):
+    CSS_PATH = "mouse01.css"
+
+    def compose(self) -> ComposeResult:
+        yield TextLog()
+        yield PlayArea(Ball("Textual"))
+
+
+if __name__ == "__main__":
+    app = MouseApp()
+    app.run()

docs/guide/input.md

@@ -0,0 +1,26 @@
+# Input
+
+This chapter will discuss how to make your app respond to input in the form of key presses and mouse actions.
+
+!!! quote
+
+    More Input!
+
+    — Johnny Five
+
+## Key events
+
+The most fundamental way to receive input in via [Key](./events/key) events. Let's take a closer look at key events with an app that will display key events as you type.
+
+=== "key01.py"
+
+    ```python title="key01.py" hl_lines="12-13"
+    --8<-- "docs/examples/guide/input/key01.py"
+    ```
+
+=== "Output"
+
+    ```{.textual path="docs/examples/guide/input/key01.py", press="T,e,x,t,u,a,l,!,_"}
+    ```
+
+Note the key event handler which