mirror of
https://github.com/Textualize/textual.git
synced 2025-10-17 02:38:12 +03:00
4148b1d450
* 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.
144 lines
3.6 KiB
Markdown
144 lines
3.6 KiB
Markdown
# 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
|