fxwidgets

FXWidgets - Custom Qt widgets for fxgui.

This package provides a collection of custom Qt widgets built on top of qtpy, offering enhanced functionality and consistent styling for DCC applications.

All public classes are re-exported here for backward compatibility

from fxgui.fxwidgets import FXMainWindow, FXSplashScreen

Or import from the package directly

from fxgui import fxwidgets window = fxwidgets.FXMainWindow()

Classes:

Name	Description
FXApplication	Customized QApplication class.
FXCamelCaseValidator	Validator for camelCase without special characters or numbers.
FXCapitalizedLetterValidator	Validator for names that must start with a capital letter and contain
FXCollapsibleWidget	A widget that can expand or collapse its content.
FXColorLabelDelegate	A custom delegate to paint items with specific colors and icons based
FXElidedLabel	A QLabel that elides text with '...' when it doesn't fit.
FXFloatingDialog	A floating dialog that appears at the cursor's position.
FXIconLineEdit	A line edit that displays an icon on the left or right side.
FXLettersUnderscoreValidator	Validator for letters and underscores, with optional numbers support.
FXLowerCaseValidator	Validator for lowercase letters only, with optional numbers and
FXMainWindow	Customized QMainWindow class.
FXOutputLogHandler	Custom logging handler that sends log messages to an output log widget.
FXOutputLogWidget	A reusable read-only output log widget for displaying application logs.
FXPasswordLineEdit	A custom widget that includes a password line edit with a show/hide button.
FXResizedScrollArea	A custom scroll area that emits a signal when resized.
FXSingleton	Metaclass for Qt classes that are singletons.
FXSortedTreeWidgetItem	Custom QTreeWidgetItem that provides natural sorting for strings
FXSplashScreen	Customized QSplashScreen class.
FXStatusBar	Customized QStatusBar class.
FXSystemTray	A system tray icon with a context menu.
FXThumbnailDelegate	Custom item delegate for showing thumbnails in tree/list views.
FXWidget

FXApplication

Bases: QApplication

Customized QApplication class.

On initialization, the application loads the previously saved theme from persistent storage. If no theme was saved, defaults to "dark".

Methods:

Name	Description
instance	Return the existing instance or create a new one if it doesn't

instance classmethod

instance(*args, **kwargs)

Return the existing instance or create a new one if it doesn't exist.

FXCamelCaseValidator

Bases: QRegularExpressionValidator

Validator for camelCase without special characters or numbers.

This validator ensures input follows camelCase format: starts with a lowercase letter, followed by zero or more groups of an uppercase letter followed by lowercase letters.

Examples:

>>> from qtpy.QtWidgets import QLineEdit
>>> line_edit = QLineEdit()
>>> line_edit.setValidator(FXCamelCaseValidator())

FXCapitalizedLetterValidator

Bases: QValidator

Validator for names that must start with a capital letter and contain only letters.

This validator ensures the first character is uppercase and all characters are alphabetic.

Examples:

>>> from qtpy.QtWidgets import QLineEdit
>>> line_edit = QLineEdit()
>>> line_edit.setValidator(FXCapitalizedLetterValidator())

Methods:

Name	Description
fixup	Automatically capitalize the first letter.
validate	Allow only letters and must start with a capital letter.

fixup

fixup(input_string: str) -> str

Automatically capitalize the first letter.

validate

validate(input_string: str, pos: int)

Allow only letters and must start with a capital letter.

FXCollapsibleWidget

Bases: QWidget

A widget that can expand or collapse its content.

The widget consists of a header with a toggle button and a content area that can be shown or hidden with an animation effect.

Parameters:

Name	Type	Description	Default
parent	Optional[QWidget]	Parent widget.	None
title	str	Title displayed in the header.	''
animation_duration	int	Duration of expand/collapse animation in ms.	150
max_content_height	int	Maximum height for content area when expanded (0 = no limit).	300
title_icon	Optional[Union[QIcon, str]]	Optional icon to display before the title. Can be a QIcon, an icon name string (for fxicons), or None.	None

Examples:

>>> from qtpy.QtWidgets import QLabel, QVBoxLayout
>>> collapsible = FXCollapsibleWidget(title="Settings")
>>> layout = QVBoxLayout()
>>> layout.addWidget(QLabel("Option 1"))
>>> layout.addWidget(QLabel("Option 2"))
>>> collapsible.set_content_layout(layout)
>>>
>>> # With an icon
>>> collapsible_with_icon = FXCollapsibleWidget(
...     title="Settings",
...     title_icon="settings"
... )

Methods:

Name	Description
__init__	Initialize the collapsible section.
get_title	Get the current title text.
get_title_icon	Get the current title icon.
set_content_layout	Set the layout for the content area.
set_title	Set the title text.
set_title_icon	Set an icon to display before the title.

__init__

__init__(
    parent: Optional[QWidget] = None,
    title: str = "",
    animation_duration: int = 150,
    max_content_height: int = 300,
    title_icon: Optional[Union[QIcon, str]] = None,
)

Initialize the collapsible section.

get_title

get_title() -> str

Get the current title text.

Returns:

Type	Description
str	The current title text.

get_title_icon

get_title_icon() -> Optional[QIcon]

Get the current title icon.

Returns:

Type	Description
Optional[QIcon]	The current title icon, or None if no icon is set.

set_content_layout

set_content_layout(content_layout: QLayout) -> None

Set the layout for the content area.

Parameters:

Name	Type	Description	Default
content_layout	QLayout	The layout to set for the content area.	required

set_title

set_title(title: str) -> None

Set the title text.

Parameters:

Name	Type	Description	Default
title	str	The title text to display.	required

set_title_icon

set_title_icon(icon: Union[QIcon, str, None]) -> None

Set an icon to display before the title.

Parameters:

Name	Type	Description	Default
icon	Union[QIcon, str, None]	The icon to display. Can be: - A QIcon instance - A string icon name (resolved via fxicons.get_icon) - None to remove the icon	required

Examples:

>>> collapsible = FXCollapsibleWidget(title="Settings")
>>> collapsible.set_title_icon("settings")  # Using icon name
>>> collapsible.set_title_icon(QIcon("path/to/icon.png"))  # Using QIcon
>>> collapsible.set_title_icon(None)  # Remove icon

FXColorLabelDelegate

Bases: QStyledItemDelegate

A custom delegate to paint items with specific colors and icons based on their text content.

Methods:

Name	Description
__init__	Initializes the delegate with a dictionary of colors and icons.
paint	Paints the item with the specified colors and icons.
sizeHint	Provides the size hint for the item.

__init__

__init__(
    colors_icons: Dict[str, Tuple[QColor, QColor, QColor, QIcon, bool]],
    parent: Optional[QWidget] = None,
    margin_left: int = 2,
    margin_top: Optional[int] = None,
    margin_bottom: Optional[int] = None,
)

Initializes the delegate with a dictionary of colors and icons.

Parameters:

Name	Type	Description	Default
colors_icons	Dict[str, Tuple[QColor, QColor, QColor, QIcon, bool]]	A dictionary where keys are text patterns and values are tuples containing background color, border color, text/icon color, icon, and a boolean indicating if the icon should be colored.	required
parent	Optional[QWidget]	The parent object.	None
margin_left	int	The left margin for the text and icon. Defaults to 2.	2
margin_top	Optional[int]	The top margin for the text and icon. Defaults to margin_left.	None
margin_bottom	Optional[int]	The bottom margin for the text and icon. Defaults to margin_left.	None

paint

paint(
    painter: QPainter, option: QStyleOptionViewItem, index: QModelIndex
) -> None

Paints the item with the specified colors and icons.

Parameters:

Name	Type	Description	Default
painter	QPainter	The painter used to draw the item.	required
option	QStyleOptionViewItem	The style options for the item.	required
index	QModelIndex	The model index of the item.	required

sizeHint

sizeHint(option: QStyleOptionViewItem, index: QModelIndex) -> QSize

Provides the size hint for the item.

Parameters:

Name	Type	Description	Default
option	QStyleOptionViewItem	The style options for the item.	required
index	QModelIndex	The model index of the item.	required

Returns:

Type	Description
QSize	The size hint for the item.

FXElidedLabel

Bases: QLabel

A QLabel that elides text with '...' when it doesn't fit.

This label automatically truncates text and adds an ellipsis when the text is too long to fit within the available space.

Methods:

Name	Description
resizeEvent	Re-elide text when the label is resized.
setText	Set the text and store the full text for elision.

resizeEvent

resizeEvent(event) -> None

Re-elide text when the label is resized.

setText

setText(text: str) -> None

Set the text and store the full text for elision.

FXFloatingDialog

Bases: QDialog

A floating dialog that appears at the cursor's position. It closes when any mouse button except the right one is pressed.

Parameters:

Name	Type	Description	Default
parent	QtWidget	Parent widget. Defaults to hou.qt.mainWindow().	None
icon	QPixmap	The QPixmap icon.	None
title	str	The dialog title.	None

Attributes:

Name	Type	Description
dialog_icon	QIcon	The icon of the dialog.
dialog_title	str	The title of the dialog.
drop_position	QPoint	The drop position of the dialog.
dialog_position	Tuple[int, int]	The position of the dialog.
parent_package	int	Whether the dialog is standalone application, or belongs to a DCC parent.
popup	bool	Whether the dialog is a popup or not.

Methods:

Name	Description
closeEvent	Removes the parent of the dialog and closes it.
mousePressEvent	Closes the dialog when any mouse button except the right one is pressed.
set_dialog_icon	Sets the dialog's icon.
set_dialog_title	Sets the dialog's title.
show_under_cursor	Moves the dialog to the current cursor position and displays it.

closeEvent

closeEvent(event: QCloseEvent) -> None

Removes the parent of the dialog and closes it.

Parameters:

Name	Type	Description	Default
event	QCloseEvent	The close event.	required

mousePressEvent

mousePressEvent(event: QMouseEvent) -> None

Closes the dialog when any mouse button except the right one is pressed.

Parameters:

Name	Type	Description	Default
event	QMouseEvent	The mouse press event.	required

set_dialog_icon

set_dialog_icon(icon: Optional[QPixmap] = None) -> None

Sets the dialog's icon.

Parameters:

Name	Type	Description	Default
icon	QPixmap	The QPixmap icon.	None

set_dialog_title

set_dialog_title(title: str = None) -> None

Sets the dialog's title.

Parameters:

Name	Type	Description	Default
title	str	The title of the dialog.	None

show_under_cursor

show_under_cursor() -> int

Moves the dialog to the current cursor position and displays it.

Returns:

Name	Type	Description
int	int	The result of the QDialog exec_() method, which is an integer. It returns a DialogCode that can be Accepted or Rejected.

FXIconLineEdit

Bases: QLineEdit

A line edit that displays an icon on the left or right side.

The icon is theme-aware and will refresh automatically when the application theme changes.

Parameters:

Name	Type	Description	Default
icon_name	Optional[str]	The name of the icon to display.	None
icon_position	str	The position of the icon ('left' or 'right').	'left'
parent	Optional[QWidget]	The parent widget.	None

Methods:

Name	Description
resizeEvent	Reposition the icon when the line edit is resized.

resizeEvent

resizeEvent(event)

Reposition the icon when the line edit is resized.

FXLettersUnderscoreValidator

Bases: QRegularExpressionValidator

Validator for letters and underscores, with optional numbers support.

Parameters:

Name	Type	Description	Default
allow_numbers	bool	If True, allows numbers in addition to letters and underscores.	False
parent	Optional[QWidget]	Parent widget.	None

Examples:

>>> from qtpy.QtWidgets import QLineEdit
>>> line_edit = QLineEdit()
>>> line_edit.setValidator(FXLettersUnderscoreValidator(allow_numbers=True))

FXLowerCaseValidator

Bases: QRegularExpressionValidator

Validator for lowercase letters only, with optional numbers and underscores support.

Parameters:

Name	Type	Description	Default
allow_numbers	bool	If True, allows numbers in addition to lowercase letters.	False
allow_underscores	bool	If True, allows underscores in addition to lowercase letters.	False
parent	Optional[QWidget]	Parent widget.	None

Examples:

>>> from qtpy.QtWidgets import QLineEdit
>>> line_edit = QLineEdit()
>>> line_edit.setValidator(FXLowerCaseValidator(allow_numbers=True))

FXMainWindow

Bases: QMainWindow

Customized QMainWindow class.

Parameters:

Name	Type	Description	Default
parent	QWidget	Parent widget. Defaults to hou.qt.mainWindow().	None
icon	str	Path to the window icon image. Defaults to None.	None
title	str	Title of the window. Defaults to None.	None
size	Tuple[int, int]	Window size as width and height. Defaults to None.	None
documentation	str	URL to the tool's documentation. Defaults to None.	None
version	str	Version label for the window. Defaults to None.	None
company	str	Company name for the window. Defaults to Company.	None
ui_file	str	Path to the UI file for loading. Defaults to None.	None
set_stylesheet	bool	Whether to set the default stylesheet. Defaults to True.	True

Methods:

Name	Description
get_available_themes	Get a list of all available theme names.
hide_banner	Hides the banner.
hide_status_line	Hides the status line.
setCentralWidget	Overrides the QMainWindow's setCentralWidget method to ensure that the
setWindowTitle	Override the setWindowTitle method to use _set_window_title.
set_banner_icon	Sets the icon of the banner.
set_banner_text	Sets the text of the banner.
set_company_label	Sets the company label in the status bar.
set_project_label	Sets the project label in the status bar.
set_status_line_colors	Set the colors of the status line.
set_theme	Set the theme of the window.
set_ui_file	Sets the UI file and loads the UI.
set_version_label	Sets the version label in the status bar.
show_banner	Shows the banner.
show_status_line	Shows the status line.
statusBar	Returns the FXStatusBar instance associated with this window.
toggle_theme	Toggle the theme of the window to the next available theme.

get_available_themes

get_available_themes() -> list

Get a list of all available theme names.

Returns:

Type	Description
list	List of theme names (e.g., ["dark", "light"]).

Examples:

>>> window = FXMainWindow()
>>> themes = window.get_available_themes()
>>> print(themes)  # ['dark', 'light']

hide_banner

hide_banner() -> None

Hides the banner.

hide_status_line

hide_status_line() -> None

Hides the status line.

setCentralWidget

setCentralWidget(widget)

Overrides the QMainWindow's setCentralWidget method to ensure that the status line is always at the bottom of the window and the banner is always at the top.

Parameters:

Name	Type	Description	Default
widget	QWidget	The widget to set as the central widget.	required

Note

Overrides the base class method.

setWindowTitle

setWindowTitle(title: str) -> None

Override the setWindowTitle method to use _set_window_title.

Parameters:

Name	Type	Description	Default
title	str	The new window title.	required

set_banner_icon

set_banner_icon(icon: QIcon, size: int = 20) -> None

Sets the icon of the banner.

Parameters:

Name	Type	Description	Default
icon	QIcon	The icon to set in the banner.	required
size	int	The size of the icon. Defaults to 20.	20

set_banner_text

set_banner_text(text: str) -> None

Sets the text of the banner.

Parameters:

Name	Type	Description	Default
text	str	The text to set in the banner.	required

set_company_label

set_company_label(company: str) -> None

Sets the company label in the status bar.

Parameters:

Name	Type	Description	Default
company	str	The company name.	required

Note

Overrides the base class method.

set_project_label

set_project_label(project: str) -> None

Sets the project label in the status bar.

Parameters:

Name	Type	Description	Default
project	str	The project name.	required

Note

Overrides the base class method.

set_status_line_colors

set_status_line_colors(color_a: str, color_b: str) -> None

Set the colors of the status line.

Parameters:

Name	Type	Description	Default
color_a	str	The first color of the gradient.	required
color_b	str	The second color of the gradient.	required

set_theme

set_theme(theme: str) -> str

Set the theme of the window.

This method can be called from external code to apply a specific theme, including when running inside a DCC like Houdini, Maya, or Nuke where you don't have direct access to QApplication.

Parameters:

Name	Type	Description	Default
theme	str	The theme name to apply (e.g., "dark", "light", or custom).	required

Returns:

Name	Type	Description
str	str	The theme that was applied.

Examples:

>>> window = FXMainWindow()
>>> window.show()
>>> window.set_theme("light")
>>> window.set_theme("dark")

set_ui_file

set_ui_file(ui_file: str) -> None

Sets the UI file and loads the UI.

set_version_label

set_version_label(version: str) -> None

Sets the version label in the status bar.

Parameters:

Name	Type	Description	Default
version	str	The version string.	required

Note

Overrides the base class method.

show_banner

show_banner() -> None

Shows the banner.

show_status_line

show_status_line() -> None

Shows the status line.

statusBar

statusBar() -> FXStatusBar

Returns the FXStatusBar instance associated with this window.

Returns:

Name	Type	Description
FXStatusBar	FXStatusBar	The FXStatusBar instance associated with this window.

Note

Overrides the base class method.

toggle_theme

toggle_theme() -> str

Toggle the theme of the window to the next available theme.

This method can be called from external code to cycle through themes, including when running inside a DCC like Houdini, Maya, or Nuke where you don't have direct access to QApplication.

Returns:

Name	Type	Description
str	str	The new theme that was applied.

Examples:

>>> window = FXMainWindow()
>>> window.show()
>>> new_theme = window.toggle_theme()
>>> print(f"Switched to {new_theme} theme")

FXOutputLogHandler

Bases: Handler

Custom logging handler that sends log messages to an output log widget.

This handler is used internally by FXOutputLogWidget to capture log messages and display them in the widget.

Parameters:

Name	Type	Description	Default
log_widget	FXOutputLogWidget	The FXOutputLogWidget to send messages to.	required

Methods:

Name	Description
emit	Emit a log record to the output log widget.

emit

emit(record: LogRecord) -> None

Emit a log record to the output log widget.

FXOutputLogWidget

Bases: QWidget

A reusable read-only output log widget for displaying application logs.

This widget provides a text display area that captures and shows logging output from the application. It supports ANSI color codes, search functionality, and log throttling for performance.

Parameters:

Name	Type	Description	Default
parent	Optional[QWidget]	Parent widget.	None
capture_output	bool	If True, adds a logging handler to capture log output from Python's logging module.	False

Signals

log_message: Emitted when a log message is received (for thread-safe delivery).

Examples:

>>> from fxgui import fxwidgets
>>> log_widget = fxwidgets.FXOutputLogWidget(capture_output=True)
>>> log_widget.show()

Methods:

Name	Description
__init__	Initialize the output log widget.
append_log	Append text to the log output with ANSI color conversion.
clear_log	Clear the log output.
closeEvent	Handle widget close event to restore output streams.
keyPressEvent	Handle keyboard shortcuts.
restore_output_streams	Remove logging handler from all loggers where it was added.

__init__

__init__(parent: Optional[QWidget] = None, capture_output: bool = False)

Initialize the output log widget.

append_log

append_log(text: str) -> None

Append text to the log output with ANSI color conversion.

Parameters:

Name	Type	Description	Default
text	str	Text to append (may contain ANSI color codes).	required

clear_log

clear_log() -> None

Clear the log output.

closeEvent

closeEvent(event: QCloseEvent) -> None

Handle widget close event to restore output streams.

keyPressEvent

keyPressEvent(event: QKeyEvent) -> None

Handle keyboard shortcuts.

restore_output_streams

restore_output_streams() -> None

Remove logging handler from all loggers where it was added.

FXPasswordLineEdit

Bases: QWidget

A custom widget that includes a password line edit with a show/hide button.

Parameters:

Name	Type	Description	Default
parent	Optional[QWidget]	The parent widget.	None
icon_position	str	The position of the icon ('left' or 'right').	'right'

Methods:

Name	Description
toggle_reveal	Toggles the echo mode between password and normal, and changes the

toggle_reveal

toggle_reveal()

Toggles the echo mode between password and normal, and changes the icon of the reveal button accordingly.

FXResizedScrollArea

Bases: QScrollArea

A custom scroll area that emits a signal when resized.

This widget extends QScrollArea to emit a resized signal whenever the widget is resized, which is useful for responsive layouts.

Signals

resized: Emitted when the scroll area is resized.

Examples:

>>> scroll_area = FXResizedScrollArea()
>>> scroll_area.resized.connect(lambda: print("Resized!"))

Methods:

Name	Description
resizeEvent	Emit the resized signal when the widget is resized.

resizeEvent

resizeEvent(event)

Emit the resized signal when the widget is resized.

FXSingleton

Bases: type(QObject)

Metaclass for Qt classes that are singletons.

This metaclass ensures that only one instance of each class can exist. If an instance already exists, it returns the existing instance instead of creating a new one. Each subclass gets its own singleton instance.

Examples:

>>> from fxgui import fxwidgets
>>>
>>> class MySingletonWindow(fxwidgets.FXMainWindow, metaclass=fxwidgets.FXSingleton):
...     pass
>>>
>>> window1 = MySingletonWindow()
>>> window2 = MySingletonWindow()
>>> assert window1 is window2  # Same instance

Methods:

Name	Description
reset_instance	Reset the singleton instance. Useful for testing or cleanup.

reset_instance

reset_instance()

Reset the singleton instance. Useful for testing or cleanup.

FXSortedTreeWidgetItem

Bases: QTreeWidgetItem

Custom QTreeWidgetItem that provides natural sorting for strings containing numbers. This is useful for sorting items like version numbers or other strings where numeric parts should be ordered numerically.

For example, this class will sort the following strings in the correct human-friendly order:

• "something1"
• "something9"
• "something17"
• "something25"

Instead of the default sorting order:

• "something1"
• "something17"
• "something25"
• "something9"

Methods:

Name	Description
__lt__	Override the less-than operator to provide a custom sorting logic.

__lt__

__lt__(other: FXSortedTreeWidgetItem) -> bool

Override the less-than operator to provide a custom sorting logic.

Parameters:

Name	Type	Description	Default
other	FXSortedTreeWidgetItem	Another instance of FXSortedTreeWidgetItem to compare with.	required

Returns:

Type	Description
bool	True if the current item is less than the other item according to
bool	the natural sort order, False otherwise.

FXSplashScreen

Bases: QSplashScreen

Customized QSplashScreen class.

Methods:

Name	Description
paintEvent	Override to draw the pixmap with rounded corners.
set_border	Set the border around the splash screen.
set_company_label	Set the company name for the splash screen.
set_corner_radius	Set the corner radius for rounded corners.
set_icon	Set the icon for the splash screen.
set_information_text	Set the information text for the splash screen.
set_overlay_opacity	Set the opacity of the grey overlay background.
set_pixmap	Set the pixmap for the splash screen.
set_progress	Set the progress value for the splash screen.
set_project_label	Set the project name for the splash screen.
set_title	Set the title for the splash screen.
set_version_label	Set the version information for the splash screen.
toggle_fade_in	Toggle the fade-in effect for the splash screen.
toggle_progress_bar_visibility	Toggle the visibility of the progress bar.

paintEvent

paintEvent(event) -> None

Override to draw the pixmap with rounded corners.

set_border

set_border(width: int, color: str = '#555555') -> None

Set the border around the splash screen.

Parameters:

Name	Type	Description	Default
width	int	The border width in pixels. Use 0 for no border.	required
color	str	The border color as a hex string.	'#555555'

set_company_label

set_company_label(company: str) -> None

Set the company name for the splash screen.

Parameters:

Name	Type	Description	Default
company	str	The company name.	required

set_corner_radius

set_corner_radius(radius: int) -> None

Set the corner radius for rounded corners.

Parameters:

Name	Type	Description	Default
radius	int	The corner radius in pixels. Use 0 for sharp corners.	required

set_icon

set_icon(icon_path: str) -> None

Set the icon for the splash screen.

Parameters:

Name	Type	Description	Default
icon_path	str	The path to the icon file.	required

set_information_text

set_information_text(information: str) -> None

Set the information text for the splash screen.

Parameters:

Name	Type	Description	Default
information	str	The information text.	required

set_overlay_opacity

set_overlay_opacity(opacity: float) -> None

Set the opacity of the grey overlay background.

Parameters:

Name	Type	Description	Default
opacity	float	The opacity value between 0.0 (transparent) and 1.0 (opaque).	required

set_pixmap

set_pixmap(image_path: str) -> None

Set the pixmap for the splash screen.

Parameters:

Name	Type	Description	Default
image_path	str	The path to the image file.	required

set_progress

set_progress(value: int, max_range: int = 100)

Set the progress value for the splash screen.

Parameters:

Name	Type	Description	Default
value	int	The progress value.	required
max_range	int	The maximum progress value. Defaults to 100.	100

set_project_label

set_project_label(project: str) -> None

Set the project name for the splash screen.

Parameters:

Name	Type	Description	Default
project	str	The project name.	required

set_title

set_title(title: str) -> None

Set the title for the splash screen.

Parameters:

Name	Type	Description	Default
title	str	The title string.	required

set_version_label

set_version_label(version: str) -> None

Set the version information for the splash screen.

Parameters:

Name	Type	Description	Default
version	str	The version string.	required

toggle_fade_in

toggle_fade_in(fade_in: bool) -> None

Toggle the fade-in effect for the splash screen.

Parameters:

Name	Type	Description	Default
fade_in	bool	Whether to fade in the splash screen.	required

toggle_progress_bar_visibility

toggle_progress_bar_visibility(show: bool) -> None

Toggle the visibility of the progress bar.

Parameters:

Name	Type	Description	Default
show	bool	Whether to show the progress bar.	required

FXStatusBar

Bases: QStatusBar

Customized QStatusBar class.

Parameters:

Name	Type	Description	Default
parent	QWidget	Parent widget. Defaults to None.	None
project	str	Project name. Defaults to None.	None
version	str	Version information. Defaults to None.	None
company	str	Company name. Defaults to None.	None

Attributes:

Name	Type	Description
project	str	The project name.
version	str	The version string.
company	str	The company name.
icon_label	QLabel	The icon label.
message_label	QLabel	The message label.
project_label	QLabel	The project label.
version_label	QLabel	The version label.
company_label	QLabel	The company label.

Methods:

Name	Description
clearMessage	Clears the message from the status bar.
hide_status_line	Hide the status line and border line.
resizeEvent	Handle resize to position the status line and border correctly.
set_status_line_colors	Set the status line gradient colors.
showMessage	Display a message in the status bar with a specified severity.
show_status_line	Show the status line and border line.

clearMessage

clearMessage()

Clears the message from the status bar.

Note

Overrides the base class method.

hide_status_line

hide_status_line() -> None

Hide the status line and border line.

resizeEvent

resizeEvent(event) -> None

Handle resize to position the status line and border correctly.

set_status_line_colors

set_status_line_colors(color_a: str, color_b: str) -> None

Set the status line gradient colors.

Parameters:

Name	Type	Description	Default
color_a	str	The first color of the gradient.	required
color_b	str	The second color of the gradient.	required

showMessage

showMessage(
    message: str,
    severity_type: int = 4,
    duration: float = 2.5,
    time: bool = True,
    logger: Optional[Logger] = None,
    set_color: bool = True,
    pixmap: Optional[QPixmap] = None,
    background_color: Optional[str] = None,
)

Display a message in the status bar with a specified severity.

Parameters:

Name	Type	Description	Default
message	str	The message to be displayed.	required
severity_type	int	The severity level of the message. Should be one of CRITICAL, ERROR, WARNING, SUCCESS, INFO, or DEBUG. Defaults to INFO.	4
duration	float	The duration in seconds for which the message should be displayed. Defaults to2.5.	2.5
time	bool	Whether to display the current time before the message. Defaults to True.	True
logger	Logger	A logger object to log the message. Defaults to None.	None
set_color	bool	Whether to set the status bar color depending on the log verbosity. Defaults to True.	True
pixmap	QPixmap	A custom pixmap to be displayed in the status bar. Defaults to None.	None
background_color	str	A custom background color for the status bar. Defaults to None.	None

Examples:

To display a critical error message with a red background

>>> self.showMessage(
...     "Critical error occurred!",
...     severity_type=self.CRITICAL,
...     duration=5,
...     logger=my_logger,
... )

Note

You can either use the FXMainWindow instance to retrieve the verbosity constants, or the fxwidgets module. Overrides the base class method.

show_status_line

show_status_line() -> None

Show the status line and border line.

FXSystemTray

Bases: QObject

A system tray icon with a context menu.

Parameters:

Name	Type	Description	Default
parent	QWidget	The parent widget. Defaults to None.	None
icon	str	The icon path. Defaults to None.	None

Attributes:

Name	Type	Description
tray_icon	QSystemTrayIcon	The system tray icon.
quit_action	QAction	The action to quit the application.
tray_menu	QMenu	The tray menu.

Methods:

Name	Description
show	Shows the system tray icon.
on_tray_icon_activated	Shows the tray menu above the taskbar.
closeEvent	Closes the application.

Examples:

>>> app = FXApplication()
>>> system_tray = FXSystemTray()
>>> hello_action = QAction(
...     fxicons.get_icon("visibility"), "Set Project", system_tray
... )
>>> system_tray.tray_menu.insertAction(
...     system_tray.quit_action, hello_action
... )
>>> system_tray.tray_menu.insertSeparator(system_tray.quit_action)
>>> system_tray.show()
>>> app.exec_()

Note

Inherits from QObject, not QSystemTrayIcon.

add_action

add_action(action: QAction) -> None

Adds an action to the tray menu.

Parameters:

Name	Type	Description	Default
action	QAction	The action to add to the tray menu.	required

set_icon

set_icon(icon_path: str) -> None

Sets a new icon for the system tray.

Parameters:

Name	Type	Description	Default
icon_path	str	The path to the new icon.	required

show

show()

Shows the system tray icon.

FXThumbnailDelegate

Bases: QStyledItemDelegate

Custom item delegate for showing thumbnails in tree/list views.

This delegate displays items with thumbnails, titles, descriptions, and status indicators. It supports Markdown formatting in descriptions and tooltips.

Note

Store data in items using the following roles: - Qt.UserRole + 1 (bool): Whether to show the thumbnail. - Qt.UserRole + 2 (str): Path to the thumbnail image. - Qt.UserRole + 3 (str): Description text (supports Markdown). - Qt.UserRole + 4 (QColor): Status dot indicator color. - Qt.UserRole + 5 (QColor): Status label background color. - Qt.UserRole + 6 (str): Status label text. - Qt.UserRole + 7 (bool): Whether to show the status dot. - Qt.UserRole + 8 (bool): Whether to show the status label.

Properties

show_thumbnail: Whether to show thumbnails globally. show_status_dot: Whether to show the status dot indicator globally. show_status_label: Whether to show the status label globally.

Note

Global properties and per-item roles work together: - An element is shown only if BOTH global property is True AND per-item role is True (or None/unset). - Setting per-item role to False hides that element for that item.

Examples:

>>> from fxgui import fxwidgets
>>> from qtpy.QtWidgets import QTreeWidget, QTreeWidgetItem
>>> from qtpy.QtCore import Qt
>>> from qtpy.QtGui import QColor
>>>
>>> tree = QTreeWidget()
>>> delegate = fxwidgets.FXThumbnailDelegate()
>>> delegate.show_thumbnail = True
>>> delegate.show_status_dot = True
>>> delegate.show_status_label = True
>>> tree.setItemDelegate(delegate)
>>>
>>> item = QTreeWidgetItem(tree, ["My Item"])
>>> item.setData(0, fxwidgets.FXThumbnailDelegate.THUMBNAIL_VISIBLE_ROLE, True)
>>> item.setData(0, fxwidgets.FXThumbnailDelegate.THUMBNAIL_PATH_ROLE, "/path/to/image.png")
>>> item.setData(0, fxwidgets.FXThumbnailDelegate.DESCRIPTION_ROLE, "**Bold** description")
>>> item.setData(0, fxwidgets.FXThumbnailDelegate.STATUS_DOT_COLOR_ROLE, QColor("green"))
>>> # Hide status dot for this specific item
>>> item.setData(0, fxwidgets.FXThumbnailDelegate.STATUS_DOT_VISIBLE_ROLE, False)

Methods:

Name	Description
__init__	Initialize the thumbnail delegate.
helpEvent	Provide Markdown-formatted tooltips.
markdown_to_html	Convert Markdown text to HTML.
markdown_to_plain_text	Convert Markdown text to plain text by removing formatting.
paint	Paint the item at the given index.
sizeHint	Return the size hint for the item at the given index.

Attributes:

Name	Type	Description
show_status_dot	bool	Whether the status dot is shown.
show_status_label	bool	Whether the status label is shown.
show_thumbnail	bool	Whether thumbnails are shown globally.

show_status_dot property writable

show_status_dot: bool

Whether the status dot is shown.

show_status_label property writable

show_status_label: bool

Whether the status label is shown.

show_thumbnail property writable

show_thumbnail: bool

Whether thumbnails are shown globally.

Individual items can override via THUMBNAIL_VISIBLE_ROLE.

__init__

__init__(parent: Optional[QWidget] = None)

Initialize the thumbnail delegate.

Parameters:

Name	Type	Description	Default
parent	Optional[QWidget]	The parent widget.	None

helpEvent

helpEvent(
    event, view, option: QStyleOptionViewItem, index: QModelIndex
) -> bool

Provide Markdown-formatted tooltips.

Parameters:

Name	Type	Description	Default
event		The help event.	required
view		The view widget.	required
option	QStyleOptionViewItem	Style options.	required
index	QModelIndex	The model index.	required

Returns:

Type	Description
bool	True if the event was handled.

markdown_to_html staticmethod

markdown_to_html(text: str) -> str

Convert Markdown text to HTML.

Parameters:

Name	Type	Description	Default
text	str	Markdown-formatted text.	required

Returns:

Type	Description
str	HTML-formatted text.

markdown_to_plain_text staticmethod

markdown_to_plain_text(text: str) -> str

Convert Markdown text to plain text by removing formatting.

Parameters:

Name	Type	Description	Default
text	str	Markdown-formatted text.	required

Returns:

Type	Description
str	Plain text with Markdown formatting removed.

paint

paint(
    painter: QPainter, option: QStyleOptionViewItem, index: QModelIndex
) -> None

Paint the item at the given index.

Parameters:

Name	Type	Description	Default
painter	QPainter	The painter to use for drawing.	required
option	QStyleOptionViewItem	The style options for the item.	required
index	QModelIndex	The model index of the item.	required

sizeHint

sizeHint(option: QStyleOptionViewItem, index: QModelIndex) -> QSize

Return the size hint for the item at the given index.

Parameters:

Name	Type	Description	Default
option	QStyleOptionViewItem	The style options for the item.	required
index	QModelIndex	The model index of the item.	required

Returns:

Type	Description
QSize	The size hint for the item.

FXWidget

Bases: QWidget