Full API reference

Complete symbol listing for ezqt_widgets, auto-generated from source docstrings via mkdocstrings.

This page renders every public class, method, and attribute defined in the package. For a curated, module-by-module navigation, see the API index.

ezqt_widgets

ezqt_widgets - Custom Qt widgets collection for PySide6.

ezqt_widgets is a collection of custom and reusable Qt widgets for PySide6. It provides advanced, reusable, and styled graphical components to facilitate the development of modern and ergonomic interfaces.

Main Features: - Enhanced button widgets (date picker, icon buttons, loading buttons) - Advanced input widgets (auto-complete, search, tab replacement) - Enhanced label widgets (clickable tags, framed labels, hover labels, indicators) - Utility widgets (circular timers, draggable lists, option selectors, toggles) - Modern and ergonomic UI components - Fully typed API with type hints - PySide6 compatible

Quick Start: >>> from ezqt_widgets import DateButton, IconButton, AutoCompleteInput >>> from PySide6.QtWidgets import QApplication >>> >>> app = QApplication([]) >>> >>> # Create a date button >>> date_btn = DateButton() >>> date_btn.show() >>> >>> # Create an icon button >>> icon_btn = IconButton(icon="path/to/icon.png", text="Click me") >>> icon_btn.show() >>> >>> # Create an auto-complete input >>> input_widget = AutoCompleteInput(completions=["option1", "option2"]) >>> input_widget.show() >>> >>> app.exec()

AnimationDuration module-attribute

AnimationDuration: TypeAlias = int

Type alias for animation duration in milliseconds.

Used by: Widgets with animations (ToggleSwitch, LoaderButton, etc.)

ColorType module-attribute

ColorType: TypeAlias = QColor | str

Type alias for color specifications.

Accepts

• QColor: A Qt color object
• str: Color string (hex "#RRGGBB", named color "red", etc.)

Used by: Widgets with custom painting (ToggleSwitch, CircularTimer, etc.)

EventCallback module-attribute

EventCallback: TypeAlias = Callable[[], None]

Type alias for event callbacks without parameters.

Used by: Click handlers, event callbacks, etc.

IconSource module-attribute

IconSource: TypeAlias = QIcon | str | None

Type alias for icon sources.

Accepts

• QIcon: A Qt icon object (ThemeIcon recommended)
• str: Path to an icon file (local path, resource path, or URL)
• None: No icon

Note

ThemeIcon is a QIcon subclass and is supported wherever QIcon is accepted.

Used by: IconButton, DateButton, LoaderButton, etc.

SizeType module-attribute

SizeType: TypeAlias = QSize | tuple[int, int]

Type alias for size specifications.

Accepts

• QSize: A Qt size object
• tuple[int, int]: (width, height) tuple

Used by: IconButton, widget sizing, etc.

ValueCallback module-attribute

ValueCallback: TypeAlias = Callable[[Any], None]

Type alias for value change callbacks.

Used by: Signal handlers, value change callbacks, etc.

WidgetParent module-attribute

WidgetParent: TypeAlias = QWidget | None

Type alias for widget parent parameter.

Accepts

• QWidget: A parent widget
• None: No parent (top-level widget)

Used by: All widget constructors.

DateButton

DateButton(parent: WidgetParent = None, date: QDate | str | None = None, date_format: str = 'dd/MM/yyyy', placeholder: str = 'Select a date', show_calendar_icon: bool = True, icon_size: SizeType = QSize(16, 16), minimum_date: QDate | None = None, maximum_date: QDate | None = None, min_width: int | None = None, min_height: int | None = None, *args: Any, **kwargs: Any)

Bases: QToolButton

Button widget for date selection with integrated calendar.

Features

• Displays current selected date
• Opens calendar dialog on click
• Configurable date format
• Placeholder text when no date selected
• Calendar icon with customizable appearance
• Date validation and parsing
• Optional minimum and maximum date constraints

Parameters:

Name	Type	Description	Default
parent	WidgetParent	The parent widget (default: None).	None
date	QDate | str | None	Initial date (QDate, date string, or None for current date).	None
date_format	str	Format for displaying the date (default: "dd/MM/yyyy").	'dd/MM/yyyy'
placeholder	str	Text to display when no date is selected (default: "Select a date").	'Select a date'
show_calendar_icon	bool	Whether to show calendar icon (default: True).	True
icon_size	SizeType	Size of the calendar icon (default: QSize(16, 16)).	QSize(16, 16)
minimum_date	QDate | None	Minimum selectable date (default: None, no constraint).	None
maximum_date	QDate | None	Maximum selectable date (default: None, no constraint).	None
min_width	int | None	Minimum width of the button (default: None, auto-calculated).	None
min_height	int | None	Minimum height of the button (default: None, auto-calculated).	None
*args	Any	Additional arguments passed to QToolButton.	()
**kwargs	Any	Additional keyword arguments passed to QToolButton.	{}

Signals

dateChanged(QDate): Emitted when the date changes. dateSelected(QDate): Emitted when a date is selected from calendar.

Example

from ezqt_widgets import DateButton btn = DateButton(date_format="dd/MM/yyyy", placeholder="Pick a date") btn.dateChanged.connect(lambda d: print(d.toString("dd/MM/yyyy"))) btn.setToday() btn.show()

Initialize the date button.

date property writable

date: QDate

Get or set the selected date.

Returns:

Type	Description
QDate	The current selected date.

show_calendar_icon property writable

show_calendar_icon: bool

Get or set calendar icon visibility.

Returns:

Type	Description
bool	True if calendar icon is visible, False otherwise.

date_string property writable

date_string: str

Get or set the date as formatted string.

Returns:

Type	Description
str	The formatted date string.

date_format property writable

date_format: str

Get or set the date format.

Returns:

Type	Description
str	The current date format string.

placeholder property writable

placeholder: str

Get or set the placeholder text.

Returns:

Type	Description
str	The current placeholder text.

icon_size property writable

icon_size: QSize

Get or set the icon size.

Returns:

Type	Description
QSize	The current icon size.

minimum_date property writable

minimum_date: QDate | None

Get or set the minimum selectable date.

Returns:

Type	Description
QDate | None	The minimum date, or None if no constraint is set.

maximum_date property writable

maximum_date: QDate | None

Get or set the maximum selectable date.

Returns:

Type	Description
QDate | None	The maximum date, or None if no constraint is set.

min_width property writable

min_width: int | None

Get or set the minimum width of the button.

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

Returns:

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

clearDate

clearDate() -> None

Clear the selected date.

setToday

setToday() -> None

Set the date to today.

openCalendar

openCalendar() -> None

Open the calendar dialog.

setTheme

setTheme(theme: str) -> None

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

mousePressEvent

mousePressEvent(event: QMouseEvent) -> None

Handle mouse press events.

The left-button press opens the calendar dialog directly. The clicked signal is emitted only after the user confirms a date (inside openCalendar), not unconditionally on press.

Parameters:

Name	Type	Description	Default
event	QMouseEvent	The mouse event.	required

sizeHint

sizeHint() -> QSize

Get the recommended size for the button.

Returns:

Type	Description
QSize	The recommended size.

minimumSizeHint

minimumSizeHint() -> QSize

Get the minimum size hint for the button.

Returns:

Type	Description
QSize	The minimum size hint.

refreshStyle

refreshStyle() -> None

Refresh the widget's style.

Useful after dynamic stylesheet changes.

DatePickerDialog

DatePickerDialog(parent: WidgetParent = None, current_date: QDate | None = None, min_date: QDate | None = None, max_date: QDate | None = None)

Bases: QDialog

Dialog for date selection with calendar widget.

Provides a modal dialog with a calendar widget for selecting dates. The dialog emits accepted signal when a date is selected and confirmed.

Parameters:

Name	Type	Description	Default
parent	WidgetParent	The parent widget (default: None).	None
current_date	QDate | None	The current selected date (default: None).	None
min_date	QDate | None	The minimum selectable date (default: None).	None
max_date	QDate | None	The maximum selectable date (default: None).	None

Example

from ezqt_widgets import DatePickerDialog from PySide6.QtCore import QDate dialog = DatePickerDialog(current_date=QDate.currentDate()) if dialog.exec(): ... date = dialog.selected_date() ... print(date.toString("dd/MM/yyyy"))

Initialize the date picker dialog.

selectedDate

selectedDate() -> QDate | None

Get the selected date.

Returns:

Type	Description
QDate | None	The selected date, or None if no date was selected.

IconButton

IconButton(parent: WidgetParent = None, icon: IconSourceExtended = None, text: str = '', icon_size: SizeType = QSize(20, 20), text_visible: bool = True, spacing: int = 10, min_width: int | None = None, min_height: int | None = None, *args: Any, **kwargs: Any)

Bases: QToolButton

Enhanced button widget with icon and optional text support.

Features

• Icon support from various sources (ThemeIcon, QIcon, QPixmap, path, URL, SVG)
• Optional text display with configurable visibility
• Customizable icon size and spacing
• Property-based access to icon and text
• Signals for icon and text changes
• Hover and click effects

Parameters:

Name	Type	Description	Default
parent	WidgetParent	The parent widget (default: None).	None
icon	IconSourceExtended	The icon to display (ThemeIcon, QIcon, QPixmap, path, resource, URL, or SVG).	None
text	str	The button text (default: "").	''
icon_size	SizeType	Size of the icon (default: QSize(20, 20)).	QSize(20, 20)
text_visible	bool	Whether the text is initially visible (default: True).	True
spacing	int	Spacing between icon and text in pixels (default: 10).	10
min_width	int | None	Minimum width of the button (default: None, auto-calculated).	None
min_height	int | None	Minimum height of the button (default: None, auto-calculated).	None
*args	Any	Additional arguments passed to QToolButton.	()
**kwargs	Any	Additional keyword arguments passed to QToolButton.	{}

Signals

iconChanged(QIcon): Emitted when the icon changes. textChanged(str): Emitted when the text changes. iconLoadFailed(str): Emitted when an icon URL fetch fails, with the URL.

Example

from ezqt_widgets import IconButton btn = IconButton(icon="path/to/icon.png", text="Open", icon_size=(20, 20)) btn.iconChanged.connect(lambda icon: print("icon changed")) btn.text_visible = False btn.show()

Initialize the icon button.

icon property writable

icon: QIcon | None

Get or set the button icon.

Returns:

Type	Description
QIcon | None	The current icon, or None if no icon is set.

text property writable

text: str

Get or set the button text.

Returns:

Type	Description
str	The current button text.

text_visible property writable

text_visible: bool

Get or set text visibility.

Returns:

Type	Description
bool	True if text is visible, False otherwise.

icon_size property writable

icon_size: QSize

Get or set the icon size.

Returns:

Type	Description
QSize	The current icon size.

spacing property writable

spacing: int

Get or set spacing between icon and text.

Returns:

Type	Description
int	The current spacing in pixels.

min_width property writable

min_width: int | None

Get or set the minimum width of the button.

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

Returns:

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

setTheme

setTheme(theme: str) -> None

Update the 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 current icon.

clearText

clearText() -> None

Clear the button text.

toggleTextVisibility

toggleTextVisibility() -> None

Toggle text visibility.

setIconColor

setIconColor(color: str = '#FFFFFF', opacity: float = 0.5) -> None

Apply color and opacity to the current icon.

Parameters:

Name	Type	Description	Default
color	str	The color to apply (default: "#FFFFFF").	'#FFFFFF'
opacity	float	The opacity level (default: 0.5).	0.5

sizeHint

sizeHint() -> QSize

Get the recommended size for the button.

Returns:

Type	Description
QSize	The recommended size.

minimumSizeHint

minimumSizeHint() -> QSize

Get the minimum size hint for the button.

Returns:

Type	Description
QSize	The minimum size hint.

refreshStyle

refreshStyle() -> None

Refresh the widget's style.

Useful after dynamic stylesheet changes.

LoaderButton

LoaderButton(parent: WidgetParent = None, text: str = '', icon: IconSourceExtended = None, loading_text: str = 'Loading...', loading_icon: IconSourceExtended = None, success_icon: IconSourceExtended = None, error_icon: IconSourceExtended = None, success_text: str = 'Success!', error_text: str = 'Error', icon_size: QSize | tuple[int, int] = QSize(16, 16), animation_speed: AnimationDuration = 100, auto_reset: bool = True, success_display_time: AnimationDuration = 1000, error_display_time: AnimationDuration = 2000, min_width: int | None = None, min_height: int | None = None, *args: Any, **kwargs: Any)

Bases: QToolButton

Button widget with integrated loading animation.

Features

• Loading state with animated spinner
• Success state with checkmark icon
• Error state with X icon
• Configurable loading, success, and error text/icons
• Configurable success and error result texts
• Smooth transitions between states
• Disabled state during loading
• Customizable animation speed
• Progress indication support (0-100)
• Auto-reset after completion with configurable display times
• Configurable spinner icon size
• Safe timer cleanup on widget destruction

Parameters:

Name	Type	Description	Default
parent	WidgetParent	The parent widget (default: None).	None
text	str	Button text (default: "").	''
icon	IconSourceExtended	Button icon (ThemeIcon, QIcon, QPixmap, or path, default: None).	None
loading_text	str	Text to display during loading (default: "Loading...").	'Loading...'
loading_icon	IconSourceExtended	Icon to display during loading (ThemeIcon, QIcon, QPixmap, or path, default: None, auto-generated).	None
success_icon	IconSourceExtended	Icon to display on success (ThemeIcon, QIcon, QPixmap, or path, default: None, auto-generated checkmark).	None
error_icon	IconSourceExtended	Icon to display on error (ThemeIcon, QIcon, QPixmap, or path, default: None, auto-generated X mark).	None
success_text	str	Text to display when loading succeeds (default: "Success!").	'Success!'
error_text	str	Text to display when loading fails (default: "Error").	'Error'
icon_size	QSize | tuple[int, int]	Size of spinner and state icons (default: QSize(16, 16)).	QSize(16, 16)
animation_speed	AnimationDuration	Animation speed in milliseconds (default: 100).	100
auto_reset	bool	Whether to auto-reset after loading (default: True).	True
success_display_time	AnimationDuration	Time to display success state in milliseconds (default: 1000).	1000
error_display_time	AnimationDuration	Time to display error state in milliseconds (default: 2000).	2000
min_width	int | None	Minimum width of the button (default: None, auto-calculated).	None
min_height	int | None	Minimum height of the button (default: None, auto-calculated).	None
*args	Any	Additional arguments passed to QToolButton.	()
**kwargs	Any	Additional keyword arguments passed to QToolButton.	{}

Signals

loadingStarted(): Emitted when loading starts. loadingFinished(): Emitted when loading finishes successfully. loadingFailed(str): Emitted when loading fails with error message. progressChanged(int): Emitted when progress value changes (0-100).

Example

from ezqt_widgets import LoaderButton btn = LoaderButton(text="Submit", loading_text="Sending...") btn.loadingFinished.connect(lambda: print("done")) btn.startLoading()

After completion:

btn.stopLoading(success=True) btn.show()

Initialize the loader button.

icon property writable

icon: QIcon | None

Get or set the button icon.

Returns:

Type	Description
QIcon | None	The current button icon, or None if no icon is set.

text property writable

text: str

Get or set the button text.

Returns:

Type	Description
str	The current button text.

loading_icon property writable

loading_icon: QIcon | None

Get or set the loading icon.

Returns:

Type	Description
QIcon | None	The current loading icon, or None if not set.

success_icon property writable

success_icon: QIcon | None

Get or set the success icon.

Returns:

Type	Description
QIcon | None	The current success icon, or None if not set.

error_icon property writable

error_icon: QIcon | None

Get or set the error icon.

Returns:

Type	Description
QIcon | None	The current error icon, or None if not set.

loading_text property writable

loading_text: str

Get or set the loading text.

Returns:

Type	Description
str	The current loading text.

success_text property writable

success_text: str

Get or set the text displayed on success.

Returns:

Type	Description
str	The current success text.

error_text property writable

error_text: str

Get or set the base text displayed on error.

Returns:

Type	Description
str	The current error text.

icon_size property writable

icon_size: QSize

Get or set the spinner and state icon size.

Returns:

Type	Description
QSize	The current icon size.

progress property writable

progress: int

Get or set the current progress value (0-100).

When set during loading, the progress percentage is shown in the text label instead of the generic loading text. The spinner is kept visible. Setting this property outside of loading state is silently ignored.

Returns:

Type	Description
int	The current progress value.

success_display_time property writable

success_display_time: AnimationDuration

Get or set the success display time.

Returns:

Type	Description
AnimationDuration	The success display time in milliseconds.

error_display_time property writable

error_display_time: AnimationDuration

Get or set the error display time.

Returns:

Type	Description
AnimationDuration	The error display time in milliseconds.

is_loading property

is_loading: bool

Get the current loading state.

Returns:

Type	Description
bool	True if loading, False otherwise.

animation_speed property writable

animation_speed: AnimationDuration

Get or set the animation speed.

Returns:

Type	Description
AnimationDuration	The animation speed in milliseconds.

auto_reset property writable

auto_reset: bool

Get or set auto-reset behavior.

Returns:

Type	Description
bool	True if auto-reset is enabled, False otherwise.

min_width property writable

min_width: int | None

Get or set the minimum width of the button.

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

Returns:

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

startLoading

startLoading() -> None

Start the loading animation.

stopLoading

stopLoading(success: bool = True, error_message: str = '') -> None

Stop the loading animation.

Parameters:

Name	Type	Description	Default
success	bool	Whether the operation succeeded (default: True).	True
error_message	str	Error message if operation failed (default: "").	''

resetLoading

resetLoading() -> None

Reset the button to its original state.

Can be called manually when auto_reset is False.

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

mousePressEvent

mousePressEvent(event: QMouseEvent) -> None

Handle mouse press events.

Parameters:

Name	Type	Description	Default
event	QMouseEvent	The mouse event.	required

sizeHint

sizeHint() -> QSize

Get the recommended size for the button.

Returns:

Type	Description
QSize	The recommended size.

minimumSizeHint

minimumSizeHint() -> QSize

Get the minimum size hint for the button.

Returns:

Type	Description
QSize	The minimum size hint.

refreshStyle

refreshStyle() -> None

Refresh the widget's style.

Useful after dynamic stylesheet changes.

AutoCompleteInput

AutoCompleteInput(parent: WidgetParent = None, suggestions: list[str] | None = None, case_sensitive: bool = False, filter_mode: MatchFlag = MatchContains, completion_mode: CompletionMode = PopupCompletion, *args: Any, **kwargs: Any)

Bases: QLineEdit

QLineEdit subclass with autocompletion support.

Provides a text input widget with autocompletion functionality. You can provide a list of suggestions (strings) to be used for autocompletion.

Parameters:

Name	Type	Description	Default
parent	WidgetParent	The parent widget (default: None).	None
suggestions	list[str] | None	List of strings to use for autocompletion (default: empty list).	None
case_sensitive	bool	Whether the autocompletion is case sensitive (default: False).	False
filter_mode	MatchFlag	Filter mode for completion (default: Qt.MatchFlag.MatchContains).	MatchContains
completion_mode	CompletionMode	Completion mode (default: QCompleter.CompletionMode.PopupCompletion).	PopupCompletion
*args	Any	Additional arguments passed to QLineEdit.	()
**kwargs	Any	Additional keyword arguments passed to QLineEdit.	{}

Properties

suggestions: Get or set the list of suggestions for autocompletion. case_sensitive: Get or set whether autocompletion is case sensitive. filter_mode: Get or set the filter mode for completion. completion_mode: Get or set the completion mode.

Example

from ezqt_widgets import AutoCompleteInput inp = AutoCompleteInput(suggestions=["Alice", "Bob", "Charlie"]) inp.case_sensitive = False inp.suggestions = ["Alice", "Bob", "Charlie", "Dave"] inp.show()

Initialize the auto-complete input.

suggestions property writable

suggestions: list[str]

Get the list of suggestions.

Returns:

Type	Description
list[str]	A copy of the current suggestions list.

case_sensitive property writable

case_sensitive: bool

Get whether autocompletion is case sensitive.

Returns:

Type	Description
bool	True if case sensitive, False otherwise.

filter_mode property writable

filter_mode: MatchFlag

Get the filter mode for completion.

Returns:

Type	Description
MatchFlag	The current filter mode.

completion_mode property writable

completion_mode: CompletionMode

Get the completion mode.

Returns:

Type	Description
CompletionMode	The current completion mode.

addSuggestion

addSuggestion(suggestion: str) -> None

Add a suggestion to the list.

Parameters:

Name	Type	Description	Default
suggestion	str	The suggestion string to add.	required

removeSuggestion

removeSuggestion(suggestion: str) -> None

Remove a suggestion from the list.

Parameters:

Name	Type	Description	Default
suggestion	str	The suggestion string to remove.	required

clearSuggestions

clearSuggestions() -> None

Clear all suggestions.

refreshStyle

refreshStyle() -> None

Refresh the widget's style.

Useful after dynamic stylesheet changes.

FilePickerInput

FilePickerInput(parent: WidgetParent = None, *, placeholder: str = 'Select a file...', mode: Literal['file', 'directory'] = 'file', filter: str = '', dialog_title: str = '')

Bases: QWidget

Composite input widget combining a QLineEdit and a folder icon button.

Clicking the folder button opens a QFileDialog (file or directory mode). The selected path is displayed in the QLineEdit. The widget supports theme-aware icon rendering via ThemeIcon.

Features

• File or directory selection via QFileDialog
• Editable QLineEdit for manual path entry
• Theme-aware folder icon via ThemeIcon
• Signals for file selection and path text changes
• Configurable placeholder, filter, and dialog title

Parameters:

Name	Type	Description	Default
parent	WidgetParent	The parent widget (default: None).	None
placeholder	str	Placeholder text for the QLineEdit (default: "Select a file...").	'Select a file...'
mode	Literal['file', 'directory']	Selection mode, either "file" or "directory" (default: "file").	'file'
filter	str	File filter string for QFileDialog, e.g. "Images (.png .jpg)" (default: "").	''
dialog_title	str	Title for the QFileDialog window (default: "").	''

Properties

path: Get or set the current file/directory path. mode: Get or set the selection mode ("file" or "directory"). placeholder_text: Get or set the QLineEdit placeholder text. filter: Get or set the file dialog filter string. dialog_title: Get or set the file dialog window title.

Signals

fileSelected(str): Emitted when a path is chosen via the dialog. pathChanged(str): Emitted on every text change in the QLineEdit.

Example

from ezqt_widgets import FilePickerInput picker = FilePickerInput(placeholder="Choose a CSV file...", ... filter="CSV files (*.csv)") picker.fileSelected.connect(lambda p: print(f"Selected: {p}")) picker.show()

Initialize the file picker input.

path property writable

path: str

Get the current path displayed in the QLineEdit.

Returns:

Type	Description
str	The current path string.

mode property writable

mode: Literal['file', 'directory']

Get the file dialog selection mode.

Returns:

Type	Description
Literal['file', 'directory']	The current mode ("file" or "directory").

placeholder_text property writable

placeholder_text: str

Get the QLineEdit placeholder text.

Returns:

Type	Description
str	The current placeholder text.

filter property writable

filter: str

Get the file dialog filter string.

Returns:

Type	Description
str	The current filter string.

dialog_title property writable

dialog_title: str

Get the file dialog window title.

Returns:

Type	Description
str	The current dialog title.

clear

clear() -> None

Clear the current path from the QLineEdit.

setTheme

setTheme(theme: str) -> None

Update the folder 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.

PasswordInput

PasswordInput(parent: QWidget | None = None, show_strength: bool = True, strength_bar_height: int = 3, show_icon: IconSourceExtended = SVG_EYE_OPEN, hide_icon: IconSourceExtended = SVG_EYE_CLOSED, icon_size: QSize | tuple[int, int] = QSize(16, 16), *args: Any, **kwargs: Any)

Bases: QWidget

Enhanced password input widget with integrated strength bar.

Features

• QLineEdit in password mode with integrated strength bar
• Right-side icon with click functionality
• Icon management system (ThemeIcon, QIcon, QPixmap, path, URL, SVG)
• Animated strength bar that fills the bottom border
• Signal strengthChanged(int) emitted on password change
• Color-coded strength indicator
• External QSS styling support with CSS variables

Parameters:

Name	Type	Description	Default
parent	QWidget | None	The parent widget (default: None).	None
show_strength	bool	Whether to show the password strength bar (default: True).	True
strength_bar_height	int	Height of the strength bar in pixels (default: 3).	3
show_icon	IconSourceExtended	Icon for show password (ThemeIcon, QIcon, QPixmap, str, or None, default: URL to icons8.com).	SVG_EYE_OPEN
hide_icon	IconSourceExtended	Icon for hide password (ThemeIcon, QIcon, QPixmap, str, or None, default: URL to icons8.com).	SVG_EYE_CLOSED
icon_size	QSize | tuple[int, int]	Size of the icon (QSize or tuple, default: QSize(16, 16)).	QSize(16, 16)
*args	Any	Additional arguments passed to QWidget.	()
**kwargs	Any	Additional keyword arguments passed to QWidget.	{}

Properties

password: Get or set the password text. show_strength: Get or set whether to show the strength bar. strength_bar_height: Get or set the strength bar height. show_icon: Get or set the show password icon. hide_icon: Get or set the hide password icon. icon_size: Get or set the icon size.

Signals

strengthChanged(int): Emitted when password strength changes. iconClicked(): Emitted when the icon is clicked.

Initialize the password input widget.

show_icon property writable

show_icon: QIcon | None

Get the show password icon.

Returns:

Type	Description
QIcon | None	The current show password icon, or None if not set.

hide_icon property writable

hide_icon: QIcon | None

Get the hide password icon.

Returns:

Type	Description
QIcon | None	The current hide password icon, or None if not set.

password property writable

password: str

Get the password text.

Returns:

Type	Description
str	The current password text.

show_strength property writable

show_strength: bool

Get whether the strength bar is shown.

Returns:

Type	Description
bool	True if strength bar is shown, False otherwise.

strength_bar_height property writable

strength_bar_height: int

Get the strength bar height.

Returns:

Type	Description
int	The current strength bar height in pixels.

icon_size property writable

icon_size: QSize

Get the icon size.

Returns:

Type	Description
QSize	The current icon size.

togglePassword

togglePassword() -> None

Toggle password visibility.

updateStrength

updateStrength(text: str) -> None

Update password strength.

Parameters:

Name	Type	Description	Default
text	str	The password text to evaluate.	required

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

SearchInput

SearchInput(parent: WidgetParent = None, max_history: int = 20, search_icon: IconSourceExtended = None, icon_position: str = 'left', clear_button: bool = True, *args: Any, **kwargs: Any)

Bases: QLineEdit

QLineEdit subclass for search input with integrated history.

Features

• Maintains a history of submitted searches
• Navigate history with up/down arrows
• Emits a searchSubmitted(str) signal on validation (Enter)
• Optional search icon (left or right)
• Optional clear button

Parameters:

Name	Type	Description	Default
parent	WidgetParent	The parent widget (default: None).	None
max_history	int	Maximum number of history entries to keep (default: 20).	20
search_icon	IconSourceExtended	Icon to display as search icon (ThemeIcon, QIcon, QPixmap, str, or None, default: None).	None
icon_position	str	Icon position, 'left' or 'right' (default: 'left').	'left'
clear_button	bool	Whether to show a clear button (default: True).	True
*args	Any	Additional arguments passed to QLineEdit.	()
**kwargs	Any	Additional keyword arguments passed to QLineEdit.	{}

Properties

search_icon: Get or set the search icon. icon_position: Get or set the icon position ('left' or 'right'). clear_button: Get or set whether the clear button is shown. max_history: Get or set the maximum history size.

Signals

searchSubmitted(str): Emitted when a search is submitted (Enter key).

Example

from ezqt_widgets import SearchInput search = SearchInput(max_history=10, clear_button=True) search.searchSubmitted.connect(lambda q: print(f"Search: {q}")) search.setPlaceholderText("Type and press Enter...") search.show()

Initialize the search input.

search_icon property writable

search_icon: QIcon | None

Get the search icon.

Returns:

Type	Description
QIcon | None	The current search icon, or None if not set.

icon_position property writable

icon_position: str

Get the icon position.

Returns:

Type	Description
str	The current icon position ('left' or 'right').

clear_button property writable

clear_button: bool

Get whether the clear button is shown.

Returns:

Type	Description
bool	True if clear button is shown, False otherwise.

max_history property writable

max_history: int

Get the maximum history size.

Returns:

Type	Description
int	The maximum number of history entries.

addToHistory

addToHistory(text: str) -> None

Add a search term to history.

Parameters:

Name	Type	Description	Default
text	str	The search term to add.	required

getHistory

getHistory() -> list[str]

Get the search history.

Returns:

Type	Description
list[str]	A copy of the search history list.

clearHistory

clearHistory() -> None

Clear the search history.

setHistory

setHistory(history_list: list[str]) -> None

Set the search history.

Parameters:

Name	Type	Description	Default
history_list	list[str]	List of history entries to set.	required

keyPressEvent

keyPressEvent(event: QKeyEvent) -> None

Handle key press events.

Parameters:

Name	Type	Description	Default
event	QKeyEvent	The key event.	required

setTheme

setTheme(theme: str) -> None

Update the search 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.

SpinBoxInput

SpinBoxInput(parent: WidgetParent = None, *, value: int = 0, minimum: int = 0, maximum: int = 100, step: int = 1, prefix: str = '', suffix: str = '')

Bases: QWidget

Custom numeric spin box with integrated decrement and increment buttons.

Provides a fully stylable numeric input with − and + buttons flanking a central QLineEdit. Supports mouse wheel increments and real-time QIntValidator clamping.

Features

• Decrement (−) and increment (+) QToolButtons
• Central QLineEdit with QIntValidator
• Mouse wheel increments/decrements by step
• Value clamped between minimum and maximum at all times
• Optional prefix and suffix labels
• Signal emitted only when value changes

Parameters:

Name	Type	Description	Default
parent	WidgetParent	The parent widget (default: None).	None
value	int	Initial value (default: 0).	0
minimum	int	Minimum allowed value (default: 0).	0
maximum	int	Maximum allowed value (default: 100).	100
step	int	Step size for increment/decrement (default: 1).	1
prefix	str	String prepended to the displayed value (default: "").	''
suffix	str	String appended to the displayed value (default: "").	''

Properties

value: Get or set the current integer value. minimum: Get or set the minimum allowed value. maximum: Get or set the maximum allowed value. step: Get or set the step size. prefix: Get or set the display prefix. suffix: Get or set the display suffix.

Signals

valueChanged(int): Emitted when the value changes.

Example

from ezqt_widgets import SpinBoxInput spin = SpinBoxInput(value=10, minimum=0, maximum=100, step=5) spin.valueChanged.connect(lambda v: print(f"Value: {v}")) spin.show()

Initialize the spin box input.

value property writable

value: int

Get the current integer value.

Returns:

Type	Description
int	The current value.

minimum property writable

minimum: int

Get the minimum allowed value.

Returns:

Type	Description
int	The current minimum.

maximum property writable

maximum: int

Get the maximum allowed value.

Returns:

Type	Description
int	The current maximum.

step property writable

step: int

Get the step size for increment/decrement.

Returns:

Type	Description
int	The current step size.

prefix property writable

prefix: str

Get the display prefix.

Returns:

Type	Description
str	The current prefix string.

suffix property writable

suffix: str

Get the display suffix.

Returns:

Type	Description
str	The current suffix string.

setValue

setValue(value: int) -> None

Set the value, clamped between minimum and maximum.

Parameters:

Name	Type	Description	Default
value	int	The new value to set.	required

stepUp

stepUp() -> None

Increment the value by step, clamped at maximum.

stepDown

stepDown() -> None

Decrement the value by step, clamped at minimum.

wheelEvent

wheelEvent(event: QWheelEvent) -> None

Handle mouse wheel to increment or decrement by step.

Parameters:

Name	Type	Description	Default
event	QWheelEvent	The wheel event.	required

refreshStyle

refreshStyle() -> None

Refresh the widget style.

Useful after dynamic stylesheet changes.

TabReplaceTextEdit

TabReplaceTextEdit(parent: WidgetParent = None, tab_replacement: str = '\n', sanitize_on_paste: bool = True, remove_empty_lines: bool = True, preserve_whitespace: bool = False, *args: Any, **kwargs: Any)

Bases: QPlainTextEdit

QPlainTextEdit subclass with tab replacement and text sanitization.

Sanitizes pasted text by replacing tab characters according to the chosen mode and removing empty lines. Useful for pasting tabular data or ensuring clean input.

Parameters:

Name	Type	Description	Default
parent	WidgetParent	The parent widget (default: None).	None
tab_replacement	str	The string to replace tab characters with (default: "\n").	'\n'
sanitize_on_paste	bool	Whether to sanitize pasted text (default: True).	True
remove_empty_lines	bool	Whether to remove empty lines during sanitization (default: True).	True
preserve_whitespace	bool	Whether to preserve leading/trailing whitespace (default: False).	False
*args	Any	Additional arguments passed to QPlainTextEdit.	()
**kwargs	Any	Additional keyword arguments passed to QPlainTextEdit.	{}

Properties

tab_replacement: Get or set the string used to replace tab characters. sanitize_on_paste: Enable or disable sanitizing pasted text. remove_empty_lines: Get or set whether to remove empty lines. preserve_whitespace: Get or set whether to preserve whitespace.

Example

from ezqt_widgets import TabReplaceTextEdit editor = TabReplaceTextEdit(tab_replacement=";", remove_empty_lines=True) editor.setPlainText("alpha\tbeta\n\ngamma\tdelta")

Paste triggers sanitization; tabs become ";" and empty lines removed

editor.show()

Initialize the tab replace text edit.

tab_replacement property writable

tab_replacement: str

Get the string used to replace tab characters.

Returns:

Type	Description
str	The current tab replacement string.

sanitize_on_paste property writable

sanitize_on_paste: bool

Get whether sanitizing pasted text is enabled.

Returns:

Type	Description
bool	True if sanitization is enabled, False otherwise.

remove_empty_lines property writable

remove_empty_lines: bool

Get whether empty lines are removed.

Returns:

Type	Description
bool	True if empty lines are removed, False otherwise.

preserve_whitespace property writable

preserve_whitespace: bool

Get whether whitespace is preserved.

Returns:

Type	Description
bool	True if whitespace is preserved, False otherwise.

sanitizeText

sanitizeText(text: str) -> str

Sanitize text by replacing tabs and optionally removing empty lines.

Parameters:

Name	Type	Description	Default
text	str	The text to sanitize.	required

Returns:

Type	Description
str	The sanitized text.

keyPressEvent

keyPressEvent(event: QKeyEvent) -> None

Handle key press events.

Overridden method from QPlainTextEdit. Modifies the behavior of the paste operation and tab key handling.

Parameters:

Name	Type	Description	Default
event	QKeyEvent	The key event.	required

refreshStyle

refreshStyle() -> None

Refresh the widget's style.

Useful after dynamic stylesheet changes.

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

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

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.

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.

opacity property writable

opacity: float

Get the opacity of the hover icon.

Returns:

Type	Description
float	The current opacity level.

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

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.

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.

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.

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

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.

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.

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

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

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

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

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: show_source: true members_order: source