Metadata-Version: 2.1
Name: textual-countdown
Version: 0.1.0
Summary: A visual coutndown widget for Textal applications
Home-page: https://github.com/davep/textual-countdown
Author: Dave Pearson
Author-email: davep@davep.org
Maintainer: Dave Pearson
Maintainer-email: davep@davep.org
License: License :: OSI Approved :: MIT License
Project-URL: Documentation, https://github.com/davep/textual-countdown/blob/main/README.md
Project-URL: Source, https://github.com/davep/textual-countdown
Project-URL: Issues, https://github.com/davep/textual-countdown/issues
Project-URL: Discussions, https://github.com/davep/textual-countdown/discussions
Keywords: terminal,library,widget
Classifier: License :: OSI Approved :: MIT License
Classifier: Environment :: Console
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Terminals
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: textual >=0.47.0

# textual-countdown

![Textual Countdown demo](https://raw.githubusercontent.com/davep/textual-countdown/main/images/textual-countdown.gif)

## 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)
