Skip to content

Commit 154fe35

Browse files
pip-install-pythonpip-install-python
committed
added dash gauge
1 parent 6ab8b4b commit 154fe35

File tree

8 files changed

+792
-0
lines changed

8 files changed

+792
-0
lines changed

‎docs/dash_gauge/dash_gauge.md‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
---
2+
name: Gauge Suite
3+
description: A collection of gauge, knob, thermostat, joystick, and display components for Dash.
4+
endpoint: /pip/dash_gauge
5+
package: dash_gauge
6+
icon: mdi:gauge # Or choose another icon e.g., akar-icons:gauge, fluent:gauge-24-regular
7+
---
8+
9+
.. toc::
10+
11+
[Visit GitHub Repo](https://github.com/pip-install-python/dash-gauge)
12+
13+
### Installation
14+
15+
```bash
16+
pip install dash-gauge
17+
```
18+
19+
20+
### Introduction
21+
22+
The `dash-gauge` package provides a suite of interactive and visually appealing components to enhance your Plotly Dash dashboards. Built as wrappers around popular React libraries, this collection includes:
23+
24+
* **`DashGauge`**: Customizable gauge charts (Grafana, Semicircle, Radial styles).
25+
* **`DashRotaryKnob`**: Interactive rotary knob controls with various skins.
26+
* **`DashThermostat`**: A thermostat-like input component.
27+
* **`DashRCJoystick`**: A virtual joystick component for directional input.
28+
* **`Dash7SegmentDisplay`**: A classic 7-segment display for numbers and hex values.
29+
30+
This page documents each component included in the suite.
31+
32+
.. exec::docs.dash_gauge.introduction_example
33+
:code: false
34+
35+
.. sourcetabs::docs/dash_gauge/introduction_example.py
36+
:defaultExpanded: false
37+
:withExpandedButton: true
38+
39+
---
40+
41+
### DashGauge
42+
43+
Displays a value on a customizable gauge. Supports different styles, color ranges, sub-arcs, custom labels, and pointers. Ideal for visualizing KPIs, sensor readings, or progress metrics.
44+
45+
.. exec::docs.dash_gauge.gauge_example
46+
:code: false
47+
48+
.. sourcetabs::docs/dash_gauge/gauge_example.py
49+
:defaultExpanded: false
50+
:withExpandedButton: true
51+
52+
53+
#### DashGauge Props
54+
55+
| Prop | Type | Default | Description |
56+
|-------------------|----------------------------|--------------|----------------------------------------------------------------------------------------------------------------------------------------------|
57+
| `id` | string | - | Component ID for Dash callbacks. |
58+
| `value` | number | `33` | The value the gauge should indicate. |
59+
| `type` | string | `'grafana'` | Style of the gauge. Choices: `'grafana'`, `'semicircle'`, `'radial'`. |
60+
| `minValue` | number | `0` | Minimum value of the gauge scale. |
61+
| `maxValue` | number | `100` | Maximum value of the gauge scale. |
62+
| `className` | string | `dash-gauge` | CSS class name for the component. |
63+
| `style` | object | `{}` | Inline CSS styles for the component. |
64+
| `marginInPercent` | number or object | `undefined` | Sets the margin for the chart inside the SVG. Can be a single number or `{top, bottom, left, right}`. |
65+
| `arc` | object | `{}` | Configuration for the gauge arc (e.g., `width`, `padding`, `cornerRadius`, `colorArray`, `subArcs`, `gradient`). See `usage_gauge.py` for details. |
66+
| `pointer` | object | `{}` | Configuration for the gauge pointer/needle (e.g., `type`, `color`, `length`, `width`, `animate`, `elastic`). See `usage_gauge.py` for details. |
67+
| `labels` | object | `{}` | Configuration for value and tick labels (e.g., `valueLabel`, `tickLabels`, `formatTextValue`, `hideMinMax`). See `usage_gauge.py` for details. |
68+
| `setProps` | func | - | Dash-assigned callback function. |
69+
70+
**Note:** For detailed examples of `arc`, `pointer`, and `labels` configurations, please refer to the `usage_gauge.py` file in the GitHub repository.
71+
72+
---
73+
74+
### DashRotaryKnob
75+
76+
An interactive knob component, useful for selecting values within a range (e.g., volume, tuning). Comes with multiple visual skins from the `react-rotary-knob-skin-pack`.
77+
78+
.. exec::docs.dash_gauge.knob_example
79+
:code: false
80+
81+
.. sourcetabs::docs/dash_gauge/knob_example.py
82+
:defaultExpanded: false
83+
:withExpandedButton: true
84+
85+
#### DashRotaryKnob Props
86+
87+
| Prop | Type | Default | Description |
88+
|-----------------|---------|-----------|------------------------------------------------------------------------------------------------------------|
89+
| `id` | string | - | Component ID for Dash callbacks. |
90+
| `value` | number | `0` | The current value of the knob. Updated via interaction or callbacks. |
91+
| `min` | number | `0` | Minimum value of the knob. |
92+
| `max` | number | `100` | Maximum value of the knob. |
93+
| `step` | number | `1` | Increment/decrement step size. |
94+
| `skinName` | string | `'s1'` | Selects the visual appearance (e.g., `'s1'`, `'s5'`, `'s10'`, up to `'s18'`). See repository for examples. |
95+
| `preciseMode` | boolean | `true` | If true, requires Shift key + drag for fine adjustments. |
96+
| `unlockDistance`| number | `0` | Degrees the mouse must move vertically to "unlock" the knob for rotation. |
97+
| `className` | string | `''` | CSS class name for the component. |
98+
| `style` | object | `{}` | Inline CSS styles for the component. |
99+
| `setProps` | func | - | Dash-assigned callback function. |
100+
101+
**Note:** Explore all 18 skins by changing the `skinName` prop! See `usage_rotary_knob.py` for an interactive example. Only skins 1 & 10-15 look good 🤷‍ "no idea why the other skins don't alin correctly".
102+
103+
---
104+
105+
### DashThermostat
106+
107+
A component mimicking a thermostat interface for setting a target value, typically temperature.
108+
109+
.. exec::docs.dash_gauge.thermostat_example
110+
:code: false
111+
112+
.. sourcetabs::docs/dash_gauge/thermostat_example.py
113+
:defaultExpanded: false
114+
:withExpandedButton: true
115+
116+
#### DashThermostat Props
117+
118+
| Prop | Type | Default | Description |
119+
|--------------|---------|-------------|---------------------------------------------------------------------------------------------------------|
120+
| `id` | string | - | Component ID for Dash callbacks. |
121+
| `value` | number | Required | The current set value (e.g., temperature). Updated via interaction or callbacks. |
122+
| `min` | number | `0` | Minimum value of the thermostat scale. |
123+
| `max` | number | `100` | Maximum value of the thermostat scale. |
124+
| `valueSuffix`| string | `'°'` | Text to display after the value (e.g., `'°C'`, `'°F'`, `'%`). |
125+
| `disabled` | boolean | `false` | If true, disables user interaction with the thermostat. |
126+
| `handle` | object | `undefined` | Configuration object for the draggable handle (e.g., `size`, `colors`). See `react-thermostat` docs. |
127+
| `track` | object | `undefined` | Configuration object for the background track (e.g., `colors`, `thickness`, `markers`). See `react-thermostat` docs. |
128+
| `className` | string | `''` | CSS class name for the component. |
129+
| `style` | object | `{}` | Inline CSS styles for the component. Note: Component has min-width/height defaults. |
130+
| `setProps` | func | - | Dash-assigned callback function. |
131+
132+
**Note:** The `usage_thermostat.py` example demonstrates complex interaction with custom styling and mode switching. It may require CSS files placed in an `assets` folder.
133+
134+
---
135+
136+
### DashRCJoystick
137+
138+
A virtual joystick component that reports direction, angle, and distance based on user interaction. Useful for controlling elements in simulations, games, or robotics dashboards.
139+
140+
.. exec::docs.dash_gauge.joystick_example
141+
:code: false
142+
143+
.. sourcetabs::docs/dash_gauge/joystick_example.py
144+
:defaultExpanded: false
145+
:withExpandedButton: true
146+
147+
#### DashRCJoystick Props
148+
149+
| Prop | Type | Default | Description |
150+
|----------------------|---------|--------------|---------------------------------------------------------------------------------------------------------------------------------------------|
151+
| `id` | string | - | Component ID for Dash callbacks. |
152+
| `baseRadius` | number | `75` | Radius of the joystick's static base circle. |
153+
| `controllerRadius` | number | `35` | Radius of the movable controller knob. |
154+
| `directionCountMode` | string | `'Five'` | Determines the reported directions. Choices: `'Five'` (Center, Top, Bottom, Left, Right), `'Nine'` (includes diagonals). |
155+
| `insideMode` | boolean | `false` | If true, the controller knob stays within the base radius. |
156+
| `throttle` | number | `0` | Throttle time in milliseconds for `onChange` events. `0` means no throttle. |
157+
| `className` | string | `''` | CSS class name for the container. |
158+
| `style` | object | `{}` | Inline CSS styles for the container. |
159+
| `controllerClassName`| string | `undefined` | Additional CSS class for the controller knob. |
160+
| **Read-only Props** | | | *(These props are updated by the component and read in callbacks)* |
161+
| `angle` | number | `undefined` | [Readonly] Current angle of the joystick (degrees). `undefined` when centered. |
162+
| `direction` | string | `'Center'` | [Readonly] Current direction string (e.g., 'Top', 'BottomLeft', 'Center'). Possible values depend on `directionCountMode`. |
163+
| `distance` | number | `0` | [Readonly] Current distance of the controller from the center (normalized 0-1 based on `baseRadius`). |
164+
| `setProps` | func | - | Dash-assigned callback function. |
165+
166+
**Note:** See `usage_rc_joystick.py` for an example controlling the joystick's appearance and reading its state.
167+
168+
---

‎docs/dash_gauge/display_example.py‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
import dash
2+
from dash import html, dcc, callback, Input, Output
3+
import dash_gauge as dg
4+
import dash_mantine_components as dmc
5+
6+
# Based on usage_7_segment_display.py
7+
8+
# Common colors for dropdown
9+
color_options = [
10+
{"label": "Red", "value": "red"}, {"label": "Blue", "value": "blue"},
11+
{"label": "Green", "value": "lime"}, {"label": "Yellow", "value": "yellow"},
12+
{"label": "Cyan", "value": "cyan"}, {"label": "Orange", "value": "orange"},
13+
{"label": "Black", "value": "black"}, {"label": "White", "value": "white"},
14+
]
15+
16+
bg_color_options = [
17+
{'label': 'Dark Gray', 'value': '#222222'}, {'label': 'Black', 'value': '#111111'},
18+
{'label': 'None', 'value': ''}
19+
] + color_options
20+
21+
component = dmc.Container([
22+
dmc.Title("Dash7SegmentDisplay Example", order=3, ta="center", mb="lg"),
23+
dmc.Grid(
24+
gutter="xl",
25+
children=[
26+
# Left side: Display Component
27+
dmc.GridCol(span={"md": 5, "sm": 12}, children=dmc.Stack(align="center", children=[
28+
dmc.Text("Display Output", fw=500),
29+
dg.Dash7SegmentDisplay(
30+
id='my-display-docs',
31+
value="1235",
32+
count=5,
33+
height=80,
34+
color='cyan',
35+
backgroundColor='#222222',
36+
skew=True,
37+
style={'marginTop': '20px', 'marginBottom': '20px'}
38+
),
39+
# Optional second display
40+
dg.Dash7SegmentDisplay(
41+
id='my-display-hex-docs',
42+
value="A0B1", # Example Hex
43+
count=4,
44+
height=60,
45+
color='orange',
46+
backgroundColor='#111111',
47+
),
48+
])),
49+
50+
# Right side: Controls
51+
dmc.GridCol(span={"md": 7, "sm": 12}, children=dmc.Stack([
52+
dmc.Text("Controls", fw=500),
53+
dmc.TextInput(
54+
id='display-value-input-docs',
55+
label="Value (Number or Hex String)",
56+
value='1235',
57+
mb="sm"
58+
),
59+
dmc.Text("Number of Digits (count):", size="sm", fw=500),
60+
dmc.Slider(
61+
id='display-count-slider-docs', min=1, max=10, step=1, value=5,
62+
marks=[{"value": i, "label": str(i)} for i in range(1, 11)],
63+
mb="sm"
64+
),
65+
dmc.Text("Digit Height (pixels):", size="sm", fw=500),
66+
dmc.Slider(
67+
id='display-height-slider-docs', min=20, max=200, step=10, value=80,
68+
marks=[{"value": i, "label": str(i)} for i in range(20, 201, 40)],
69+
mb="sm"
70+
),
71+
dmc.Select(
72+
id='display-color-dropdown-docs',
73+
label="Segment Color", data=color_options, value='cyan',
74+
clearable=False, mb="sm"
75+
),
76+
dmc.Select(
77+
id='display-bgcolor-dropdown-docs',
78+
label="Background Color", data=bg_color_options, value='#222222',
79+
clearable=False, mb="sm"
80+
),
81+
dmc.Checkbox(
82+
id='display-skew-checklist-docs',
83+
label='Skew Digits',
84+
checked=True,
85+
mb="sm"
86+
),
87+
]))
88+
])
89+
], fluid=True)
90+
91+
@callback(
92+
Output('my-display-docs', 'value'),
93+
Output('my-display-docs', 'count'),
94+
Output('my-display-docs', 'height'),
95+
Output('my-display-docs', 'color'),
96+
Output('my-display-docs', 'backgroundColor'),
97+
Output('my-display-docs', 'skew'),
98+
# Also update the hex display value for demo purposes
99+
Output('my-display-hex-docs', 'value'),
100+
Input('display-value-input-docs', 'value'),
101+
Input('display-count-slider-docs', 'value'),
102+
Input('display-height-slider-docs', 'value'),
103+
Input('display-color-dropdown-docs', 'value'),
104+
Input('display-bgcolor-dropdown-docs', 'value'),
105+
Input('display-skew-checklist-docs', 'checked')
106+
)
107+
def update_display_output_docs(val_input, count, height, color, bgcolor, skew_checked):
108+
final_bgcolor = bgcolor if bgcolor else None
109+
# For demo, show input value in both displays if possible, otherwise default hex
110+
hex_val = val_input if len(val_input) <= 4 else "DEMO"
111+
112+
return val_input, count, height, color, final_bgcolor, skew_checked, hex_val

0 commit comments

Comments
 (0)