tessl/pypi-pyqt-fluent-widgets

A fluent design widgets library based on PyQt5 providing modern Windows 11-style UI components

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Material Effects

Name: tessl/pypi-pyqt-fluent-widgets
Author: tessl

Acrylic blur effects, material design components, and advanced visual effects for modern UI aesthetics. These components provide Windows 11-style acrylic blur effects and material design integration.

Important Note: Material effect components are NOT automatically exported from the main qfluentwidgets module and must be imported directly from the qfluentwidgets.components.material submodule.

Core Imports

from qfluentwidgets.components.material import (
    AcrylicWidget, AcrylicBrush,
    AcrylicMenu, AcrylicLineEdit, AcrylicComboBox,
    AcrylicFlyout, AcrylicToolTip
)

Capabilities

Acrylic Base Components

Core acrylic effect components providing the foundation for blur and transparency effects.

class AcrylicWidget(QWidget):
    def __init__(self, parent=None): ...
    def setAcrylicEnabled(self, enabled: bool): ...
    def isAcrylicEnabled(self) -> bool: ...
    def setBlurRadius(self, radius: int): ...
    def blurRadius(self) -> int: ...
    def setTintColor(self, color: QColor): ...
    def tintColor(self) -> QColor: ...

class AcrylicBrush(QBrush):
    def __init__(self, tintColor: QColor, luminosityOpacity: float = 0.85, 
                 tintOpacity: float = 0.0, blurRadius: float = 30.0): ...
    def setTintColor(self, color: QColor): ...
    def setLuminosityOpacity(self, opacity: float): ...
    def setTintOpacity(self, opacity: float): ...
    def setBlurRadius(self, radius: float): ...

Usage Example:

from qfluentwidgets.components.material import AcrylicWidget, AcrylicBrush
from PyQt5.QtGui import QColor

# Basic acrylic widget
acrylic_panel = AcrylicWidget(self)
acrylic_panel.setFixedSize(400, 300)
acrylic_panel.setAcrylicEnabled(True)
acrylic_panel.setBlurRadius(40)
acrylic_panel.setTintColor(QColor(255, 255, 255, 180))

# Custom acrylic brush for painting
acrylic_brush = AcrylicBrush(
    tintColor=QColor(0, 120, 212, 100),
    luminosityOpacity=0.8,
    tintOpacity=0.1,
    blurRadius=25.0
)

# Use in custom painting
def paintEvent(self, event):
    painter = QPainter(self)
    painter.setBrush(acrylic_brush)
    painter.drawRect(self.rect())

Acrylic Menus

Context menus and system tray menus with acrylic blur effects for enhanced visual appeal.

class AcrylicMenu(RoundMenu):
    def __init__(self, parent=None): ...
    def setBlurRadius(self, radius: int): ...
    def setAcrylicEnabled(self, enabled: bool): ...

class AcrylicLineEditMenu(RoundMenu):
    def __init__(self, parent=None): ...
    # Specialized acrylic menu for line edit controls

class AcrylicCheckableMenu(RoundMenu):
    def __init__(self, parent=None): ...
    # Acrylic menu with checkable items

class AcrylicSystemTrayMenu(SystemTrayMenu):
    def __init__(self, parent=None): ...
    # System tray menu with acrylic effects

Usage Example:

from qfluentwidgets.components.material import AcrylicMenu, AcrylicSystemTrayMenu
from qfluentwidgets import Action, FluentIcon as FIF

# Acrylic context menu
acrylic_menu = AcrylicMenu(self)
acrylic_menu.setBlurRadius(30)

# Add actions
new_action = Action(FIF.ADD, "New", self)
open_action = Action(FIF.FOLDER, "Open", self)
save_action = Action(FIF.SAVE, "Save", self)

acrylic_menu.addAction(new_action)
acrylic_menu.addAction(open_action)
acrylic_menu.addSeparator()
acrylic_menu.addAction(save_action)

# Show acrylic menu
def show_acrylic_menu(self, pos):
    acrylic_menu.exec(self.mapToGlobal(pos))

# Acrylic system tray menu
tray_menu = AcrylicSystemTrayMenu()
tray_menu.addAction(Action(FIF.VIEW, "Show", self))
tray_menu.addAction(Action(FIF.SETTING, "Settings", self))
tray_menu.addAction(Action(FIF.POWER_BUTTON, "Quit", self))

system_tray.setContextMenu(tray_menu)

Acrylic Input Controls

Input widgets with acrylic background effects for modern, translucent interfaces.

class AcrylicLineEdit(LineEdit):
    def __init__(self, parent=None): ...
    def setAcrylicEnabled(self, enabled: bool): ...
    def setBlurRadius(self, radius: int): ...

class AcrylicSearchLineEdit(SearchLineEdit):
    def __init__(self, parent=None): ...
    def setAcrylicEnabled(self, enabled: bool): ...

class AcrylicComboBox(ComboBox):
    def __init__(self, parent=None): ...
    def setAcrylicEnabled(self, enabled: bool): ...
    def setBlurRadius(self, radius: int): ...

class AcrylicEditableComboBox(EditableComboBox):
    def __init__(self, parent=None): ...
    def setAcrylicEnabled(self, enabled: bool): ...

Usage Example:

from qfluentwidgets.components.material import (AcrylicLineEdit, AcrylicSearchLineEdit, 
                                                AcrylicComboBox)

# Acrylic text input
search_input = AcrylicSearchLineEdit(self)
search_input.setPlaceholderText("Search with acrylic effect...")
search_input.setAcrylicEnabled(True)
search_input.setFixedWidth(300)

# Acrylic combo box
language_combo = AcrylicComboBox(self)
language_combo.addItems(["English", "Spanish", "French", "German"])
language_combo.setAcrylicEnabled(True)
language_combo.setBlurRadius(25)

# Form with acrylic inputs
form_layout = QFormLayout()
form_layout.addRow("Name:", AcrylicLineEdit(self))
form_layout.addRow("Email:", AcrylicLineEdit(self))
form_layout.addRow("Country:", language_combo)

# Style acrylic inputs for better visibility
search_input.setStyleSheet("""
    AcrylicSearchLineEdit {
        background-color: rgba(255, 255, 255, 0.7);
        border: 1px solid rgba(0, 0, 0, 0.1);
        border-radius: 8px;
    }
""")

Acrylic Flyouts and Tooltips

Popup components with acrylic effects for enhanced visual hierarchy and modern aesthetics.

class AcrylicFlyout(Flyout):
    def __init__(self, parent=None): ...
    def setAcrylicEnabled(self, enabled: bool): ...
    def setBlurRadius(self, radius: int): ...

class AcrylicFlyoutView(FlyoutView):
    def __init__(self, parent=None): ...
    def setAcrylicEnabled(self, enabled: bool): ...

class AcrylicToolTip(ToolTip):
    def __init__(self, text: str = "", parent=None): ...
    def setAcrylicEnabled(self, enabled: bool): ...
    def setBlurRadius(self, radius: int): ...

class AcrylicToolTipFilter(QObject):
    def __init__(self, parent=None): ...
    def eventFilter(self, obj: QObject, event: QEvent) -> bool: ...

Usage Example:

from qfluentwidgets.components.material import AcrylicFlyout, AcrylicToolTip
from qfluentwidgets import TitleLabel, BodyLabel, PushButton

# Acrylic flyout with content
acrylic_flyout = AcrylicFlyout(self)
acrylic_flyout.setBlurRadius(35)

# Create flyout content
flyout_widget = QWidget()
flyout_layout = QVBoxLayout(flyout_widget)

title = TitleLabel("Quick Settings")
content = BodyLabel("Adjust your preferences quickly")
action_btn = PushButton("Open Full Settings")

flyout_layout.addWidget(title)
flyout_layout.addWidget(content)
flyout_layout.addWidget(action_btn)

acrylic_flyout.addWidget(flyout_widget)

# Show flyout near button
def show_flyout():
    acrylic_flyout.show(trigger_button)

trigger_button.clicked.connect(show_flyout)

# Acrylic tooltips
acrylic_tooltip = AcrylicToolTip("This is an enhanced tooltip with acrylic effects", self)
acrylic_tooltip.setBlurRadius(20)

# Install acrylic tooltip filter
tooltip_filter = AcrylicToolTipFilter()
widget.installEventFilter(tooltip_filter)

Acrylic Effect Configuration

Blur Parameters

# Configure blur intensity
widget.setBlurRadius(40)  # Higher values = more blur

# Typical blur radius values:
# - Subtle effect: 10-20
# - Medium effect: 20-35  
# - Strong effect: 35-50
# - Very strong: 50+

Tint and Opacity

from PyQt5.QtGui import QColor

# Configure tint color and opacity
acrylic_widget.setTintColor(QColor(0, 120, 212, 80))  # Blue tint with transparency

# Common tint configurations:
light_tint = QColor(255, 255, 255, 100)  # Light mode
dark_tint = QColor(32, 32, 32, 120)      # Dark mode
accent_tint = QColor(0, 120, 212, 90)    # Accent color

# Apply based on theme
from qfluentwidgets import isDarkTheme

if isDarkTheme():
    acrylic_widget.setTintColor(dark_tint)
else:
    acrylic_widget.setTintColor(light_tint)

Performance Considerations

# Enable/disable acrylic effects based on performance
class AcrylicManager:
    def __init__(self):
        self.low_performance_mode = False
    
    def configure_acrylic_widgets(self, widgets):
        for widget in widgets:
            if hasattr(widget, 'setAcrylicEnabled'):
                widget.setAcrylicEnabled(not self.low_performance_mode)
    
    def set_performance_mode(self, low_performance):
        self.low_performance_mode = low_performance
        # Update all acrylic widgets
        self.update_all_acrylic_widgets()

# Use lower blur radius for better performance
if system_is_low_end():
    widget.setBlurRadius(15)  # Reduced blur
else:
    widget.setBlurRadius(30)  # Full blur

Platform-Specific Behavior

Windows Integration

# Acrylic effects work best on Windows 10/11
import platform

if platform.system() == "Windows":
    # Enable full acrylic effects
    acrylic_widget.setAcrylicEnabled(True)
    acrylic_widget.setBlurRadius(30)
else:
    # Fallback to solid colors on other platforms
    acrylic_widget.setAcrylicEnabled(False)
    acrylic_widget.setStyleSheet("background-color: rgba(255, 255, 255, 0.9);")

Theme Integration

from qfluentwidgets import isDarkTheme, themeColor

def update_acrylic_appearance():
    """Update acrylic widgets based on current theme"""
    
    if isDarkTheme():
        # Dark theme acrylic settings
        tint = QColor(30, 30, 30, 100)
        border_color = "rgba(255, 255, 255, 0.1)"
    else:
        # Light theme acrylic settings  
        tint = QColor(255, 255, 255, 120)
        border_color = "rgba(0, 0, 0, 0.1)"
    
    # Update all acrylic widgets
    for widget in acrylic_widgets:
        widget.setTintColor(tint)
        widget.setStyleSheet(f"border: 1px solid {border_color};")

# Connect to theme changes
from qfluentwidgets import SystemThemeListener

theme_listener = SystemThemeListener(self)
theme_listener.themeChanged.connect(lambda: update_acrylic_appearance())

Custom Acrylic Effects

Creating Custom Acrylic Widgets

from qfluentwidgets.components.material import AcrylicWidget

class CustomAcrylicPanel(AcrylicWidget):
    def __init__(self, parent=None):
        super().__init__(parent)
        self.setupUi()
        self.setupAcrylic()
    
    def setupUi(self):
        layout = QVBoxLayout(self)
        
        # Add content to acrylic panel
        self.title = TitleLabel("Acrylic Panel")
        self.content = BodyLabel("Content with blur background")
        
        layout.addWidget(self.title)
        layout.addWidget(self.content)
    
    def setupAcrylic(self):
        self.setAcrylicEnabled(True)
        self.setBlurRadius(25)
        self.setTintColor(QColor(255, 255, 255, 100))
        
        # Custom styling
        self.setStyleSheet("""
            CustomAcrylicPanel {
                border-radius: 12px;
                border: 1px solid rgba(255, 255, 255, 0.2);
            }
        """)

# Usage
acrylic_panel = CustomAcrylicPanel(self)
acrylic_panel.setFixedSize(300, 200)

Animated Acrylic Effects

from PyQt5.QtCore import QPropertyAnimation, QEasingCurve

class AnimatedAcrylicWidget(AcrylicWidget):
    def __init__(self, parent=None):
        super().__init__(parent)
        self.blur_animation = QPropertyAnimation(self, b"blurRadius")
        self.blur_animation.setDuration(300)
        self.blur_animation.setEasingCurve(QEasingCurve.OutCubic)
    
    def enterEvent(self, event):
        # Increase blur on hover
        self.blur_animation.setStartValue(self.blurRadius())
        self.blur_animation.setEndValue(40)
        self.blur_animation.start()
        super().enterEvent(event)
    
    def leaveEvent(self, event):
        # Decrease blur on leave
        self.blur_animation.setStartValue(self.blurRadius())
        self.blur_animation.setEndValue(20)
        self.blur_animation.start()
        super().leaveEvent(event)

Best Practices

Performance Optimization

Use moderate blur radius (20-35) for good balance of effect and performance
Disable acrylic on low-end systems automatically
Limit number of acrylic widgets visible simultaneously
Use acrylic effects strategically for key UI elements

Visual Hierarchy

Reserve acrylic effects for floating elements (menus, flyouts, panels)
Use consistent tint colors that match your theme
Ensure sufficient contrast between content and background
Test with different wallpapers to ensure readability

Accessibility

Provide fallback styling for users who disable transparency effects
Maintain good contrast ratios even with blur effects
Test with screen readers to ensure acrylic doesn't interfere
Allow users to disable effects in settings

Install with Tessl CLI

npx tessl i tessl/pypi-pyqt-fluent-widgets

docs

buttons.md

dialog-notification.md

tessl/pypi-pyqt-fluent-widgets