fxutils

Utility functions for the fxgui package.

This module provides general-purpose utility functions for Qt-based applications including UI loading, action creation, widget effects, tree filtering, and tooltip formatting.

Functions:

Name	Description
load_ui	Load a Qt Designer UI file.
create_action	Create a QAction with common settings.
add_shadows	Apply drop shadow effect to a widget.
filter_tree	Filter QTreeWidget items by text.
set_formatted_tooltip	Set a styled tooltip with title.
get_formatted_time	Get current time as formatted string.
deprecated	Decorator to mark functions as deprecated.

Examples:

Loading a UI file:

>>> from fxgui.fxutils import load_ui
>>> ui = load_ui(parent_widget, "path/to/ui_file.ui")

Creating an action:

>>> action = create_action(
...     parent=window,
...     name="Save",
...     icon=get_icon("save"),
...     trigger=save_callback,
...     shortcut="Ctrl+S"
... )

add_shadows

add_shadows(
    parent: QWidget,
    shadow_object: QWidget,
    color: str = "#000000",
    blur: float = 10,
    offset: float = 0,
) -> QGraphicsDropShadowEffect

Apply shadows to a widget.

Parameters:

Name	Type	Description	Default
parent	QWidget	Parent object.	required
shadow_object	QWidget	Object to receive shadows.	required
color	str	Color of the shadows. Defaults to #000000.	'#000000'
blur	float	Blur level of the shadows. Defaults to 10.	10
offset	float	Offset of the shadow from the shadow_object. Defaults to 0.	0

Returns:

Name	Type	Description
QGraphicsDropShadowEffect	QGraphicsDropShadowEffect	The shadow object.

Examples:

>>> # Apply shadows to `self.top_toolbar` widget
>>> add_shadows(self, self.top_toolbar, "#212121")

create_action

create_action(
    parent: QWidget,
    name: str,
    icon: Union[str, QIcon] = None,
    trigger: Optional[Callable] = None,
    enable: bool = True,
    visible: bool = True,
    shortcut: Optional[str] = None,
    checkable: bool = False,
    icon_name: Optional[str] = None,
) -> QAction

Create a QAction with common settings.

Parameters:

Name	Type	Description	Default
parent	QWidget	Parent widget for the action.	required
name	str	Display name for the action.	required
icon	Union[str, QIcon]	Icon for the action. Can be a path string or a QIcon object. Deprecated: prefer using icon_name for automatic theme updates.	None
trigger	Optional[Callable]	Callback function to execute when triggered. Defaults to None.	None
enable	bool	Whether the action is enabled. Defaults to True.	True
visible	bool	Whether the action is visible. Defaults to True.	True
shortcut	Optional[str]	Keyboard shortcut (e.g., "Ctrl+S"). Defaults to None.	None
checkable	bool	Whether the action is checkable. Defaults to False.	False
icon_name	Optional[str]	Name of the icon from fxicons. When provided, the action will be registered for automatic icon updates on theme changes.	None

Returns:

Type	Description
QAction	The created QAction.

Examples:

>>> action = create_action(
...     parent=window,
...     name="Save",
...     icon_name="save",
...     trigger=lambda: print("Saved!"),
...     shortcut="Ctrl+S"
... )

deprecated

deprecated(func: Callable) -> Callable

Decorator to mark functions as deprecated.

When a decorated function is called, it emits a DeprecationWarning to alert users that the function will be removed in a future version.

Parameters:

Name	Type	Description	Default
func	Callable	The function to mark as deprecated.	required

Returns:

Type	Description
Callable	A wrapper function that emits a warning before calling the original.

Examples:

>>> @deprecated
... def old_function():
...     return "old behavior"
>>> old_function()  # Emits DeprecationWarning

filter_tree

filter_tree(
    filter_bar_object: QLineEdit, tree_to_filter: QTreeWidget, column: int = 0
) -> None

Filters the items of a tree by displaying or hiding them based on whether they match the filter text. Both root and child items are considered.

.. deprecated:: Consider using :class:fxgui.fxcore.FXSortFilterProxyModel for more sophisticated filtering with fuzzy matching support.

Parameters:

Name	Type	Description	Default
filter_bar_object	QLineEdit	The QLineEdit widget representing the filter bar.	required
tree_to_filter	QTreeWidget	The QTreeWidget to be filtered.	required
column	int	The column index to use for text filtering. Defaults to 0.	0

Examples:

>>> filter_bar = QLineEdit()
>>> tree_widget = QTreeWidget()
>>> filter_tree(filter_bar, tree_widget, column=1)

get_formatted_time

get_formatted_time(
    display_seconds: bool = False, display_date: bool = False
) -> str

Returns the current time as a formatted string.

Parameters:

Name	Type	Description	Default
display_seconds	bool	Whether to display the seconds. Defaults to False.	False
display_date	bool	Whether to display the date. Defaults to False.	False

Returns:

Name	Type	Description
str	str	The formatted current time.

Examples:

>>> get_formatted_time()
'14:30'
>>> get_formatted_time(display_seconds=True)
'14:30:45'
>>> get_formatted_time(display_date=True)
'2025-12-29 14:30'

load_ui

load_ui(parent: QWidget, ui_file: str) -> QWidget

Load a UI file and return the loaded UI as a QWidget.

Parameters:

Name	Type	Description	Default
parent	QWidget	Parent object.	required
ui_file	str	Path to the UI file.	required

Returns:

Name	Type	Description
QWidget	QWidget	The loaded UI.

Raises:

Type	Description
FileNotFoundError	If the specified UI file doesn't exist.

Examples:

To load a UI file located in the same directory as the Python script

>>> from pathlib import Path
>>> ui_path = Path(__file__).with_suffix('.ui')
>>> loaded_ui = load_ui(self, ui_path)

set_formatted_tooltip

set_formatted_tooltip(
    widget: QWidget, title: str, tooltip: str, duration: int = 5
) -> None

Set a formatted tooltip. The tooltip will be displayed with a bold title, and a separator line between the title and the tooltip text.

Parameters:

Name	Type	Description	Default
widget	QWidget	The widget to set the tooltip.	required
title	str	The title of the tooltip.	required
tooltip	str	The tooltip text.	required
duration	int	The duration in seconds to show the tooltip. Defaults to 5.	5

Examples:

>>> set_formatted_tooltip(
...     self, "Tooltip", "This is a <b>formatted</b> tooltip."
... )