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 with a selected and an unselected state.

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

Parameters:

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

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.

name property writable

name: str

Get the tag text.

Returns:

Type	Description
str	The current tag text.

enabled property writable

enabled: bool

Get the enabled state.

Returns:

Type	Description
bool	True if enabled, False otherwise.

status_color property writable

status_color: str

Get the status color.

Returns:

Type	Description
str	The current status color.

min_width property writable

min_width: int | None

Get the minimum width.

Returns:

Type	Description
int | None	The minimum width, or None if not set.

min_height property writable

min_height: int | None

Get the minimum height.

Returns:

Type	Description
int | None	The minimum height, or None if not set.

mousePressEvent

mousePressEvent(event: QMouseEvent) -> None

Handle mouse press events.

Parameters:

Name	Type	Description	Default
event	QMouseEvent	The mouse event.	required

keyPressEvent

keyPressEvent(event: QKeyEvent) -> None

Handle key press events.

Parameters:

Name	Type	Description	Default
event	QKeyEvent	The key event.	required

sizeHint

sizeHint() -> QSize

Return the recommended size for the widget.

Returns:

Type	Description
QSize	The recommended size.

minimumSizeHint

minimumSizeHint() -> QSize

Return the minimum size for the widget.

Returns:

Type	Description
QSize	The minimum size hint.

refreshStyle

refreshStyle() -> None

Refresh the widget style.

Useful after dynamic stylesheet changes.

options: members_order: source

---

FramedLabel

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

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

Parameters:

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

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.

text property writable

text: str

Get or set the label text.

Returns:

Type	Description
str	The current label text.

alignment property writable

alignment: AlignmentFlag

Get or set the alignment of the label.

Returns:

Type	Description
AlignmentFlag	The current alignment.

min_width property writable

min_width: int | None

Get or set the minimum width.

Returns:

Type	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:

Type	Description
int | None	The minimum height, or None if not set.

minimumSizeHint

minimumSizeHint() -> QSize

Get the minimum size hint for the widget.

Returns:

Type	Description
QSize	The minimum size hint.

refreshStyle

refreshStyle() -> None

Refresh the widget's style.

Useful after dynamic stylesheet changes.

options: members_order: source

---

HoverLabel

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

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

Parameters:

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

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.

opacity property writable

opacity: float

Get the opacity of the hover icon.

Returns:

Type	Description
float	The current opacity level.

hover_icon property writable

hover_icon: QIcon | None

Get the hover icon.

Returns:

Type	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:

Type	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:

Type	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:

Type	Description
int	The current icon padding in pixels.

icon_enabled property writable

icon_enabled: bool

Enable or disable the hover icon.

Returns:

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

Parameters:

Name	Type	Description	Default
theme	str	The new theme ("dark" or "light").	required

clearIcon

clearIcon() -> None

Remove the hover icon.

mouseMoveEvent

mouseMoveEvent(event: QMouseEvent) -> None

Handle mouse movement events.

Parameters:

Name	Type	Description	Default
event	QMouseEvent	The mouse event.	required

mousePressEvent

mousePressEvent(event: QMouseEvent) -> None

Handle mouse press events.

Parameters:

Name	Type	Description	Default
event	QMouseEvent	The mouse event.	required

enterEvent

enterEvent(event: QEnterEvent) -> None

Handle enter events.

Parameters:

Name	Type	Description	Default
event	QEnterEvent	The enter event.	required

leaveEvent

leaveEvent(event: QEvent) -> None

Handle leave events.

Parameters:

Name	Type	Description	Default
event	QEvent	The leave event.	required

paintEvent

paintEvent(event: QPaintEvent) -> None

Paint the widget.

Parameters:

Name	Type	Description	Default
event	QPaintEvent	The paint event.	required

resizeEvent

resizeEvent(event: QResizeEvent) -> None

Handle resize events.

Parameters:

Name	Type	Description	Default
event	QResizeEvent	The resize event.	required

minimumSizeHint

minimumSizeHint() -> QSize

Get the minimum size hint for the widget.

Returns:

Type	Description
QSize	The minimum size hint.

refreshStyle

refreshStyle() -> None

Refresh the widget's style.

Useful after dynamic stylesheet changes.

options: members_order: source

---

IndicatorLabel

A QFrame combining a text label and a circular colored LED to represent a named status.

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.

Parameters:

Name	Type	Description	Default
parent	WidgetParent	The parent widget (default: None).	None
status_map	dict[str, dict[str, str]] | None	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"}, ... }	None
initial_status	str	The initial status key to use (default: "neutral").	'neutral'
*args	Any	Additional arguments passed to QFrame.	()
**kwargs	Any	Additional keyword arguments passed to QFrame.	{}

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.

status property writable

status: str

Get the current status key.

Returns:

Type	Description
str	The current status key.

setStatus

setStatus(status: str) -> None

Set the current status and update the display.

Parameters:

Name	Type	Description	Default
status	str	The status key to set.	required

Raises:

Type	Description
ValueError	If status is not in the status_map.

refreshStyle

refreshStyle() -> None

Refresh the widget style.

Useful after dynamic stylesheet changes.

options: members_order: source

---

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

Parameters:

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

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.

name property writable

name: str

Get the tag text.

Returns:

Type	Description
str	The current tag text.

enabled property writable

enabled: bool

Get the enabled state.

Returns:

Type	Description
bool	True if enabled, False otherwise.

status_color property writable

status_color: str

Get the status color.

Returns:

Type	Description
str	The current status color.

min_width property writable

min_width: int | None

Get the minimum width.

Returns:

Type	Description
int | None	The minimum width, or None if not set.

min_height property writable

min_height: int | None

Get the minimum height.

Returns:

Type	Description
int | None	The minimum height, or None if not set.

mousePressEvent

mousePressEvent(event: QMouseEvent) -> None

Handle mouse press events.

Parameters:

Name	Type	Description	Default
event	QMouseEvent	The mouse event.	required

keyPressEvent

keyPressEvent(event: QKeyEvent) -> None

Handle key press events.

Parameters:

Name	Type	Description	Default
event	QKeyEvent	The key event.	required

sizeHint

sizeHint() -> QSize

Return the recommended size for the widget.

Returns:

Type	Description
QSize	The recommended size.

minimumSizeHint

minimumSizeHint() -> QSize

Return the minimum size for the widget.

Returns:

Type	Description
QSize	The minimum size hint.

refreshStyle

refreshStyle() -> None

Refresh the widget style.

Useful after dynamic stylesheet changes.

---

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

Parameters:

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

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.

text property writable

text: str

Get or set the label text.

Returns:

Type	Description
str	The current label text.

alignment property writable

alignment: AlignmentFlag

Get or set the alignment of the label.

Returns:

Type	Description
AlignmentFlag	The current alignment.

min_width property writable

min_width: int | None

Get or set the minimum width.

Returns:

Type	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:

Type	Description
int | None	The minimum height, or None if not set.

minimumSizeHint

minimumSizeHint() -> QSize

Get the minimum size hint for the widget.

Returns:

Type	Description
QSize	The minimum size hint.

refreshStyle

refreshStyle() -> None

Refresh the widget's style.

Useful after dynamic stylesheet changes.

---

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

Parameters:

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

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.

opacity property writable

opacity: float

Get the opacity of the hover icon.

Returns:

Type	Description
float	The current opacity level.

hover_icon property writable

hover_icon: QIcon | None

Get the hover icon.

Returns:

Type	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:

Type	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:

Type	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:

Type	Description
int	The current icon padding in pixels.

icon_enabled property writable

icon_enabled: bool

Enable or disable the hover icon.

Returns:

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

Parameters:

Name	Type	Description	Default
theme	str	The new theme ("dark" or "light").	required

clearIcon

clearIcon() -> None

Remove the hover icon.

mouseMoveEvent

mouseMoveEvent(event: QMouseEvent) -> None

Handle mouse movement events.

Parameters:

Name	Type	Description	Default
event	QMouseEvent	The mouse event.	required

mousePressEvent

mousePressEvent(event: QMouseEvent) -> None

Handle mouse press events.

Parameters:

Name	Type	Description	Default
event	QMouseEvent	The mouse event.	required

enterEvent

enterEvent(event: QEnterEvent) -> None

Handle enter events.

Parameters:

Name	Type	Description	Default
event	QEnterEvent	The enter event.	required

leaveEvent

leaveEvent(event: QEvent) -> None

Handle leave events.

Parameters:

Name	Type	Description	Default
event	QEvent	The leave event.	required

paintEvent

paintEvent(event: QPaintEvent) -> None

Paint the widget.

Parameters:

Name	Type	Description	Default
event	QPaintEvent	The paint event.	required

resizeEvent

resizeEvent(event: QResizeEvent) -> None

Handle resize events.

Parameters:

Name	Type	Description	Default
event	QResizeEvent	The resize event.	required

minimumSizeHint

minimumSizeHint() -> QSize

Get the minimum size hint for the widget.

Returns:

Type	Description
QSize	The minimum size hint.

refreshStyle

refreshStyle() -> None

Refresh the widget's style.

Useful after dynamic stylesheet changes.

---

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.

Parameters:

Name	Type	Description	Default
parent	WidgetParent	The parent widget (default: None).	None
status_map	dict[str, dict[str, str]] | None	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"}, ... }	None
initial_status	str	The initial status key to use (default: "neutral").	'neutral'
*args	Any	Additional arguments passed to QFrame.	()
**kwargs	Any	Additional keyword arguments passed to QFrame.	{}

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.

status property writable

status: str

Get the current status key.

Returns:

Type	Description
str	The current status key.

setStatus

setStatus(status: str) -> None

Set the current status and update the display.

Parameters:

Name	Type	Description	Default
status	str	The status key to set.	required

Raises:

Type	Description
ValueError	If status is not in the status_map.

refreshStyle

refreshStyle() -> None

Refresh the widget style.

Useful after dynamic stylesheet changes.