fxwidgets

This module provides a wrapper around the QtWidgets module for fxgui.

It includes custom widgets and utility functions to enhance the functionality and ease of use of the standard Qt widgets within the fxgui framework.

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.

FXIconLineEdit

Bases: QLineEdit

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

Parameters:

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

resizeEvent

resizeEvent(event)

Reposition the icon when the line edit is resized.

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)

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

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.

FXPasswordLineEdit

Bases: QWidget

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

Parameters:

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

toggle_reveal

toggle_reveal()

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

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.

set_colors

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

Set the color scheme for the splash screen.

Parameters:

Name	Type	Description	Default
color_a	str	The primary color.	required
color_b	str	The secondary color.	required

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

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

FXWidget

Bases: QWidget