Skip to content

Miscellaneous widgets

Utility widgets: animated circular timer, drag-and-drop list, option selector, theme-aware icon, toggleable icon, modern toggle switch, animated notification banner, and collapsible accordion section.

CircularTimer

A QWidget that draws an animated arc representing elapsed time, growing clockwise from the 12 o'clock position.

CircularTimer 

CircularTimer(parent: WidgetParent = None, duration: int = 5000, ring_color: ColorType = '#0078d4', node_color: ColorType = '#2d2d2d', ring_width_mode: Literal['small', 'medium', 'large'] = 'medium', pen_width: int | float | None = None, loop: bool = False, *args: Any, **kwargs: Any)

Bases: QWidget

Animated circular timer for indicating progress or elapsed time.

Features
  • Animated circular progress indicator
  • Customizable colors for ring and center
  • Configurable duration and loop mode
  • Click events for interaction
  • Smooth animation with configurable frame rate

Parameters:

Name Type Description Default
parent WidgetParent

Parent widget (default: None).

 None
duration int

Total animation duration in milliseconds (default: 5000).

 5000
ring_color ColorType

Color of the progress arc (default: "#0078d4"). Supports: hex (#ff0000), rgb(255,0,0), rgba(255,0,0,0.5), names (red).

 '#0078d4'
node_color ColorType

Color of the center (default: "#2d2d2d"). Supports: hex (#ffffff), rgb(255,255,255), rgba(255,255,255,0.8), names (white).

 '#2d2d2d'
ring_width_mode Literal['small', 'medium', 'large']

"small", "medium" (default), or "large". Controls the dynamic thickness of the arc.

 'medium'
pen_width int | float | None

Thickness of the arc (takes priority over ring_width_mode if set).

 None
loop bool

If True, the timer loops automatically at each cycle (default: False).

 False
*args Any

Additional arguments passed to QWidget.

 ()
**kwargs Any

Additional keyword arguments passed to QWidget.

 {}
Signals

timerReset(): Emitted when the timer is reset. clicked(): Emitted when the widget is clicked. cycleCompleted(): Emitted at each end of cycle (even if loop=False).

Example

from ezqt_widgets import CircularTimer timer = CircularTimer(duration=10000, ring_color="#0078d4", loop=True) timer.cycleCompleted.connect(lambda: print("cycle done")) timer.clicked.connect(timer.reset) timer.start() timer.show()

Initialize the circular timer.

duration property writable 

duration: int

Get the total duration.

Returns:

Type Description
int

The total duration in milliseconds.

elapsed property writable 

elapsed: int

Get the elapsed time.

Returns:

Type Description
int

The elapsed time in milliseconds.

running property 

running: bool

Get whether the timer is running.

Returns:

Type Description
bool

True if running, False otherwise.

ring_color property writable 

ring_color: QColor

Get the ring color.

Returns:

Type Description
QColor

The current ring color.

node_color property writable 

node_color: QColor

Get the node color.

Returns:

Type Description
QColor

The current node color.

ring_width_mode property writable 

ring_width_mode: str

Get the ring width mode.

Returns:

Type Description
str

The current ring width mode ("small", "medium", or "large").

pen_width property writable 

pen_width: float | None

Get the pen width.

Returns:

Type Description
float | None

The pen width, or None if using ring_width_mode.

loop property writable 

loop: bool

Get whether the timer loops.

Returns:

Type Description
bool

True if looping, False otherwise.

mousePressEvent 

mousePressEvent(_event: QMouseEvent) -> None

Handle mouse press events.

Parameters:

Name Type Description Default
_event QMouseEvent

The mouse event (unused but required by signature).

 required

start 

start() -> None

Start the circular timer.

stop 

stop() -> None

Stop the circular timer.

reset 

reset() -> None

Reset the circular timer.

minimumSizeHint 

minimumSizeHint() -> QSize

Get the recommended minimum size for the widget.

Returns:

Type Description
QSize

The minimum size hint.

paintEvent 

paintEvent(_event: QPaintEvent) -> None

Draw the animated circular timer.

Parameters:

Name Type Description Default
_event QPaintEvent

The paint event (unused but required by signature).

 required

refreshStyle 

refreshStyle() -> None

Refresh the widget's style.

Useful after dynamic stylesheet changes.

options: members_order: source

CollapsibleSection

An accordion-style QWidget with a clickable header and smooth expand/collapse animation.

CollapsibleSection 

CollapsibleSection(parent: WidgetParent = None, *, title: str = '', expanded: bool = True)

Bases: QWidget

Accordion-style section widget with animated expand/collapse.

The header is always visible. Clicking anywhere on the header (or calling toggle()) animates the content area between 0 height and its natural size hint height.

Features
  • Clickable header with title label and ToggleIcon chevron
  • Smooth height animation via QPropertyAnimation on maximumHeight
  • Supports an arbitrary QWidget as content via setContentWidget()
  • expand()/collapse()/toggle() public API
  • Theme propagation to the ToggleIcon chevron

Parameters:

Name Type Description Default
parent WidgetParent

The parent widget (default: None).

 None
title str

Header title text (default: "").

 ''
expanded bool

Initial expanded state (default: True).

 True
Properties

title: Get or set the header title text. is_expanded: Get the current expanded state.

Signals

expandedChanged(bool): Emitted when the expanded state changes.

Example

from ezqt_widgets import CollapsibleSection section = CollapsibleSection(title="Settings", expanded=False) section.setContentWidget(my_form_widget) section.expandedChanged.connect(lambda e: print(f"Expanded: {e}")) section.show()

Initialize the collapsible section.

title property writable 

title: str

Get the header title text.

Returns:

Type Description
str

The current title string.

is_expanded property 

is_expanded: bool

Get the current expanded state.

Returns:

Type Description
bool

True if the section is expanded, False if collapsed.

setContentWidget 

setContentWidget(widget: QWidget) -> None

Set the widget displayed in the collapsible content area.

Replaces any previously set content widget. The section keeps its current expanded/collapsed state.

Parameters:

Name Type Description Default
widget QWidget

The widget to display as content.

 required

expand 

expand() -> None

Expand the content area with animation.

collapse 

collapse() -> None

Collapse the content area with animation.

toggle 

toggle() -> None

Toggle between expanded and collapsed states.

setTheme 

setTheme(theme: str) -> None

Update the toggle 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

refreshStyle 

refreshStyle() -> None

Refresh the widget style.

Useful after dynamic stylesheet changes.

options: members_order: source

DraggableItem

A QFrame representing a single removable item in a DraggableList.

DraggableItem 

DraggableItem(item_id: str, text: str, parent: WidgetParent = None, icon: IconSourceExtended = None, compact: bool = False, **kwargs: Any)

Bases: QFrame

Draggable item widget for DraggableList.

This item can be moved by drag & drop and always contains a HoverLabel for a consistent interface.

Parameters:

Name Type Description Default
item_id str

Unique identifier for the item.

 required
text str

Text to display in the item.

 required
parent WidgetParent

Parent widget (default: None).

 None
icon IconSourceExtended

Icon for the item (default: None, uses default icon).

 None
compact bool

Whether to display in compact mode (default: False).

 False
**kwargs Any

Additional keyword arguments passed to HoverLabel.

 {}
Signals

itemClicked(str): Emitted when the item is clicked. itemRemoved(str): Emitted when the item is removed.

Example

from ezqt_widgets import DraggableItem item = DraggableItem(item_id="item-1", text="First item") item.itemClicked.connect(lambda id: print(f"Clicked: {id}")) item.itemRemoved.connect(lambda id: print(f"Removed: {id}")) item.show()

Initialize the draggable item.

item_id property 

item_id: str

Get the item identifier.

Returns:

Type Description
str

The unique identifier of the item.

text property 

text: str

Get the item text.

Returns:

Type Description
str

The display text of the item.

content_widget property 

content_widget: HoverLabel

Get the inner HoverLabel widget.

Returns:

Type Description
HoverLabel

The HoverLabel used for display and interaction.

icon_color property writable 

icon_color: str

Get the icon color of the HoverLabel.

Returns:

Type Description
str

The current icon color.

compact property writable 

compact: bool

Get the compact mode.

Returns:

Type Description
bool

True if compact mode is enabled, False otherwise.

mousePressEvent 

mousePressEvent(event: QMouseEvent) -> None

Handle mouse press events for drag start.

Parameters:

Name Type Description Default
event QMouseEvent

The mouse event.

 required

mouseMoveEvent 

mouseMoveEvent(event: QMouseEvent) -> None

Handle mouse movement for drag & drop.

Parameters:

Name Type Description Default
event QMouseEvent

The mouse event.

 required

mouseReleaseEvent 

mouseReleaseEvent(event: QMouseEvent) -> None

Handle mouse release events for drag end.

Parameters:

Name Type Description Default
event QMouseEvent

The mouse event.

 required

sizeHint 

sizeHint() -> QSize

Get the recommended size for the widget based on content.

Returns:

Type Description
QSize

The recommended size.

minimumSizeHint 

minimumSizeHint() -> QSize

Get the minimum size 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

DraggableList

A QWidget containing a scrollable list of DraggableItem instances reorderable by drag-and-drop.

DraggableList 

DraggableList(parent: WidgetParent = None, items: list[str] | None = None, allow_drag_drop: bool = True, allow_remove: bool = True, max_height: int = 300, min_width: int = 150, compact: bool = False, *args: Any, **kwargs: Any)

Bases: QWidget

List widget with reorderable items via drag & drop and removal.

This widget allows managing a list of items that users can reorder by drag & drop and remove individually.

Features
  • List of items reorderable by drag & drop
  • Item removal via HoverLabel (red icon on hover)
  • Consistent interface with HoverLabel for all items
  • Signals for reordering and removal events
  • Smooth and intuitive interface
  • Appearance customization
  • Automatic item order management
  • Integrated removal icon in HoverLabel
Use cases
  • Reorderable task list
  • Option selector with customizable order
  • File management interface
  • Priority-ordered element configuration

Parameters:

Name Type Description Default
parent WidgetParent

The parent widget (default: None).

 None
items list[str] | None

Initial list of items (default: []).

 None
allow_drag_drop bool

Allow drag & drop for reordering (default: True).

 True
allow_remove bool

Allow item removal via HoverLabel (default: True).

 True
max_height int

Maximum height of the widget (default: 300).

 300
min_width int

Minimum width of the widget (default: 150).

 150
compact bool

Display items in compact mode (reduced height) (default: False).

 False
*args Any

Additional arguments passed to item widgets.

 ()
**kwargs Any

Additional keyword arguments passed to item widgets.

 {}
Signals

itemMoved(str, int, int): Emitted when an item is moved (item_id, old_position, new_position). itemRemoved(str, int): Emitted when an item is removed (item_id, position). itemAdded(str, int): Emitted when an item is added (item_id, position). itemClicked(str): Emitted when an item is clicked (item_id). orderChanged(list): Emitted when the item order changes (new ordered list).

Example

draggable_list = DraggableList( ... items=["Item 1", "Item 2", "Item 3"], ... icon="https://img.icons8.com/?size=100&id=8329&format=png&color=000000" ... ) draggable_list.itemMoved.connect( ... lambda item_id, old_pos, new_pos: print(f"Moved {item_id} from {old_pos} to {new_pos}") ... ) draggable_list.itemRemoved.connect( ... lambda item_id, pos: print(f"Removed {item_id} at {pos}") ... )

Initialize the draggable list.

items property writable 

items: list[str]

Get the list of items.

Returns:

Type Description
list[str]

A copy of the current items list.

item_count property 

item_count: int

Get the number of items in the list.

Returns:

Type Description
int

The number of items (read-only).

allow_drag_drop property writable 

allow_drag_drop: bool

Get whether drag & drop is allowed.

Returns:

Type Description
bool

True if drag & drop is allowed, False otherwise.

allow_remove property writable 

allow_remove: bool

Get whether item removal is allowed.

Returns:

Type Description
bool

True if removal is allowed, False otherwise.

icon_color property writable 

icon_color: str

Get the icon color of the items.

Returns:

Type Description
str

The current icon color.

compact property writable 

compact: bool

Get the compact mode.

Returns:

Type Description
bool

True if compact mode is enabled, False otherwise.

min_width property writable 

min_width: int

Get the minimum width of the widget.

Returns:

Type Description
int

The minimum width.

addItem 

addItem(item_id: str, text: str | None = None) -> None

Add an item to the list.

Parameters:

Name Type Description Default
item_id str

Unique identifier for the item.

 required
text str | None

Text to display (uses item_id if None).

 None

removeItem 

removeItem(item_id: str) -> bool

Remove an item from the list.

Parameters:

Name Type Description Default
item_id str

Identifier of the item to remove.

 required

Returns:

Type Description
bool

True if the item was removed, False otherwise.

clearItems 

clearItems() -> None

Remove all items from the list.

moveItem 

moveItem(item_id: str, new_position: int) -> bool

Move an item to a new position.

Parameters:

Name Type Description Default
item_id str

Identifier of the item to move.

 required
new_position int

New position (0-based).

 required

Returns:

Type Description
bool

True if the item was moved, False otherwise.

getItemPosition 

getItemPosition(item_id: str) -> int

Get the position of an item.

Parameters:

Name Type Description Default
item_id str

Identifier of the item.

 required

Returns:

Type Description
int

Position of the item (-1 if not found).

dragEnterEvent 

dragEnterEvent(event: QDragEnterEvent) -> None

Handle drag enter events.

Parameters:

Name Type Description Default
event QDragEnterEvent

The drag enter event.

 required

dragMoveEvent 

dragMoveEvent(event: QDragMoveEvent) -> None

Handle drag move events.

Parameters:

Name Type Description Default
event QDragMoveEvent

The drag move event.

 required

dropEvent 

dropEvent(event: QDropEvent) -> None

Handle drop events.

Parameters:

Name Type Description Default
event QDropEvent

The drop event.

 required

sizeHint 

sizeHint() -> QSize

Get the recommended size for the widget based on content.

Returns:

Type Description
QSize

The recommended size.

minimumSizeHint 

minimumSizeHint() -> QSize

Get the minimum size 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

NotificationBanner

An animated slide-down notification banner QWidget that overlays the top of a parent widget.

NotificationBanner 

NotificationBanner(parent: QWidget)

Bases: QWidget

Animated slide-down notification banner overlaying a parent widget.

The banner slides in from the top of its parent widget and can auto-dismiss after a configurable duration. A close button is always visible for manual dismissal. The banner repositions itself when the parent is resized via event filtering.

Features
  • Slide-down animation via QPropertyAnimation on geometry
  • Four severity levels: INFO, WARNING, ERROR, SUCCESS
  • Auto-dismiss via QTimer when duration > 0
  • Manual close button (×)
  • Level icon via inline SVG rendered to ThemeIcon
  • Parent resize tracking via event filter

Parameters:

Name Type Description Default
parent QWidget

The parent widget inside which the banner is displayed. Must be a valid QWidget (not None).

 required
Signals

dismissed(): Emitted when the banner is hidden (any cause).

Example

from ezqt_widgets import NotificationBanner, NotificationLevel banner = NotificationBanner(parent=main_widget) banner.dismissed.connect(lambda: print("Banner closed")) banner.showNotification("File saved!", NotificationLevel.SUCCESS)

Initialize the notification banner.

Parameters:

Name Type Description Default
parent QWidget

The parent widget that hosts the banner overlay.

 required

showNotification 

showNotification(message: str, level: NotificationLevel = INFO, duration: int = 3000) -> None

Display a notification banner with the given message and level.

Parameters:

Name Type Description Default
message str

The text to display in the banner.

 required
level NotificationLevel

The severity level (default: NotificationLevel.INFO).

 INFO
duration int

Display duration in milliseconds. Use 0 for a permanent banner that requires manual dismissal (default: 3000).

 3000

eventFilter 

eventFilter(obj: object, event: QEvent) -> bool

Track parent resize events to reposition the banner.

Parameters:

Name Type Description Default
obj object

The object that generated the event.

 required
event QEvent

The event.

 required

Returns:

Type Description
bool

False to allow normal event propagation.

refreshStyle 

refreshStyle() -> None

Refresh the widget style.

Useful after dynamic stylesheet changes.

options: members_order: source

NotificationLevel

An Enum that sets the visual severity of a NotificationBanner.

NotificationLevel

Bases: Enum

Severity level for a notification banner.

Attributes:

Name Type Description
INFO

Informational message (blue).
WARNING

Warning message (amber).
ERROR

Error message (red).
SUCCESS

Success message (green).

options: members_order: source

OptionSelector

A QFrame displaying a horizontal or vertical row of text options with an animated selector rectangle.

OptionSelector 

OptionSelector(items: list[str], default_id: int = 0, min_width: int | None = None, min_height: int | None = None, orientation: str = 'horizontal', animation_duration: int = 300, parent: WidgetParent = None, *args: Any, **kwargs: Any)

Bases: QFrame

Option selector widget with animated selector.

Features
  • Multiple selectable options displayed as labels
  • Animated selector that moves between options
  • Single selection mode (radio behavior)
  • Configurable default selection by ID (index)
  • Smooth animations with easing curves
  • Click events for option selection
  • Uses IDs internally for robust value handling

Parameters:

Name Type Description Default
items list[str]

List of option texts to display.

 required
default_id int

Default selected option ID (index) (default: 0).

 0
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
orientation str

Layout orientation: "horizontal" or "vertical" (default: "horizontal").

 'horizontal'
animation_duration int

Duration of the selector animation in milliseconds (default: 300).

 300
parent WidgetParent

The parent widget (default: None).

 None
*args Any

Additional arguments passed to QFrame.

 ()
**kwargs Any

Additional keyword arguments passed to QFrame.

 {}
Signals

clicked(): Emitted when an option is clicked. valueChanged(str): Emitted when the selected value changes. valueIdChanged(int): Emitted when the selected value ID changes.

Example

from ezqt_widgets import OptionSelector selector = OptionSelector(items=["Day", "Week", "Month"], default_id=0) selector.valueChanged.connect(lambda v: print(f"Selected: {v}")) selector.show()

Initialize the option selector.

value property writable 

value: str

Get or set the currently selected option text.

Returns:

Type Description
str

The currently selected option text, or empty string if none.

value_id property writable 

value_id: int

Get or set the currently selected option ID.

Returns:

Type Description
int

The currently selected option ID.

options property 

options: list[str]

Get the list of available options.

Returns:

Type Description
list[str]

A copy of the options list.

default_id property writable 

default_id: int

Get or set the default option ID.

Returns:

Type Description
int

The default option ID.

selected_option property 

selected_option: FramedLabel | None

Get the currently selected option widget.

Returns:

Type Description
FramedLabel | None

The selected option widget, or None if none selected.

orientation property writable 

orientation: str

Get or set the orientation of the selector.

Returns:

Type Description
str

The current orientation ("horizontal" or "vertical").

min_width property writable 

min_width: int | None

Get or set the minimum width of the widget.

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 of the widget.

Returns:

Type Description
int | None

The minimum height, or None if not set.

animation_duration property writable 

animation_duration: int

Get or set the animation duration in milliseconds.

Returns:

Type Description
int

The animation duration in milliseconds.

initializeSelector 

initializeSelector(default_id: int = 0) -> None

Initialize the selector with default position.

Parameters:

Name Type Description Default
default_id int

The default option ID to select.

 0

addOption 

addOption(option_id: int, option_text: str) -> None

Add a new option to the selector.

Parameters:

Name Type Description Default
option_id int

The ID for the option.

 required
option_text str

The text to display for the option.

 required

toggleSelection 

toggleSelection(option_id: int) -> None

Handle option selection.

Parameters:

Name Type Description Default
option_id int

The ID of the option to select.

 required

moveSelector 

moveSelector(option: FramedLabel) -> None

Animate the selector to the selected option.

Parameters:

Name Type Description Default
option FramedLabel

The option widget to move the selector to.

 required

resizeEvent 

resizeEvent(event: QResizeEvent) -> None

Handle resize events to keep selector aligned.

sizeHint 

sizeHint() -> QSize

Get the recommended size for the widget.

Returns:

Type Description
QSize

The recommended size.

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

ThemeIcon

A QIcon subclass that recolors itself to match the active theme (dark or light).

ThemeIcon 

ThemeIcon(icon: IconSourceExtended, theme: str = 'dark', dark_color: QColor | str | None = None, light_color: QColor | str | None = None)

Bases: QIcon

QIcon subclass with automatic theme-based color adaptation.

This icon adapts its color based on the specified theme
  • Dark theme: icon rendered in the resolved dark color.
  • Light theme: icon rendered in the resolved light color.

The icon can be updated dynamically by calling :meth:setTheme when the application theme changes.

Parameters:

Name Type Description Default
icon IconSourceExtended

The source icon (QIcon, QPixmap, or path string).

 required
theme str

The initial theme ("dark" or "light", default: "dark").

 'dark'
dark_color QColor | str | None

Optional color for dark theme (hex or rgb(...) string).

 None
light_color QColor | str | None

Optional color for light theme (hex or rgb(...) string).

 None

Raises:

Type Description
TypeError

If icon is None.
Properties

theme: Get or set the active theme. original_icon: Get or set the source icon.

Example

from ezqt_widgets.widgets.misc.theme_icon import ThemeIcon

Basic usage with automatic white/black color adaptation

icon = ThemeIcon("path/to/icon.png", theme="dark") button.setIcon(icon)

Custom colors for each theme

icon = ThemeIcon("icon.png", dark_color="#FFFFFF", light_color="#333333")

Factory method from any source (QIcon, QPixmap, path, or None)

themed = ThemeIcon.from_source("icon.svg", theme="light")

Adapt to a new theme dynamically

icon.setTheme("light")

Initialize the theme icon.

Parameters:

Name Type Description Default
icon IconSourceExtended

The source icon (QIcon, QPixmap, or path string).

 required
theme str

The initial theme ("dark" or "light").

 'dark'
dark_color QColor | str | None

Optional color for dark theme (hex or rgb(...) string).

 None
light_color QColor | str | None

Optional color for light theme (hex or rgb(...) string).

 None

Raises:

Type Description
TypeError

If icon is None.

theme property writable 

theme: str

Get the current theme.

Returns:

Type Description
str

The current theme ("dark" or "light").

original_icon property writable 

original_icon: QIcon

Get the original (uncolored) source icon.

Returns:

Type Description
QIcon

The original icon.

from_source classmethod 

from_source(source: IconSourceExtended, theme: str = 'dark', dark_color: QColor | str | None = None, light_color: QColor | str | None = None) -> ThemeIcon | None

Create a ThemeIcon from any supported source.

Parameters:

Name Type Description Default
source IconSourceExtended

The icon source (ThemeIcon, QIcon, QPixmap, or path string).

 required
theme str

The initial theme ("dark" or "light").

 'dark'
dark_color QColor | str | None

Optional color for dark theme (hex or rgb(...) string).

 None
light_color QColor | str | None

Optional color for light theme (hex or rgb(...) string).

 None

Returns:

Type Description
ThemeIcon | None

A ThemeIcon instance or None if source is None.

setTheme 

setTheme(theme: str) -> None

Update the icon color for the given theme.

Convenience method equivalent to setting the :attr:theme property.

Parameters:

Name Type Description Default
theme str

The new theme ("dark" or "light").

 required

options: members_order: source

ToggleIcon

A QLabel that alternates between two icons representing opened and closed states.

ToggleIcon 

ToggleIcon(parent: WidgetParent = None, opened_icon: IconSourceExtended = None, closed_icon: IconSourceExtended = None, icon_size: int = 16, icon_color: ColorType | None = None, initial_state: str = 'closed', min_width: int | None = None, min_height: int | None = None, *args: Any, **kwargs: Any)

Bases: QLabel

Label with toggleable icons to indicate an open/closed state.

Features
  • Toggleable icons for open/closed states
  • Custom icons or default painted icons
  • Configurable icon size and color
  • Click and keyboard events for toggling
  • Property-based state management

Parameters:

Name Type Description Default
parent WidgetParent

Parent widget (default: None).

 None
opened_icon IconSourceExtended

Icon to display when state is "opened" (ThemeIcon, QIcon, QPixmap, path, or URL). If None, uses paintEvent (default: None).

 None
closed_icon IconSourceExtended

Icon to display when state is "closed" (ThemeIcon, QIcon, QPixmap, path, or URL). If None, uses paintEvent (default: None).

 None
icon_size int

Icon size in pixels (default: 16).

 16
icon_color ColorType | None

Color to apply to icons (default: white with 0.5 opacity).

 None
initial_state str

Initial state ("opened" or "closed", default: "closed").

 'closed'
min_width int | None

Minimum width of the widget (default: None).

 None
min_height int | None

Minimum height of the widget (default: None).

 None
*args Any

Additional arguments passed to QLabel.

 ()
**kwargs Any

Additional keyword arguments passed to QLabel.

 {}
Signals

stateChanged(str): Emitted when the state changes ("opened" or "closed"). clicked(): Emitted when the widget is clicked.

Example

from ezqt_widgets import ToggleIcon toggle = ToggleIcon(initial_state="closed", icon_size=20) toggle.stateChanged.connect(lambda s: print(f"State: {s}")) toggle.toggleState() toggle.show()

Initialize the toggle icon.

state property writable 

state: str

Get the current state.

Returns:

Type Description
str

The current state ("opened" or "closed").

opened_icon property writable 

opened_icon: QPixmap | None

Get or set the opened state icon.

Returns:

Type Description
QPixmap | None

The opened icon pixmap, or None if using default.

closed_icon property writable 

closed_icon: QPixmap | None

Get or set the closed state icon.

Returns:

Type Description
QPixmap | None

The closed icon pixmap, or None if using default.

icon_size property writable 

icon_size: int

Get or set the icon size.

Returns:

Type Description
int

The current icon size in pixels.

icon_color property writable 

icon_color: QColor

Get or set the icon color.

Returns:

Type Description
QColor

The current icon color.

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.

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

paintEvent 

paintEvent(event: QPaintEvent) -> None

Draw the icon if no custom icon is provided, centered in a square.

Parameters:

Name Type Description Default
event QPaintEvent

The paint event.

 required

minimumSizeHint 

minimumSizeHint() -> QSize

Calculate a minimum square size based on icon and margins.

Returns:

Type Description
QSize

The minimum size hint.

setTheme 

setTheme(theme: str) -> None

Update all icons' color for the given theme.

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

Parameters:

Name Type Description Default
theme str

The new theme ("dark" or "light").

 required

toggleState 

toggleState() -> None

Toggle between opened and closed states.

setStateOpened 

setStateOpened() -> None

Force the state to opened.

setStateClosed 

setStateClosed() -> None

Force the state to closed.

isOpened 

isOpened() -> bool

Check if the state is opened.

Returns:

Type Description
bool

True if opened, False otherwise.

isClosed 

isClosed() -> bool

Check if the state is closed.

Returns:

Type Description
bool

True if closed, False otherwise.

refreshStyle 

refreshStyle() -> None

Refresh the widget style.

Useful after dynamic stylesheet changes.

options: members_order: source

ToggleSwitch

A QWidget that renders an animated toggle switch with a sliding circle.

ToggleSwitch 

ToggleSwitch(parent: WidgetParent = None, checked: bool = False, width: int = 50, height: int = 24, animation: bool = True, *args: Any, **kwargs: Any)

Bases: QWidget

Modern toggle switch widget with animated sliding circle.

Features
  • Smooth animation when toggling
  • Customizable colors for on/off states
  • Configurable size and border radius
  • Click to toggle functionality
  • Property-based access to state
  • Signal emitted on state change

Parameters:

Name Type Description Default
parent WidgetParent

The parent widget (default: None).

 None
checked bool

Initial state of the toggle (default: False).

 False
width int

Width of the toggle switch (default: 50).

 50
height int

Height of the toggle switch (default: 24).

 24
animation bool

Whether to animate the toggle (default: True).

 True
*args Any

Additional arguments passed to QWidget.

 ()
**kwargs Any

Additional keyword arguments passed to QWidget.

 {}
Signals

toggled(bool): Emitted when the toggle state changes.

Example

from ezqt_widgets import ToggleSwitch switch = ToggleSwitch(checked=False, width=50, height=24) switch.toggled.connect(lambda state: print(f"On: {state}")) switch.checked = True switch.show()

Initialize the toggle switch.

checked property writable 

checked: bool

Get the toggle state.

Returns:

Type Description
bool

True if checked, False otherwise.

width property writable 

width: int

Get the width of the toggle.

Returns:

Type Description
int

The current width in pixels.

height property writable 

height: int

Get the height of the toggle.

Returns:

Type Description
int

The current height in pixels.

animation property writable 

animation: bool

Get whether animation is enabled.

Returns:

Type Description
bool

True if animation is enabled, False otherwise.

toggle 

toggle() -> None

Toggle the switch state.

mousePressEvent 

mousePressEvent(event: QMouseEvent) -> None

Handle mouse press events.

Parameters:

Name Type Description Default
event QMouseEvent

The mouse event.

 required

paintEvent 

paintEvent(_event: QPaintEvent) -> None

Custom paint event to draw the toggle switch.

Parameters:

Name Type Description Default
_event QPaintEvent

The paint event (unused but required by signature).

 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

CircularTimer

A QWidget that draws an animated arc representing elapsed time. The arc grows clockwise from the 12 o'clock position.

Signals:

Signal Signature Emitted when
timerReset () resetTimer() is called
clicked () The widget is clicked
cycleCompleted () One full cycle ends (whether or not loop is True)

Constructor parameters:

Parameter Type Default Description
parent QWidget \| None None Parent widget
duration int 5000 Total cycle duration in milliseconds
ring_color QColor \| str "#0078d4" Color of the progress arc; supports hex, rgb(), rgba(), and named colors
node_color QColor \| str "#2d2d2d" Fill color of the inner circle
ring_width_mode "small" \| "medium" \| "large" "medium" Dynamic arc thickness preset
pen_width int \| float \| None None Explicit arc thickness; takes priority over ring_width_mode if set
loop bool False Whether the animation restarts automatically at the end of each cycle

Properties:

Property Type Description
duration int Gets or sets the cycle duration in milliseconds
elapsed int Gets or sets the elapsed time in milliseconds
running bool Read-only; True while the timer is active
ring_color QColor Gets or sets the arc color
node_color QColor Gets or sets the inner circle color
ring_width_mode str Gets or sets the thickness preset
pen_width float \| None Gets or sets an explicit arc thickness
loop bool Gets or sets whether the timer loops

Methods:

Method Signature Description
startTimer() () -> None Starts the animation from the current elapsed position
stopTimer() () -> None Stops the animation and resets elapsed to 0
resetTimer() () -> None Resets elapsed to 0 and emits timerReset without stopping
refreshStyle() () -> None Re-applies the QSS stylesheet

Example:

from PySide6.QtWidgets import QApplication
from ezqt_widgets import CircularTimer

app = QApplication([])

timer = CircularTimer(duration=10000, ring_color="#0078d4", loop=True)
timer.cycleCompleted.connect(lambda: print("cycle done"))
timer.clicked.connect(timer.resetTimer)
timer.startTimer()
timer.show()

app.exec()

CircularTimer 

CircularTimer(parent: WidgetParent = None, duration: int = 5000, ring_color: ColorType = '#0078d4', node_color: ColorType = '#2d2d2d', ring_width_mode: Literal['small', 'medium', 'large'] = 'medium', pen_width: int | float | None = None, loop: bool = False, *args: Any, **kwargs: Any)

Bases: QWidget

Animated circular timer for indicating progress or elapsed time.

Features
  • Animated circular progress indicator
  • Customizable colors for ring and center
  • Configurable duration and loop mode
  • Click events for interaction
  • Smooth animation with configurable frame rate

Parameters:

Name Type Description Default
parent WidgetParent

Parent widget (default: None).

 None
duration int

Total animation duration in milliseconds (default: 5000).

 5000
ring_color ColorType

Color of the progress arc (default: "#0078d4"). Supports: hex (#ff0000), rgb(255,0,0), rgba(255,0,0,0.5), names (red).

 '#0078d4'
node_color ColorType

Color of the center (default: "#2d2d2d"). Supports: hex (#ffffff), rgb(255,255,255), rgba(255,255,255,0.8), names (white).

 '#2d2d2d'
ring_width_mode Literal['small', 'medium', 'large']

"small", "medium" (default), or "large". Controls the dynamic thickness of the arc.

 'medium'
pen_width int | float | None

Thickness of the arc (takes priority over ring_width_mode if set).

 None
loop bool

If True, the timer loops automatically at each cycle (default: False).

 False
*args Any

Additional arguments passed to QWidget.

 ()
**kwargs Any

Additional keyword arguments passed to QWidget.

 {}
Signals

timerReset(): Emitted when the timer is reset. clicked(): Emitted when the widget is clicked. cycleCompleted(): Emitted at each end of cycle (even if loop=False).

Example

from ezqt_widgets import CircularTimer timer = CircularTimer(duration=10000, ring_color="#0078d4", loop=True) timer.cycleCompleted.connect(lambda: print("cycle done")) timer.clicked.connect(timer.reset) timer.start() timer.show()

Initialize the circular timer.

duration property writable 

duration: int

Get the total duration.

Returns:

Type Description
int

The total duration in milliseconds.

elapsed property writable 

elapsed: int

Get the elapsed time.

Returns:

Type Description
int

The elapsed time in milliseconds.

running property 

running: bool

Get whether the timer is running.

Returns:

Type Description
bool

True if running, False otherwise.

ring_color property writable 

ring_color: QColor

Get the ring color.

Returns:

Type Description
QColor

The current ring color.

node_color property writable 

node_color: QColor

Get the node color.

Returns:

Type Description
QColor

The current node color.

ring_width_mode property writable 

ring_width_mode: str

Get the ring width mode.

Returns:

Type Description
str

The current ring width mode ("small", "medium", or "large").

pen_width property writable 

pen_width: float | None

Get the pen width.

Returns:

Type Description
float | None

The pen width, or None if using ring_width_mode.

loop property writable 

loop: bool

Get whether the timer loops.

Returns:

Type Description
bool

True if looping, False otherwise.

mousePressEvent 

mousePressEvent(_event: QMouseEvent) -> None

Handle mouse press events.

Parameters:

Name Type Description Default
_event QMouseEvent

The mouse event (unused but required by signature).

 required

start 

start() -> None

Start the circular timer.

stop 

stop() -> None

Stop the circular timer.

reset 

reset() -> None

Reset the circular timer.

minimumSizeHint 

minimumSizeHint() -> QSize

Get the recommended minimum size for the widget.

Returns:

Type Description
QSize

The minimum size hint.

paintEvent 

paintEvent(_event: QPaintEvent) -> None

Draw the animated circular timer.

Parameters:

Name Type Description Default
_event QPaintEvent

The paint event (unused but required by signature).

 required

refreshStyle 

refreshStyle() -> None

Refresh the widget's style.

Useful after dynamic stylesheet changes.

DraggableItem

A QFrame representing a single item in a DraggableList. It embeds a HoverLabel whose hover icon triggers removal.

Signals:

Signal Signature Emitted when
itemClicked (str) The item is clicked; the string is item_id
itemRemoved (str) The removal icon is clicked; the string is item_id

Constructor parameters:

Parameter Type Default Description
item_id str — Unique identifier for this item (required)
text str — Text displayed in the item (required)
parent QWidget \| None None Parent widget
icon QIcon \| QPixmap \| str \| None None Icon for the HoverLabel; defaults to an icons8 drag icon
compact bool False Compact display mode (reduced height: 24–32 px vs 40–60 px)

Properties:

Property Type Description
icon_color str Gets or sets the icon color of the internal HoverLabel
compact bool Gets or sets compact mode; adjusts height constraints

Methods:

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

Usage with DraggableList

DraggableItem is designed to be managed by DraggableList. Use DraggableList.addItem() rather than instantiating DraggableItem directly in most cases.

DraggableItem 

DraggableItem(item_id: str, text: str, parent: WidgetParent = None, icon: IconSourceExtended = None, compact: bool = False, **kwargs: Any)

Bases: QFrame

Draggable item widget for DraggableList.

This item can be moved by drag & drop and always contains a HoverLabel for a consistent interface.

Parameters:

Name Type Description Default
item_id str

Unique identifier for the item.

 required
text str

Text to display in the item.

 required
parent WidgetParent

Parent widget (default: None).

 None
icon IconSourceExtended

Icon for the item (default: None, uses default icon).

 None
compact bool

Whether to display in compact mode (default: False).

 False
**kwargs Any

Additional keyword arguments passed to HoverLabel.

 {}
Signals

itemClicked(str): Emitted when the item is clicked. itemRemoved(str): Emitted when the item is removed.

Example

from ezqt_widgets import DraggableItem item = DraggableItem(item_id="item-1", text="First item") item.itemClicked.connect(lambda id: print(f"Clicked: {id}")) item.itemRemoved.connect(lambda id: print(f"Removed: {id}")) item.show()

Initialize the draggable item.

item_id property 

item_id: str

Get the item identifier.

Returns:

Type Description
str

The unique identifier of the item.

text property 

text: str

Get the item text.

Returns:

Type Description
str

The display text of the item.

content_widget property 

content_widget: HoverLabel

Get the inner HoverLabel widget.

Returns:

Type Description
HoverLabel

The HoverLabel used for display and interaction.

icon_color property writable 

icon_color: str

Get the icon color of the HoverLabel.

Returns:

Type Description
str

The current icon color.

compact property writable 

compact: bool

Get the compact mode.

Returns:

Type Description
bool

True if compact mode is enabled, False otherwise.

mousePressEvent 

mousePressEvent(event: QMouseEvent) -> None

Handle mouse press events for drag start.

Parameters:

Name Type Description Default
event QMouseEvent

The mouse event.

 required

mouseMoveEvent 

mouseMoveEvent(event: QMouseEvent) -> None

Handle mouse movement for drag & drop.

Parameters:

Name Type Description Default
event QMouseEvent

The mouse event.

 required

mouseReleaseEvent 

mouseReleaseEvent(event: QMouseEvent) -> None

Handle mouse release events for drag end.

Parameters:

Name Type Description Default
event QMouseEvent

The mouse event.

 required

sizeHint 

sizeHint() -> QSize

Get the recommended size for the widget based on content.

Returns:

Type Description
QSize

The recommended size.

minimumSizeHint 

minimumSizeHint() -> QSize

Get the minimum size for the widget.

Returns:

Type Description
QSize

The minimum size hint.

refreshStyle 

refreshStyle() -> None

Refresh the widget's style.

Useful after dynamic stylesheet changes.

DraggableList

A QWidget containing a scrollable list of DraggableItem instances that can be reordered by drag-and-drop and removed individually.

Signals:

Signal Signature Emitted when
itemMoved (str, int, int) An item is dropped at a new position; args are item_id, old_position, new_position
itemRemoved (str, int) An item is removed; args are item_id, position
itemAdded (str, int) An item is added; args are item_id, position
itemClicked (str) An item is clicked; the string is item_id
orderChanged (list) The item order changes; the list is the new ordered item_id list

Constructor parameters:

Parameter Type Default Description
parent QWidget \| None None Parent widget
items list[str] \| None None Initial list of item identifiers
allow_drag_drop bool True Whether drag-and-drop reordering is permitted
allow_remove bool True Whether items can be removed via the hover icon
max_height int 300 Maximum widget height in pixels
min_width int 150 Minimum widget width in pixels
compact bool False Compact display mode for all items

Properties:

Property Type Description
items list[str] Gets or sets the full item list (returns a copy); setting rebuilds all item widgets
item_count int Read-only; number of items currently in the list
allow_drag_drop bool Gets or sets whether drag-and-drop is allowed
allow_remove bool Gets or sets whether item removal is allowed; updates all existing items
icon_color str Gets or sets the icon color for all items
compact bool Gets or sets compact mode for all items
min_width int Gets or sets the minimum widget width

Methods:

Method Signature Description
addItem() (item_id: str, text: str \| None) -> None Adds an item; text defaults to item_id if None; no-op if item_id already exists
removeItem() (item_id: str) -> bool Removes the item with the given id; returns True if found and removed
clearItems() () -> None Removes all items and emits orderChanged([])
moveItem() (item_id: str, new_position: int) -> bool Moves an item to a new 0-based position; returns True on success
getItemPosition() (item_id: str) -> int Returns the 0-based position of the item, or -1 if not found
refreshStyle() () -> None Re-applies the QSS stylesheet

Example:

from PySide6.QtWidgets import QApplication
from ezqt_widgets import DraggableList

app = QApplication([])

task_list = DraggableList(
    items=["design", "implement", "test", "deploy"],
    allow_drag_drop=True,
    allow_remove=True,
    compact=False,
)
task_list.itemMoved.connect(
    lambda id, old, new: print(f"Moved '{id}' from {old} to {new}")
)
task_list.itemRemoved.connect(
    lambda id, pos: print(f"Removed '{id}' at position {pos}")
)
task_list.show()

app.exec()

DraggableList 

DraggableList(parent: WidgetParent = None, items: list[str] | None = None, allow_drag_drop: bool = True, allow_remove: bool = True, max_height: int = 300, min_width: int = 150, compact: bool = False, *args: Any, **kwargs: Any)

Bases: QWidget

List widget with reorderable items via drag & drop and removal.

This widget allows managing a list of items that users can reorder by drag & drop and remove individually.

Features
  • List of items reorderable by drag & drop
  • Item removal via HoverLabel (red icon on hover)
  • Consistent interface with HoverLabel for all items
  • Signals for reordering and removal events
  • Smooth and intuitive interface
  • Appearance customization
  • Automatic item order management
  • Integrated removal icon in HoverLabel
Use cases
  • Reorderable task list
  • Option selector with customizable order
  • File management interface
  • Priority-ordered element configuration

Parameters:

Name Type Description Default
parent WidgetParent

The parent widget (default: None).

 None
items list[str] | None

Initial list of items (default: []).

 None
allow_drag_drop bool

Allow drag & drop for reordering (default: True).

 True
allow_remove bool

Allow item removal via HoverLabel (default: True).

 True
max_height int

Maximum height of the widget (default: 300).

 300
min_width int

Minimum width of the widget (default: 150).

 150
compact bool

Display items in compact mode (reduced height) (default: False).

 False
*args Any

Additional arguments passed to item widgets.

 ()
**kwargs Any

Additional keyword arguments passed to item widgets.

 {}
Signals

itemMoved(str, int, int): Emitted when an item is moved (item_id, old_position, new_position). itemRemoved(str, int): Emitted when an item is removed (item_id, position). itemAdded(str, int): Emitted when an item is added (item_id, position). itemClicked(str): Emitted when an item is clicked (item_id). orderChanged(list): Emitted when the item order changes (new ordered list).

Example

draggable_list = DraggableList( ... items=["Item 1", "Item 2", "Item 3"], ... icon="https://img.icons8.com/?size=100&id=8329&format=png&color=000000" ... ) draggable_list.itemMoved.connect( ... lambda item_id, old_pos, new_pos: print(f"Moved {item_id} from {old_pos} to {new_pos}") ... ) draggable_list.itemRemoved.connect( ... lambda item_id, pos: print(f"Removed {item_id} at {pos}") ... )

Initialize the draggable list.

items property writable 

items: list[str]

Get the list of items.

Returns:

Type Description
list[str]

A copy of the current items list.

item_count property 

item_count: int

Get the number of items in the list.

Returns:

Type Description
int

The number of items (read-only).

allow_drag_drop property writable 

allow_drag_drop: bool

Get whether drag & drop is allowed.

Returns:

Type Description
bool

True if drag & drop is allowed, False otherwise.

allow_remove property writable 

allow_remove: bool

Get whether item removal is allowed.

Returns:

Type Description
bool

True if removal is allowed, False otherwise.

icon_color property writable 

icon_color: str

Get the icon color of the items.

Returns:

Type Description
str

The current icon color.

compact property writable 

compact: bool

Get the compact mode.

Returns:

Type Description
bool

True if compact mode is enabled, False otherwise.

min_width property writable 

min_width: int

Get the minimum width of the widget.

Returns:

Type Description
int

The minimum width.

addItem 

addItem(item_id: str, text: str | None = None) -> None

Add an item to the list.

Parameters:

Name Type Description Default
item_id str

Unique identifier for the item.

 required
text str | None

Text to display (uses item_id if None).

 None

removeItem 

removeItem(item_id: str) -> bool

Remove an item from the list.

Parameters:

Name Type Description Default
item_id str

Identifier of the item to remove.

 required

Returns:

Type Description
bool

True if the item was removed, False otherwise.

clearItems 

clearItems() -> None

Remove all items from the list.

moveItem 

moveItem(item_id: str, new_position: int) -> bool

Move an item to a new position.

Parameters:

Name Type Description Default
item_id str

Identifier of the item to move.

 required
new_position int

New position (0-based).

 required

Returns:

Type Description
bool

True if the item was moved, False otherwise.

getItemPosition 

getItemPosition(item_id: str) -> int

Get the position of an item.

Parameters:

Name Type Description Default
item_id str

Identifier of the item.

 required

Returns:

Type Description
int

Position of the item (-1 if not found).

dragEnterEvent 

dragEnterEvent(event: QDragEnterEvent) -> None

Handle drag enter events.

Parameters:

Name Type Description Default
event QDragEnterEvent

The drag enter event.

 required

dragMoveEvent 

dragMoveEvent(event: QDragMoveEvent) -> None

Handle drag move events.

Parameters:

Name Type Description Default
event QDragMoveEvent

The drag move event.

 required

dropEvent 

dropEvent(event: QDropEvent) -> None

Handle drop events.

Parameters:

Name Type Description Default
event QDropEvent

The drop event.

 required

sizeHint 

sizeHint() -> QSize

Get the recommended size for the widget based on content.

Returns:

Type Description
QSize

The recommended size.

minimumSizeHint 

minimumSizeHint() -> QSize

Get the minimum size for the widget.

Returns:

Type Description
QSize

The minimum size hint.

refreshStyle 

refreshStyle() -> None

Refresh the widget's style.

Useful after dynamic stylesheet changes.

OptionSelector

A QFrame displaying a horizontal or vertical row of text options with an animated selector rectangle that slides to the chosen option.

Signals:

Signal Signature Emitted when
clicked () Any option is clicked
valueChanged (str) The selected option text changes
valueIdChanged (int) The selected option index changes

Constructor parameters:

Parameter Type Default Description
items list[str] — List of option texts to display (required)
default_id int 0 Index of the initially selected option
min_width int \| None None Minimum width
min_height int \| None None Minimum height
orientation str "horizontal" Layout: "horizontal" or "vertical"
animation_duration int 300 Selector slide animation duration in milliseconds
parent QWidget \| None None Parent widget

Properties:

Property Type Description
value str Gets or sets the selected option by text
value_id int Gets or sets the selected option by index
options list[str] Read-only; returns a copy of the options list
default_id int Gets or sets the default selection index
selected_option FramedLabel \| None Read-only; the currently selected option widget
orientation str Gets or sets the layout orientation
min_width int \| None Gets or sets minimum width
min_height int \| None Gets or sets minimum height
animation_duration int Gets or sets the animation duration in milliseconds

Methods:

Method Signature Description
initializeSelector() (default_id: int) -> None Positions the selector at the given index without animation
addOption() (option_id: int, option_text: str) -> None Adds a new option at the given id position
toggleSelection() (option_id: int) -> None Selects an option by id and animates the selector
moveSelector() (option: FramedLabel) -> None Animates the selector to the given option widget
refreshStyle() () -> None Re-applies the QSS stylesheet

Example:

from PySide6.QtWidgets import QApplication
from ezqt_widgets import OptionSelector

app = QApplication([])

selector = OptionSelector(
    items=["Day", "Week", "Month", "Year"],
    default_id=0,
    orientation="horizontal",
    animation_duration=250,
)
selector.valueChanged.connect(lambda v: print(f"Selected: {v}"))
selector.show()

app.exec()

OptionSelector 

OptionSelector(items: list[str], default_id: int = 0, min_width: int | None = None, min_height: int | None = None, orientation: str = 'horizontal', animation_duration: int = 300, parent: WidgetParent = None, *args: Any, **kwargs: Any)

Bases: QFrame

Option selector widget with animated selector.

Features
  • Multiple selectable options displayed as labels
  • Animated selector that moves between options
  • Single selection mode (radio behavior)
  • Configurable default selection by ID (index)
  • Smooth animations with easing curves
  • Click events for option selection
  • Uses IDs internally for robust value handling

Parameters:

Name Type Description Default
items list[str]

List of option texts to display.

 required
default_id int

Default selected option ID (index) (default: 0).

 0
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
orientation str

Layout orientation: "horizontal" or "vertical" (default: "horizontal").

 'horizontal'
animation_duration int

Duration of the selector animation in milliseconds (default: 300).

 300
parent WidgetParent

The parent widget (default: None).

 None
*args Any

Additional arguments passed to QFrame.

 ()
**kwargs Any

Additional keyword arguments passed to QFrame.

 {}
Signals

clicked(): Emitted when an option is clicked. valueChanged(str): Emitted when the selected value changes. valueIdChanged(int): Emitted when the selected value ID changes.

Example

from ezqt_widgets import OptionSelector selector = OptionSelector(items=["Day", "Week", "Month"], default_id=0) selector.valueChanged.connect(lambda v: print(f"Selected: {v}")) selector.show()

Initialize the option selector.

value property writable 

value: str

Get or set the currently selected option text.

Returns:

Type Description
str

The currently selected option text, or empty string if none.

value_id property writable 

value_id: int

Get or set the currently selected option ID.

Returns:

Type Description
int

The currently selected option ID.

options property 

options: list[str]

Get the list of available options.

Returns:

Type Description
list[str]

A copy of the options list.

default_id property writable 

default_id: int

Get or set the default option ID.

Returns:

Type Description
int

The default option ID.

selected_option property 

selected_option: FramedLabel | None

Get the currently selected option widget.

Returns:

Type Description
FramedLabel | None

The selected option widget, or None if none selected.

orientation property writable 

orientation: str

Get or set the orientation of the selector.

Returns:

Type Description
str

The current orientation ("horizontal" or "vertical").

min_width property writable 

min_width: int | None

Get or set the minimum width of the widget.

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 of the widget.

Returns:

Type Description
int | None

The minimum height, or None if not set.

animation_duration property writable 

animation_duration: int

Get or set the animation duration in milliseconds.

Returns:

Type Description
int

The animation duration in milliseconds.

initializeSelector 

initializeSelector(default_id: int = 0) -> None

Initialize the selector with default position.

Parameters:

Name Type Description Default
default_id int

The default option ID to select.

 0

addOption 

addOption(option_id: int, option_text: str) -> None

Add a new option to the selector.

Parameters:

Name Type Description Default
option_id int

The ID for the option.

 required
option_text str

The text to display for the option.

 required

toggleSelection 

toggleSelection(option_id: int) -> None

Handle option selection.

Parameters:

Name Type Description Default
option_id int

The ID of the option to select.

 required

moveSelector 

moveSelector(option: FramedLabel) -> None

Animate the selector to the selected option.

Parameters:

Name Type Description Default
option FramedLabel

The option widget to move the selector to.

 required

resizeEvent 

resizeEvent(event: QResizeEvent) -> None

Handle resize events to keep selector aligned.

sizeHint 

sizeHint() -> QSize

Get the recommended size for the widget.

Returns:

Type Description
QSize

The recommended size.

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.

ThemeIcon

A QIcon subclass that recolors itself to white (dark theme) or black (light theme) when the active theme changes. Custom colors for each theme can be specified.

Constructor parameters:

Parameter Type Default Description
icon QIcon \| QPixmap \| str — Source icon (required); None raises TypeError
theme str "dark" Initial theme: "dark" or "light"
dark_color QColor \| str \| None None Color applied in dark theme; defaults to white
light_color QColor \| str \| None None Color applied in light theme; defaults to black

Properties:

Property Type Description
theme str Gets or sets the active theme; setting recolors the icon immediately
original_icon QIcon Gets or sets the source icon; setting triggers a recolor

Methods:

Method Signature Description
setTheme() (theme: str) -> None Convenience alias for setting the theme property
from_source() (source, theme, dark_color, light_color) -> ThemeIcon \| None Class method; returns None if source is None, otherwise wraps it in a ThemeIcon

Example:

from ezqt_widgets import ThemeIcon

# Auto dark/light colors (white in dark mode, black in light mode)
icon = ThemeIcon("path/to/icon.png", theme="dark")

# Custom colors
icon = ThemeIcon(
    "path/to/icon.svg",
    dark_color="#FFFFFF",
    light_color="#333333",
)

# Switch theme at runtime
icon.setTheme("light")

# Factory method — returns None if source is None
themed = ThemeIcon.from_source("path/to/icon.png", theme="dark")

ThemeIcon 

ThemeIcon(icon: IconSourceExtended, theme: str = 'dark', dark_color: QColor | str | None = None, light_color: QColor | str | None = None)

Bases: QIcon

QIcon subclass with automatic theme-based color adaptation.

This icon adapts its color based on the specified theme
  • Dark theme: icon rendered in the resolved dark color.
  • Light theme: icon rendered in the resolved light color.

The icon can be updated dynamically by calling :meth:setTheme when the application theme changes.

Parameters:

Name Type Description Default
icon IconSourceExtended

The source icon (QIcon, QPixmap, or path string).

 required
theme str

The initial theme ("dark" or "light", default: "dark").

 'dark'
dark_color QColor | str | None

Optional color for dark theme (hex or rgb(...) string).

 None
light_color QColor | str | None

Optional color for light theme (hex or rgb(...) string).

 None

Raises:

Type Description
TypeError

If icon is None.
Properties

theme: Get or set the active theme. original_icon: Get or set the source icon.

Example

from ezqt_widgets.widgets.misc.theme_icon import ThemeIcon

Basic usage with automatic white/black color adaptation

icon = ThemeIcon("path/to/icon.png", theme="dark") button.setIcon(icon)

Custom colors for each theme

icon = ThemeIcon("icon.png", dark_color="#FFFFFF", light_color="#333333")

Factory method from any source (QIcon, QPixmap, path, or None)

themed = ThemeIcon.from_source("icon.svg", theme="light")

Adapt to a new theme dynamically

icon.setTheme("light")

Initialize the theme icon.

Parameters:

Name Type Description Default
icon IconSourceExtended

The source icon (QIcon, QPixmap, or path string).

 required
theme str

The initial theme ("dark" or "light").

 'dark'
dark_color QColor | str | None

Optional color for dark theme (hex or rgb(...) string).

 None
light_color QColor | str | None

Optional color for light theme (hex or rgb(...) string).

 None

Raises:

Type Description
TypeError

If icon is None.

theme property writable 

theme: str

Get the current theme.

Returns:

Type Description
str

The current theme ("dark" or "light").

original_icon property writable 

original_icon: QIcon

Get the original (uncolored) source icon.

Returns:

Type Description
QIcon

The original icon.

from_source classmethod 

from_source(source: IconSourceExtended, theme: str = 'dark', dark_color: QColor | str | None = None, light_color: QColor | str | None = None) -> ThemeIcon | None

Create a ThemeIcon from any supported source.

Parameters:

Name Type Description Default
source IconSourceExtended

The icon source (ThemeIcon, QIcon, QPixmap, or path string).

 required
theme str

The initial theme ("dark" or "light").

 'dark'
dark_color QColor | str | None

Optional color for dark theme (hex or rgb(...) string).

 None
light_color QColor | str | None

Optional color for light theme (hex or rgb(...) string).

 None

Returns:

Type Description
ThemeIcon | None

A ThemeIcon instance or None if source is None.

setTheme 

setTheme(theme: str) -> None

Update the icon color for the given theme.

Convenience method equivalent to setting the :attr:theme property.

Parameters:

Name Type Description Default
theme str

The new theme ("dark" or "light").

 required

ToggleIcon

A QLabel that alternates between two icons representing an "opened" and a "closed" state. When no custom icons are provided, a built-in painted triangle arrow is used.

Signals:

Signal Signature Emitted when
stateChanged (str) The state changes; value is "opened" or "closed"
clicked () The widget is clicked

Constructor parameters:

Parameter Type Default Description
parent QWidget \| None None Parent widget
opened_icon QIcon \| QPixmap \| str \| None None Icon shown in the opened state; uses painted arrow if None
closed_icon QIcon \| QPixmap \| str \| None None Icon shown in the closed state; uses painted arrow if None
icon_size int 16 Icon size in pixels (square)
icon_color QColor \| str \| None None Color applied to icons; defaults to semi-transparent white
initial_state str "closed" Starting state: "opened" or "closed"
min_width int \| None None Minimum width
min_height int \| None None Minimum height

Properties:

Property Type Description
state str Gets or sets the current state ("opened" or "closed")
opened_icon QPixmap \| None Gets or sets the opened-state icon
closed_icon QPixmap \| None Gets or sets the closed-state icon
icon_size int Gets or sets the icon size in pixels
icon_color QColor Gets or sets the color applied to icons
min_width int \| None Gets or sets minimum width
min_height int \| None Gets or sets minimum height

Methods:

Method Signature Description
toggleState() () -> None Switches between "opened" and "closed"
setStateOpened() () -> None Forces state to "opened"
setStateClosed() () -> None Forces state to "closed"
isOpened() () -> bool Returns True if state is "opened"
isClosed() () -> bool Returns True if state is "closed"
refreshStyle() () -> None Re-applies the QSS stylesheet

Keyboard support: Space, Enter, and Return keys toggle the state when the widget has focus.

Example:

from PySide6.QtWidgets import QApplication
from ezqt_widgets import ToggleIcon

app = QApplication([])

toggle = ToggleIcon(initial_state="closed", icon_size=20)
toggle.stateChanged.connect(lambda s: print(f"State: {s}"))
toggle.toggleState()  # now "opened"
toggle.show()

app.exec()

ToggleIcon 

ToggleIcon(parent: WidgetParent = None, opened_icon: IconSourceExtended = None, closed_icon: IconSourceExtended = None, icon_size: int = 16, icon_color: ColorType | None = None, initial_state: str = 'closed', min_width: int | None = None, min_height: int | None = None, *args: Any, **kwargs: Any)

Bases: QLabel

Label with toggleable icons to indicate an open/closed state.

Features
  • Toggleable icons for open/closed states
  • Custom icons or default painted icons
  • Configurable icon size and color
  • Click and keyboard events for toggling
  • Property-based state management

Parameters:

Name Type Description Default
parent WidgetParent

Parent widget (default: None).

 None
opened_icon IconSourceExtended

Icon to display when state is "opened" (ThemeIcon, QIcon, QPixmap, path, or URL). If None, uses paintEvent (default: None).

 None
closed_icon IconSourceExtended

Icon to display when state is "closed" (ThemeIcon, QIcon, QPixmap, path, or URL). If None, uses paintEvent (default: None).

 None
icon_size int

Icon size in pixels (default: 16).

 16
icon_color ColorType | None

Color to apply to icons (default: white with 0.5 opacity).

 None
initial_state str

Initial state ("opened" or "closed", default: "closed").

 'closed'
min_width int | None

Minimum width of the widget (default: None).

 None
min_height int | None

Minimum height of the widget (default: None).

 None
*args Any

Additional arguments passed to QLabel.

 ()
**kwargs Any

Additional keyword arguments passed to QLabel.

 {}
Signals

stateChanged(str): Emitted when the state changes ("opened" or "closed"). clicked(): Emitted when the widget is clicked.

Example

from ezqt_widgets import ToggleIcon toggle = ToggleIcon(initial_state="closed", icon_size=20) toggle.stateChanged.connect(lambda s: print(f"State: {s}")) toggle.toggleState() toggle.show()

Initialize the toggle icon.

state property writable 

state: str

Get the current state.

Returns:

Type Description
str

The current state ("opened" or "closed").

opened_icon property writable 

opened_icon: QPixmap | None

Get or set the opened state icon.

Returns:

Type Description
QPixmap | None

The opened icon pixmap, or None if using default.

closed_icon property writable 

closed_icon: QPixmap | None

Get or set the closed state icon.

Returns:

Type Description
QPixmap | None

The closed icon pixmap, or None if using default.

icon_size property writable 

icon_size: int

Get or set the icon size.

Returns:

Type Description
int

The current icon size in pixels.

icon_color property writable 

icon_color: QColor

Get or set the icon color.

Returns:

Type Description
QColor

The current icon color.

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.

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

paintEvent 

paintEvent(event: QPaintEvent) -> None

Draw the icon if no custom icon is provided, centered in a square.

Parameters:

Name Type Description Default
event QPaintEvent

The paint event.

 required

minimumSizeHint 

minimumSizeHint() -> QSize

Calculate a minimum square size based on icon and margins.

Returns:

Type Description
QSize

The minimum size hint.

setTheme 

setTheme(theme: str) -> None

Update all icons' color for the given theme.

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

Parameters:

Name Type Description Default
theme str

The new theme ("dark" or "light").

 required

toggleState 

toggleState() -> None

Toggle between opened and closed states.

setStateOpened 

setStateOpened() -> None

Force the state to opened.

setStateClosed 

setStateClosed() -> None

Force the state to closed.

isOpened 

isOpened() -> bool

Check if the state is opened.

Returns:

Type Description
bool

True if opened, False otherwise.

isClosed 

isClosed() -> bool

Check if the state is closed.

Returns:

Type Description
bool

True if closed, False otherwise.

refreshStyle 

refreshStyle() -> None

Refresh the widget style.

Useful after dynamic stylesheet changes.

ToggleSwitch

A QWidget that renders an animated toggle switch with a sliding circle. Clicking or setting checked triggers a smooth animation.

Signals:

Signal Signature Emitted when
toggled (bool) The checked state changes; value is the new state

Constructor parameters:

Parameter Type Default Description
parent QWidget \| None None Parent widget
checked bool False Initial checked state
width int 50 Width of the switch in pixels (minimum 20)
height int 24 Height of the switch in pixels (minimum 12)
animation bool True Whether the circle slides with animation

Properties:

Property Type Description
checked bool Gets or sets the toggle state; emits toggled and animates on change
width int Gets or sets the switch width
height int Gets or sets the switch height
animation bool Gets or sets whether animation is enabled

Methods:

Method Signature Description
toggle() () -> None Inverts the current checked state
refreshStyle() () -> None Re-applies the QSS stylesheet

Default colors (not configurable via constructor):

Element Off state On state
Background rgb(44, 49, 58) rgb(150, 205, 50)
Circle rgb(255, 255, 255) rgb(255, 255, 255)
Border rgb(52, 59, 72) rgb(52, 59, 72)

Apply a QSS stylesheet to the parent or the application to override these colors.

Example:

from PySide6.QtWidgets import QApplication
from ezqt_widgets import ToggleSwitch

app = QApplication([])

switch = ToggleSwitch(checked=False, width=50, height=24, animation=True)
switch.toggled.connect(lambda on: print(f"On: {on}"))
switch.checked = True  # animates to the on position
switch.show()

app.exec()

ToggleSwitch 

ToggleSwitch(parent: WidgetParent = None, checked: bool = False, width: int = 50, height: int = 24, animation: bool = True, *args: Any, **kwargs: Any)

Bases: QWidget

Modern toggle switch widget with animated sliding circle.

Features
  • Smooth animation when toggling
  • Customizable colors for on/off states
  • Configurable size and border radius
  • Click to toggle functionality
  • Property-based access to state
  • Signal emitted on state change

Parameters:

Name Type Description Default
parent WidgetParent

The parent widget (default: None).

 None
checked bool

Initial state of the toggle (default: False).

 False
width int

Width of the toggle switch (default: 50).

 50
height int

Height of the toggle switch (default: 24).

 24
animation bool

Whether to animate the toggle (default: True).

 True
*args Any

Additional arguments passed to QWidget.

 ()
**kwargs Any

Additional keyword arguments passed to QWidget.

 {}
Signals

toggled(bool): Emitted when the toggle state changes.

Example

from ezqt_widgets import ToggleSwitch switch = ToggleSwitch(checked=False, width=50, height=24) switch.toggled.connect(lambda state: print(f"On: {state}")) switch.checked = True switch.show()

Initialize the toggle switch.

checked property writable 

checked: bool

Get the toggle state.

Returns:

Type Description
bool

True if checked, False otherwise.

width property writable 

width: int

Get the width of the toggle.

Returns:

Type Description
int

The current width in pixels.

height property writable 

height: int

Get the height of the toggle.

Returns:

Type Description
int

The current height in pixels.

animation property writable 

animation: bool

Get whether animation is enabled.

Returns:

Type Description
bool

True if animation is enabled, False otherwise.

toggle 

toggle() -> None

Toggle the switch state.

mousePressEvent 

mousePressEvent(event: QMouseEvent) -> None

Handle mouse press events.

Parameters:

Name Type Description Default
event QMouseEvent

The mouse event.

 required

paintEvent 

paintEvent(_event: QPaintEvent) -> None

Custom paint event to draw the toggle switch.

Parameters:

Name Type Description Default
_event QPaintEvent

The paint event (unused but required by signature).

 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.

NotificationBanner

An animated slide-down notification banner QWidget that overlays the top of a parent widget. The banner can auto-dismiss after a configurable duration, and always provides a manual close button.

NotificationLevel

NotificationLevel is an Enum that sets the visual severity of the banner.

Member Value Background color
INFO "INFO" #3b82f6 (blue)
WARNING "WARNING" #f59e0b (amber)
ERROR "ERROR" #ef4444 (red)
SUCCESS "SUCCESS" #22c55e (green) 
from ezqt_widgets import NotificationLevel

level = NotificationLevel.SUCCESS

Signals:

Signal Signature Emitted when
dismissed () The banner is hidden, whether by auto-dismiss or manually

Constructor parameters:

Parameter Type Default Description
parent QWidget — The parent widget that hosts the banner overlay (required, not None)

Methods:

Method Signature Description
showNotification() (message: str, level: NotificationLevel, duration: int) -> None Displays the banner with the given message, level, and duration
refreshStyle() () -> None Re-applies the QSS stylesheet

showNotification() parameters:

Parameter Type Default Description
message str — Text displayed in the banner (required)
level NotificationLevel NotificationLevel.INFO Severity level controlling background color and icon
duration int 3000 Display duration in milliseconds. Pass 0 for permanent (manual-only dismiss)

Behavior notes:

  • The banner is 48 px tall and spans the full width of the parent widget.
  • Slide-in and slide-out use a QPropertyAnimation on geometry with an OutCubic easing curve (250 ms).
  • Calling showNotification() while a banner is already visible cancels the previous auto-dismiss timer and replaces the content immediately.
  • The banner tracks parent resize events via an event filter and repositions itself automatically while visible.
  • The parent argument is mandatory. Passing None will raise an AttributeError at initialization.

Example:

from PySide6.QtWidgets import QApplication, QWidget
from ezqt_widgets import NotificationBanner, NotificationLevel

app = QApplication([])

window = QWidget()
window.resize(600, 400)

banner = NotificationBanner(parent=window)
banner.dismissed.connect(lambda: print("Banner dismissed"))

# Show a success banner that auto-dismisses after 4 seconds
banner.showNotification(
    "Configuration saved successfully.",
    NotificationLevel.SUCCESS,
    duration=4000,
)

# Show a permanent error banner (requires manual close)
banner.showNotification(
    "Connection lost. Check network settings.",
    NotificationLevel.ERROR,
    duration=0,
)

window.show()
app.exec()

NotificationBanner 

NotificationBanner(parent: QWidget)

Bases: QWidget

Animated slide-down notification banner overlaying a parent widget.

The banner slides in from the top of its parent widget and can auto-dismiss after a configurable duration. A close button is always visible for manual dismissal. The banner repositions itself when the parent is resized via event filtering.

Features
  • Slide-down animation via QPropertyAnimation on geometry
  • Four severity levels: INFO, WARNING, ERROR, SUCCESS
  • Auto-dismiss via QTimer when duration > 0
  • Manual close button (×)
  • Level icon via inline SVG rendered to ThemeIcon
  • Parent resize tracking via event filter

Parameters:

Name Type Description Default
parent QWidget

The parent widget inside which the banner is displayed. Must be a valid QWidget (not None).

 required
Signals

dismissed(): Emitted when the banner is hidden (any cause).

Example

from ezqt_widgets import NotificationBanner, NotificationLevel banner = NotificationBanner(parent=main_widget) banner.dismissed.connect(lambda: print("Banner closed")) banner.showNotification("File saved!", NotificationLevel.SUCCESS)

Initialize the notification banner.

Parameters:

Name Type Description Default
parent QWidget

The parent widget that hosts the banner overlay.

 required

showNotification 

showNotification(message: str, level: NotificationLevel = INFO, duration: int = 3000) -> None

Display a notification banner with the given message and level.

Parameters:

Name Type Description Default
message str

The text to display in the banner.

 required
level NotificationLevel

The severity level (default: NotificationLevel.INFO).

 INFO
duration int

Display duration in milliseconds. Use 0 for a permanent banner that requires manual dismissal (default: 3000).

 3000

eventFilter 

eventFilter(obj: object, event: QEvent) -> bool

Track parent resize events to reposition the banner.

Parameters:

Name Type Description Default
obj object

The object that generated the event.

 required
event QEvent

The event.

 required

Returns:

Type Description
bool

False to allow normal event propagation.

refreshStyle 

refreshStyle() -> None

Refresh the widget style.

Useful after dynamic stylesheet changes.

CollapsibleSection

An accordion-style QWidget with a clickable header and smooth expand/collapse animation. The header is always visible; clicking it toggles the content area between its natural height and zero.

Signals:

Signal Signature Emitted when
expandedChanged (bool) The expanded state changes; value is the new state

Constructor parameters:

Parameter Type Default Description
parent QWidget \| None None Parent widget
title str "" Header title text
expanded bool True Initial expanded state

Properties:

Property Type Description
title str Gets or sets the header title text
is_expanded bool Read-only; True if the content area is currently expanded

Methods:

Method Signature Description
setContentWidget() (widget: QWidget) -> None Sets the widget displayed in the collapsible area; replaces any previous content
expand() () -> None Expands the content area with animation; no-op if already expanded
collapse() () -> None Collapses the content area with animation; no-op if already collapsed
toggle() () -> None Toggles between expanded and collapsed states
setTheme() (theme: str) -> None Updates the chevron icon color; connect to a themeChanged signal
refreshStyle() () -> None Re-applies the QSS stylesheet

Behavior notes:

  • The expand/collapse animation operates on maximumHeight of the content area using QPropertyAnimation with an InOutCubic easing curve (200 ms).
  • expandedChanged is emitted before the animation completes.
  • Calling setContentWidget() replaces any previously set widget and re-applies the current expanded/collapsed state without animation.
  • The header chevron uses a ToggleIcon and reflects the current state (chevron-down when expanded, chevron-right when collapsed).
  • setTheme() propagates the theme to the internal ToggleIcon chevron.

Example:

from PySide6.QtWidgets import QApplication, QWidget, QFormLayout, QLineEdit
from ezqt_widgets import CollapsibleSection

app = QApplication([])

# Build a form to use as content
form_widget = QWidget()
form_layout = QFormLayout(form_widget)
form_layout.addRow("Host:", QLineEdit("localhost"))
form_layout.addRow("Port:", QLineEdit("5432"))

section = CollapsibleSection(title="Database settings", expanded=False)
section.setContentWidget(form_widget)
section.expandedChanged.connect(lambda e: print(f"Expanded: {e}"))
section.show()

app.exec()

CollapsibleSection 

CollapsibleSection(parent: WidgetParent = None, *, title: str = '', expanded: bool = True)

Bases: QWidget

Accordion-style section widget with animated expand/collapse.

The header is always visible. Clicking anywhere on the header (or calling toggle()) animates the content area between 0 height and its natural size hint height.

Features
  • Clickable header with title label and ToggleIcon chevron
  • Smooth height animation via QPropertyAnimation on maximumHeight
  • Supports an arbitrary QWidget as content via setContentWidget()
  • expand()/collapse()/toggle() public API
  • Theme propagation to the ToggleIcon chevron

Parameters:

Name Type Description Default
parent WidgetParent

The parent widget (default: None).

 None
title str

Header title text (default: "").

 ''
expanded bool

Initial expanded state (default: True).

 True
Properties

title: Get or set the header title text. is_expanded: Get the current expanded state.

Signals

expandedChanged(bool): Emitted when the expanded state changes.

Example

from ezqt_widgets import CollapsibleSection section = CollapsibleSection(title="Settings", expanded=False) section.setContentWidget(my_form_widget) section.expandedChanged.connect(lambda e: print(f"Expanded: {e}")) section.show()

Initialize the collapsible section.

title property writable 

title: str

Get the header title text.

Returns:

Type Description
str

The current title string.

is_expanded property 

is_expanded: bool

Get the current expanded state.

Returns:

Type Description
bool

True if the section is expanded, False if collapsed.

setContentWidget 

setContentWidget(widget: QWidget) -> None

Set the widget displayed in the collapsible content area.

Replaces any previously set content widget. The section keeps its current expanded/collapsed state.

Parameters:

Name Type Description Default
widget QWidget

The widget to display as content.

 required

expand 

expand() -> None

Expand the content area with animation.

collapse 

collapse() -> None

Collapse the content area with animation.

toggle 

toggle() -> None

Toggle between expanded and collapsed states.

setTheme 

setTheme(theme: str) -> None

Update the toggle 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

refreshStyle 

refreshStyle() -> None

Refresh the widget style.

Useful after dynamic stylesheet changes.