# textual-countdown
## Introduction
This library provides a simple visual countdown widget, designed to subtly
let the user know that a period of time is passing; essentially a simple
"wait some time" progress bar.
Uses could be as a non-intrusive countdown in some sort of quiz application,
or a cool-down display in an application that's waiting to hit a busy API
endpoint again.
## Installing
The package can be installed with `pip` or related tools, for example:
```sh
$ pip install textual-countdown
```
## Demo
Once installed, you can try a demo of the library with:
```sh
$ python -m textual_countdown
```
## Using the widget
To import the widget, do:
```python
from textual_countdown import Countdown
```
The `Countdown` widget can then be composed into your application like any
other Textual widget.
### Controlling the countdown
The widget provides the following methods:
- `start(countdown: float) -> None` -- call this to start a countdown,
giving the number of seconds to count down.
- `cancel() -> None` -- to cancel a countdown.
There is also a `is_running` property to check if the countdown is running.
### Events
The following events will be sent from the widget:
- `Countdown.Started` -- posted when a countdown starts.
- `Countdown.Finished` -- posted when a countdown finishes.
- `Countdown.Cancelled` -- posted if a countdown is cancelled.
All events have a `countdown` property that points to the widget that sent
them; `Started` and `Finished` also have a `counting` property that gives
the amount of time being counted.
### Styling
The non-counting colour for the countdown display is controlled by the
standard Textual `colour` CSS style. The active time-remaining portion of
the display is controlled by a `countdown--remaining` component class.
As an example, if you wanted to colour the non-running/expired portion of a
countdown as red, and the time remaining as green, you could do:
```scss
Countdown {
color: red;
&> .countdown--remaining {
color: green;
}
}
```
Additionally, when a `Countdown` is running, it will have a
`countdown--running` class applied; this allows styling of non-running and
running countdown widgets.
[//]: # (README.md ends here)
Raw data
{
"_id": null,
"home_page": "https://github.com/davep/textual-countdown",
"name": "textual-countdown",
"maintainer": "Dave Pearson",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "davep@davep.org",
"keywords": "terminal,library,widget",
"author": "Dave Pearson",
"author_email": "davep@davep.org",
"download_url": "https://files.pythonhosted.org/packages/ce/8a/792e987347559e7c596d06f244f3da15dc8ad830243838ffde10616f6473/textual-countdown-0.1.1.tar.gz",
"platform": null,
"description": "# textual-countdown\n\n\n\n## Introduction\n\nThis library provides a simple visual countdown widget, designed to subtly\nlet the user know that a period of time is passing; essentially a simple\n\"wait some time\" progress bar.\n\nUses could be as a non-intrusive countdown in some sort of quiz application,\nor a cool-down display in an application that's waiting to hit a busy API\nendpoint again.\n\n## Installing\n\nThe package can be installed with `pip` or related tools, for example:\n\n```sh\n$ pip install textual-countdown\n```\n\n## Demo\n\nOnce installed, you can try a demo of the library with:\n\n```sh\n$ python -m textual_countdown\n```\n\n## Using the widget\n\nTo import the widget, do:\n\n```python\nfrom textual_countdown import Countdown\n```\n\nThe `Countdown` widget can then be composed into your application like any\nother Textual widget.\n\n### Controlling the countdown\n\nThe widget provides the following methods:\n\n- `start(countdown: float) -> None` -- call this to start a countdown,\n giving the number of seconds to count down.\n- `cancel() -> None` -- to cancel a countdown.\n\nThere is also a `is_running` property to check if the countdown is running.\n\n### Events\n\nThe following events will be sent from the widget:\n\n- `Countdown.Started` -- posted when a countdown starts.\n- `Countdown.Finished` -- posted when a countdown finishes.\n- `Countdown.Cancelled` -- posted if a countdown is cancelled.\n\nAll events have a `countdown` property that points to the widget that sent\nthem; `Started` and `Finished` also have a `counting` property that gives\nthe amount of time being counted.\n\n### Styling\n\nThe non-counting colour for the countdown display is controlled by the\nstandard Textual `colour` CSS style. The active time-remaining portion of\nthe display is controlled by a `countdown--remaining` component class.\n\nAs an example, if you wanted to colour the non-running/expired portion of a\ncountdown as red, and the time remaining as green, you could do:\n\n```scss\nCountdown {\n color: red;\n\n &> .countdown--remaining {\n color: green;\n }\n}\n```\n\nAdditionally, when a `Countdown` is running, it will have a\n`countdown--running` class applied; this allows styling of non-running and\nrunning countdown widgets.\n\n[//]: # (README.md ends here)\n",
"bugtrack_url": null,
"license": "License :: OSI Approved :: MIT License",
"summary": "A visual coutndown widget for Textal applications",
"version": "0.1.1",
"project_urls": {
"Discussions": "https://github.com/davep/textual-countdown/discussions",
"Documentation": "https://github.com/davep/textual-countdown/blob/main/README.md",
"Homepage": "https://github.com/davep/textual-countdown",
"Issues": "https://github.com/davep/textual-countdown/issues",
"Source": "https://github.com/davep/textual-countdown"
},
"split_keywords": [
"terminal",
"library",
"widget"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "385cc76c3fcd129bd15ee5a7db2caad47c92b8c3203236b9b1d3403073b4d6e3",
"md5": "d50b15b5c126d07eb9d3d53b4e335502",
"sha256": "38731db208bb76be491d20df3fb3d6890524f1bee603a4ac8c798418a84a7f4d"
},
"downloads": -1,
"filename": "textual_countdown-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d50b15b5c126d07eb9d3d53b4e335502",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 5644,
"upload_time": "2024-03-10T12:58:09",
"upload_time_iso_8601": "2024-03-10T12:58:09.686291Z",
"url": "https://files.pythonhosted.org/packages/38/5c/c76c3fcd129bd15ee5a7db2caad47c92b8c3203236b9b1d3403073b4d6e3/textual_countdown-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ce8a792e987347559e7c596d06f244f3da15dc8ad830243838ffde10616f6473",
"md5": "344825025f9e821d03f2225198a768ac",
"sha256": "c644551c7808308813957cd2ae3170e167050430fe045f545d4960b4354582dc"
},
"downloads": -1,
"filename": "textual-countdown-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "344825025f9e821d03f2225198a768ac",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 4998,
"upload_time": "2024-03-10T12:58:11",
"upload_time_iso_8601": "2024-03-10T12:58:11.420311Z",
"url": "https://files.pythonhosted.org/packages/ce/8a/792e987347559e7c596d06f244f3da15dc8ad830243838ffde10616f6473/textual-countdown-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-10 12:58:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "davep",
"github_project": "textual-countdown",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "textual-countdown"
}
JSON
