0
# PyQt-Fluent-Widgets
1

2
A comprehensive fluent design widgets library for PyQt5 applications, enabling developers to create modern Windows 11-style user interfaces with native fluent design components. This library provides an extensive collection of UI widgets including buttons, input controls, navigation components, dialogs, and advanced material effects like acrylic backgrounds, all following Microsoft's Fluent Design System principles.
3

4
## Package Information
5

6
- **Package Name**: PyQt-Fluent-Widgets
7
- **Import Name**: qfluentwidgets  
8
- **Language**: Python
9
- **Installation**: `pip install PyQt-Fluent-Widgets`
10
- **Dependencies**: PyQt5>=5.15.0, PyQt5-Frameless-Window>=0.4.0, darkdetect
11
- **Optional Dependencies**: scipy, pillow, colorthief (install with `pip install PyQt-Fluent-Widgets[full]`)
12

13
## Core Imports
14

15
```python
16
import qfluentwidgets
17
```
18

19
Common import patterns:
20

21
```python
22
from qfluentwidgets import (
23
    FluentWindow, NavigationInterface, PushButton, PrimaryPushButton,
24
    FluentIcon, setTheme, Theme, setThemeColor
25
)
26
```
27

28
Icon imports:
29

30
```python
31
from qfluentwidgets import FluentIcon as FIF
32
```
33

34
## Basic Usage
35

36
```python
37
import sys
38
from PyQt5.QtCore import Qt
39
from PyQt5.QtWidgets import QApplication, QWidget
40
from qfluentwidgets import (
41
    FluentWindow, NavigationInterface, PushButton, PrimaryPushButton,
42
    FluentIcon as FIF, setTheme, Theme, NavigationItemPosition,
43
    NavigationAvatarWidget
44
)
45

46
class MainWindow(FluentWindow):
47
    def __init__(self):
48
        super().__init__()
49
        self.initWindow()
50
        self.initNavigation()
51
        
52
    def initWindow(self):
53
        self.resize(900, 700)
54
        self.setWindowTitle('Fluent App')
55
        
56
        # Apply theme
57
        setTheme(Theme.AUTO)
58
        
59
    def initNavigation(self):
60
        # Create interfaces
61
        self.homeInterface = QWidget()
62
        self.settingsInterface = QWidget()
63
        
64
        # Add to navigation
65
        self.addSubInterface(self.homeInterface, FIF.HOME, 'Home')
66
        self.addSubInterface(self.settingsInterface, FIF.SETTING, 'Settings')
67
        
68
        # Add separator and avatar
69
        self.navigationInterface.addSeparator()
70
        self.navigationInterface.addWidget(
71
            routeKey='avatar',
72
            widget=NavigationAvatarWidget('User', 'avatar.png'),
73
            position=NavigationItemPosition.BOTTOM
74
        )
75

76
if __name__ == '__main__':
77
    # High DPI support
78
    QApplication.setHighDpiScaleFactorRoundingPolicy(
79
        Qt.HighDpiScaleFactorRoundingPolicy.PassThrough
80
    )
81
    QApplication.setAttribute(Qt.AA_EnableHighDpiScaling)
82
    QApplication.setAttribute(Qt.AA_UseHighDpiPixmaps)
83
    
84
    app = QApplication(sys.argv)
85
    window = MainWindow()
86
    window.show()
87
    app.exec_()
88
```
89

90
## Architecture
91

92
The library is organized around five core modules that provide comprehensive fluent design functionality:
93

94
- **Components**: The main widget collection including buttons, inputs, navigation, dialogs, and material effects
95
- **Common**: Theme system, configuration, icons, styling, and utility functions
96
- **Window**: Fluent-styled window classes with integrated navigation
97
- **Multimedia**: Media player components for audio/video playback
98
- **Resources**: Embedded resources including icons and stylesheets
99

100
The architecture follows Microsoft's Fluent Design System principles with automatic theme detection, smooth animations, and modern visual effects.
101

102
## Capabilities
103

104
### Button Widgets
105

106
Modern button components with fluent design styling, supporting multiple constructor patterns, icons, and various visual styles including primary, transparent, toggle, and hyperlink variants.
107

108
```python { .api }
109
class PushButton(QPushButton):
110
    def __init__(self, parent: QWidget = None): ...
111
    def __init__(self, text: str, parent: QWidget = None, icon: Union[QIcon, str, FluentIconBase] = None): ...
112
    def __init__(self, icon: Union[QIcon, FluentIconBase], text: str, parent: QWidget = None): ...
113

114
class PrimaryPushButton(PushButton): ...
115
class TransparentPushButton(PushButton): ...
116
class TogglePushButton(PushButton): ...  
117
class HyperlinkButton(QPushButton):
118
    def __init__(self, url: str, text: str, parent: QWidget = None, icon: Union[QIcon, FluentIconBase, str] = None): ...
119
```
120

121
[Button Widgets](./buttons.md)
122

123
### Window and Navigation
124

125
Fluent-styled windows with integrated navigation interfaces, supporting hierarchical navigation, route-based page switching, and modern title bars with system integration.
126

127
```python { .api }
128
class FluentWindow(FluentWindowBase):
129
    def __init__(self, parent=None): ...
130
    def addSubInterface(self, interface: QWidget, icon: Union[FluentIconBase, QIcon, str], text: str,
131
                      position=NavigationItemPosition.TOP, parent=None, isTransparent=False) -> NavigationTreeWidget: ...
132

133
class NavigationInterface(QWidget):
134
    def __init__(self, parent=None, showMenuButton=True, showReturnButton=False, collapsible=True): ...
135
    def addItem(self, routeKey: str, icon: Union[str, QIcon, FluentIconBase], text: str, onClick=None,
136
               selectable=True, position=NavigationItemPosition.TOP, tooltip: str = None,
137
               parentRouteKey: str = None) -> NavigationTreeWidget: ...
138
```
139

140
[Window and Navigation](./window-navigation.md)
141

142
### Input Controls
143

144
Comprehensive form controls including text inputs, combo boxes, sliders, date/time pickers, and spinboxes with fluent design styling and advanced features.
145

146
```python { .api }
147
class LineEdit(QLineEdit):
148
    def __init__(self, parent=None): ...
149

150
class ComboBox(QComboBox):
151
    def __init__(self, parent=None): ...
152
    def setPlaceholderText(self, text: str): ...
153

154
class SearchLineEdit(LineEdit): ...
155
class PasswordLineEdit(LineEdit): ...
156
class TextEdit(QTextEdit): ...
157
class PlainTextEdit(QPlainTextEdit): ...
158
```
159

160
[Input Controls](./input-controls.md)
161

162
### Display Widgets
163

164
Labels, images, cards, and container widgets for displaying content with fluent design typography and layout patterns.
165

166
```python { .api }
167
class CardWidget(QWidget):
168
    def __init__(self, parent=None): ...
169

170
class ElevatedCardWidget(CardWidget): ...
171
class SimpleCardWidget(CardWidget): ...
172
class HeaderCardWidget(CardWidget): ...
173

174
class BodyLabel(QLabel): ...
175
class TitleLabel(QLabel): ...
176
class SubtitleLabel(QLabel): ...
177
class LargeTitleLabel(QLabel): ...
178
class DisplayLabel(QLabel): ...
179
class ImageLabel(QLabel): ...
180
class AvatarWidget(QLabel): ...
181
class PixmapLabel(QLabel): ...
182
class IconWidget(QWidget): ...
183
```
184

185
[Display Widgets](./display-widgets.md)
186

187
### List and View Widgets
188

189
Advanced list, table, and tree components with custom delegates, smooth scrolling, and fluent design integration.
190

191
```python { .api }
192
class ListWidget(QListWidget): ...
193
class ListView(QListView): ...
194
class TableWidget(QTableWidget): ...
195
class TableView(QTableView): ...
196
class TreeWidget(QTreeWidget): ...
197
class TreeView(QTreeView): ...
198
class CycleListWidget(QListWidget): ...
199

200
class ListItemDelegate(QStyledItemDelegate): ...
201
class TableItemDelegate(QStyledItemDelegate): ...
202
class TreeItemDelegate(QStyledItemDelegate): ...
203
```
204

205
[List and View Widgets](./list-view-widgets.md)
206

207
### Menu and Command System
208

209
Context menus, command bars, and system tray menus with fluent styling, animations, and modern interaction patterns.
210

211
```python { .api }
212
class RoundMenu(QMenu): ...
213
class DWMMenu(QMenu): ...
214
class LineEditMenu(RoundMenu): ...
215
class CheckableMenu(RoundMenu): ...
216
class SystemTrayMenu(QMenu): ...
217
class CheckableSystemTrayMenu(SystemTrayMenu): ...
218

219
class CommandBar(QWidget): ...
220
class CommandButton(QToolButton): ...
221
class CommandBarView(QWidget): ...
222
```
223

224
[Menu and Command System](./menu-command.md)
225

226
### Dialog and Notification System
227

228
Modal dialogs, message boxes, flyouts, and notification components with fluent design animations and positioning.
229

230
```python { .api }
231
class MessageBox(MaskDialogBase): ...
232
class MessageDialog(MaskDialogBase): ...
233
class Dialog(MaskDialogBase): ...
234
class ColorDialog(MaskDialogBase): ...
235
class FolderListDialog(MaskDialogBase): ...
236

237
class InfoBar(QWidget): ...
238
class InfoBadge(QWidget): ...
239
class DotInfoBadge(InfoBadge): ...
240
class IconInfoBadge(InfoBadge): ...
241

242
class TeachingTip(QWidget): ...
243
class PopupTeachingTip(TeachingTip): ...
244
class Flyout(QWidget): ...
245
class FlyoutView(QWidget): ...
246
class ToolTip(QWidget): ...
247
class StateToolTip(QWidget): ...
248
```
249

250
[Dialog and Notification System](./dialog-notification.md)
251

252
### Settings and Configuration
253

254
Setting cards, configuration management, and option panels for building preference interfaces with validation and persistence.
255

256
```python { .api }
257
class SettingCard(QWidget): ...
258
class SwitchSettingCard(SettingCard): ...
259
class ComboBoxSettingCard(SettingCard): ...
260
class RangeSettingCard(SettingCard): ...
261
class PushSettingCard(SettingCard): ...
262
class ColorSettingCard(SettingCard): ...
263
class HyperlinkCard(SettingCard): ...
264
class ExpandSettingCard(SettingCard): ...
265
class FolderListSettingCard(SettingCard): ...
266
class OptionsSettingCard(SettingCard): ...
267
class SettingCardGroup(QWidget): ...
268

269
class QConfig(QObject): ...
270
class ConfigItem: ...
271
class ConfigValidator: ...
272
```
273

274
[Settings and Configuration](./settings-config.md)
275

276
### Material Effects
277

278
Acrylic blur effects, material design components, and advanced visual effects for modern UI aesthetics.
279

280
```python { .api }
281
class AcrylicWidget(QWidget): ...
282
class AcrylicBrush(QBrush): ...
283

284
class AcrylicMenu(RoundMenu): ...
285
class AcrylicLineEditMenu(RoundMenu): ...
286
class AcrylicCheckableMenu(RoundMenu): ...
287
class AcrylicSystemTrayMenu(SystemTrayMenu): ...
288

289
class AcrylicLineEdit(LineEdit): ...
290
class AcrylicSearchLineEdit(SearchLineEdit): ...
291
class AcrylicComboBox(ComboBox): ...
292
class AcrylicEditableComboBox(EditableComboBox): ...
293

294
class AcrylicFlyout(Flyout): ...
295
class AcrylicFlyoutView(FlyoutView): ...
296
class AcrylicToolTip(ToolTip): ...
297
```
298

299
[Material Effects](./material-effects.md)
300

301
### Theme and Styling System
302

303
Comprehensive theme management with automatic dark/light mode detection, color customization, and fluent design stylesheets.
304

305
```python { .api }
306
class Theme(Enum):
307
    LIGHT = "Light"
308
    DARK = "Dark"
309
    AUTO = "Auto"
310

311
def setTheme(theme: Theme): ...
312
def setThemeColor(color: QColor): ...
313
def isDarkTheme() -> bool: ...
314
def toggleTheme(): ...
315

316
class FluentIcon(FluentIconBase, Enum): ...
317
class ThemeColor(Enum): ...
318
```
319

320
[Theme and Styling System](./theme-styling.md)
321

322
### Layout and Animation
323

324
Advanced layout managers, smooth scrolling, animated containers, and transition effects for fluid user experiences.
325

326
```python { .api }
327
class FlowLayout(QLayout): ...
328
class ExpandLayout(QVBoxLayout): ...
329
class VBoxLayout(QVBoxLayout): ...
330

331
class ScrollArea(QScrollArea): ...
332
class SmoothScrollArea(ScrollArea): ...
333
class SingleDirectionScrollArea(ScrollArea): ...
334
class SmoothScrollBar(QScrollBar): ...
335

336
class PopUpAniStackedWidget(QStackedWidget): ...
337
class OpacityAniStackedWidget(QStackedWidget): ...
338

339
class ProgressBar(QProgressBar): ...
340
class ProgressRing(QWidget): ...
341
class IndeterminateProgressBar(ProgressBar): ...
342
class IndeterminateProgressRing(ProgressRing): ...
343
```
344

345
[Layout and Animation](./layout-animation.md)
346

347
### Multimedia Components  
348

349
Media player widgets, video display, and audio/video control components with modern playback interfaces.
350

351
```python { .api }
352
class MediaPlayer(QWidget): ...
353
class MediaPlayerBase(QWidget): ...
354
class VideoWidget(QVideoWidget): ...
355
class StandardMediaPlayBar(QWidget): ...
356
class SimpleMediaPlayBar(QWidget): ...
357
class MediaPlayBarButton(QToolButton): ...
358
```
359

360
[Multimedia Components](./multimedia.md)
361

362
## Error Handling
363

364
Common exceptions that may be raised:
365

366
- **ImportError**: When required PyQt5 dependencies are not installed
367
- **AttributeError**: When accessing undefined widget properties or methods  
368
- **ValueError**: When providing invalid parameters to configuration functions
369
- **RuntimeError**: When widget operations are performed outside the main thread
370

371
Most widget methods follow PyQt5 conventions and raise standard Qt exceptions for invalid operations.