fuzzy_search_tree

_fuzzy_search_tree ¶

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

Classes:

Name	Description
`FXFuzzySearchTree`	A searchable tree widget with fuzzy matching capabilities.

Functions:

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

Classes¶

FXFuzzySearchTree ¶

FXFuzzySearchTree(
    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_tree.FXFuzzySearchTree[FXFuzzySearchTree]
              fxgui.fxstyle.FXThemeAware[FXThemeAware]

                              fxgui.fxstyle.FXThemeAware --> fxgui.fxwidgets._fuzzy_search_tree.FXFuzzySearchTree
                


              click fxgui.fxwidgets._fuzzy_search_tree.FXFuzzySearchTree href "" "fxgui.fxwidgets._fuzzy_search_tree.FXFuzzySearchTree"
              click fxgui.fxstyle.FXThemeAware href "" "fxgui.fxstyle.FXThemeAware"

A searchable tree widget with fuzzy matching capabilities.

This widget combines a search bar with a tree 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).

The tree supports hierarchical data with parent-child relationships. When filtering, parent items remain visible if any of their children match.

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. item_expanded: Emitted when an item is expanded. Passes the item text. item_collapsed: Emitted when an item is collapsed. Passes the item text.

Examples:

Basic usage with hierarchical data:

>>> fuzzy_tree = FXFuzzySearchTree(placeholder="Search assets...")
>>> fuzzy_tree.add_item("Characters")
>>> fuzzy_tree.add_item("Hero", parent="Characters")
>>> fuzzy_tree.add_item("Villain", parent="Characters")
>>> fuzzy_tree.item_selected.connect(lambda text: print(f"Selected: {text}"))

With ratio slider for user adjustment:

>>> fuzzy_tree = FXFuzzySearchTree(show_ratio_slider=True, ratio=0.6)
>>> fuzzy_tree.set_items({
...     "Props": ["sword", "shield", "chair"],
...     "Vehicles": ["car", "truck", "motorcycle"],
... })

Methods:

Name	Description
`add_item`	Add a single item to the tree.
`clear`	Clear all items from the tree.
`clear_search`	Clear the search input.
`collapse_all`	Collapse all items in the tree.
`collapse_item`	Collapse an item by its text.
`expand_all`	Expand all items in the tree.
`expand_item`	Expand an item by its text.
`get_item`	Get an item by its text.
`remove_item`	Remove an item from the tree 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 tree items from a list or dictionary.
`set_placeholder`	Set the search bar placeholder text.
`set_selection_mode`	Set the tree 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 item texts in the source model.
`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.
`top_level_items`	`List[str]`	Return top-level item texts.
`tree_view`	`QTreeView`	Return the tree view for advanced customization.

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 item texts in the source model.

Returns:

Type	Description
`List[str]`	List of all item texts (including nested items).

proxy_model `property` ¶

proxy_model: FXSortFilterProxyModel

Return the proxy model for advanced customization.

Returns:

Type	Description
`FXSortFilterProxyModel`	The underlying proxy model.

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.

top_level_items `property` ¶

top_level_items: List[str]

Return top-level item texts.

Returns:

Type	Description
`List[str]`	List of top-level item texts only.

tree_view `property` ¶

tree_view: QTreeView

Return the tree view for advanced customization.

Returns:

Type	Description
`QTreeView`	The underlying QTreeView.

Functions¶

add_item ¶

add_item(
    text: str, parent: Optional[str] = None, data: Optional[dict] = None
) -> QStandardItem

Add a single item to the tree.

Parameters:

Name	Type	Description	Default
`text` ¶	`str`	The item text to add.	required
`parent` ¶	`Optional[str]`	The parent item text. If None, adds as top-level item.	`None`
`data` ¶	`Optional[dict]`	Optional dictionary of user data to store on the item.	`None`

Returns:

Type	Description
`QStandardItem`	The created QStandardItem.

clear ¶

clear() -> None

Clear all items from the tree.

clear_search ¶

clear_search() -> None

Clear the search input.

collapse_all ¶

collapse_all() -> None

Collapse all items in the tree.

collapse_item ¶

collapse_item(text: str) -> bool

Collapse an item by its text.

Parameters:

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

Returns:

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

expand_all ¶

expand_all() -> None

Expand all items in the tree.

expand_item ¶

expand_item(text: str) -> bool

Expand an item by its text.

Parameters:

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

Returns:

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

get_item ¶

get_item(text: str) -> Optional[QStandardItem]

Get an item by its text.

Parameters:

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

Returns:

Type	Description
`Optional[QStandardItem]`	The QStandardItem if found, None otherwise.

remove_item ¶

remove_item(text: str) -> bool

Remove an item from the tree 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: Union[List[str], Dict[str, List[str]]]) -> None

Set the tree items from a list or dictionary.

Parameters:

Name	Type	Description	Default
`items` ¶	`Union[List[str], Dict[str, List[str]]]`	Either a flat list of strings (creates top-level items), or a dictionary where keys are parent items and values are lists of child items.	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 tree 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 FXFuzzySearchTree widget.

fuzzy_search_tree