Implement a Progress Bar widget. (#2333)

* First prototype of PB. * Repurpose UnderlineBar. * Factor out 'Bar' widget. * Revert "Factor out 'Bar' widget." This reverts commit 0bb4871adf. * Add Bar widget. * Cap progress at 100%. * Add skeleton for the ETA label. [skip ci] * Add ETA display. * Improve docstrings. * Directly compute percentage. * Watch percentage changes directly. [skip ci] * Documentation. * Make reactive percentage private. Instead, we create a public read-only percentage property. * Update griffe to fix documentation issue. Related issues: #1572, https://github.com/mkdocstrings/griffe/issues/128. Related PRs: https://github.com/mkdocstrings/griffe/pull/135. * Add example and docs. * Address review feedback. [skip ci] * More documentation. * Add tests. * Changelog. * More tests. * Fix/fake tests. * Final tweaks.
2025-10-17 02:38:12 +03:00 · 2023-04-26 15:25:39 +01:00
parent ee0d407067
commit 4148b1d450
20 changed files with 2242 additions and 262 deletions
--- a/docs/widgets/progress_bar.md
+++ b/docs/widgets/progress_bar.md
@@ -0,0 +1,143 @@
+# ProgressBar
+
+
+A widget that displays progress on a time-consuming task.
+
+- [ ] Focusable
+- [ ] Container
+
+## Examples
+
+### Progress Bar in Isolation
+
+The example below shows a progress bar in isolation.
+It shows the progress bar in:
+
+ - its indeterminate state, when the `total` progress hasn't been set yet;
+ - the middle of the progress; and
+ - the completed state.
+
+=== "Indeterminate state"
+
+    ```{.textual path="docs/examples/widgets/progress_bar_isolated_.py" press="f"}
+    ```
+
+=== "39% done"
+
+    ```{.textual path="docs/examples/widgets/progress_bar_isolated_.py" press="t"}
+    ```
+
+=== "Completed"
+
+    ```{.textual path="docs/examples/widgets/progress_bar_isolated_.py" press="u"}
+    ```
+
+=== "progress_bar_isolated.py"
+
+    ```python
+    --8<-- "docs/examples/widgets/progress_bar_isolated.py"
+    ```
+
+### Complete App Example
+
+The example below shows a simple app with a progress bar that is keeping track of a fictitious funding level for an organisation.
+
+=== "Output"
+
+    ```{.textual path="docs/examples/widgets/progress_bar.py"}
+    ```
+
+=== "Output (partial funding)"
+
+    ```{.textual path="docs/examples/widgets/progress_bar.py" press="tab,1,5,enter,2,0,enter"}
+    ```
+
+=== "Output (full funding)"
+
+    ```{.textual path="docs/examples/widgets/progress_bar.py" press="tab,1,5,enter,2,0,enter,6,5,enter"}
+    ```
+
+=== "progress_bar.py"
+
+    ```python hl_lines="15"
+    --8<-- "docs/examples/widgets/progress_bar.py"
+    ```
+
+    1. We create a progress bar with a total of `100` steps and we hide the ETA countdown because we are not keeping track of a continuous, uninterrupted task.
+
+=== "progress_bar.css"
+
+    ```sass
+    --8<-- "docs/examples/widgets/progress_bar.css"
+    ```
+
+
+### Custom Styling
+
+This shows a progress bar with custom styling.
+Refer to the [section below](#styling-the-progress-bar) for more information.
+
+=== "Indeterminate state"
+
+    ```{.textual path="docs/examples/widgets/progress_bar_styled_.py" press="f"}
+    ```
+
+=== "39% done"
+
+    ```{.textual path="docs/examples/widgets/progress_bar_styled_.py" press="t"}
+    ```
+
+=== "Completed"
+
+    ```{.textual path="docs/examples/widgets/progress_bar_styled_.py" press="u"}
+    ```
+
+=== "progress_bar_styled.py"
+
+    ```python
+    --8<-- "docs/examples/widgets/progress_bar_styled.py"
+    ```
+
+=== "progress_bar_styled.css"
+
+    ```sass
+    --8<-- "docs/examples/widgets/progress_bar_styled.css"
+    ```
+
+## Reactive Attributes
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `percentage` | `float | None` | `None` | The read-only percentage of progress that has been made. This is `None` if the `total` hasn't been set. |
+| `progress` | `float` | `0` | The number of steps of progress already made. |
+| `total` | `float | None` | `None` | The total number of steps that we are keeping track of. |
+
+## Messages
+
+- [ProgressBar.Completed][textual.widgets.ProgressBar.Completed]
+- [ProgressBar.Started][textual.widgets.ProgressBar.Started]
+
+
+## Styling the Progress Bar
+
+The progress bar is composed of three sub-widgets that can be styled independently:
+
+| Widget name | ID | Description |
+|-------------|----|-------------|
+| `Bar` | `#bar` | The bar that visually represents the progress made. |
+| `PercentageStatus` | `#percentage` | [Label](./label.md) that shows the percentage of completion. |
+| `ETAStatus` | `#eta` | [Label](./label.md) that shows the estimated time to completion. |
+
+### Bar Component Classes
+
+::: textual.widgets._progress_bar.Bar.COMPONENT_CLASSES
+    options:
+      show_root_heading: false
+      show_root_toc_entry: false
+
+---
+
+
+::: textual.widgets.ProgressBar
+    options:
+      heading_level: 2