Improving data table documentation (#2279)

* Improving data table documentation

* More info on DataTable

* Add note on retrieving cursor coordinate

* Add note on DataTable supporting more than just strings

* Add note on cell styling and justifying - common question

* Slight rewording

* Explaining what "row labels" are.

* Update docs/widgets/data_table.md

Co-authored-by: Will McGugan <willmcgugan@gmail.com>

* Update docs/widgets/data_table.md

Co-authored-by: Will McGugan <willmcgugan@gmail.com>

* Update docs/widgets/data_table.md

Co-authored-by: Will McGugan <willmcgugan@gmail.com>

* Update docs/widgets/data_table.md

Co-authored-by: Rodrigo Girão Serrão <5621605+rodrigogiraoserrao@users.noreply.github.com>

* Update docs/widgets/data_table.md

Co-authored-by: Rodrigo Girão Serrão <5621605+rodrigogiraoserrao@users.noreply.github.com>

* Update docs/widgets/data_table.md

Co-authored-by: Rodrigo Girão Serrão <5621605+rodrigogiraoserrao@users.noreply.github.com>

* Update docs/widgets/data_table.md

Co-authored-by: Rodrigo Girão Serrão <5621605+rodrigogiraoserrao@users.noreply.github.com>

* Update docs/widgets/data_table.md

Co-authored-by: Rodrigo Girão Serrão <5621605+rodrigogiraoserrao@users.noreply.github.com>

* Improve data table fixed rows/columns docs

* Update some examples

---------

Co-authored-by: Will McGugan <willmcgugan@gmail.com>
Co-authored-by: Rodrigo Girão Serrão <5621605+rodrigogiraoserrao@users.noreply.github.com>

docs/examples/widgets/data_table.py

@@ -21,9 +21,8 @@ class TableApp(App):
 
     def on_mount(self) -> None:
         table = self.query_one(DataTable)
-        rows = iter(ROWS)
-        table.add_columns(*next(rows))
-        table.add_rows(rows)
+        table.add_columns(*ROWS[0])
+        table.add_rows(ROWS[1:])
 
 
 app = TableApp()

docs/examples/widgets/data_table_cursors.py

@@ -0,0 +1,40 @@
+from itertools import cycle
+
+from textual.app import App, ComposeResult
+from textual.widgets import DataTable
+
+ROWS = [
+    ("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),
+    (10, "Darren Burns", "Scotland", 51.84),
+]
+
+cursors = cycle(["column", "row", "cell"])
+
+
+class TableApp(App):
+    def compose(self) -> ComposeResult:
+        yield DataTable()
+
+    def on_mount(self) -> None:
+        table = self.query_one(DataTable)
+        table.cursor_type = next(cursors)
+        table.zebra_stripes = True
+        table.add_columns(*ROWS[0])
+        table.add_rows(ROWS[1:])
+
+    def key_c(self):
+        table = self.query_one(DataTable)
+        table.cursor_type = next(cursors)
+
+
+app = TableApp()
+if __name__ == "__main__":
+    app.run()

docs/examples/widgets/data_table_fixed.py

@@ -0,0 +1,25 @@
+from textual.app import App, ComposeResult
+from textual.widgets import DataTable
+
+
+class TableApp(App):
+    CSS = "DataTable {height: 1fr}"
+
+    def compose(self) -> ComposeResult:
+        yield DataTable()
+
+    def on_mount(self) -> None:
+        table = self.query_one(DataTable)
+        table.focus()
+        table.add_columns("A", "B", "C")
+        for number in range(1, 100):
+            table.add_row(str(number), str(number * 2), str(number * 3))
+        table.fixed_rows = 2
+        table.fixed_columns = 1
+        table.cursor_type = "row"
+        table.zebra_stripes = True
+
+
+app = TableApp()
+if __name__ == "__main__":
+    app.run()

docs/examples/widgets/data_table_labels.py

@@ -0,0 +1,34 @@
+from rich.text import Text
+
+from textual.app import App, ComposeResult
+from textual.widgets import DataTable
+
+ROWS = [
+    ("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),
+    (10, "Darren Burns", "Scotland", 51.84),
+]
+
+
+class TableApp(App):
+    def compose(self) -> ComposeResult:
+        yield DataTable()
+
+    def on_mount(self) -> None:
+        table = self.query_one(DataTable)
+        table.add_columns(*ROWS[0])
+        for number, row in enumerate(ROWS[1:], start=1):
+            label = Text(str(number), style="#B0FC38 italic")
+            table.add_row(*row, label=label)
+
+
+app = TableApp()
+if __name__ == "__main__":
+    app.run()

docs/examples/widgets/data_table_renderables.py

@@ -0,0 +1,37 @@
+from rich.text import Text
+
+from textual.app import App, ComposeResult
+from textual.widgets import DataTable
+
+ROWS = [
+    ("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),
+    (10, "Darren Burns", "Scotland", 51.84),
+]
+
+
+class TableApp(App):
+    def compose(self) -> ComposeResult:
+        yield DataTable()
+
+    def on_mount(self) -> None:
+        table = self.query_one(DataTable)
+        table.add_columns(*ROWS[0])
+        for row in ROWS[1:]:
+            # Adding styled and justified `Text` objects instead of plain strings.
+            styled_row = [
+                Text(str(cell), style="italic #03AC13", justify="right") for cell in row
+            ]
+            table.add_row(*styled_row)
+
+
+app = TableApp()
+if __name__ == "__main__":
+    app.run()