IndicatorLabel

A non-interactive custom widget for PySide6 that displays a text label with a configurable indicator.

The indicator can be positioned on the left or right side of the text and changes color based on the checked property.

Features

• Configurable indicator position - indicator on left or right side of the label.
• ON/OFF state with customizable colors - Bright red (checked) / Dark red (unchecked) by default.
• Flexible color input - Accepts QColor objects or hex color or natural language strings (e.g., "#FF0000" or "red") See QtColor.fromString
• StyleSheet support - Override colors via qproperty-* directives.
• Configurable sizing - Indicator size and spacing from the label text are adjustable.
• PySide6 Designer support - Use in Qt Designer for visual form editing.

Installation

Requirements

• Python 3.13+
• PySide6 6.11.0+

Install from source

# Clone the repository
git clone <repository-url>
cd indicatorlabel

# Install with Poetry
poetry install

# Or install in development mode with pip
pip install -e .

Usage

Quick Start

from PySide6.QtWidgets import QApplication
from indicatorlabel import IndicatorLabel
from PySide6.QtCore import Qt

app = QApplication([])

# Create the widget
label = IndicatorLabel()
label.text = "System Status: Online"
label.checked = True  # bright red
label.setLayoutDirection(Qt.LayoutDirection.LeftToRight)

label.show()
app.exec()

Custom Colors

from PySide6.QtGui import QColor

# Using QColor
label.on_color = QColor(255, 0, 0)      # Bright red when checked
label.off_color = QColor(50, 0, 0)      # Dark red when unchecked

# Using hex strings
label.on_color = "#FF0000"
label.off_color = "#320000"

# Using natural language strings
label.on_color = "green"
label.off_color = "blue"

Sizing and Spacing

# Indicator diameter in pixels (minimum: 4)
label.indicator_size = 16

# Space between indicator and text in pixels
label.spacing = 8

Font Customization

from PySide6.QtGui import QFont

font = QFont("Arial", 14, QFont.Weight.Bold)
label.setFont(font)

StyleSheet Support

# Override colors via stylesheet
label.setStyleSheet("""
    IndicatorLabel {
        qproperty-on_color: #00FF00;
        qproperty-off_color: #003300;
    }
""")

Complete Example

import sys
from PySide6.QtWidgets import QApplication, QVBoxLayout, QWidget
from PySide6.QtGui import QFont, QColor
from indicatorlabel import IndicatorLabel

class MyWindow(QWidget):
    def __init__(self):
        super().__init__()
        layout = QVBoxLayout(self)

        # Active status indicator
        active_label = IndicatorLabel()
        active_label.text = "System: Active"
        active_label.checked = True
        active_label.setLayoutDirection(Qt.LayoutDirection.LeftToRight)
        active_label.setFont(QFont("Segoe UI", 12))
        layout.addWidget(active_label)

        # Inactive status with custom colors
        inactive_label = IndicatorLabel()
        inactive_label.text = "Backup: Standby"
        inactive_label.checked = False
        inactive_label.setLayoutDirection(Qt.LayoutDirection.RightToLeft)
        inactive_label.on_color = QColor(0, 150, 0)      # Green when active
        inactive_label.off_color = QColor(0, 40, 0)      # Dark green when inactive
        layout.addWidget(inactive_label)

        self.show()

if __name__ == "__main__":
    app = QApplication(sys.argv)
    window = MyWindow()
    sys.exit(app.exec())

You can also find a full interactive example in the extra-directory.

PySide6 Designer Integration

IndicatorLabel includes a plugin for PySide6 Designer (pyside6-designer), allowing you to design forms visually.

Setting Up the Designer Plugin

1. Set the environment variable to point to the plugin directory:

   # Linux/macOS
   export PYSIDE_DESIGNER_PLUGINS=/path/to/indicatorlabel
   
   # Windows
   set PYSIDE_DESIGNER_PLUGINS=C:\path\to\indicatorlabel
   

2. Launch Designer:

   pyside6-designer
   

How It Works

PySide6 Designer looks for filenames matching register*.py from the directories specified by PYSIDE_DESIGNER_PLUGINS that then load the plugin into the Designer. This project uses registerwidget.py for this.

Loading Designer UI Files

After designing in Designer, generate Python code for a single UI-file with:

pyside6-uic myform.ui -o ui_myform.py

Or use pyside6-project to compile all the project-related QRC- and UI-files. See PySide6-documentation for details.

Use in your application:

from PySide6.QtWidgets import QApplication, QWidget
from ui_myform import Ui_MyForm

class MyWindow(QWidget):
    def __init__(self):
        super().__init__()
        self.ui = Ui_MyForm()
        self.ui.setupUi(self)
        # Access the IndicatorLabel:
        self.ui.indicatorLabel.setText("Updated")

if __name__ == "__main__":
    app = QApplication([])
    window = MyWindow()
    window.show()
    app.exec()

API Reference

Properties

Property	Type	Description
text	str	The label text displayed next to the indicator
checked	bool	True for ON state, False for OFF state
on_color	QColor | str	indicator color when checked=True
off_color	QColor | str	indicator color when checked=False
indicator_size	int	Diameter of the indicator in pixels (minimum: 4)
spacing	int	Pixels between indicator and text

Methods

Method	Description
isChecked() -> bool	Get the current checked state
setChecked(bool)	Set the checked state
setIndicatorSize(int)	Set the indicator diameter
setSpacing(int)	Set the indicator-text spacing
setOnColor(QColor | str)	Set the ON state color
setOffColor(QColor | str)	Set the OFF state color
setFont(QFont)	Set the label font
font() -> QFont	Get the current font

Signals

Signal	Description
stateChanged(bool)	Emitted when the checked state changes

Running Examples

The repository includes example scripts to help you get started:

# Built-in demo (run from project root)
poetry run python -m indicatorlabel

# Interactive example with controls
poetry run python extra/example.py

License

This project is licensed under the BSD 3-Clause License - see the LICENSE file for details.