Label Widgets¶

Interactive and styled label widgets: clickable tags, framed labels, hover icons, and LED status indicators.

ClickableTagLabel¶

A QFrame that behaves as a toggleable tag. Clicking it switches between a selected and an unselected state and emits the corresponding signals.

Signals:

Signal	Signature	Emitted when
`clicked`	`()`	The tag is clicked
`toggle_keyword`	`(str)`	The tag is toggled; the string is the tag's `name`
`stateChanged`	`(bool)`	The `enabled` state changes; `True` means selected

Constructor parameters:

Parameter	Type	Default	Description
`name`	`str`	`""`	Text displayed inside the tag
`enabled`	`bool`	`False`	Initial selected state
`status_color`	`str`	`"#0078d4"`	Color of the text when selected (any valid CSS color)
`min_width`	`int \\| None`	`None`	Minimum width; auto-calculated if `None`
`min_height`	`int \\| None`	`None`	Minimum height; auto-calculated if `None`
`parent`	`QWidget \\| None`	`None`	Parent widget

Properties:

Property	Type	Description
`name`	`str`	Gets or sets the tag text; updates the display immediately
`enabled`	`bool`	Gets or sets the selected state; emits `stateChanged` on change
`status_color`	`str`	Gets or sets the color used when selected
`min_width`	`int \\| None`	Gets or sets the minimum width
`min_height`	`int \\| None`	Gets or sets the minimum height

Methods:

Method	Signature	Description
`refreshStyle()`	`() -> None`	Re-applies the QSS stylesheet

Keyboard support: Space, Enter, and Return keys toggle the tag when it has focus.

Example:

from PySide6.QtWidgets import QApplication
from ezqt_widgets import ClickableTagLabel

app = QApplication([])

tag = ClickableTagLabel(name="Python", enabled=False, status_color="#0078d4")
tag.stateChanged.connect(lambda selected: print(f"Selected: {selected}"))
tag.toggle_keyword.connect(lambda kw: print(f"Toggled: {kw}"))
tag.show()

app.exec()

ClickableTagLabel ¶

ClickableTagLabel(name: str = '', enabled: bool = False, status_color: str = '#0078d4', min_width: int | None = None, min_height: int | None = None, parent: WidgetParent = None, *args: Any, **kwargs: Any)

Bases: QFrame

Tag-like clickable label with toggleable state.

Features

Clickable tag with enabled/disabled state
Emits signals on click and state change
Customizable text, font, min width/height
Customizable status color (traditional name or hex)
QSS-friendly (type/class/status properties)
Automatic minimum size calculation
Keyboard focus and accessibility

PARAMETER	DESCRIPTION
`name`	Text to display in the tag (default: ""). TYPE: `str` DEFAULT: `''`
`enabled`	Initial state (default: False). TYPE: `bool` DEFAULT: `False`
`status_color`	Color when selected (default: "#0078d4"). TYPE: `str` DEFAULT: `'#0078d4'`
`min_width`	Minimum width (default: None, auto-calculated). TYPE: `int \| None` DEFAULT: `None`
`min_height`	Minimum height (default: None, auto-calculated). TYPE: `int \| None` DEFAULT: `None`
`parent`	Parent widget (default: None). TYPE: `WidgetParent` DEFAULT: `None`
`*args`	Additional arguments passed to QFrame. TYPE: `Any` DEFAULT: `()`
`**kwargs`	Additional keyword arguments passed to QFrame. TYPE: `Any` DEFAULT: `{}`

Signals

clicked(): Emitted when the tag is clicked. toggleKeyword(str): Emitted with the tag name when toggled. stateChanged(bool): Emitted when the enabled state changes.

Example

from ezqt_widgets import ClickableTagLabel tag = ClickableTagLabel(name="Python", enabled=False, status_color="#0078d4") tag.stateChanged.connect(lambda state: print(f"Active: {state}")) tag.toggleKeyword.connect(lambda kw: print(f"Toggled: {kw}")) tag.show()

Initialize the clickable tag label.

Source code in src/ezqt_widgets/widgets/label/clickable_tag_label.py

def __init__(
    self,
    name: str = "",
    enabled: bool = False,
    status_color: str = "#0078d4",
    min_width: int | None = None,
    min_height: int | None = None,
    parent: WidgetParent = None,
    *args: Any,
    **kwargs: Any,
) -> None:
    """Initialize the clickable tag label."""
    super().__init__(parent, *args, **kwargs)

    self.setProperty("type", "ClickableTagLabel")

    # Initialize properties
    self._name: str = name
    self._enabled: bool = enabled
    self._status_color: str = status_color
    self._min_width: int | None = min_width
    self._min_height: int | None = min_height

    # Setup UI
    self._setup_ui()
    self._update_display()

name `property` `writable` ¶

name: str

Get the tag text.

RETURNS	DESCRIPTION
`str`	The current tag text.

enabled `property` `writable` ¶

enabled: bool

Get the enabled state.

RETURNS	DESCRIPTION
`bool`	True if enabled, False otherwise.

status_color `property` `writable` ¶

status_color: str

Get the status color.

RETURNS	DESCRIPTION
`str`	The current status color.

min_width `property` `writable` ¶

min_width: int | None

Get the minimum width.

RETURNS	DESCRIPTION
`int \| None`	The minimum width, or None if not set.

min_height `property` `writable` ¶

min_height: int | None

Get the minimum height.

RETURNS	DESCRIPTION
`int \| None`	The minimum height, or None if not set.

mousePressEvent ¶

mousePressEvent(event: QMouseEvent) -> None

Handle mouse press events.

PARAMETER	DESCRIPTION
`event`	The mouse event. TYPE: `QMouseEvent`

Source code in src/ezqt_widgets/widgets/label/clickable_tag_label.py

def mousePressEvent(self, event: QMouseEvent) -> None:
    """Handle mouse press events.

    Args:
        event: The mouse event.
    """
    if event.button() == Qt.MouseButton.LeftButton:
        self.enabled = not self.enabled
        self.clicked.emit()
        self.toggleKeyword.emit(self._name)
    super().mousePressEvent(event)

keyPressEvent ¶

keyPressEvent(event: QKeyEvent) -> None

Handle key press events.

PARAMETER	DESCRIPTION
`event`	The key event. TYPE: `QKeyEvent`

Source code in src/ezqt_widgets/widgets/label/clickable_tag_label.py

def keyPressEvent(self, event: QKeyEvent) -> None:
    """Handle key press events.

    Args:
        event: The key event.
    """
    if event.key() in [Qt.Key.Key_Space, Qt.Key.Key_Return, Qt.Key.Key_Enter]:
        self.enabled = not self.enabled
        self.clicked.emit()
        self.toggleKeyword.emit(self._name)
    else:
        super().keyPressEvent(event)

sizeHint ¶

sizeHint() -> QSize

Return the recommended size for the widget.

RETURNS	DESCRIPTION
`QSize`	The recommended size.

Source code in src/ezqt_widgets/widgets/label/clickable_tag_label.py

def sizeHint(self) -> QSize:
    """Return the recommended size for the widget.

    Returns:
        The recommended size.
    """
    return QSize(80, 24)

minimumSizeHint ¶

minimumSizeHint() -> QSize

Return the minimum size for the widget.

RETURNS	DESCRIPTION
`QSize`	The minimum size hint.

Source code in src/ezqt_widgets/widgets/label/clickable_tag_label.py

def minimumSizeHint(self) -> QSize:
    """Return the minimum size for the widget.

    Returns:
        The minimum size hint.
    """
    font_metrics = self._label.fontMetrics()
    text_width = font_metrics.horizontalAdvance(self._name)
    min_width = self._min_width if self._min_width is not None else text_width + 16
    min_height = (
        self._min_height
        if self._min_height is not None
        else max(font_metrics.height() + 8, 20)
    )

    return QSize(min_width, min_height)

refreshStyle ¶

refreshStyle() -> None

Refresh the widget style.

Useful after dynamic stylesheet changes.

Source code in src/ezqt_widgets/widgets/label/clickable_tag_label.py

def refreshStyle(self) -> None:
    """Refresh the widget style.

    Useful after dynamic stylesheet changes.
    """
    self.style().unpolish(self)
    self.style().polish(self)
    self.update()

FramedLabel¶

A QFrame containing a QLabel, providing the layout and styling flexibility of a frame with the simplicity of a label interface.

Signals:

Signal	Signature	Emitted when
`textChanged`	`(str)`	The `text` property is set to a different value

Constructor parameters:

Parameter	Type	Default	Description
`text`	`str`	`""`	Initial label text
`parent`	`QWidget \\| None`	`None`	Parent widget
`alignment`	`Qt.AlignmentFlag`	`Qt.AlignmentFlag.AlignCenter`	Text alignment
`style_sheet`	`str \\| None`	`None`	Custom stylesheet applied to the QFrame; defaults to transparent background
`min_width`	`int \\| None`	`None`	Minimum width
`min_height`	`int \\| None`	`None`	Minimum height

Properties:

Property	Type	Description
`text`	`str`	Gets or sets the label text; emits `textChanged` on change
`alignment`	`Qt.AlignmentFlag`	Gets or sets the text alignment
`min_width`	`int \\| None`	Gets or sets the minimum width
`min_height`	`int \\| None`	Gets or sets the minimum height

Methods:

Method	Signature	Description
`refreshStyle()`	`() -> None`	Re-applies the QSS stylesheet

Example:

from PySide6.QtWidgets import QApplication
from ezqt_widgets import FramedLabel

app = QApplication([])

label = FramedLabel(text="Section Title", min_height=30)
label.textChanged.connect(lambda t: print(f"New text: {t}"))
label.text = "Updated Title"
label.show()

app.exec()

FramedLabel ¶

FramedLabel(text: str = '', parent: WidgetParent = None, alignment: AlignmentFlag = AlignCenter, style_sheet: str | None = None, min_width: int | None = None, min_height: int | None = None, *args: Any, **kwargs: Any)

Bases: QFrame

Flexible label widget based on QFrame for advanced styling.

This widget encapsulates a QLabel inside a QFrame, allowing you to benefit from QFrame's styling and layout capabilities while providing a simple interface for text display, alignment, and dynamic style updates.

Features

Property-based access to the label text and alignment
Emits a textChanged(str) signal when the text changes
Allows custom stylesheet injection for advanced appearance
Suitable for use as a header, section label, or any styled context

PARAMETER	DESCRIPTION
`text`	The initial text to display in the label (default: ""). TYPE: `str` DEFAULT: `''`
`parent`	The parent widget (default: None). TYPE: `WidgetParent` DEFAULT: `None`
`alignment`	The alignment of the label text (default: Qt.AlignmentFlag.AlignCenter). TYPE: `AlignmentFlag` DEFAULT: `AlignCenter`
`style_sheet`	Custom stylesheet to apply to the QFrame (default: None, uses transparent background). TYPE: `str \| None` DEFAULT: `None`
`min_width`	Minimum width constraint for the widget (default: None). TYPE: `int \| None` DEFAULT: `None`
`min_height`	Minimum height constraint for the widget (default: None). TYPE: `int \| None` DEFAULT: `None`
`*args`	Additional arguments passed to QFrame. TYPE: `Any` DEFAULT: `()`
`**kwargs`	Additional keyword arguments passed to QFrame. TYPE: `Any` DEFAULT: `{}`

Signals

textChanged(str): Emitted when the label text changes.

Example

from ezqt_widgets import FramedLabel label = FramedLabel(text="Section Title", min_height=30) label.textChanged.connect(lambda t: print(f"New text: {t}")) label.text = "Updated Title" label.show()

Initialize the framed label.

Source code in src/ezqt_widgets/widgets/label/framed_label.py

def __init__(
    self,
    text: str = "",
    parent: WidgetParent = None,
    alignment: Qt.AlignmentFlag = Qt.AlignmentFlag.AlignCenter,
    style_sheet: str | None = None,
    min_width: int | None = None,
    min_height: int | None = None,
    *args: Any,
    **kwargs: Any,
) -> None:
    """Initialize the framed label."""
    super().__init__(parent, *args, **kwargs)
    self.setProperty("type", "FramedLabel")

    # Initialize properties
    self._min_width: int | None = min_width
    self._min_height: int | None = min_height
    self._alignment: Qt.AlignmentFlag = alignment

    # Setup styling
    self.setStyleSheet(style_sheet or "background-color: transparent;")
    self.setSizePolicy(QSizePolicy.Policy.Expanding, QSizePolicy.Policy.Expanding)

    # Setup layout
    layout = QVBoxLayout(self)
    layout.setSpacing(0)
    layout.setContentsMargins(0, 0, 0, 0)
    layout.setAlignment(alignment)

    # Setup label
    self._label = QLabel(text, self)
    self._label.setAlignment(alignment)
    layout.addWidget(self._label)

text `property` `writable` ¶

text: str

Get or set the label text.

RETURNS	DESCRIPTION
`str`	The current label text.

alignment `property` `writable` ¶

alignment: AlignmentFlag

Get or set the alignment of the label.

RETURNS	DESCRIPTION
`AlignmentFlag`	The current alignment.

min_width `property` `writable` ¶

min_width: int | None

Get or set the minimum width.

RETURNS	DESCRIPTION
`int \| None`	The minimum width, or None if not set.

min_height `property` `writable` ¶

min_height: int | None

Get or set the minimum height.

RETURNS	DESCRIPTION
`int \| None`	The minimum height, or None if not set.

minimumSizeHint ¶

minimumSizeHint() -> QSize

Get the minimum size hint for the widget.

RETURNS	DESCRIPTION
`QSize`	The minimum size hint.

Source code in src/ezqt_widgets/widgets/label/framed_label.py

def minimumSizeHint(self) -> QSize:
    """Get the minimum size hint for the widget.

    Returns:
        The minimum size hint.
    """
    font_metrics = self.fontMetrics()
    text_width = font_metrics.horizontalAdvance(self.text)
    text_height = font_metrics.height()

    content_width = text_width + 16  # 8px padding on each side
    content_height = text_height + 8  # 4px padding top/bottom

    min_width = self._min_width if self._min_width is not None else content_width
    min_height = (
        self._min_height if self._min_height is not None else content_height
    )

    return QSize(max(min_width, content_width), max(min_height, content_height))

refreshStyle ¶

refreshStyle() -> None

Refresh the widget's style.

Useful after dynamic stylesheet changes.

Source code in src/ezqt_widgets/widgets/label/framed_label.py

def refreshStyle(self) -> None:
    """Refresh the widget's style.

    Useful after dynamic stylesheet changes.
    """
    self.style().unpolish(self)
    self.style().polish(self)
    self.update()

HoverLabel¶

A QLabel that shows a floating icon in its right margin when the mouse hovers over it. Clicking the icon emits hoverIconClicked.

Signals:

Signal	Signature	Emitted when
`hoverIconClicked`	`()`	The hover icon area is clicked with the left mouse button

Constructor parameters:

Parameter	Type	Default	Description
`parent`	`QWidget \\| None`	`None`	Parent widget
`icon`	`QIcon \\| QPixmap \\| str \\| None`	`None`	Icon to display on hover; supports paths, URLs, and SVG
`text`	`str`	`""`	Label text
`opacity`	`float`	`0.5`	Opacity of the hover icon (0.0–1.0)
`icon_size`	`QSize \\| tuple[int, int]`	`QSize(16, 16)`	Size of the hover icon
`icon_color`	`QColor \\| str \\| None`	`None`	Optional color overlay applied to the icon
`icon_padding`	`int`	`8`	Pixels of right padding reserved for the icon
`icon_enabled`	`bool`	`True`	Whether the hover icon is shown
`min_width`	`int \\| None`	`None`	Minimum width

Properties:

Property	Type	Description
`opacity`	`float`	Gets or sets the icon opacity
`hover_icon`	`QIcon \\| None`	Gets or sets the hover icon; `None` hides it
`icon_size`	`QSize`	Gets or sets the icon size
`icon_color`	`QColor \\| str \\| None`	Gets or sets the color overlay
`icon_padding`	`int`	Gets or sets the right-side padding in pixels
`icon_enabled`	`bool`	Gets or sets whether the icon is shown on hover

Methods:

Method	Signature	Description
`clearIcon()`	`() -> None`	Removes the hover icon and clears the right padding
`refreshStyle()`	`() -> None`	Re-applies the QSS stylesheet

URL icons

Icon URLs are fetched asynchronously. The icon appears after the network response completes.

Example:

from PySide6.QtWidgets import QApplication
from ezqt_widgets import HoverLabel

app = QApplication([])

label = HoverLabel(
    text="Hover me",
    icon="https://img.icons8.com/?size=100&id=8329&format=png&color=000000",
    opacity=0.7,
    icon_color="#FF4444",
)
label.hoverIconClicked.connect(lambda: print("icon clicked"))
label.show()

app.exec()

HoverLabel ¶

HoverLabel(parent: WidgetParent = None, icon: IconSourceExtended = None, text: str = '', opacity: float = 0.5, icon_size: SizeType = QSize(16, 16), icon_color: ColorType | None = None, icon_padding: int = 8, icon_enabled: bool = True, min_width: int | None = None, *args: Any, **kwargs: Any)

Bases: QLabel

Interactive QLabel that displays a floating icon when hovered.

This widget is useful for adding contextual actions or visual cues to labels in a Qt interface.

Features

Displays a custom icon on hover with configurable opacity, size, color overlay, and padding
Emits a hoverIconClicked signal when the icon is clicked
Handles mouse events and cursor changes for better UX
Text and icon can be set at construction or via properties
Icon can be enabled/disabled dynamically
Supports PNG/JPG and SVG icons (local, resource, URL)
Robust error handling for icon loading

Use cases

Contextual action button in a label
Info or help icon on hover
Visual feedback for interactive labels

PARAMETER	DESCRIPTION
`parent`	The parent widget (default: None). TYPE: `WidgetParent` DEFAULT: `None`
`icon`	The icon to display on hover (ThemeIcon, QIcon, QPixmap, path, resource, URL, or SVG). TYPE: `IconSourceExtended` DEFAULT: `None`
`text`	The label text (default: ""). TYPE: `str` DEFAULT: `''`
`opacity`	The opacity of the hover icon (default: 0.5). TYPE: `float` DEFAULT: `0.5`
`icon_size`	The size of the hover icon (default: QSize(16, 16)). TYPE: `SizeType` DEFAULT: `QSize(16, 16)`
`icon_color`	Optional color overlay to apply to the icon (default: None). TYPE: `ColorType \| None` DEFAULT: `None`
`icon_padding`	Padding (in px) to the right of the text for the icon (default: 8). TYPE: `int` DEFAULT: `8`
`icon_enabled`	Whether the icon is shown on hover (default: True). TYPE: `bool` DEFAULT: `True`
`min_width`	Minimum width of the widget (default: None). TYPE: `int \| None` DEFAULT: `None`
`*args`	Additional arguments passed to QLabel. TYPE: `Any` DEFAULT: `()`
`**kwargs`	Additional keyword arguments passed to QLabel. TYPE: `Any` DEFAULT: `{}`

Signals

hoverIconClicked(): Emitted when the hover icon is clicked.

Example

label = HoverLabel( ... text="Hover me!", ... icon="/path/to/icon.png", ... icon_color="#00BFFF" ... ) label.icon_enabled = True label.icon_padding = 12 label.clearIcon()

Initialize the hover label.

Source code in src/ezqt_widgets/widgets/label/hover_label.py

def __init__(
    self,
    parent: WidgetParent = None,
    icon: IconSourceExtended = None,
    text: str = "",
    opacity: float = 0.5,
    icon_size: SizeType = QSize(16, 16),
    icon_color: ColorType | None = None,
    icon_padding: int = 8,
    icon_enabled: bool = True,
    min_width: int | None = None,
    *args: Any,
    **kwargs: Any,
) -> None:
    """Initialize the hover label."""
    super().__init__(parent, *args, text=text or "", **kwargs)
    self.setProperty("type", "HoverLabel")

    # Initialize properties
    self._opacity: float = opacity
    self._hover_icon: QIcon | None = None
    self._icon_size: QSize = (
        QSize(*icon_size) if isinstance(icon_size, (tuple, list)) else icon_size
    )
    self._icon_color: QColor | str | None = icon_color
    self._icon_padding: int = icon_padding
    self._icon_enabled: bool = icon_enabled
    self._min_width: int | None = min_width
    self._pending_icon_url: str | None = None
    self._url_fetcher: UrlFetcher | None = None

    # State variables
    self._show_hover_icon: bool = False

    # Setup widget
    self.setMouseTracking(True)
    self.setCursor(Qt.CursorShape.ArrowCursor)

    # Set minimum width
    if self._min_width:
        self.setMinimumWidth(self._min_width)

    # Set icon if provided
    if icon:
        self.hover_icon = icon

opacity `property` `writable` ¶

opacity: float

Get the opacity of the hover icon.

RETURNS	DESCRIPTION
`float`	The current opacity level.

hover_icon `property` `writable` ¶

hover_icon: QIcon | None

Get the hover icon.

RETURNS	DESCRIPTION
`QIcon \| None`	The current hover icon, or None if not set.

icon_size `property` `writable` ¶

icon_size: QSize

Get or set the size of the hover icon.

RETURNS	DESCRIPTION
`QSize`	The current icon size.

icon_color `property` `writable` ¶

icon_color: QColor | str | None

Get or set the color overlay of the hover icon.

RETURNS	DESCRIPTION
`QColor \| str \| None`	The current icon color (QColor, str, or None).

icon_padding `property` `writable` ¶

icon_padding: int

Get or set the right padding for the icon.

RETURNS	DESCRIPTION
`int`	The current icon padding in pixels.

icon_enabled `property` `writable` ¶

icon_enabled: bool

Enable or disable the hover icon.

RETURNS	DESCRIPTION
`bool`	True if icon is enabled, False otherwise.

setTheme ¶

setTheme(theme: str) -> None

Update the hover icon color for the given theme.

Can be connected directly to a theme-change signal to keep the icon in sync with the application's color scheme.

PARAMETER	DESCRIPTION
`theme`	The new theme (`"dark"` or `"light"`). TYPE: `str`

Source code in src/ezqt_widgets/widgets/label/hover_label.py

def setTheme(self, theme: str) -> None:
    """Update the hover icon color for the given theme.

    Can be connected directly to a theme-change signal to keep
    the icon in sync with the application's color scheme.

    Args:
        theme: The new theme (``"dark"`` or ``"light"``).
    """
    if isinstance(self._hover_icon, ThemeIcon):
        self._hover_icon.setTheme(theme)
        self.update()

clearIcon ¶

clearIcon() -> None

Remove the hover icon.

Source code in src/ezqt_widgets/widgets/label/hover_label.py

def clearIcon(self) -> None:
    """Remove the hover icon."""
    self._hover_icon = None
    self._update_padding_style()
    self.update()

mouseMoveEvent ¶

mouseMoveEvent(event: QMouseEvent) -> None

Handle mouse movement events.

PARAMETER	DESCRIPTION
`event`	The mouse event. TYPE: `QMouseEvent`

Source code in src/ezqt_widgets/widgets/label/hover_label.py

def mouseMoveEvent(self, event: QMouseEvent) -> None:
    """Handle mouse movement events.

    Args:
        event: The mouse event.
    """
    if not self._icon_enabled or not self._hover_icon:
        super().mouseMoveEvent(event)
        return

    icon_x = self.width() - self._icon_size.width() - 4
    icon_y = (self.height() - self._icon_size.height()) // 2
    icon_rect = QRect(
        icon_x, icon_y, self._icon_size.width(), self._icon_size.height()
    )

    if icon_rect.contains(event.pos()):
        self.setCursor(Qt.CursorShape.PointingHandCursor)
    else:
        self.setCursor(Qt.CursorShape.ArrowCursor)

    super().mouseMoveEvent(event)

mousePressEvent ¶

mousePressEvent(event: QMouseEvent) -> None

Handle mouse press events.

PARAMETER	DESCRIPTION
`event`	The mouse event. TYPE: `QMouseEvent`

Source code in src/ezqt_widgets/widgets/label/hover_label.py

def mousePressEvent(self, event: QMouseEvent) -> None:
    """Handle mouse press events.

    Args:
        event: The mouse event.
    """
    if not self._icon_enabled or not self._hover_icon:
        super().mousePressEvent(event)
        return

    icon_x = self.width() - self._icon_size.width() - 4
    icon_y = (self.height() - self._icon_size.height()) // 2
    icon_rect = QRect(
        icon_x, icon_y, self._icon_size.width(), self._icon_size.height()
    )

    if (
        icon_rect.contains(event.position().toPoint())
        and event.button() == Qt.MouseButton.LeftButton
    ):
        self.hoverIconClicked.emit()
    else:
        super().mousePressEvent(event)

enterEvent ¶

enterEvent(event: QEnterEvent) -> None

Handle enter events.

PARAMETER	DESCRIPTION
`event`	The enter event. TYPE: `QEnterEvent`

Source code in src/ezqt_widgets/widgets/label/hover_label.py

def enterEvent(self, event: QEnterEvent) -> None:
    """Handle enter events.

    Args:
        event: The enter event.
    """
    self._show_hover_icon = True
    self.update()
    super().enterEvent(event)

leaveEvent ¶

leaveEvent(event: QEvent) -> None

Handle leave events.

PARAMETER	DESCRIPTION
`event`	The leave event. TYPE: `QEvent`

Source code in src/ezqt_widgets/widgets/label/hover_label.py

def leaveEvent(self, event: QEvent) -> None:
    """Handle leave events.

    Args:
        event: The leave event.
    """
    self._show_hover_icon = False
    self.setCursor(Qt.CursorShape.ArrowCursor)
    self.update()
    super().leaveEvent(event)

paintEvent ¶

paintEvent(event: QPaintEvent) -> None

Paint the widget.

PARAMETER	DESCRIPTION
`event`	The paint event. TYPE: `QPaintEvent`

Source code in src/ezqt_widgets/widgets/label/hover_label.py

def paintEvent(self, event: QPaintEvent) -> None:
    """Paint the widget.

    Args:
        event: The paint event.
    """
    super().paintEvent(event)

    # Draw hover icon if needed
    if self._show_hover_icon and self._hover_icon and self._icon_enabled:
        painter = QPainter(self)
        painter.setRenderHint(QPainter.RenderHint.Antialiasing)
        painter.setOpacity(self._opacity)

        icon_x = self.width() - self._icon_size.width() - 4
        icon_y = (self.height() - self._icon_size.height()) // 2
        icon_rect = QRect(
            icon_x, icon_y, self._icon_size.width(), self._icon_size.height()
        )

        icon_pixmap = self._hover_icon.pixmap(self._icon_size)

        # Apply color overlay if specified
        if self._icon_color and not icon_pixmap.isNull():
            colored_pixmap = QPixmap(icon_pixmap.size())
            colored_pixmap.fill(Qt.GlobalColor.transparent)
            overlay_painter = QPainter(colored_pixmap)
            overlay_painter.setCompositionMode(
                QPainter.CompositionMode.CompositionMode_SourceOver
            )
            overlay_painter.fillRect(
                colored_pixmap.rect(), QColor(self._icon_color)
            )
            overlay_painter.setCompositionMode(
                QPainter.CompositionMode.CompositionMode_DestinationIn
            )
            overlay_painter.drawPixmap(0, 0, icon_pixmap)
            overlay_painter.end()
            painter.drawPixmap(icon_rect, colored_pixmap)
        elif not icon_pixmap.isNull():
            painter.drawPixmap(icon_rect, icon_pixmap)

resizeEvent ¶

resizeEvent(event: QResizeEvent) -> None

Handle resize events.

PARAMETER	DESCRIPTION
`event`	The resize event. TYPE: `QResizeEvent`

Source code in src/ezqt_widgets/widgets/label/hover_label.py

def resizeEvent(self, event: QResizeEvent) -> None:
    """Handle resize events.

    Args:
        event: The resize event.
    """
    super().resizeEvent(event)
    self.update()

minimumSizeHint ¶

minimumSizeHint() -> QSize

Get the minimum size hint for the widget.

RETURNS	DESCRIPTION
`QSize`	The minimum size hint.

Source code in src/ezqt_widgets/widgets/label/hover_label.py

def minimumSizeHint(self) -> QSize:
    """Get the minimum size hint for the widget.

    Returns:
        The minimum size hint.
    """
    base = super().minimumSizeHint()
    min_width = self._min_width if self._min_width is not None else base.width()
    return QSize(min_width, base.height())

refreshStyle ¶

refreshStyle() -> None

Refresh the widget's style.

Useful after dynamic stylesheet changes.

Source code in src/ezqt_widgets/widgets/label/hover_label.py

def refreshStyle(self) -> None:
    """Refresh the widget's style.

    Useful after dynamic stylesheet changes.
    """
    self.style().unpolish(self)
    self.style().polish(self)
    self.update()

IndicatorLabel¶

A QFrame combining a text label and a circular colored LED to represent a named status. States are defined by a status_map dictionary.

Signals:

Signal	Signature	Emitted when
`statusChanged`	`(str)`	The status key changes

Constructor parameters:

Parameter	Type	Default	Description
`parent`	`QWidget \\| None`	`None`	Parent widget
`status_map`	`dict[str, dict[str, str]] \\| None`	`None`	State definitions; see format below
`initial_status`	`str`	`"neutral"`	Key of the status to display on creation

status_map format:

Each key is a status name. Each value is a dict with three required keys:

{
    "neutral": {"text": "Waiting",  "state": "none",  "color": "#A0A0A0"},
    "online":  {"text": "Online",   "state": "ok",    "color": "#4CAF50"},
    "partial": {"text": "Degraded", "state": "warn",  "color": "#FFC107"},
    "offline": {"text": "Offline",  "state": "ko",    "color": "#F44336"},
}

text: string shown in the label
state: value set as the Qt state property (for QSS selectors)
color: any valid CSS color string for the LED circle

Default status_map (used when status_map is None):

Key	text	state	color
`"neutral"`	Waiting	none	#A0A0A0
`"online"`	Online	ok	#4CAF50
`"partial"`	Services disrupted	partial	#FFC107
`"offline"`	Offline	ko	#F44336

Properties:

Property	Type	Description
`status`	`str`	Gets or sets the current status key; setting calls `setStatus()`

Methods:

Method	Signature	Description
`setStatus()`	`(status: str) -> None`	Sets the status and updates the display; raises `ValueError` if key not in `status_map`
`refreshStyle()`	`() -> None`	Re-applies the QSS stylesheet

Unknown status key

setStatus() raises ValueError if the given key is not present in status_map. Always ensure the key exists before calling it.

Example:

from PySide6.QtWidgets import QApplication
from ezqt_widgets import IndicatorLabel

app = QApplication([])

status_map = {
    "idle":    {"text": "Idle",       "state": "none",  "color": "#808080"},
    "running": {"text": "Running",    "state": "ok",    "color": "#4CAF50"},
    "error":   {"text": "Error",      "state": "error", "color": "#F44336"},
}
indicator = IndicatorLabel(status_map=status_map, initial_status="idle")
indicator.statusChanged.connect(lambda s: print(f"Status: {s}"))
indicator.status = "running"
indicator.show()

app.exec()

IndicatorLabel ¶

IndicatorLabel(parent: WidgetParent = None, status_map: dict[str, dict[str, str]] | None = None, initial_status: str = 'neutral', *args: Any, **kwargs: Any)

Bases: QFrame

Dynamic status indicator widget with label and colored LED.

This widget encapsulates a QLabel for the status text and a QLabel for the LED, both arranged horizontally. The possible states are defined in a configurable dictionary (status_map), allowing for flexible text, color, and state property assignment.

Features

Dynamic states defined via a status_map dictionary (text, state, color)
Property-based access to the current status
Emits a statusChanged(str) signal when the status changes
Allows custom status sets and colors for various use cases
Suitable for online/offline indicators, service status, etc.

PARAMETER	DESCRIPTION
`parent`	The parent widget (default: None). TYPE: `WidgetParent` DEFAULT: `None`
`status_map`	Dictionary defining possible states. Each key is a state name, and each value is a dict with keys: - text (str): The label to display - state (str): The value set as a Qt property for styling - color (str): The LED color (any valid CSS color) Example: { "neutral": {"text": "Waiting", "state": "none", "color": "#A0A0A0"}, "online": {"text": "Online", "state": "ok", "color": "#4CAF50"}, ... } TYPE: `dict[str, dict[str, str]] \| None` DEFAULT: `None`
`initial_status`	The initial status key to use (default: "neutral"). TYPE: `str` DEFAULT: `'neutral'`
`*args`	Additional arguments passed to QFrame. TYPE: `Any` DEFAULT: `()`
`**kwargs`	Additional keyword arguments passed to QFrame. TYPE: `Any` DEFAULT: `{}`

Signals

statusChanged(str): Emitted when the status changes.

Example

from ezqt_widgets import IndicatorLabel status_map = { ... "neutral": {"text": "Waiting", "state": "none", "color": "#A0A0A0"}, ... "online": {"text": "Online", "state": "ok", "color": "#4CAF50"}, ... "offline": {"text": "Offline", "state": "error", "color": "#F44336"}, ... } indicator = IndicatorLabel(status_map=status_map, initial_status="neutral") indicator.statusChanged.connect(lambda s: print(f"Status: {s}")) indicator.status = "online" indicator.show()

Initialize the indicator label.

Source code in src/ezqt_widgets/widgets/label/indicator_label.py

def __init__(
    self,
    parent: WidgetParent = None,
    status_map: dict[str, dict[str, str]] | None = None,
    initial_status: str = "neutral",
    *args: Any,
    **kwargs: Any,
) -> None:
    """Initialize the indicator label."""
    super().__init__(parent, *args, **kwargs)

    self.setProperty("type", "IndicatorLabel")

    # Default status map
    self._status_map: dict[str, dict[str, str]] = status_map or {
        "neutral": {"text": "Waiting", "state": "none", "color": "#A0A0A0"},
        "online": {"text": "Online", "state": "ok", "color": "#4CAF50"},
        "partial": {
            "text": "Services disrupted",
            "state": "partial",
            "color": "#FFC107",
        },
        "offline": {"text": "Offline", "state": "ko", "color": "#F44336"},
    }

    # State variables
    self._current_status: str = ""
    self._status_label: QLabel | None = None
    self._led_label: QLabel | None = None

    # Setup widget
    self._setup_widget()

    # Set initial status
    self.status = initial_status

status `property` `writable` ¶

status: str

Get the current status key.

RETURNS	DESCRIPTION
`str`	The current status key.

setStatus ¶

setStatus(status: str) -> None

Set the current status and update the display.

PARAMETER	DESCRIPTION
`status`	The status key to set. TYPE: `str`

RAISES	DESCRIPTION
`ValueError`	If status is not in the status_map.

Source code in src/ezqt_widgets/widgets/label/indicator_label.py

def setStatus(self, status: str) -> None:
    """Set the current status and update the display.

    Args:
        status: The status key to set.

    Raises:
        ValueError: If status is not in the status_map.
    """
    if status not in self._status_map:
        raise ValueError(f"Unknown status: {status}")

    if status != self._current_status:
        self._current_status = status
        self._update_display()
        self.statusChanged.emit(self._current_status)

refreshStyle ¶

refreshStyle() -> None

Refresh the widget style.

Useful after dynamic stylesheet changes.

Source code in src/ezqt_widgets/widgets/label/indicator_label.py

def refreshStyle(self) -> None:
    """Refresh the widget style.

    Useful after dynamic stylesheet changes.
    """
    self.style().unpolish(self)
    self.style().polish(self)
    self.update()

Label Widgets¶

ClickableTagLabel¶

ClickableTagLabel ¶

name property writable ¶

enabled property writable ¶

status_color property writable ¶

min_width property writable ¶

min_height property writable ¶

mousePressEvent ¶

keyPressEvent ¶

sizeHint ¶

minimumSizeHint ¶

refreshStyle ¶

FramedLabel¶

FramedLabel ¶

text property writable ¶

alignment property writable ¶

min_width property writable ¶

min_height property writable ¶

minimumSizeHint ¶

refreshStyle ¶

HoverLabel¶

HoverLabel ¶

opacity property writable ¶

hover_icon property writable ¶

icon_size property writable ¶

icon_color property writable ¶

icon_padding property writable ¶

icon_enabled property writable ¶

setTheme ¶

clearIcon ¶

mouseMoveEvent ¶

mousePressEvent ¶

enterEvent ¶

leaveEvent ¶

paintEvent ¶

resizeEvent ¶

minimumSizeHint ¶

refreshStyle ¶

IndicatorLabel¶

IndicatorLabel ¶

status property writable ¶

setStatus ¶

refreshStyle ¶

name `property` `writable` ¶

enabled `property` `writable` ¶

status_color `property` `writable` ¶

min_width `property` `writable` ¶

min_height `property` `writable` ¶

text `property` `writable` ¶

alignment `property` `writable` ¶

min_width `property` `writable` ¶

min_height `property` `writable` ¶

opacity `property` `writable` ¶

hover_icon `property` `writable` ¶

icon_size `property` `writable` ¶

icon_color `property` `writable` ¶

icon_padding `property` `writable` ¶

icon_enabled `property` `writable` ¶

status `property` `writable` ¶