textlog documentation

docs/api/text_log.md

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

docs/examples/widgets/text_log.py

@@ -0,0 +1,66 @@
+import csv
+import io
+
+from rich.table import Table
+from rich.syntax import Syntax
+
+from textual.app import App, ComposeResult
+from textual import events
+from textual.widgets import TextLog
+
+
+CSV = """lane,swimmer,country,time
+4,Joseph Schooling,Singapore,50.39
+2,Michael Phelps,United States,51.14
+5,Chad le Clos,South Africa,51.14
+6,László Cseh,Hungary,51.14
+3,Li Zhuhao,China,51.26
+8,Mehdy Metella,France,51.58
+7,Tom Shields,United States,51.73
+1,Aleksandr Sadovnikov,Russia,51.84"""
+
+
+CODE = '''\
+def loop_first_last(values: Iterable[T]) -> Iterable[tuple[bool, bool, T]]:
+    """Iterate and generate a tuple with a flag for first and last value."""
+    iter_values = iter(values)
+    try:
+        previous_value = next(iter_values)
+    except StopIteration:
+        return
+    first = True
+    for value in iter_values:
+        yield first, False, previous_value
+        first = False
+        previous_value = value
+    yield first, True, previous_value\
+'''
+
+
+class TextLogApp(App):
+    def compose(self) -> ComposeResult:
+        yield TextLog(highlight=True, markup=True)
+
+    def on_ready(self) -> None:
+        """Called  when the DOM is ready."""
+        text_log = self.query_one(TextLog)
+
+        text_log.write(Syntax(CODE, "python", indent_guides=True))
+
+        rows = iter(csv.reader(io.StringIO(CSV)))
+        table = Table(*next(rows))
+        for row in rows:
+            table.add_row(*row)
+
+        text_log.write(table)
+        text_log.write("[bold magenta]Write text or any Rich renderable!")
+
+    def on_key(self, event: events.Key) -> None:
+        """Write Key events to log."""
+        text_log = self.query_one(TextLog)
+        text_log.write(event)
+
+
+if __name__ == "__main__":
+    app = TextLogApp()
+    app.run()

docs/widgets/text_log.md

@@ -0,0 +1,44 @@
+# TextLog
+
+A TextLog is a widget which displays scrollable content that may be appended to in realtime.
+
+Call [TextLog.write][textual.widgets.TextLog.write] with a string or [Rich Renderable](https://rich.readthedocs.io/en/latest/protocol.html) to write content to the end of the TextLog. Call [TextLog.clear][textual.widgets.TextLog.clear] to clear the content.
+
+- [X] Focusable
+- [ ] Container
+
+## Example
+
+The example below shows each placeholder variant.
+
+=== "Output"
+
+    ```{.textual path="docs/examples/widgets/text_log.py" press="_,H,i"}
+    ```
+
+=== "text_log.py"
+
+    ```python
+    --8<-- "docs/examples/widgets/text_log.py"
+    ```
+
+
+
+## Reactive Attributes
+
+| Name        | Type   | Default | Description                                                  |
+| ----------- | ------ | ------- | ------------------------------------------------------------ |
+| `highlight` | `bool` | `False` | Automatically highlight content.                             |
+| `markup`    | `bool` | `False` | Apply Rich console markup.                                   |
+| `max_lines` | `int`  | `None`  | Maximum number of lines in the log or `None` for no maximum. |
+| `min_width` | `int`  | 78      | Minimum width of renderables.                                |
+| `wrap`      | `bool` | `False` | Enable word wrapping.                                        |
+
+## Messages
+
+This widget sends no messages.
+
+
+## See Also
+
+* [TextLog](../api/textlog.md) code reference