h3cx/dpg-gauges
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

step 2: add gauge state sizing and animation model

Browse Source
This commit is contained in:
Hector van der Aa
2026-07-02 13:54:58 +02:00
parent 44e4cbd246
commit 34fd60c34e
27 changed files with 1732 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

57
codex/AGENTS.md
View File

@@ -2,15 +2,44 @@
## Current status
Project instruction set initialized.
Step 2 completed and verified. Ready to start Step 3.
## Completed steps
None yet.
Initial setup before Step 1:
- `uv` package metadata exists.
- Runtime dependency `dearpygui` is installed.
- Dev dependencies `pytest`, `ruff`, and `pyright` are installed.
- Required package skeleton exists under `src/dpg_gauges/`.
- `examples/`, `tests/`, and `docs/` directories exist.
- `pyproject.toml` is configured for Python 3.11+, Ruff, and Pyright.
Step 1 - Public API contract and pure core:
- Public API exports are defined in `src/dpg_gauges/__init__.py`.
- Public exceptions are defined in `src/dpg_gauges/exceptions.py`.
- Shared public dataclasses and type aliases are defined in `src/dpg_gauges/types.py`.
- Pure gauge configuration dataclasses are defined in `src/dpg_gauges/gauges.py`.
- Pure scale helpers are defined in `src/dpg_gauges/scales.py`.
- Lightweight theme/style presets are defined in `src/dpg_gauges/themes.py`.
- GUI-dependent public functions are import-safe stubs for Step 1.
- Step 1 tests cover public imports, dataclass construction, clamp/normalize math, tick generation, threshold validation, formatting, and missing-gauge stubs.
## Current step
Step 1 - Public API contract and pure core.
Step 3 - Widget shell and renderer foundation.
Step 2 - State, sizing, animation, and smoothing model:
Implemented during Step 2:
- Added `DpgGaugesConfig`, `configure(...)` wiring, `GaugeState`, `DirtyFlags`, and the global gauge registry.
- Runtime API functions now mutate logical state for values, config updates, thresholds, markers, visibility, and deletion without Dear PyGui calls.
- Added pure sizing helpers for requested/measured size, last non-zero size preservation, square rects, and stretch rects.
- Added pure animation interpolation helpers and smoothing progression helpers.
- Added debug state reporting for registered gauges.
- Added Step 2 tests for registry behaviour, clamped/displayed separation, dirty flags, sizing, animation, smoothing, and invalid values.
## Design decisions
@@ -25,6 +54,7 @@ Step 1 - Public API contract and pure core.
- Gauges are display-only for the first release.
- Thresholds and redline zones are visual only; they do not trigger events.
- The public API should feel like normal Dear PyGui context-manager usage.
- Each completed build step must be checked, documented in this file, and committed before starting the next step.
## Known issues
@@ -35,7 +65,26 @@ None yet.
- Read `codex-old/README.md`, `codex-old/FEATURES.md`, `codex-old/ARCHITECTURE.md`, `codex-old/STEPS.md`, and `codex-old/AGENTS.md`.
- Inspected `/home/hector/projects/dpg-map` package, examples, tests, docs, and pyproject structure.
- Created the initial `codex/` instruction documents for `dpg-gauges`.
- Read `codex/README.md`, `codex/FEATURES.md`, `codex/ARCHITECTURE.md`, `codex/STEPS.md`, and `codex/AGENTS.md`.
- Completed missing pre-Step-1 skeleton files and directories.
- Ran `uv run python -c "import dpg_gauges; print(dpg_gauges.__name__)"`.
- Ran `uv run ruff check .`.
- Ran `uv run ruff format .`.
- Read all files under `codex/`.
- Implemented Step 1 public API exports and pure core modules.
- Added `tests/test_step1_core.py`.
- Ran `uv run pytest`.
- Ran `uv run ruff check .`.
- Ran `uv run ruff format --check .`.
- Ran `uv run pyright`.
- Read `codex/FEATURES.md`, `codex/ARCHITECTURE.md`, `codex/STEPS.md`, and `codex/AGENTS.md` before Step 2 changes.
- Implemented Step 2 state, sizing, animation, smoothing, runtime API, diagnostics, tests, and README status update.
- Ran `uv run pytest`.
- Ran `uv run ruff check .`.
- Ran `uv run ruff format --check .`.
- Ran `uv run pyright`.
- Updated instructions to require a commit after each completed step.
## Next action
Implement Step 1.
Implement Step 3.

3
codex/STEPS.md
View File

@@ -8,12 +8,13 @@ There is no Step 0. Initial setup is listed separately, then implementation star
2. Always read `codex/FEATURES.md`, `codex/ARCHITECTURE.md`, and `codex/AGENTS.md` before making code changes.
3. Keep `codex/AGENTS.md` as a rolling log of what has been done, what is broken, and what comes next.
4. Update `README.md` and `docs/` whenever public behaviour or examples change.
5. After every step, update `codex/AGENTS.md`, run relevant checks, and commit if working in git.
5. After every step, update `codex/AGENTS.md`, run relevant checks, and commit the completed step when working in git.
6. Do not casually change public API once introduced.
7. Dear PyGui calls must happen on the GUI thread only.
8. Runtime gauge updates are GUI-thread-only unless explicitly documented otherwise.
9. Prefer stable, boring implementation over clever drawing tricks.
10. Keep each step shippable and tested before moving to the next.
11. Do not start the next step while the previous completed step is still uncommitted.
## Initial setup instructions