fxwidgets

Custom widgets for the fxgui package.

FXApplication

Bases: QApplication

Customized QApplication class.

instance classmethod

instance(*args, **kwargs)

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

FXColorLabelDelegate

Bases: QStyledItemDelegate

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

__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.

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.

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.

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
color_a	str	Color to be applied to the window. Defaults to #649eff.	None
color_b	str	Color to be applied to the window. Defaults to #4188ff.	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

Attributes:

Name	Type	Description
_default_icon	str	Path to the default icon image.
window_icon	QIcon	The window icon.
window_title	str	The window title.
window_size	QSize	The window size.
documentation	str	URL to the tool's documentation.
project	str	The project name.
version	str	The version label.
company	str	The company name.
color_a	str	The first color to be applied to the window.
color_b	str	The second color to be applied to the window.
ui_file	str	Path to the UI file for loading.
ui	Optional[QWidget]	The loaded UI widget.
CRITICAL	int	Constant for critical severity level.
ERROR	int	Constant for error severity level.
WARNING	int	Constant for warning severity level.
SUCCESS	int	Constant for success severity level.
INFO	int	Constant for info severity level.
about_action	QAction	Action for the "About" menu item.
check_updates_action	QAction	Action for the "Check for Updates" menu item.
hide_action	QAction	Action for the "Hide" menu item.
hide_others_action	QAction	Action for the "Hide Others" menu item.
close_action	QAction	Action for the "Close" menu item.
settings_action	QAction	Action for the "Settings" menu item.
window_on_top_action	QAction	Action for the "Always On Top" menu item.
minimize_window_action	QAction	Action for the "Minimize" menu item.
maximize_window_action	QAction	Action for the "Maximize" menu item.
open_documentation_action	QAction	Action for the "Documentation" menu item.
home_action	QAction	Action for the "Home" toolbar item.
previous_action	QAction	Action for the "Previous" toolbar item.
next_action	QAction	Action for the "Next" toolbar item.
refresh_action	QAction	Action for the "Refresh" toolbar item.
menu_bar	QMenuBar	The menu bar of the window.
main_menu	QMenu	The main menu of the window.
about_menu	QAction	The "About" menu item.
check_updates_menu	QAction	The "Check for Updates" menu item.
close_menu	QAction	The "Close" menu item.
hide_main_menu	QAction	The "Hide" menu item.
hide_others_menu	QAction	The "Hide Others" menu item.
edit_menu	QMenu	The edit menu of the window.
settings_menu	QAction	The "Settings" menu item.
window_menu	QMenu	The window menu of the window.
minimize_menu	QAction	The "Minimize" menu item.
maximize_menu	QAction	The "Maximize" menu item.
on_top_menu	QAction	The "Always On Top" menu item.
help_menu	QMenu	The help menu of the window.
open_documentation_menu	QAction	The "Documentation" menu item.
toolbar	QToolBar	The toolbar of the window.
home_toolbar	QAction	The "Home" toolbar item.
previous_toolbar	QAction	The "Previous" toolbar item.
next_toolbar	QAction	The "Next" toolbar item.
refresh_toolbar	QAction	The "Refresh" toolbar item.
banner	QLabel	The banner label.
status_line	QFrame	The status line frame.
status_bar	FXStatusBar	The status bar of the window.
about_dialog	QDialog	The "About" dialog.

Examples:

Outside a DCC (standalone)

>>> application = fxgui.FXApplication()
>>> window = fxwidgets.FXMainWindow(
...     icon="path/to/icon.png",
...     title="My Custom Window",
...     size=(800, 600),
...     documentation="https://my_tool_docs.com",
...     project="Awesome Project",
...     version="v1.0.0",
...     company="© Super Company",
...     version="v1.0.0",
...     ui_file="path/to/ui_file.ui",
... )
>>> window.show()
>>> window.set_statusbar_message("Window initialized", window.INFO)
>>> sys.exit(app.exec_())

Inside a DCC (Houdini)

>>> houdini_window = fxdcc.get_houdini_main_window()
>>> window = fxwidgets.FXMainWindow(
...    parent=houdini_window,
...    ui_file="path/to/ui_file.ui",
...   )
>>> window.show()
>>> window.set_statusbar_message("Window initialized", window.INFO)

Inside a DCC (Houdini), hide toolbar, menu bar ans status bar

>>> houdini_window = fxdcc.get_houdini_main_window()
>>> window = fxwidgets.FXMainWindow(
...    parent=houdini_window,
...    ui_file="path/to/ui_file.ui",
...   )
>>> window.toolbar.hide()
>>> window.menu_bar.hide()
>>> window.status_bar.hide()
>>> window.show()

Inside a DCC (Houdini), override the fxgui stylesheet with the Houdini one

>>> houdini_window = fxdcc.get_houdini_main_window()
>>> window = fxwidgets.FXMainWindow(
...    parent=houdini_window,
...    ui_file="path/to/ui_file.ui",
...   )
>>> window.setStyleSheet(hou.qt.styleSheet())
>>> window.show()
>>> window.set_statusbar_message("Window initialized", window.INFO)

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_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_colors

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

Sets the accent color of the window.

Parameters:

Name	Type	Description	Default
color_a	str	The first color.	required
color_b	str	The second color.	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_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.

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.

FXPasswordLineEdit

Bases: QWidget

toggle_reveal

toggle_reveal()

Toggles the echo mode between password and normal.

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"

__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.

Parameters:

Name	Type	Description	Default
image_path	str	Path to the image to be displayed on the splash screen.	None
icon	str	Path to the icon to be displayed on the splash screen.	None
title	str	Title text to be displayed. Defaults to Untitled.	None
information	str	Information text to be displayed. Defaults to a placeholder text.	None
show_progress_bar	bool	Whether to display a progress bar. Defaults to False.	False
project	str	Project name. Defaults to Project.	None
version	str	Version information. Defaults to 0.0.0.	None
company	str	Company name. Defaults to Company.	None
color_a	str	Color A to be applied to the splash screen. Defaults to #649eff.	_COLOR_A_DEFAULT
color_b	str	Color B to be applied to the splash screen. Defaults to #4188ff.	_COLOR_B_DEFAULT
fade_in	bool	Whether to apply a fade-in effect on the splash screen. Defaults to False.	False

Attributes:

Name	Type	Description
pixmap	QPixmap	The image on the splash screen. Dewfaults to splash.png.
icon	QIcon	The icon of the splash screen. Defaults to favicon.png.
title	str	Title text to be displayed. Defaults to Untitled.
information	str	Information text to be displayed. Defaults to a placeholder Lorem Ipsum text.
show_progress_bar	bool	Whether to display a progress bar. Defaults to False.
project	str	Project name. Defaults to Project.
version	str	Version information. Defaults to v0.0.0.
company	str	Company name. Defaults to Company.
color_a	str	Color A applied to the splash screen.
color_b	str	Color B applied to the splash screen.
fade_in	bool	Whether to apply a fade-in effect on the splash screen. Defaults to False.
title_label	QLabel	Label for the title text.
info_label	QLabel	Label for the information text.
progress_bar	QProgressBar	Progress bar widget. Only created if show_progress_bar is True.
copyright_label	QLabel	Label for the copyright information.
fade_timer	QTimer	Timer for the fade-in effect. Only created if fade_in is True.

Examples:

>>> app = QApplication(sys.argv)
>>> splash = FXSplashScreen(
...     image_path="path_to_your_image.png",
...     title="My Awesome App",
...     information="Loading...",
...     show_progress_bar=True,
...     project="Cool Project",
...     version="v1.2.3",
...     company="My Company Ltd.",
...     fade_in=True,
... )
>>> splash.progress(50)
>>> splash.show()
>>> splash.progress(100)
>>> splash.close()
>>> sys.exit(app.exec_())

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.

clearMessage

clearMessage()

Clears the message from the status bar.

Note

Overrides the base class method.

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.

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(qta.icon("mdi.eye"), "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.

on_tray_icon_activated

on_tray_icon_activated(reason)

Shows the tray menu at the cursor's position.

Parameters:

Name	Type	Description	Default
reason	ActivationReason	The reason for the tray icon activation.	required

show

show()

Shows the system tray icon.

FXWidget

Bases: QWidget