AnalogGaugeWidget

AnalogGaugeWidget is a highly customizable analog gauge meter widget that provides a visually appealing way to display numerical values with analog-style indicators. It features multiple themes, smooth animations, and extensive customization options.

Custom Analog Gauge

Overview

Analog Display:
Classic analog gauge with needle pointer for intuitive value representation.
Multiple Themes:
Includes 11 preset themes with customizable color schemes.
Smooth Animations:
Fluid needle movement with drag interaction support.
Customizable Scales:
Configurable scale ranges, divisions, and appearance.
Theme Integration:
Seamlessly integrates with the custom widgets theming system.
Interactive Controls:
Supports mouse interaction for value adjustment.

Constructor

AnalogGaugeWidget(parent=None, min_value=0, max_value=1000, 
                 needle_color=QColor(0, 0, 0, 255),
                 needle_color_drag=QColor(255, 0, 0, 255),
                 scale_value_color=QColor(0, 0, 0, 255),
                 display_value_color=QColor(0, 0, 0, 255),
                 center_point_color=QColor(0, 0, 0, 255))

parent:
The parent widget (defaults to None).
min_value:
Minimum value displayed on the gauge (default: 0).
max_value:
Maximum value displayed on the gauge (default: 1000).
needle_color:
Color of the gauge needle in normal state.
needle_color_drag:
Color of the gauge needle during drag interaction.
scale_value_color:
Color of the scale numbers and markers.
display_value_color:
Color of the central value display.
center_point_color:
Color of the center pivot point.

Key Properties

`themeNumber` (int)

Purpose:
Selects the preset gauge theme (0-10).
Getter:
Returns the current theme number.
Setter:
Applies the specified theme and updates display.
Example:
```
gauge.themeNumber = 5
```

`units` (str)

Purpose:
Units label displayed below the value.
Getter:
Returns the current units string.
Setter:
Updates the units label.
Example:
```
gauge.units = "km/h"
```

`value` (int)

Purpose:
Current value displayed by the gauge needle.
Getter:
Returns the current gauge value.
Setter:
Updates the value and moves the needle.
Example:
```
gauge.value = 75
```

`minValue` (int)

Purpose:
Minimum value of the gauge scale.
Getter:
Returns the minimum scale value.
Setter:
Updates the minimum scale value.
Example:
```
gauge.minValue = 0
```

`maxValue` (int)

Purpose:
Maximum value of the gauge scale.
Getter:
Returns the maximum scale value.
Setter:
Updates the maximum scale value.
Example:
```
gauge.maxValue = 100
```

`scalaCount` (int)

Purpose:
Number of major scale divisions.
Getter:
Returns the number of scale divisions.
Setter:
Updates the scale division count.
Example:
```
gauge.scalaCount = 10
```

`enableBarGraph` (bool)

Purpose:
Enables or disables the colored bar graph background.
Getter:
Returns whether bar graph is enabled.
Setter:
Toggles the bar graph display.
Example:
```
gauge.enableBarGraph = True
```

`enableValueText` (bool)

Purpose:
Enables or disables the central value display.
Getter:
Returns whether value text is enabled.
Setter:
Toggles the value display.
Example:
```
gauge.enableValueText = True
```

`enableCenterPoint` (bool)

Purpose:
Enables or disables the center pivot point.
Getter:
Returns whether center point is enabled.
Setter:
Toggles the center point display.
Example:
```
gauge.enableCenterPoint = True
```

Methods

`setGaugeTheme(theme_number)`

Description:
Applies one of the preset gauge themes.
Parameters:
- theme_number: Integer from 0 to 10 representing different theme styles.
Example:
```
gauge.setGaugeTheme(3)  # Apply theme 3
```

`setCustomGaugeTheme(color1, color2, color3)`

Description:
Creates a custom color theme for the gauge.
Parameters:
- color1, color2, color3: Color values for gradient stops.

Example:

gauge.setCustomGaugeTheme(
    color1="#FF2B00",
    color2="#821600", 
    color3="#260600"
)

`setScalePolygonColor(**color_positions)`

Description:
Sets custom colors for the scale polygon gradient.
Parameters:
- color_positions: Keyword arguments with position (0.0-1.0) and color values.

Example:

gauge.setScalePolygonColor(
    color1="red",
    color2="blue",
    color3="green"
)

`setNeedleCenterColor(**color_positions)`

Description:
Sets custom colors for the needle center gradient.
Parameters:
- color_positions: Keyword arguments with position and color values.

`setOuterCircleColor(**color_positions)`

Description:
Sets custom colors for the outer circle gradient.
Parameters:
- color_positions: Keyword arguments with position and color values.

`updateValue(value)`

Description:
Updates the gauge value with needle movement.
Parameters:
- value: New value to display.
Example:
```
gauge.updateValue(150)
```

`setScaleStartAngle(angle)`

Description:
Sets the starting angle for the scale.
Parameters:
- angle: Starting angle in degrees.
Example:
```
gauge.setScaleStartAngle(135)
```

`setTotalScaleAngleSize(angle)`

Description:
Sets the total angle size for the scale arc.
Parameters:
- angle: Total angle size in degrees.
Example:
```
gauge.setTotalScaleAngleSize(270)
```

`setAngleOffset(offset)`

Description:
Sets the angle offset for scale rotation.
Parameters:
- offset: Offset angle in degrees.
Example:
```
gauge.setAngleOffset(0)
```

Usage Example

Basic Gauge Setup

from Custom_Widgets.AnalogGaugeWidget import AnalogGaugeWidget

# Create gauge widget
gauge = AnalogGaugeWidget()

# Configure basic properties
gauge.minValue = 0
gauge.maxValue = 100
gauge.scalaCount = 10
gauge.units = "km/h"

# Set initial value
gauge.value = 50

# Apply a theme
gauge.setGaugeTheme(5)

Custom Styling

# Create custom color theme
gauge.setCustomGaugeTheme(
    color1="#002523",
    color2="#990008", 
    color3="#00F6E9"
)

# Customize individual elements
gauge.setNeedleColor(QColor("#FF0000"))
gauge.setNeedleColorOnDrag(QColor("#00FF00"))
gauge.setScaleValueColor(QColor("#FFFFFF"))
gauge.setDisplayValueColor(QColor("#00FF00"))
gauge.setBigScaleColor(QColor("#005275"))
gauge.setFineScaleColor(QColor("#005275"))

# Configure scale appearance
gauge.setScaleStartAngle(135)
gauge.setTotalScaleAngleSize(270)
gauge.setAngleOffset(0)

Interactive Value Updates

# Update value with animation
gauge.updateValue(75)

# Connect to value changes
def on_value_changed(new_value):
    print(f"Gauge value changed to: {new_value}")

gauge.valueChanged.connect(on_value_changed)

Advanced Configuration

# Configure all display options
gauge.setEnableBarGraph(True)
gauge.setEnableValueText(True)
gauge.setEnableCenterPoint(True)
gauge.setEnableNeedlePolygon(True)
gauge.setEnableScaleText(True)
gauge.setEnableScalePolygon(True)
gauge.setEnableBigScaleGrid(True)
gauge.setEnableFineScaleGrid(True)

# Set gauge dimensions
gauge.setGaugeColorOuterRadiusFactor(1000)  # 0-1000
gauge.setGaugeColorInnerRadiusFactor(900)   # 0-1000

JSON Styling Integration

{
  "AnalogGaugeWidget": [
    {
      "name": "speedGauge",
      "units": "km/h",
      "minValue": 0,
      "maxValue": 200,
      "scalaCount": 10,
      "gaugeTheme": 5,
      "enableBarGraph": true,
      "enableValueText": true,
      "enableCenterPoint": true,
      "customGaugeTheme": [
        {
          "color1": "#002523",
          "color2": "#990008", 
          "color3": "#00F6E9"
        }
      ]
    }
  ]
}

Signals

`valueChanged(int)`

Description:
Emitted when the gauge value changes, either programmatically or via user interaction.
Parameters:
- value: The new gauge value.

Example:

gauge.valueChanged.connect(lambda value: print(f"New value: {value}"))

Design Features

Visual Elements

Needle Pointer: Smoothly animated needle with drag interaction
Scale Markers: Major and minor scale divisions with customizable colors
Value Display: Central digital value readout with units
Bar Graph: Colored background indicating value range
Center Point: Decorative center pivot with gradient effects

Interaction

Mouse Drag: Click and drag to adjust value
Visual Feedback: Needle color changes during interaction
Value Snapping: Smooth value transitions with configurable snap zones

Themes

11 Preset Themes: Range from classic to modern designs
Custom Themes: Complete color customization
Gradient Support: Multi-color gradients for all elements

Additional Notes

Performance:
Efficient rendering with minimal resource usage.
Responsive Design:
Automatically scales to container size.
Font Support:
Includes custom font support for scale and value text.
Cross-Platform:
Consistent appearance across different operating systems.
Accessibility:
Clear visual hierarchy and intuitive interaction.

The AnalogGaugeWidget is perfect for dashboards, control panels, monitoring applications, and any interface requiring intuitive analog-style value representation with modern styling and smooth interactions.

API reference

Generated from the widget's live metaobject — do not edit by hand.

Properties

Property	Type	Default
`themeNumber`	`int`	—
`units`	`string`	—
`needleColor`	`color`	—
`needleColorOnDrag`	`color`	—
`scaleValueColor`	`color`	—
`fineScaleColor`	`color`	—
`displayValueColor`	`color`	—
`centerPointColor`	`color`	—
`value`	`int`	—
`minValue`	`int`	—
`maxValue`	`int`	—
`scaleFontFamily`	`QFont`	—
`valueFontFamily`	`QFont`	—
`bigScaleColor`	`color`	—
`enableNeedlePolygon`	`bool`	—
`enableScaleText`	`bool`	—
`enableBarGraph`	`bool`	—
`enableValueText`	`bool`	—
`enableCenterPoint`	`bool`	—
`enableScalePolygon`	`bool`	—
`enableBigScaleGrid`	`bool`	—
`enableFineScaleGrid`	`bool`	—
`scalaCount`	`int`	—
`scaleStartAngle`	`float`	—
`totalScaleAngleSize`	`float`	—
`angleOffset`	`float`	—
`gaugeColorOuterRadiusFactor`	`float`	—
`gaugeColorInnerRadiusFactor`	`float`	—

Signals

Signal
`valueChanged(int)`

Methods

Method	Description
`angleOffset(args, *kwargs)`	Angle offset.
`bigScaleColor(args, *kwargs)`	Big scale color.
`centerPointColor(args, *kwargs)`	Center point color.
`center_horizontal(value)`	Center horizontal.
`center_vertical(value)`	Center vertical.
`change_value_needle_style(design)`	Change value needle style.
`create_fine_scaled_marker()`	Create fine scaled marker.
`create_polygon_pie(outer_radius, inner_raduis, start, lenght, bar_graph=True)`	Create polygon pie.
`create_scale_marker_values_text()`	Create scale marker values text.
`create_units_text()`	Create units text.
`create_values_text()`	Create values text.
`displayValueColor(args, *kwargs)`	Display value color.
`draw_big_needle_center_point(diameter=30)`	Draw big needle center point.
`draw_big_scaled_marker()`	Draw big scaled marker.
`draw_filled_polygon(outline_pen_with=0)`	Draw filled polygon.
`draw_icon_image()`	Draw icon image.
`draw_needle()`	Draw needle.
`draw_outer_circle(diameter=30)`	Draw outer circle.
`enableBarGraph(args, *kwargs)`	Enable the bar graph.
`enableBigScaleGrid(args, *kwargs)`	Enable the big scale grid.
`enableCenterPoint(args, *kwargs)`	Enable the center point.
`enableFineScaleGrid(args, *kwargs)`	Enable the fine scale grid.
`enableNeedlePolygon(args, *kwargs)`	Enable the needle polygon.
`enableScalePolygon(args, *kwargs)`	Enable the scale polygon.
`enableScaleText(args, *kwargs)`	Enable the scale text.
`enableValueText(args, *kwargs)`	Enable the value text.
`fineScaleColor(args, *kwargs)`	Fine scale color.
`gaugeColorInnerRadiusFactor(args, *kwargs)`	Gauge color inner radius factor.
`gaugeColorOuterRadiusFactor(args, *kwargs)`	Gauge color outer radius factor.
`maxValue(args, *kwargs)`	Max value.
`minValue(args, *kwargs)`	Min value.
`needleColor(args, *kwargs)`	Needle color.
`needleColorOnDrag(args, *kwargs)`	Needle color on drag.
`rescale_method()`	Rescale method.
`scalaCount(args, *kwargs)`	Scala count.
`scaleFontFamily(args, *kwargs)`	Scale font family.
`scaleStartAngle(args, *kwargs)`	Scale start angle.
`scaleValueColor(args, *kwargs)`	Scale value color.
`setAngleOffset(offset: float)`	Set the angle offset.
`setBigScaleColor(color: PySide6.QtGui.QColor)`	Set the big scale color.
`setCenterPointColor(color: PySide6.QtGui.QColor)`	Set the center point color.
`setCustomGaugeTheme(custom_theme: list)`	Set the custom gauge theme.
`setDisplayValueColor(color: PySide6.QtGui.QColor)`	Set the display value color.
`setEnableBarGraph(enable=True)`	Set the enable bar graph.
`setEnableBigScaleGrid(enable=True)`	Set the enable big scale grid.
`setEnableCenterPoint(enable=True)`	Set the enable center point.
`setEnableFineScaleGrid(enable=True)`	Set the enable fine scale grid.
`setEnableNeedlePolygon(enable: bool = True)`	Set the enable needle polygon.
`setEnableScalePolygon(enable=True)`	Set the enable scale polygon.
`setEnableScaleText(enable=True)`	Set the enable scale text.
`setEnableValueText(enable=True)`	Set the enable value text.
`setFineScaleColor(color: PySide6.QtGui.QColor)`	Set the fine scale color.
`setGaugeColorInnerRadiusFactor(value)`	Set the gauge color inner radius factor.
`setGaugeColorOuterRadiusFactor(value)`	Set the gauge color outer radius factor.
`setGaugeTheme(Theme=0)`	Set the gauge theme.
`setMaxValue(value: int)`	Set the max value.
`setMinValue(value: int)`	Set the min value.
`setMouseTracking(flag)`	Set the mouse tracking.
`setNeedleCenterColor(**color_positions)`	Set the needle center color.
`setNeedleColor(color: PySide6.QtGui.QColor)`	Set the needle color.
`setNeedleColorOnDrag(color: PySide6.QtGui.QColor)`	Set the needle color on drag.
`setOuterCircleColor(**color_positions)`	Set the outer circle color.
`setScalaCount(count)`	Set the scala count.
`setScaleFontFamily(font: PySide6.QtGui.QFont	str)`
`setScalePolygonColor(**color_positions)`	Set the scale polygon color.
`setScaleStartAngle(value)`	Set the scale start angle.
`setScaleValueColor(color: PySide6.QtGui.QColor)`	Set the scale value color.
`setTotalScaleAngleSize(value: float)`	Set the total scale angle size.
`setUnits(value: str)`	Set the units.
`setValue(value: int)`	Set the value.
`setValueFontFamily(font: PySide6.QtGui.QFont	str)`
`themeNumber(args, *kwargs)`	Theme number.
`totalScaleAngleSize(args, *kwargs)`	Total scale angle size.
`units(args, *kwargs)`	Units.
`value(args, *kwargs)`	Value.
`valueChanged(...)`	Value changed.
`valueFontFamily(args, *kwargs)`	Value font family.

Overview​

Constructor​

Key Properties​

themeNumber (int)​

units (str)​

value (int)​

minValue (int)​

maxValue (int)​

scalaCount (int)​

enableBarGraph (bool)​

enableValueText (bool)​

enableCenterPoint (bool)​

Methods​

setGaugeTheme(theme_number)​

setCustomGaugeTheme(color1, color2, color3)​

setScalePolygonColor(**color_positions)​

setNeedleCenterColor(**color_positions)​

setOuterCircleColor(**color_positions)​

updateValue(value)​

setScaleStartAngle(angle)​

setTotalScaleAngleSize(angle)​

setAngleOffset(offset)​

Usage Example​

Basic Gauge Setup​

Custom Styling​

Interactive Value Updates​

Advanced Configuration​

JSON Styling Integration​

Signals​

valueChanged(int)​

Design Features​

Visual Elements​

Interaction​

Themes​

Additional Notes​

API reference​

Properties​

Signals​

Methods​

Overview

Constructor

Key Properties

`themeNumber` (int)

`units` (str)

`value` (int)

`minValue` (int)

`maxValue` (int)

`scalaCount` (int)

`enableBarGraph` (bool)

`enableValueText` (bool)

`enableCenterPoint` (bool)

Methods

`setGaugeTheme(theme_number)`

`setCustomGaugeTheme(color1, color2, color3)`

`setScalePolygonColor(**color_positions)`

`setNeedleCenterColor(**color_positions)`

`setOuterCircleColor(**color_positions)`

`updateValue(value)`

`setScaleStartAngle(angle)`

`setTotalScaleAngleSize(angle)`

`setAngleOffset(offset)`

Usage Example

Basic Gauge Setup

Custom Styling

Interactive Value Updates

Advanced Configuration

JSON Styling Integration

Signals

`valueChanged(int)`

Design Features

Visual Elements

Interaction

Themes

Additional Notes

API reference

Properties

Signals

Methods