0
# Material Effects
1

2
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.
3

4
**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.
5

6
## Core Imports
7

8
```python
9
from qfluentwidgets.components.material import (
10
    AcrylicWidget, AcrylicBrush,
11
    AcrylicMenu, AcrylicLineEdit, AcrylicComboBox,
12
    AcrylicFlyout, AcrylicToolTip
13
)
14
```
15

16
## Capabilities
17

18
### Acrylic Base Components
19

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

22
```python { .api }
23
class AcrylicWidget(QWidget):
24
    def __init__(self, parent=None): ...
25
    def setAcrylicEnabled(self, enabled: bool): ...
26
    def isAcrylicEnabled(self) -> bool: ...
27
    def setBlurRadius(self, radius: int): ...
28
    def blurRadius(self) -> int: ...
29
    def setTintColor(self, color: QColor): ...
30
    def tintColor(self) -> QColor: ...
31

32
class AcrylicBrush(QBrush):
33
    def __init__(self, tintColor: QColor, luminosityOpacity: float = 0.85, 
34
                 tintOpacity: float = 0.0, blurRadius: float = 30.0): ...
35
    def setTintColor(self, color: QColor): ...
36
    def setLuminosityOpacity(self, opacity: float): ...
37
    def setTintOpacity(self, opacity: float): ...
38
    def setBlurRadius(self, radius: float): ...
39
```
40

41
**Usage Example:**
42
```python
43
from qfluentwidgets.components.material import AcrylicWidget, AcrylicBrush
44
from PyQt5.QtGui import QColor
45

46
# Basic acrylic widget
47
acrylic_panel = AcrylicWidget(self)
48
acrylic_panel.setFixedSize(400, 300)
49
acrylic_panel.setAcrylicEnabled(True)
50
acrylic_panel.setBlurRadius(40)
51
acrylic_panel.setTintColor(QColor(255, 255, 255, 180))
52

53
# Custom acrylic brush for painting
54
acrylic_brush = AcrylicBrush(
55
    tintColor=QColor(0, 120, 212, 100),
56
    luminosityOpacity=0.8,
57
    tintOpacity=0.1,
58
    blurRadius=25.0
59
)
60

61
# Use in custom painting
62
def paintEvent(self, event):
63
    painter = QPainter(self)
64
    painter.setBrush(acrylic_brush)
65
    painter.drawRect(self.rect())
66
```
67

68
### Acrylic Menus
69

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

72
```python { .api }
73
class AcrylicMenu(RoundMenu):
74
    def __init__(self, parent=None): ...
75
    def setBlurRadius(self, radius: int): ...
76
    def setAcrylicEnabled(self, enabled: bool): ...
77

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

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

86
class AcrylicSystemTrayMenu(SystemTrayMenu):
87
    def __init__(self, parent=None): ...
88
    # System tray menu with acrylic effects
89
```
90

91
**Usage Example:**
92
```python
93
from qfluentwidgets.components.material import AcrylicMenu, AcrylicSystemTrayMenu
94
from qfluentwidgets import Action, FluentIcon as FIF
95

96
# Acrylic context menu
97
acrylic_menu = AcrylicMenu(self)
98
acrylic_menu.setBlurRadius(30)
99

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

105
acrylic_menu.addAction(new_action)
106
acrylic_menu.addAction(open_action)
107
acrylic_menu.addSeparator()
108
acrylic_menu.addAction(save_action)
109

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

114
# Acrylic system tray menu
115
tray_menu = AcrylicSystemTrayMenu()
116
tray_menu.addAction(Action(FIF.VIEW, "Show", self))
117
tray_menu.addAction(Action(FIF.SETTING, "Settings", self))
118
tray_menu.addAction(Action(FIF.POWER_BUTTON, "Quit", self))
119

120
system_tray.setContextMenu(tray_menu)
121
```
122

123
### Acrylic Input Controls
124

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

127
```python { .api }
128
class AcrylicLineEdit(LineEdit):
129
    def __init__(self, parent=None): ...
130
    def setAcrylicEnabled(self, enabled: bool): ...
131
    def setBlurRadius(self, radius: int): ...
132

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

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

142
class AcrylicEditableComboBox(EditableComboBox):
143
    def __init__(self, parent=None): ...
144
    def setAcrylicEnabled(self, enabled: bool): ...
145
```
146

147
**Usage Example:**
148
```python
149
from qfluentwidgets.components.material import (AcrylicLineEdit, AcrylicSearchLineEdit, 
150
                                                AcrylicComboBox)
151

152
# Acrylic text input
153
search_input = AcrylicSearchLineEdit(self)
154
search_input.setPlaceholderText("Search with acrylic effect...")
155
search_input.setAcrylicEnabled(True)
156
search_input.setFixedWidth(300)
157

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

164
# Form with acrylic inputs
165
form_layout = QFormLayout()
166
form_layout.addRow("Name:", AcrylicLineEdit(self))
167
form_layout.addRow("Email:", AcrylicLineEdit(self))
168
form_layout.addRow("Country:", language_combo)
169

170
# Style acrylic inputs for better visibility
171
search_input.setStyleSheet("""
172
    AcrylicSearchLineEdit {
173
        background-color: rgba(255, 255, 255, 0.7);
174
        border: 1px solid rgba(0, 0, 0, 0.1);
175
        border-radius: 8px;
176
    }
177
""")
178
```
179

180
### Acrylic Flyouts and Tooltips
181

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

184
```python { .api }
185
class AcrylicFlyout(Flyout):
186
    def __init__(self, parent=None): ...
187
    def setAcrylicEnabled(self, enabled: bool): ...
188
    def setBlurRadius(self, radius: int): ...
189

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

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

199
class AcrylicToolTipFilter(QObject):
200
    def __init__(self, parent=None): ...
201
    def eventFilter(self, obj: QObject, event: QEvent) -> bool: ...
202
```
203

204
**Usage Example:**
205
```python
206
from qfluentwidgets.components.material import AcrylicFlyout, AcrylicToolTip
207
from qfluentwidgets import TitleLabel, BodyLabel, PushButton
208

209
# Acrylic flyout with content
210
acrylic_flyout = AcrylicFlyout(self)
211
acrylic_flyout.setBlurRadius(35)
212

213
# Create flyout content
214
flyout_widget = QWidget()
215
flyout_layout = QVBoxLayout(flyout_widget)
216

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

221
flyout_layout.addWidget(title)
222
flyout_layout.addWidget(content)
223
flyout_layout.addWidget(action_btn)
224

225
acrylic_flyout.addWidget(flyout_widget)
226

227
# Show flyout near button
228
def show_flyout():
229
    acrylic_flyout.show(trigger_button)
230

231
trigger_button.clicked.connect(show_flyout)
232

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

237
# Install acrylic tooltip filter
238
tooltip_filter = AcrylicToolTipFilter()
239
widget.installEventFilter(tooltip_filter)
240
```
241

242
## Acrylic Effect Configuration
243

244
### Blur Parameters
245

246
```python
247
# Configure blur intensity
248
widget.setBlurRadius(40)  # Higher values = more blur
249

250
# Typical blur radius values:
251
# - Subtle effect: 10-20
252
# - Medium effect: 20-35  
253
# - Strong effect: 35-50
254
# - Very strong: 50+
255
```
256

257
### Tint and Opacity
258

259
```python
260
from PyQt5.QtGui import QColor
261

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

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

270
# Apply based on theme
271
from qfluentwidgets import isDarkTheme
272

273
if isDarkTheme():
274
    acrylic_widget.setTintColor(dark_tint)
275
else:
276
    acrylic_widget.setTintColor(light_tint)
277
```
278

279
### Performance Considerations
280

281
```python
282
# Enable/disable acrylic effects based on performance
283
class AcrylicManager:
284
    def __init__(self):
285
        self.low_performance_mode = False
286
    
287
    def configure_acrylic_widgets(self, widgets):
288
        for widget in widgets:
289
            if hasattr(widget, 'setAcrylicEnabled'):
290
                widget.setAcrylicEnabled(not self.low_performance_mode)
291
    
292
    def set_performance_mode(self, low_performance):
293
        self.low_performance_mode = low_performance
294
        # Update all acrylic widgets
295
        self.update_all_acrylic_widgets()
296

297
# Use lower blur radius for better performance
298
if system_is_low_end():
299
    widget.setBlurRadius(15)  # Reduced blur
300
else:
301
    widget.setBlurRadius(30)  # Full blur
302
```
303

304
## Platform-Specific Behavior
305

306
### Windows Integration
307

308
```python
309
# Acrylic effects work best on Windows 10/11
310
import platform
311

312
if platform.system() == "Windows":
313
    # Enable full acrylic effects
314
    acrylic_widget.setAcrylicEnabled(True)
315
    acrylic_widget.setBlurRadius(30)
316
else:
317
    # Fallback to solid colors on other platforms
318
    acrylic_widget.setAcrylicEnabled(False)
319
    acrylic_widget.setStyleSheet("background-color: rgba(255, 255, 255, 0.9);")
320
```
321

322
### Theme Integration
323

324
```python
325
from qfluentwidgets import isDarkTheme, themeColor
326

327
def update_acrylic_appearance():
328
    """Update acrylic widgets based on current theme"""
329
    
330
    if isDarkTheme():
331
        # Dark theme acrylic settings
332
        tint = QColor(30, 30, 30, 100)
333
        border_color = "rgba(255, 255, 255, 0.1)"
334
    else:
335
        # Light theme acrylic settings  
336
        tint = QColor(255, 255, 255, 120)
337
        border_color = "rgba(0, 0, 0, 0.1)"
338
    
339
    # Update all acrylic widgets
340
    for widget in acrylic_widgets:
341
        widget.setTintColor(tint)
342
        widget.setStyleSheet(f"border: 1px solid {border_color};")
343

344
# Connect to theme changes
345
from qfluentwidgets import SystemThemeListener
346

347
theme_listener = SystemThemeListener(self)
348
theme_listener.themeChanged.connect(lambda: update_acrylic_appearance())
349
```
350

351
## Custom Acrylic Effects
352

353
### Creating Custom Acrylic Widgets
354

355
```python
356
from qfluentwidgets.components.material import AcrylicWidget
357

358
class CustomAcrylicPanel(AcrylicWidget):
359
    def __init__(self, parent=None):
360
        super().__init__(parent)
361
        self.setupUi()
362
        self.setupAcrylic()
363
    
364
    def setupUi(self):
365
        layout = QVBoxLayout(self)
366
        
367
        # Add content to acrylic panel
368
        self.title = TitleLabel("Acrylic Panel")
369
        self.content = BodyLabel("Content with blur background")
370
        
371
        layout.addWidget(self.title)
372
        layout.addWidget(self.content)
373
    
374
    def setupAcrylic(self):
375
        self.setAcrylicEnabled(True)
376
        self.setBlurRadius(25)
377
        self.setTintColor(QColor(255, 255, 255, 100))
378
        
379
        # Custom styling
380
        self.setStyleSheet("""
381
            CustomAcrylicPanel {
382
                border-radius: 12px;
383
                border: 1px solid rgba(255, 255, 255, 0.2);
384
            }
385
        """)
386

387
# Usage
388
acrylic_panel = CustomAcrylicPanel(self)
389
acrylic_panel.setFixedSize(300, 200)
390
```
391

392
### Animated Acrylic Effects
393

394
```python
395
from PyQt5.QtCore import QPropertyAnimation, QEasingCurve
396

397
class AnimatedAcrylicWidget(AcrylicWidget):
398
    def __init__(self, parent=None):
399
        super().__init__(parent)
400
        self.blur_animation = QPropertyAnimation(self, b"blurRadius")
401
        self.blur_animation.setDuration(300)
402
        self.blur_animation.setEasingCurve(QEasingCurve.OutCubic)
403
    
404
    def enterEvent(self, event):
405
        # Increase blur on hover
406
        self.blur_animation.setStartValue(self.blurRadius())
407
        self.blur_animation.setEndValue(40)
408
        self.blur_animation.start()
409
        super().enterEvent(event)
410
    
411
    def leaveEvent(self, event):
412
        # Decrease blur on leave
413
        self.blur_animation.setStartValue(self.blurRadius())
414
        self.blur_animation.setEndValue(20)
415
        self.blur_animation.start()
416
        super().leaveEvent(event)
417
```
418

419
## Best Practices
420

421
### Performance Optimization
422

423
1. **Use moderate blur radius** (20-35) for good balance of effect and performance
424
2. **Disable acrylic on low-end systems** automatically
425
3. **Limit number of acrylic widgets** visible simultaneously
426
4. **Use acrylic effects strategically** for key UI elements
427

428
### Visual Hierarchy
429

430
1. **Reserve acrylic effects** for floating elements (menus, flyouts, panels)
431
2. **Use consistent tint colors** that match your theme
432
3. **Ensure sufficient contrast** between content and background
433
4. **Test with different wallpapers** to ensure readability
434

435
### Accessibility
436

437
1. **Provide fallback styling** for users who disable transparency effects
438
2. **Maintain good contrast ratios** even with blur effects
439
3. **Test with screen readers** to ensure acrylic doesn't interfere
440
4. **Allow users to disable effects** in settings