0
# Dialog and Notification System
1

2
Modal dialogs, message boxes, flyouts, and notification components with fluent design animations and positioning. These components provide modern user feedback and interaction patterns with smooth animations and proper accessibility support.
3

4
## Capabilities
5

6
### Modal Dialogs
7

8
Standard modal dialogs with fluent design styling and automatic positioning.
9

10
```python { .api }
11
class Dialog(MaskDialogBase):
12
    def __init__(self, title: str, content: str, parent=None): ...
13
    def setTitleBarVisible(self, visible: bool): ...
14
    def titleBarVisible(self) -> bool: ...
15

16
class MessageBox(MaskDialogBase):
17
    def __init__(self, title: str, content: str, parent=None): ...
18
    def addButton(self, text: str, role: QMessageBox.ButtonRole) -> QPushButton: ...
19
    def buttonClicked = pyqtSignal(QPushButton)
20

21
class MessageDialog(MaskDialogBase):
22
    def __init__(self, title: str, content: str, parent=None): ...
23
    def setIcon(self, icon: Union[QIcon, FluentIconBase]): ...
24
```
25

26
**Usage Example:**
27
```python
28
from qfluentwidgets import Dialog, MessageBox, FluentIcon as FIF
29

30
# Basic dialog
31
dialog = Dialog("Settings", "Configure your preferences", self)
32
dialog.setTitleBarVisible(True)
33

34
if dialog.exec() == QDialog.Accepted:
35
    print("Settings saved")
36

37
# Message box with buttons
38
msg_box = MessageBox("Confirm Action", "Are you sure you want to delete this item?", self)
39
msg_box.addButton("Delete", QMessageBox.AcceptRole)
40
msg_box.addButton("Cancel", QMessageBox.RejectRole)
41

42
msg_box.buttonClicked.connect(self.handle_message_response)
43

44
def handle_message_response(self, button):
45
    if button.text() == "Delete":
46
        self.delete_item()
47
```
48

49
### Specialized Dialogs
50

51
Purpose-built dialogs for common operations like color selection and folder management.
52

53
```python { .api }
54
class ColorDialog(MaskDialogBase):
55
    def __init__(self, color: QColor, title: str, parent=None, enableAlpha: bool = False): ...
56
    def setColor(self, color: QColor): ...
57
    def color(self) -> QColor: ...
58
    
59
    colorChanged = pyqtSignal(QColor)
60

61
class FolderListDialog(MaskDialogBase):
62
    def __init__(self, folders: List[str], title: str, parent=None): ...
63
    def addFolder(self, folder: str): ...
64
    def removeFolder(self, folder: str): ...
65
    def folders(self) -> List[str]: ...
66
    
67
    foldersChanged = pyqtSignal(list)
68
```
69

70
**Usage Example:**
71
```python
72
from qfluentwidgets import ColorDialog, FolderListDialog
73
from PyQt5.QtGui import QColor
74

75
# Color picker dialog
76
color_dialog = ColorDialog(QColor(255, 0, 0), "Choose Color", self, enableAlpha=True)
77
color_dialog.colorChanged.connect(self.on_color_changed)
78

79
if color_dialog.exec() == QDialog.Accepted:
80
    selected_color = color_dialog.color()
81
    print(f"Selected color: {selected_color.name()}")
82

83
# Folder list dialog
84
folders = ["/home/user/Documents", "/home/user/Pictures"]
85
folder_dialog = FolderListDialog(folders, "Manage Folders", self)
86
folder_dialog.foldersChanged.connect(self.update_folder_list)
87

88
if folder_dialog.exec() == QDialog.Accepted:
89
    new_folders = folder_dialog.folders()
90
    self.save_folder_preferences(new_folders)
91
```
92

93
### Information Bars
94

95
Non-intrusive notification bars for status updates and user feedback.
96

97
```python { .api }
98
class InfoBar(QWidget):
99
    def __init__(self, icon: Union[FluentIconBase, QIcon, str], title: str, content: str,
100
                 orientation: Qt.Orientation = Qt.Horizontal, isClosable: bool = True,
101
                 duration: int = -1, position: InfoBarPosition = InfoBarPosition.TOP,
102
                 parent=None): ...
103
    def addWidget(self, widget: QWidget): ...
104
    def setCustomBackgroundColor(self, color: str, color_dark: str): ...
105
    def close(self): ...
106
    
107
    closedSignal = pyqtSignal()
108

109
class InfoBarPosition(Enum):
110
    TOP = 0
111
    BOTTOM = 1
112
    TOP_LEFT = 2
113
    TOP_RIGHT = 3
114
    BOTTOM_LEFT = 4
115
    BOTTOM_RIGHT = 5
116
    LEFT = 6
117
    RIGHT = 7
118
```
119

120
**Usage Example:**
121
```python
122
from qfluentwidgets import InfoBar, InfoBarPosition, FluentIcon as FIF
123

124
# Success notification
125
success_bar = InfoBar(
126
    FIF.ACCEPT,
127
    "Success",
128
    "File saved successfully",
129
    duration=3000,  # Auto-close after 3 seconds
130
    position=InfoBarPosition.TOP,
131
    parent=self
132
)
133
success_bar.show()
134

135
# Error notification with custom action
136
error_bar = InfoBar(
137
    FIF.ERROR,
138
    "Error",
139
    "Failed to connect to server",
140
    isClosable=True,
141
    parent=self
142
)
143

144
# Add retry button
145
retry_btn = PushButton("Retry")
146
retry_btn.clicked.connect(self.retry_connection)
147
error_bar.addWidget(retry_btn)
148

149
error_bar.show()
150
```
151

152
### Information Badges
153

154
Small status indicators for showing notifications, counts, or status information.
155

156
```python { .api }
157
class InfoBadge(QWidget):
158
    def __init__(self, text: str = "", parent=None): ...
159
    def setText(self, text: str): ...
160
    def text(self) -> str: ...
161
    def setCustomBackgroundColor(self, color: str, color_dark: str): ...
162

163
class DotInfoBadge(InfoBadge):
164
    def __init__(self, parent=None): ...
165

166
class IconInfoBadge(InfoBadge):
167
    def __init__(self, icon: Union[FluentIconBase, QIcon, str], parent=None): ...
168
    def setIcon(self, icon: Union[FluentIconBase, QIcon, str]): ...
169
```
170

171
**Usage Example:**
172
```python
173
from qfluentwidgets import InfoBadge, DotInfoBadge, IconInfoBadge, FluentIcon as FIF
174

175
# Notification count badge
176
count_badge = InfoBadge("5", self)
177
count_badge.setCustomBackgroundColor("#d13438", "#d13438")
178

179
# Status dot
180
status_dot = DotInfoBadge(self)
181
status_dot.setCustomBackgroundColor("#10893e", "#10893e")
182

183
# Icon badge
184
icon_badge = IconInfoBadge(FIF.MAIL, self)
185

186
# Position badges on buttons
187
button = PushButton("Messages", self)
188
count_badge.move(button.x() + button.width() - 10, button.y() - 5)
189
```
190

191
### Teaching Tips and Flyouts
192

193
Educational tooltips and contextual information panels with rich content support.
194

195
```python { .api }
196
class TeachingTip(QWidget):
197
    def __init__(self, target: QWidget, parent=None): ...
198
    def setTitle(self, title: str): ...
199
    def setContent(self, content: str): ...
200
    def addWidget(self, widget: QWidget): ...
201
    def show(self): ...
202
    def close(self): ...
203

204
class PopupTeachingTip(TeachingTip):
205
    def __init__(self, title: str, content: str, image: str = "", isClosable: bool = True,
206
                 tailPosition: TeachingTipTailPosition = TeachingTipTailPosition.BOTTOM,
207
                 duration: int = -1, parent=None): ...
208

209
class TeachingTipTailPosition(Enum):
210
    TOP = 0
211
    BOTTOM = 1
212
    LEFT = 2
213
    RIGHT = 3
214
    TOP_LEFT = 4
215
    TOP_RIGHT = 5
216
    BOTTOM_LEFT = 6
217
    BOTTOM_RIGHT = 7
218

219
class Flyout(QWidget):
220
    def __init__(self, parent=None): ...
221
    def addWidget(self, widget: QWidget): ...
222
    def show(self, target: QWidget): ...
223
    def close(self): ...
224

225
class FlyoutView(QWidget):
226
    def __init__(self, parent=None): ...
227
    def setTitle(self, title: str): ...
228
    def setContent(self, content: str): ...
229
```
230

231
**Usage Example:**
232
```python
233
from qfluentwidgets import PopupTeachingTip, Flyout, TeachingTipTailPosition
234

235
# Teaching tip for onboarding
236
teaching_tip = PopupTeachingTip(
237
    "Welcome!",
238
    "Click here to create a new document. You can also use Ctrl+N as a shortcut.",
239
    isClosable=True,
240
    tailPosition=TeachingTipTailPosition.BOTTOM,
241
    duration=5000,
242
    parent=self
243
)
244

245
# Show near target button
246
teaching_tip.show()
247

248
# Custom flyout with widgets
249
flyout = Flyout(self)
250
flyout_content = QWidget()
251
layout = QVBoxLayout(flyout_content)
252

253
title_label = TitleLabel("Quick Actions")
254
layout.addWidget(title_label)
255

256
action_btn = PushButton("Perform Action")
257
layout.addWidget(action_btn)
258

259
flyout.addWidget(flyout_content)
260
flyout.show(target_button)
261
```
262

263
### Tooltips
264

265
Enhanced tooltips with rich content and fluent design styling.
266

267
```python { .api }
268
class ToolTip(QWidget):
269
    def __init__(self, text: str = "", parent=None): ...
270
    def setText(self, text: str): ...
271
    def setTitle(self, title: str): ...
272
    def show(self, pos: QPoint, duration: int = 1000): ...
273

274
class StateToolTip(QWidget):
275
    def __init__(self, title: str, content: str, parent=None): ...
276
    def setTitle(self, title: str): ...
277
    def setContent(self, content: str): ...
278
    def move(self, pos: QPoint): ...
279
    def show(self): ...
280

281
class ToolTipFilter(QObject):
282
    def __init__(self, parent=None): ...
283
    def eventFilter(self, obj: QObject, event: QEvent) -> bool: ...
284
```
285

286
**Usage Example:**
287
```python
288
from qfluentwidgets import ToolTip, StateToolTip, ToolTipFilter
289

290
# Rich tooltip
291
tooltip = ToolTip("This is a helpful tooltip with additional information", self)
292
tooltip.setTitle("Help")
293

294
# Install tooltip filter for automatic showing
295
tooltip_filter = ToolTipFilter()
296
button.installEventFilter(tooltip_filter)
297

298
# State tooltip for progress indication
299
state_tooltip = StateToolTip("Processing", "Please wait while the operation completes...", self)
300
state_tooltip.show()
301

302
# Auto-hide after operation
303
self.operation_completed.connect(state_tooltip.close)
304
```
305

306
## Dialog Base Classes
307

308
Base classes for creating custom dialogs with fluent design integration.
309

310
```python { .api }
311
class MaskDialogBase(QDialog):
312
    def __init__(self, parent=None): ...
313
    def showEvent(self, event: QShowEvent): ...
314
    def hideEvent(self, event: QHideEvent): ...
315
    def setMaskColor(self, color: QColor): ...
316

317
class DialogQuitOnLastWindowClosedPolicy:
318
    def __init__(self): ...
319
```
320

321
**Usage Example:**
322
```python
323
from qfluentwidgets import MaskDialogBase
324

325
class CustomDialog(MaskDialogBase):
326
    def __init__(self, parent=None):
327
        super().__init__(parent)
328
        self.setupUi()
329
        
330
    def setupUi(self):
331
        layout = QVBoxLayout(self)
332
        
333
        # Add custom content
334
        self.title_label = TitleLabel("Custom Dialog")
335
        self.content_widget = QWidget()
336
        
337
        layout.addWidget(self.title_label)
338
        layout.addWidget(self.content_widget)
339
        
340
        # Buttons
341
        button_layout = QHBoxLayout()
342
        self.ok_button = PrimaryPushButton("OK")
343
        self.cancel_button = PushButton("Cancel")
344
        
345
        button_layout.addWidget(self.cancel_button)
346
        button_layout.addWidget(self.ok_button)
347
        layout.addLayout(button_layout)
348
        
349
        # Connect signals
350
        self.ok_button.clicked.connect(self.accept)
351
        self.cancel_button.clicked.connect(self.reject)
352

353
# Usage
354
dialog = CustomDialog(self)
355
if dialog.exec() == QDialog.Accepted:
356
    print("Dialog accepted")
357
```
358

359
## Animation and Effects
360

361
Dialogs and notifications include smooth animations and transitions:
362

363
```python
364
# Dialogs automatically include:
365
# - Fade in/out animations
366
# - Blur background effects
367
# - Smooth positioning
368
# - Responsive scaling
369

370
# InfoBars include:
371
# - Slide in/out animations
372
# - Auto-dismiss timers
373
# - Smooth color transitions
374

375
# Teaching tips include:
376
# - Bounce animations
377
# - Arrow positioning
378
# - Content transitions
379
```
380

381
## Accessibility Features
382

383
All dialog and notification components include accessibility support:
384

385
```python
386
# Set accessible properties
387
dialog.setAccessibleName("Settings Dialog")
388
info_bar.setAccessibleDescription("Success notification")
389
teaching_tip.setAccessibleRole(QAccessible.ToolTip)
390

391
# Keyboard navigation
392
dialog.setTabOrder(ok_button, cancel_button)
393

394
# Screen reader support
395
info_bar.setAccessibleText(f"{title}: {content}")
396
```