Skip to content

Input widgets

Text input widgets with auto-completion, password management, search history, tab sanitization, file selection, and numeric spin input.

AutoCompleteInput

A QLineEdit subclass with a built-in QCompleter powered by a configurable list of string suggestions.

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.

options: members_order: source

FilePickerInput

A composite QWidget combining a QLineEdit and a folder icon button that opens a QFileDialog for file or directory selection.

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.

options: members_order: source

PasswordInput

A QWidget containing a QLineEdit in password mode with an optional strength bar and a visibility-toggle icon.

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.

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.

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.

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

options: members_order: source

SearchInput

A QLineEdit subclass that maintains a submission history navigable with the Up/Down arrow keys.

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.

options: members_order: source

SpinBoxInput

A custom numeric spin box QWidget with decrement and increment buttons flanking a central QLineEdit.

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.

options: members_order: source

TabReplaceTextEdit

A QPlainTextEdit subclass that replaces tab characters with a configurable string on paste.

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.

options: members_order: source

AutoCompleteInput

A QLineEdit subclass with a built-in QCompleter powered by a configurable list of string suggestions.

Constructor parameters:

Parameter Type Default Description
parent QWidget \| None None Parent widget
suggestions list[str] \| None None Initial list of completion candidates
case_sensitive bool False Whether completion matching is case-sensitive
filter_mode Qt.MatchFlag Qt.MatchFlag.MatchContains How typed text is matched against suggestions
completion_mode QCompleter.CompletionMode QCompleter.CompletionMode.PopupCompletion How completions are presented

Properties:

Property Type Description
suggestions list[str] Gets or sets the full list of completion candidates (returns a copy)
case_sensitive bool Gets or sets case-sensitivity of matching
filter_mode Qt.MatchFlag Gets or sets the filter mode
completion_mode QCompleter.CompletionMode Gets or sets the completion mode

Methods:

Method Signature Description
addSuggestion() (suggestion: str) -> None Adds a candidate if it is not already present
removeSuggestion() (suggestion: str) -> None Removes a candidate if it exists
clearSuggestions() () -> None Removes all candidates
refreshStyle() () -> None Re-applies the QSS stylesheet

Example:

from PySide6.QtWidgets import QApplication
from ezqt_widgets import AutoCompleteInput

app = QApplication([])

inp = AutoCompleteInput(
    suggestions=["Python", "PySide6", "Qt", "PyQt6"],
    case_sensitive=False,
)
inp.addSuggestion("Rust")
inp.show()

app.exec()

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.

PasswordInput

A QWidget containing a QLineEdit in password mode, an optional colored strength bar, and a visibility-toggle icon.

Signals:

Signal Signature Emitted when
strengthChanged (int) The password text changes; value is the new strength score (0–100)
iconClicked () The visibility-toggle icon is clicked

Constructor parameters:

Parameter Type Default Description
parent QWidget \| None None Parent widget
show_strength bool True Whether to display the strength progress bar
strength_bar_height int 3 Height of the strength bar in pixels
show_icon QIcon \| QPixmap \| str \| None icons8 URL Icon displayed when the password is hidden (eye-open)
hide_icon QIcon \| QPixmap \| str \| None icons8 URL Icon displayed when the password is visible (eye-closed)
icon_size QSize \| tuple[int, int] QSize(16, 16) Size of the toggle icon

Properties:

Property Type Description
password str Gets or sets the raw password text
show_strength bool Gets or sets strength bar visibility
strength_bar_height int Gets or sets the bar height in pixels (minimum 1)
show_icon QIcon \| None Gets or sets the icon shown when password is hidden
hide_icon QIcon \| None Gets or sets the icon shown when password is visible
icon_size QSize Gets or sets the toggle icon size

Methods:

Method Signature Description
togglePassword() () -> None Switches the echo mode and updates the toggle icon
updateStrength() (text: str) -> None Recalculates the strength score and updates the bar
refreshStyle() () -> None Triggers a repaint

Strength score:

The score ranges from 0 to 100. Each criterion adds points:

Criterion Points
Length >= 8 +25
Contains uppercase letter +15
Contains lowercase letter +15
Contains digit +20
Contains special character +25

Bar color by score: 0–29 red, 30–59 orange, 60–79 green, 80–100 dark green.

Example:

from PySide6.QtWidgets import QApplication
from ezqt_widgets import PasswordInput

app = QApplication([])

field = PasswordInput(show_strength=True, strength_bar_height=4)
field.strengthChanged.connect(lambda score: print(f"Strength: {score}/100"))
field.show()

app.exec()

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.

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.

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.

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

A QLineEdit subclass that maintains a submission history navigable with the Up/Down arrow keys and emits searchSubmitted when the user presses Enter.

Signals:

Signal Signature Emitted when
searchSubmitted (str) The user presses Enter/Return; the text is also added to history

Constructor parameters:

Parameter Type Default Description
parent QWidget \| None None Parent widget
max_history int 20 Maximum number of history entries to keep
search_icon QIcon \| QPixmap \| str \| None None Optional icon displayed in the field
icon_position str "left" Icon position: "left" or "right"
clear_button bool True Whether to show Qt's built-in clear button

Properties:

Property Type Description
search_icon QIcon \| None Gets or sets the search icon
icon_position str Gets or sets the icon position ("left" or "right")
clear_button bool Gets or sets clear button visibility
max_history int Gets or sets the history size limit

Methods:

Method Signature Description
addToHistory() (text: str) -> None Adds a term to the front of history; ignores empty/whitespace-only strings
getHistory() () -> list[str] Returns a copy of the current history list
clearHistory() () -> None Empties the history and resets the navigation index
setHistory() (history_list: list[str]) -> None Replaces history with the provided list, trimmed to max_history
refreshStyle() () -> None Re-applies the QSS stylesheet

Keyboard navigation:

Key Effect
Enter / Return Submits current text, adds to history, emits searchSubmitted
Up Navigates backward through history
Down Navigates forward through history; restores current input at the end

Example:

from PySide6.QtWidgets import QApplication
from ezqt_widgets import SearchInput

app = QApplication([])

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

app.exec()

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.

TabReplaceTextEdit

A QPlainTextEdit subclass that intercepts paste events and replaces tab characters with a configurable string. Useful for pasting tabular or CSV data.

Constructor parameters:

Parameter Type Default Description
parent QWidget \| None None Parent widget
tab_replacement str "\n" String substituted for each \t character
sanitize_on_paste bool True Whether to sanitize text on paste
remove_empty_lines bool True Whether to discard empty lines during sanitization
preserve_whitespace bool False If True, keeps lines that contain only whitespace

Properties:

Property Type Description
tab_replacement str Gets or sets the tab replacement string
sanitize_on_paste bool Gets or sets whether sanitization is active on paste
remove_empty_lines bool Gets or sets whether empty lines are removed
preserve_whitespace bool Gets or sets whitespace-only line preservation

Methods:

Method Signature Description
sanitizeText() (text: str) -> str Applies tab replacement and optional empty-line removal; returns the result
refreshStyle() () -> None Re-applies the QSS stylesheet

Behavior notes:

  • Pressing the Tab key inserts tab_replacement at the cursor (no focus change).
  • Paste events (Ctrl+V) are intercepted when sanitize_on_paste is True and route through sanitizeText() before insertion.

Example:

from PySide6.QtWidgets import QApplication
from ezqt_widgets import TabReplaceTextEdit

app = QApplication([])

# Pasting "col1\tcol2\n\ncol3\tcol4" produces "col1;col2\ncol3;col4"
editor = TabReplaceTextEdit(
    tab_replacement=";",
    remove_empty_lines=True,
)
editor.show()

app.exec()

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.

FilePickerInput

A composite QWidget combining a QLineEdit and a folder icon button that opens a QFileDialog for file or directory selection. Supports theme-aware icon rendering via ThemeIcon.

Signals:

Signal Signature Emitted when
fileSelected (str) A path is chosen via the dialog
pathChanged (str) The text in the QLineEdit changes (every keystroke)

Constructor parameters:

Parameter Type Default Description
parent QWidget \| None None Parent widget
placeholder str "Select a file..." Placeholder text for the QLineEdit
mode "file" \| "directory" "file" Whether the dialog selects a file or a directory
filter str "" File filter string, e.g. "Images (*.png *.jpg)"
dialog_title str "" Window title for the QFileDialog; auto-set if empty

Properties:

Property Type Description
path str Gets or sets the current path shown in the QLineEdit
mode "file" \| "directory" Gets or sets the selection mode
placeholder_text str Gets or sets the QLineEdit placeholder text
filter str Gets or sets the file dialog filter string
dialog_title str Gets or sets the file dialog window title

Methods:

Method Signature Description
clear() () -> None Clears the current path from the QLineEdit
setTheme() (theme: str) -> None Updates the folder icon color; connect to a themeChanged signal
refreshStyle() () -> None Re-applies the QSS stylesheet

Behavior notes:

  • fileSelected is emitted only when the user picks a path via the dialog, not on manual text edits.
  • pathChanged is emitted on every text change in the QLineEdit, including manual entry.
  • When mode is "directory", the dialog default title is "Select Directory"; when "file", it is "Select File". Setting dialog_title overrides both defaults.
  • Passing an invalid value to mode (neither "file" nor "directory") leaves the mode unchanged.

Example:

from PySide6.QtWidgets import QApplication
from ezqt_widgets import FilePickerInput

app = QApplication([])

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

app.exec()

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.

SpinBoxInput

A fully custom numeric spin box QWidget with integrated decrement (−) and increment (+) QToolButton flanking a central QLineEdit. Supports mouse wheel input and real-time QIntValidator clamping.

Signals:

Signal Signature Emitted when
valueChanged (int) The integer value changes

Constructor parameters:

Parameter Type Default Description
parent QWidget \| None None Parent widget
value int 0 Initial value; clamped between minimum and maximum
minimum int 0 Minimum allowed value
maximum int 100 Maximum allowed value
step int 1 Increment/decrement step size (minimum 1)
prefix str "" String prepended to the displayed value
suffix str "" String appended to the displayed value

Properties:

Property Type Description
value int Gets or sets the current value; clamped and emits valueChanged
minimum int Gets or sets the minimum; updates the validator and re-clamps the value
maximum int Gets or sets the maximum; updates the validator and re-clamps the value
step int Gets or sets the step size (minimum 1)
prefix str Gets or sets the display prefix; refreshes the QLineEdit
suffix str Gets or sets the display suffix; refreshes the QLineEdit

Methods:

Method Signature Description
setValue() (value: int) -> None Sets the value, clamped between minimum and maximum; emits valueChanged only if the value actually changes
stepUp() () -> None Increments the value by step, clamped at maximum
stepDown() () -> None Decrements the value by step, clamped at minimum
refreshStyle() () -> None Re-applies the QSS stylesheet

Behavior notes:

  • Mouse wheel scrolling increments (scroll up) or decrements (scroll down) by step when the widget has focus.
  • valueChanged is emitted only when the value actually changes, not on every display refresh.
  • prefix and suffix are stripped before parsing the QLineEdit text.

Example:

from PySide6.QtWidgets import QApplication
from ezqt_widgets import SpinBoxInput

app = QApplication([])

spin = SpinBoxInput(value=10, minimum=0, maximum=200, step=5, suffix=" px")
spin.valueChanged.connect(lambda v: print(f"Value: {v}"))
spin.show()

app.exec()

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.