Button widgets

Specialized button widgets for date selection, icon display, and loading state management.

---

DateButton

A QToolButton that displays the currently selected date and opens a calendar dialog when clicked.

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.

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.

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.

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.

options: members_order: source

---

DatePickerDialog

A QDialog containing a QCalendarWidget for date selection. Used internally by DateButton and available as a standalone dialog.

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.

options: members_order: source

---

IconButton

A QToolButton that displays an icon from any supported source with an optional text label.

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.

icon_size property writable

icon_size: QSize

Get or set the icon size.

Returns:

Type	Description
QSize	The current icon size.

text_visible property writable

text_visible: bool

Get or set text visibility.

Returns:

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

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.

options: members_order: source

---

LoaderButton

A QToolButton that transitions between a normal state, a loading state, a success state, and an error state.

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.

text property writable

text: str

Get or set the button text.

Returns:

Type	Description
str	The current button text.

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.

loading_text property writable

loading_text: str

Get or set the loading text.

Returns:

Type	Description
str	The current loading 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.

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.

options: members_order: source