fxutils

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.
repolish	Force re-evaluation of stylesheet rules for a widget.
round_window_corners	Ask Windows 11 for a flyout's rounded corners.

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"
... )

Functions:

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.

Note

QUiLoader lives in QtUiTools, which the PyQt bindings do not ship. The import is therefore deferred to call time (a module-level one made import fxgui fail outright under PyQt5/PyQt6) and falls back to qtpy.uic.loadUi, which qtpy provides for every binding.

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)

repolish

repolish(widget: QWidget) -> None

Force re-evaluation of the stylesheet rules for a widget.

Call after changing a Qt dynamic property that a stylesheet attribute selector depends on, e.g. MyBanner[level="error"] { ... }.

Parameters:

Name	Type	Description	Default
widget	QWidget	The widget to unpolish/polish and repaint.	required

Examples:

>>> banner.setProperty("level", "error")
>>> fxutils.repolish(banner)

round_window_corners

round_window_corners(widget: QWidget) -> bool

Give widget's own window the corners and shadow of a flyout.

A tray flyout or a context menu on Windows 11 is a rounded rectangle with the compositor's own shadow under it, and the platform draws both for any window that asks. Asking is one DwmSetWindowAttribute call, which is the whole reason this exists rather than a paint event: rounding a window by hand needs a translucent frameless widget and a paint event that agrees with it, the shadow under that needs a transparent margin on every edge, and a window seated by its own edges then has to subtract those margins from every position it computes. The compositor's answer changes no geometry at all -- the window keeps the rectangle it was given, and the OS clips and shades it.

Nothing here raises. Off Windows 11 -- an older build, another platform, the offscreen platform a test runs under -- the answer is False and the window keeps its square corners, because a square panel is still a panel and an application that refuses to open because a compositor declined is not.

This is the one place in fxgui that reaches for ctypes. It is stdlib, it is loaded lazily by the platform guard below on every system that is not Windows, and there is no Qt API for the request.

Parameters:

Name	Type	Description	Default
widget	QWidget	The window to round. Must already BE a window: this reads its native handle, and asking a widget for one creates it, so a child widget would be made native for nothing.	required

Returns:

Name	Type	Description
bool	bool	Whether the compositor took the request. False is an
	bool	ordinary answer rather than a failure -- it is what every
	bool	platform without Windows 11's window rounding says.

Examples:

>>> panel.show()
>>> fxutils.round_window_corners(panel)
True

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."
... )

Note

Superseded by fxwidgets.apply_tip, which is theme-aware, escapes the caller's strings, renders a keyboard shortcut as a keycap and also sets a status tip. Prefer it for new code.

This function is kept as-is rather than reimplemented over apply_tip because the two have incompatible contracts: tooltip here is documented as accepting markup (see the example above), which apply_tip escapes on purpose so a path or a name cannot corrupt the layout. Rewriting it would turn a caller's <b> into literal text and drop setToolTipDuration.