101 lines
3.2 KiB
Markdown
101 lines
3.2 KiB
Markdown
# dpg-gauges
|
|
|
|
Dear PyGui gauge widgets for dashboards and telemetry displays.
|
|
|
|
## Install
|
|
|
|
```bash
|
|
uv add dpg-gauges
|
|
```
|
|
|
|
For local development from another project:
|
|
|
|
```bash
|
|
uv add --editable ../dpg-gauges
|
|
```
|
|
|
|
## Minimal Example
|
|
|
|
```python
|
|
import dearpygui.dearpygui as dpg
|
|
import dpg_gauges as dpgg
|
|
|
|
dpg.create_context()
|
|
with dpg.window(label="Dashboard"):
|
|
dpgg.analog_gauge(tag="rpm", label="RPM", value=3200, max_value=8000, width=220, height=220)
|
|
dpgg.digital_gauge(tag="speed", label="Speed", value=88, unit="km/h", width=220, height=90)
|
|
|
|
dpg.create_viewport(title="gauges", width=520, height=340)
|
|
dpg.setup_dearpygui()
|
|
dpg.show_viewport()
|
|
dpg.start_dearpygui()
|
|
dpg.destroy_context()
|
|
```
|
|
|
|
## Dashboard Example
|
|
|
|
```python
|
|
with dpg.window(label="Engine"):
|
|
with dpgg.gauge_panel(label="Powertrain", width=-1, height=260):
|
|
with dpgg.gauge_grid(columns=3, min_column_width=180):
|
|
dpgg.analog_gauge(tag="rpm", label="RPM", max_value=8000, redline_start=6500)
|
|
dpgg.bar_gauge(tag="boost", label="Boost", max_value=30, unit="psi")
|
|
dpgg.status_light(tag="ecu", label="ECU", state=True)
|
|
```
|
|
|
|
`gauge_grid` is a wrapping, table-backed layout. An integer `columns` value is a maximum; if the
|
|
parent is too narrow for `columns * min_column_width`, the grid uses fewer columns and continues on
|
|
the next row instead of creating a horizontal scrollbar. Use `columns="auto"` for autobreak mode,
|
|
where the grid derives the column count from the available width. Gauges with `width=0` or
|
|
`width=-1` fill their grid cell.
|
|
|
|
Gauges also accept Dear PyGui's usual `parent` argument for adding a gauge to an
|
|
existing container after that container has already been created:
|
|
|
|
```python
|
|
dpg.add_window(tag="data_input", label="Data Input")
|
|
dpgg.analog_gauge(tag="rpm", parent="data_input", label="RPM")
|
|
```
|
|
|
|
The `parent` is applied to the gauge's outer group. The gauge's internal drawlist
|
|
is then parented to that group.
|
|
|
|
## GUI-Thread Contract
|
|
|
|
Dear PyGui item operations must happen on the GUI thread. Gauge creation and runtime updates such as
|
|
`set_value`, `update_gauge`, `set_thresholds`, and `delete_gauge` are GUI-thread functions. Worker
|
|
threads may produce data, but applications should marshal the latest values to a Dear PyGui frame
|
|
callback before calling dpg-gauges APIs.
|
|
|
|
## Animation And Smoothing
|
|
|
|
Animation changes the displayed value over a short duration without changing the raw target value.
|
|
Smoothing improves readability during high-rate updates.
|
|
|
|
```python
|
|
dpgg.digital_gauge(
|
|
tag="speed",
|
|
animation=dpgg.AnimationConfig(enabled=True, duration=0.15),
|
|
smoothing=dpgg.SmoothingConfig(enabled=True, alpha=0.25, max_step=5),
|
|
)
|
|
```
|
|
|
|
Disable animation with `animation=False` for immediate response.
|
|
|
|
## Thresholds And Markers
|
|
|
|
Thresholds and markers are visual only; they do not trigger callbacks or alarms.
|
|
|
|
```python
|
|
dpgg.bar_gauge(
|
|
tag="coolant",
|
|
min_value=40,
|
|
max_value=120,
|
|
thresholds=[dpgg.ThresholdBand(100, 120, (255, 45, 45, 150))],
|
|
markers=[dpgg.GaugeMarker(110, (255, 255, 255, 255), thickness=3)],
|
|
)
|
|
```
|
|
|
|
Implemented gauge types: analog, digital, bar, level, status light, segmented, compass,
|
|
thermometer, battery, and multi-value.
|