fuzzy_search_list

_fuzzy_search_list ¶

Fuzzy search list widget with relevance-based filtering and sorting.

Classes:

Name	Description
`FXFuzzySearchList`	A searchable list widget with fuzzy matching capabilities.

Functions:

Name	Description
`example`	Run an example demonstrating the FXFuzzySearchList widget.

Classes¶

FXFuzzySearchList ¶

FXFuzzySearchList(
    parent: Optional[QWidget] = None,
    placeholder: str = "Search...",
    ratio: float = 0.5,
    show_ratio_slider: bool = False,
    color_match: bool = True,
)

Bases: FXThemeAware, QWidget


              flowchart TD
              fxgui.fxwidgets._fuzzy_search_list.FXFuzzySearchList[FXFuzzySearchList]
              fxgui.fxstyle.FXThemeAware[FXThemeAware]

                              fxgui.fxstyle.FXThemeAware --> fxgui.fxwidgets._fuzzy_search_list.FXFuzzySearchList
                


              click fxgui.fxwidgets._fuzzy_search_list.FXFuzzySearchList href "" "fxgui.fxwidgets._fuzzy_search_list.FXFuzzySearchList"
              click fxgui.fxstyle.FXThemeAware href "" "fxgui.fxstyle.FXThemeAware"

A searchable list widget with fuzzy matching capabilities.

This widget combines a search bar with a list view that uses fuzzy matching to filter and sort items by relevance. Items are colored based on their match quality (green for good matches, red for poor matches).

Parameters:

Name	Type	Description	Default
`parent` ¶	`Optional[QWidget]`	Parent widget.	`None`
`placeholder` ¶	`str`	Placeholder text for the search input.	`'Search...'`
`ratio` ¶	`float`	Initial similarity ratio threshold (0.0 to 1.0).	`0.5`
`show_ratio_slider` ¶	`bool`	Whether to show the ratio adjustment slider.	`False`
`color_match` ¶	`bool`	Whether to color items based on match quality.	`True`

Signals

item_selected: Emitted when an item is clicked. Passes the item text. item_double_clicked: Emitted when an item is double-clicked. Passes the item text. item_activated: Emitted when Enter is pressed on an item. Passes the item text. selection_changed: Emitted when the selection changes. Passes a list of selected item texts.

Examples:

Basic usage with a list of strings:

>>> fuzzy_list = FXFuzzySearchList(placeholder="Search fruits...")
>>> fuzzy_list.set_items(["apple", "apricot", "banana", "cherry"])
>>> fuzzy_list.item_selected.connect(lambda text: print(f"Selected: {text}"))

With ratio slider for user adjustment:

>>> fuzzy_list = FXFuzzySearchList(show_ratio_slider=True, ratio=0.6)
>>> fuzzy_list.set_items(["character_hero", "character_villain", "prop_chair"])

Methods:

Name	Description
`add_item`	Add a single item to the list.
`clear`	Clear all items from the list.
`clear_search`	Clear the search input.
`remove_item`	Remove an item from the list by its text.
`select_item`	Select an item by its text.
`setFocus`	Set focus to the search input.
`set_color_match`	Enable or disable color-coded match quality.
`set_items`	Set the list items from a list of strings.
`set_placeholder`	Set the search bar placeholder text.
`set_selection_mode`	Set the list view selection mode.
`show_ratio_slider`	Show or hide the ratio adjustment slider.

Attributes:

Name	Type	Description
`current_item`	`Optional[str]`	Return the current item text.
`items`	`List[str]`	Return all items in the source model.
`list_view`	`QListView`	Return the list view for advanced customization.
`proxy_model`	`FXSortFilterProxyModel`	Return the proxy model for advanced customization.
`ratio`	`float`	Return the current similarity ratio threshold.
`search_text`	`str`	Return the current search text.
`selected_items`	`List[str]`	Return currently selected items.
`source_model`	`QStandardItemModel`	Return the source model for advanced customization.
`visible_items`	`List[str]`	Return currently visible (filtered) items.

Attributes¶

current_item `property` ¶

current_item: Optional[str]

Return the current item text.

Returns:

Type	Description
`Optional[str]`	The current item text, or None if no item is current.

items `property` ¶

items: List[str]

Return all items in the source model.

Returns:

Type	Description
`List[str]`	List of all item texts.

list_view `property` ¶

list_view: QListView

Return the list view for advanced customization.

Returns:

Type	Description
`QListView`	The underlying QListView.

proxy_model `property` ¶

proxy_model: FXSortFilterProxyModel

Return the proxy model for advanced customization.

Returns:

Type	Description
`FXSortFilterProxyModel`	The underlying FXSortFilterProxyModel.

ratio `property` `writable` ¶

ratio: float

Return the current similarity ratio threshold.

Returns:

Type	Description
`float`	The ratio threshold (0.0 to 1.0).

search_text `property` `writable` ¶

search_text: str

Return the current search text.

Returns:

Type	Description
`str`	The current search text.

selected_items `property` ¶

selected_items: List[str]

Return currently selected items.

Returns:

Type	Description
`List[str]`	List of selected item texts.

source_model `property` ¶

source_model: QStandardItemModel

Return the source model for advanced customization.

Returns:

Type	Description
`QStandardItemModel`	The underlying QStandardItemModel.

visible_items `property` ¶

visible_items: List[str]

Return currently visible (filtered) items.

Returns:

Type	Description
`List[str]`	List of visible item texts.

Functions¶

add_item ¶

add_item(text: str) -> None

Add a single item to the list.

Parameters:

Name	Type	Description	Default
`text` ¶	`str`	The item text to add.	required

clear ¶

clear() -> None

Clear all items from the list.

clear_search ¶

clear_search() -> None

Clear the search input.

remove_item ¶

remove_item(text: str) -> bool

Remove an item from the list by its text.

Parameters:

Name	Type	Description	Default
`text` ¶	`str`	The item text to remove.	required

Returns:

Type	Description
`bool`	True if the item was found and removed, False otherwise.

select_item ¶

select_item(text: str) -> bool

Select an item by its text.

Parameters:

Name	Type	Description	Default
`text` ¶	`str`	The item text to select.	required

Returns:

Type	Description
`bool`	True if the item was found and selected, False otherwise.

setFocus ¶

setFocus() -> None

Set focus to the search input.

set_color_match ¶

set_color_match(enabled: bool) -> None

Enable or disable color-coded match quality.

Parameters:

Name	Type	Description	Default
`enabled` ¶	`bool`	Whether to enable color matching.	required

set_items ¶

set_items(items: List[str]) -> None

Set the list items from a list of strings.

Parameters:

Name	Type	Description	Default
`items` ¶	`List[str]`	List of strings to display.	required

set_placeholder ¶

set_placeholder(text: str) -> None

Set the search bar placeholder text.

Parameters:

Name	Type	Description	Default
`text` ¶	`str`	The placeholder text.	required

set_selection_mode ¶

set_selection_mode(mode: SelectionMode) -> None

Set the list view selection mode.

Parameters:

Name	Type	Description	Default
`mode` ¶	`SelectionMode`	The selection mode (e.g., SingleSelection, ExtendedSelection).	required

show_ratio_slider ¶

show_ratio_slider(visible: bool = True) -> None

Show or hide the ratio adjustment slider.

Parameters:

Name	Type	Description	Default
`visible` ¶	`bool`	Whether to show the slider.	`True`

Functions¶

example ¶

example() -> None

Run an example demonstrating the FXFuzzySearchList widget.

fuzzy_search_list