docs and reference

docs/guide/events.md

@@ -1,10 +1,6 @@
 # Events and Messages
 
-We've used event handler methods in many of the examples in this guide. This chapter explores events and messages (see below) in more detail.
-
-!!! tip
-
-    See [events](../events/index.md) for a comprehensive reference on the events Textual sends.
+We've used event handler methods in many of the examples in this guide. This chapter explores [events](../events/index.md) and messages (see below) in more detail.
 
 ## Messages
 
@@ -14,23 +10,25 @@ More on that later, but for now keep in mind that events are also messages, and
 
 ## Message Queue
 
-Every Textual app and widget contains a *message queue*. You can think of a message queue as orders at a restaurant. The chef takes an order and makes the dish. Orders that arrive while the chef is cooking are placed in a line. When the chef has finished a dish they pick up the first order that was added.
+Every [App][textual.app.App] and [Widget][textual.widget.Widget] object contains a *message queue*. You can think of a message queue as orders at a restaurant. The chef takes an order and makes the dish. Orders that arrive while the chef is cooking are placed in a line. When the chef has finished a dish they pick up the next order in the line.
 
-Textual processes messages in the same way. Messages are picked off the message queue and processed (cooked) by a handler method. This guarantees messages and events are processed even if your code can not handle them right way. 
+Textual processes messages in the same way. Messages are picked off a queue and processed (cooked) by a handler method. This guarantees messages and events are processed even if your code can not handle them right way. 
 
-This processing of messages is done within an asyncio Task which is started when you mount the widget. The task monitors an asyncio queue for new messages. When a message arrives, the task dispatches it to the appropriate handler method. Once all messages have been processed the task goes back to waiting for messages.
+This processing of messages is done within an asyncio Task which is started when you mount the widget. The task monitors a queue for new messages and dispatches them to the appropriate handler when they arrive.
 
-If you aren't yet familiar with asyncio, you can consider this part to be black box and trust that Textual will get events to your handler methods.
+!!! tip
 
-By way of an example, let's consider what happens if you were to type "Text" in to a text input widget. When you hit the ++t++ key it is translated in to a [key][textual.events.Key] event and sent to the widget's message queue. Ditto for ++e++, ++x++, and ++t++. 
+    The FastAPI docs have an [excellent introduction](https://fastapi.tiangolo.com/async/) to Python async programming.
 
-The widget's task will pick the first key event from the queue (for the ++t++ key) and call the `on_key` handler to update the display.
+By way of an example, let's consider what happens if you were to type "Text" in to a `TextInput` widget. When you hit the ++t++ key, Textual creates a [key][textual.events.Key] event and sends it to the widget's message queue. Ditto for ++e++, ++x++, and ++t++. 
+
+The widget's task will pick the first message from the queue (a key event for the ++t++ key) and call the `on_key` method with the event as the first argument. In other words it will call `TextInput.on_key(event)`, which updates the display to show the new letter.
 
 <div class="excalidraw">
 --8<-- "docs/images/events/queue.excalidraw.svg"
 </div>
 
-When the `on_key` method returns, Textual will get the next event off the the queue and repeat the process for the remaining keys. At some point the queue will be empty and the widget is said to be in an *idle* state.
+When the `on_key` method returns, Textual will get the next event from the the queue and repeat the process for the remaining keys. At some point the queue will be empty and the widget is said to be in an *idle* state.
 
 !!! note
 
@@ -43,30 +41,29 @@ When the `on_key` method returns, Textual will get the next event off the the qu
 
 ## Default behaviors
 
-You may be familiar with Python's [super](https://docs.python.org/3/library/functions.html#super) function to call a function defined in a base class. You will not have to do this for Textual event handlers as Textual will automatically call any handler methods defined in the base class.
+You may be familiar with Python's [super](https://docs.python.org/3/library/functions.html#super) function to call a function defined in a base class. You will not have to use this in event handlers as Textual will automatically call handler methods defined in a widget's base class(es).
 
-For instance if you define a custom widget, Textual will call its `on_key` handler when you hit a key. Textual will also run any `on_key` methods found in the widget's base classes, including `Widget.on_key` where key bindings are processed. Without this behavior, you would have to remember to call `super().on_key(event)` on all key handlers or key bindings would break. 
+For instance, let's say we are building the classic game of Pong and we have written a `Paddle` widget which extends [Static][textual.widgets.Static]. When a [Key][textual.events.Key] event arrives, Textual calls `Paddle.on_key` (to respond to ++left++ and ++right++ keys), then `Static.on_key`, and finally `Widget.on_key`.
 
 ### Preventing default behaviors
 
-If you don't want this behavior you can call [prevent_default()][textual.message.Message.prevent_default] on the event object. This tells Textual not to call any handlers on base classes.
+If you don't want this behavior you can call [prevent_default()][textual.message.Message.prevent_default] on the event object. This tells Textual not to call any more handlers on base classes.
 
 !!! warning
 
-    Don't call `prevent_default` lightly. It *may* break some of Textual's standard features.
-
+    You won't need `prevent_default` very often. Be sure to know what your base classes do before calling it, or you risk disabling some core features builtin to Textual.
 
 ## Bubbling
 
-Messages have a `bubble` attribute. If this is set to `True` then events will be sent to their parent widget. Input events typically bubble so that a widget will have the opportunity to process events after its children.
+Messages have a `bubble` attribute. If this is set to `True` then events will be sent to a widget's parent after processing. Input events typically bubble so that a widget will have the opportunity to respond to input events if they aren't handled by their children.
 
-The following diagram shows an (abbreviated) DOM for a UI with a container and two buttons. With the "No" button [focused](#) it will receive the key event first.
+The following diagram shows an (abbreviated) DOM for a UI with a container and two buttons. With the "No" button [focused](#), it will receive the key event first.
 
 <div class="excalidraw">
 --8<-- "docs/images/events/bubble1.excalidraw.svg"
 </div>
 
-After Textual calls `Button.on_key` the event _bubbles_ to the buttons parent and will call `Container.on_key` (if it exists).
+After Textual calls `Button.on_key` the event _bubbles_ to the button's parent and will call `Container.on_key` (if it exists).
 
 <div class="excalidraw">
 --8<-- "docs/images/events/bubble2.excalidraw.svg"
@@ -82,7 +79,7 @@ The App class is always the root of the DOM, so there is no where for the event
 
 ### Stopping bubbling
 
-Event handlers may stop this bubble behavior by calling the [stop()][textual.message.Message.stop] method on the event or message. You might want to do this if a widget has responded to the event in an authoritative way. For instance if a text input widget responded to a key event you probably do not want it to also invoke a key binding.
+Event handlers may stop this bubble behavior by calling the [stop()][textual.message.Message.stop] method on the event or message. You might want to do this if a widget has responded to the event in an authoritative way. For instance when a text input widget responds to a key event it stops the bubbling so that the key doesn't also invoke a key binding.
 
 ## Custom messages
 
@@ -90,7 +87,7 @@ You can create custom messages for your application that may be used in the same
 
 The most common reason to do this is if you are building a custom widget and you need to inform a parent widget about a state change.
 
-Let's look at an example which defines a custom message. The following example creates color buttons which, when clicked, send a custom message.
+Let's look at an example which defines a custom message. The following example creates color buttons which&mdash;when clicked&mdash;send a custom message.
 
 === "custom01.py"
 
@@ -105,9 +102,9 @@ Let's look at an example which defines a custom message. The following example c
 
 Note the custom message class which extends [Message][textual.message.Message]. The constructor stores a [color][textual.color.Color] object which handler methods will be able to inspect.
 
-The message class is defined within the widget class itself. This is not strictly required but recommended.
+The message class is defined within the widget class itself. This is not strictly required but recommended, for these reasons:
 
-- If reduces the amount of imports. If you were to import ColorButton, you have access to the message class via `ColorButton.Selected`.
+- It reduces the amount of imports. If you import `ColorButton`, you have access to the message class via `ColorButton.Selected`.
 - It creates a namespace for the handler. So rather than `on_selected`, the handler name becomes `on_color_button_selected`. This makes it less likely that your chosen name will clash with another message.
 
 
@@ -159,11 +156,11 @@ This pattern is a convenience that saves writing out a parameter that may not be
 
 Method handlers may be coroutines. If you prefix your handlers with the `async` keyword, Textual will `await` them. This lets your handler use the `await` keyword for asynchronous APIs.
 
-If your event handlers are coroutines it will allow multiple events to be processed concurrently, but bear in mind an individual widget (or app) will not be able to pick up a new message from the message queue until the handler has returned. This is rarely a problem in practice; as long has handlers return within a few milliseconds the UI will remain responsive. But slow handlers might make your app hard to use.
+If your event handlers are coroutines it will allow multiple events to be processed concurrently, but bear in mind an individual widget (or app) will not be able to pick up a new message from its message queue until the handler has returned. This is rarely a problem in practice; as long has handlers return within a few milliseconds the UI will remain responsive. But slow handlers might make your app hard to use.
 
 !!! info
 
-    To re-use the chef analogy, if an order comes in for beef wellington (which takes a while to cook), orders may start to pile up and customers may have to wait for their meal. The _solution_ would be to have another chef work on the wellington while the first chef picks up new orders.
+    To re-use the chef analogy, if an order comes in for beef wellington (which takes a while to cook), orders may start to pile up and customers may have to wait for their meal. The solution would be to have another chef work on the wellington while the first chef picks up new orders.
 
 Network access is a common cause of slow handlers. If you try to retrieve a file from the internet, the message handler may take anything up to a few seconds to return, which would prevent the widget or app from updating during that time. The solution is to launch a new asyncio task to do the network task in the background.
 

docs/reference/static.md

@@ -0,0 +1 @@
+::: textual.widgets.Static

mkdocs.yml

@@ -100,6 +100,7 @@ nav:
     - "reference/query.md"
     - "reference/reactive.md"
     - "reference/screen.md"
+    - "reference/static.md"
     - "reference/timer.md"
     - "reference/widget.md"
 

src/textual/_doc.py

@@ -73,7 +73,7 @@ def rich(source, language, css_class, options, md, attrs, **kwargs) -> str:
         exec(source, globals)
     except Exception:
         error_console.print_exception()
-        console.bell()
+        # console.bell()
 
     if "output" in globals:
         console.print(globals["output"])