Metadata-Version: 2.4
Name: deephaven-plugin-clockface
Version: 0.1.0
Summary: A Deephaven deephaven.ui element that renders a live clock in one of several faces — modern digital, retro seven-segment, analog, split-flap, binary, nixie tube or word clock — themed to match the Deephaven UI.
Author: mikebender
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/mofojed/deephaven-plugin-clockface
Project-URL: Repository, https://github.com/mofojed/deephaven-plugin-clockface
Project-URL: Issues, https://github.com/mofojed/deephaven-plugin-clockface/issues
Keywords: deephaven,plugin,clock,clockface,ui
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Environment :: Plugins
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: deephaven-core>=0.35.1
Requires-Dist: deephaven-plugin>=0.6.0
Requires-Dist: deephaven-plugin-utilities>=0.0.2
Requires-Dist: deephaven-plugin-ui>=0.41.0
Dynamic: license-file

# deephaven-plugin-clockface

A live clock for [deephaven.ui](https://github.com/deephaven/deephaven-plugins) panels, in seven
faces — modern digital, seven-segment retro, analog, split-flap, binary, nixie tube and word clock.
Every face is drawn from the Deephaven theme's own colors, so it fits whatever theme is in use.

![A clock cycling through each of its faces](_assets/clockface.gif)

The clock ticks from the browser, so it keeps time without server round trips and a wall of clocks
costs no more than one.

## Install

```sh
pip install deephaven-plugin-clockface
```

Then restart the Deephaven server.

## Usage

```python
from deephaven import ui

from deephaven_plugin_clockface import clockface


@ui.component
def my_panel():
    return clockface()


my_clock = my_panel()
```

Pick a face, a time zone and a format:

```python
clockface(face="analog", timezone="Asia/Tokyo", twenty_four_hour=True, show_date=True)
```

## Faces

| `face`      | Looks like                                                             |
| ----------- | ---------------------------------------------------------------------- |
| `"digital"` | A modern digital readout. The default.                                 |
| `"retro"`   | A seven-segment display, unlit segments and all.                       |
| `"analog"`  | A dial with hour, minute and second hands.                             |
| `"flip"`    | A split-flap board; each card flips as its digit changes.              |
| `"binary"`  | Binary-coded decimal — one column of dots per digit.                   |
| `"nixie"`   | Glowing tube digits.                                                   |
| `"word"`    | The time spelled out, to the nearest five minutes: "quarter past ten". |

## Options

| Option             | Type   | Default     | Notes                                                              |
| ------------------ | ------ | ----------- | ------------------------------------------------------------------ |
| `face`             | `str`  | `"digital"` | One of the faces above. An unknown name raises `ValueError`.       |
| `timezone`         | `str`  | `None`      | IANA name, e.g. `"America/New_York"`. Defaults to the viewer's.    |
| `twenty_four_hour` | `bool` | `False`     | Ignored by `"word"`, which always spells the hour in 12-hour form. |
| `show_seconds`     | `bool` | `True`      | Ignored by `"word"`, which reads to the nearest five minutes.      |
| `show_date`        | `bool` | `False`     | Adds a date line under the time.                                   |

`timezone` is read by the browser, so it accepts any zone the viewer's browser knows. An
unrecognized name falls back to local time rather than blanking the clock.

## A wall of clocks

Each instance keeps its own time, so a trading-desk row is just the component repeated:

```python
from deephaven import ui

from deephaven_plugin_clockface import clockface

DESKS = [
    ("New York", "America/New_York"),
    ("London", "Europe/London"),
    ("Tokyo", "Asia/Tokyo"),
]


@ui.component
def desk_clocks():
    return ui.flex(
        *[
            ui.flex(
                ui.heading(city, level=4),
                clockface(face="flip", timezone=zone, twenty_four_hour=True),
                direction="column",
                align_items="center",
            )
            for city, zone in DESKS
        ],
        gap="size-400",
    )


world_clock = desk_clocks()
```

## Letting the user pick a face

`face` is an ordinary prop, so anything Python can compute can drive it:

```python
from deephaven import ui

from deephaven_plugin_clockface import FACES, clockface


@ui.component
def face_picker():
    face, set_face = ui.use_state("digital")

    return ui.flex(
        clockface(face=face),
        ui.picker(
            *[ui.item(name, key=name) for name in FACES],
            label="Face",
            selected_key=face,
            on_change=set_face,
        ),
        direction="column",
    )


picker = face_picker()
```

## Examples

Runnable panels live in [`examples/`](./examples):

- [`clockface_demo.py`](./examples/clockface_demo.py) — a face picker and a world-clock row.
- [`all_faces.py`](./examples/all_faces.py) — every face, side by side.

## Contributing

See [AGENTS.md](./AGENTS.md) for the project layout and how to build, run and test it.
