Metadata-Version: 2.4
Name: indicatorlabel
Version: 0.9.1
Summary: A PySide6 custom widget that displays a text label with a configurable indicator.
License-Expression: BSD-3-Clause
License-File: LICENSE
Keywords: PySide6,Qt,custom widget,indicator,label,GUI
Author: Nita Vesa
Author-email: nita.vesa@outlook.com
Requires-Python: >=3.10,<3.15
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Environment :: Plugins
Requires-Dist: pyside6 (>=6.10.0,<7.0.0)
Description-Content-Type: text/markdown

# 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.

![IndicatorLabel Example](extra/IndicatorLabel.png)

## 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]( https://doc.qt.io/qtforpython-6/PySide6/QtGui/QColor.html#PySide6.QtGui.QColor.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

```bash
# 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

```python
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

```python
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

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

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

### Font Customization

```python
from PySide6.QtGui import QFont

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

### StyleSheet Support

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

### Complete Example

```python
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:

   ```bash
   # Linux/macOS
   export PYSIDE_DESIGNER_PLUGINS=/path/to/indicatorlabel

   # Windows
   set PYSIDE_DESIGNER_PLUGINS=C:\path\to\indicatorlabel
   ```

2. **Launch Designer:**

   ```bash
   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:

```bash
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:

```python
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:

```bash
# 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](LICENSE) file for details.

