0
# Window and Navigation
1

2
Fluent-styled windows with integrated navigation interfaces, supporting hierarchical navigation, route-based page switching, and modern title bars with system integration. These components provide the foundation for modern Windows 11-style applications.
3

4
## Capabilities
5

6
### Fluent Window
7

8
Main application window with integrated navigation interface, fluent design title bar, and automatic theme support.
9

10
```python { .api }
11
class FluentWindow(FluentWindowBase):
12
    def __init__(self, parent=None): ...
13
    
14
    def addSubInterface(self, interface: QWidget, icon: Union[FluentIconBase, QIcon, str], text: str,
15
                      position=NavigationItemPosition.TOP, parent=None, isTransparent=False) -> NavigationTreeWidget: ...
16
    def switchTo(self, interface: QWidget): ...
17
    def stackedWidget(self) -> QStackedWidget: ...
18
    def resizeEvent(self, e): ...
19
    def closeEvent(self, e): ...
20
```
21

22
**Usage Example:**
23
```python
24
from qfluentwidgets import FluentWindow, FluentIcon as FIF, NavigationItemPosition
25
from PyQt5.QtWidgets import QWidget, QApplication
26
from PyQt5.QtCore import Qt
27

28
class MainWindow(FluentWindow):
29
    def __init__(self):
30
        super().__init__()
31
        self.initWindow()
32
        self.initNavigation()
33
        
34
    def initWindow(self):
35
        self.resize(900, 700)
36
        self.setWindowTitle('My Fluent App')
37
        
38
        # Center window on screen
39
        desktop = QApplication.desktop().availableGeometry()
40
        w, h = desktop.width(), desktop.height()
41
        self.move(w//2 - self.width()//2, h//2 - self.height()//2)
42
        
43
    def initNavigation(self):
44
        # Create interface pages
45
        self.homeInterface = HomeWidget(self)
46
        self.settingsInterface = SettingsWidget(self)
47
        self.aboutInterface = AboutWidget(self)
48
        
49
        # Add to navigation
50
        self.addSubInterface(self.homeInterface, FIF.HOME, 'Home')
51
        self.addSubInterface(self.settingsInterface, FIF.SETTING, 'Settings')
52
        
53
        # Add separator
54
        self.navigationInterface.addSeparator()
55
        
56
        # Add bottom items
57
        self.addSubInterface(
58
            self.aboutInterface, 
59
            FIF.INFO, 
60
            'About', 
61
            NavigationItemPosition.BOTTOM
62
        )
63
```
64

65
### Microsoft-Style Fluent Window
66

67
Alternative window style that more closely matches Microsoft's own fluent design applications.
68

69
```python { .api }
70
class MSFluentWindow(FluentWindowBase):
71
    def __init__(self, parent=None): ...
72
    def addSubInterface(self, interface: QWidget, icon: Union[FluentIconBase, QIcon, str], text: str,
73
                      position=NavigationItemPosition.TOP, parent=None, isTransparent=False) -> NavigationTreeWidget: ...
74
```
75

76
**Usage Example:**  
77
```python
78
from qfluentwidgets import MSFluentWindow, FluentIcon as FIF
79

80
class MSStyleWindow(MSFluentWindow):
81
    def __init__(self):
82
        super().__init__()
83
        self.resize(1000, 750)
84
        self.setWindowTitle('Microsoft Style App')
85
        
86
        # Add interfaces with MS styling
87
        self.addSubInterface(self.mainInterface, FIF.HOME, 'Home')
88
        self.addSubInterface(self.dataInterface, FIF.DATABASE, 'Data')
89
```
90

91
### Split Fluent Window
92

93
Window with split navigation panel that can be collapsed or expanded for more flexible layout options.
94

95
```python { .api }
96
class SplitFluentWindow(FluentWindowBase):
97
    def __init__(self, parent=None): ...
98
    def addSubInterface(self, interface: QWidget, icon: Union[FluentIconBase, QIcon, str], text: str,
99
                      position=NavigationItemPosition.TOP, parent=None, isTransparent=False) -> NavigationTreeWidget: ...
100
```
101

102
### Navigation Interface
103

104
Core navigation component that manages route-based page switching, hierarchical navigation, and navigation items.
105

106
```python { .api }
107
class NavigationInterface(QWidget):
108
    def __init__(self, parent=None, showMenuButton=True, showReturnButton=False, collapsible=True): ...
109
    
110
    def addItem(self, routeKey: str, icon: Union[str, QIcon, FluentIconBase], text: str, onClick=None,
111
               selectable=True, position=NavigationItemPosition.TOP, tooltip: str = None,
112
               parentRouteKey: str = None) -> NavigationTreeWidget: ...
113
               
114
    def addWidget(self, routeKey: str, widget: NavigationWidget, onClick=None, 
115
                 position=NavigationItemPosition.TOP, tooltip: str = None,
116
                 parentRouteKey: str = None) -> NavigationTreeWidget: ...
117
                 
118
    def addSeparator(self, position=NavigationItemPosition.TOP): ...
119
    def setCurrentItem(self, routeKey: str): ...
120
    def setExpandWidth(self, width: int): ...
121
    def setCollapsible(self, collapsible: bool): ...
122
    def panel(self) -> NavigationPanel: ...
123
```
124

125
**Usage Example:**
126
```python
127
from qfluentwidgets import NavigationInterface, NavigationAvatarWidget, FluentIcon as FIF
128

129
# Create standalone navigation
130
nav = NavigationInterface(self, showMenuButton=True, collapsible=True)
131

132
# Add navigation items
133
nav.addItem('home', FIF.HOME, 'Home', self.show_home)
134
nav.addItem('documents', FIF.DOCUMENT, 'Documents', self.show_documents)
135
nav.addItem('pictures', FIF.PHOTO, 'Pictures', self.show_pictures)
136

137
# Add separator
138
nav.addSeparator()
139

140
# Add hierarchical items
141
nav.addItem('settings', FIF.SETTING, 'Settings')
142
nav.addItem('general', FIF.SETTING, 'General', parentRouteKey='settings')
143
nav.addItem('advanced', FIF.DEVELOPER_TOOLS, 'Advanced', parentRouteKey='settings')
144

145
# Add custom widget
146
avatar = NavigationAvatarWidget('John Doe', 'avatar.png')
147
nav.addWidget('profile', avatar, self.show_profile, NavigationItemPosition.BOTTOM)
148

149
# Set current page
150
nav.setCurrentItem('home')
151
```
152

153
### Navigation Components
154

155
Individual navigation elements for building custom navigation interfaces.
156

157
```python { .api }
158
class NavigationWidget(QWidget): ...
159

160
class NavigationPushButton(NavigationWidget):
161
    def __init__(self, icon: Union[str, QIcon, FluentIconBase], text: str, isSelectable: bool = True, parent=None): ...
162

163
class NavigationToolButton(NavigationWidget):
164
    def __init__(self, icon: Union[str, QIcon, FluentIconBase], isSelectable: bool = True, parent=None): ...
165
    
166
class NavigationSeparator(NavigationWidget): ...
167

168
class NavigationTreeWidget(NavigationWidget):
169
    def __init__(self, icon: Union[str, QIcon, FluentIconBase], text: str, isSelectable: bool = True, parent=None): ...
170
    def addChild(self, child: NavigationWidget): ...
171

172
class NavigationAvatarWidget(NavigationWidget):
173
    def __init__(self, name: str, avatar: Union[str, QPixmap, QIcon], parent=None): ...
174
    def setName(self, name: str): ...
175
    def setAvatar(self, avatar: Union[str, QPixmap, QIcon]): ...
176
```
177

178
**Usage Example:**
179
```python
180
from qfluentwidgets import (NavigationPushButton, NavigationSeparator, 
181
                           NavigationAvatarWidget, FluentIcon as FIF)
182

183
# Create individual navigation components
184
home_btn = NavigationPushButton(FIF.HOME, 'Home', True, self)
185
settings_btn = NavigationPushButton(FIF.SETTING, 'Settings', True, self)
186
separator = NavigationSeparator(self)
187
avatar = NavigationAvatarWidget('User', 'user_avatar.png', self)
188

189
# Connect signals
190
home_btn.clicked.connect(self.show_home_page)
191
settings_btn.clicked.connect(self.show_settings_page)
192
```
193

194
### Navigation Bar
195

196
Horizontal navigation bar for tab-style navigation patterns.
197

198
```python { .api }
199
class NavigationBar(QWidget):
200
    def __init__(self, parent=None): ...
201
    def addItem(self, routeKey: str, icon: Union[str, QIcon, FluentIconBase], text: str, onClick=None,
202
               selectable: bool = True, tooltip: str = None) -> NavigationBarPushButton: ...
203
    def setCurrentItem(self, routeKey: str): ...
204

205
class NavigationBarPushButton(QPushButton): ...
206
```
207

208
**Usage Example:**
209
```python
210
from qfluentwidgets import NavigationBar, FluentIcon as FIF
211

212
# Create horizontal navigation bar
213
nav_bar = NavigationBar(self)
214

215
# Add navigation items
216
nav_bar.addItem('overview', FIF.HOME, 'Overview', self.show_overview)
217
nav_bar.addItem('analytics', FIF.CHART, 'Analytics', self.show_analytics)
218
nav_bar.addItem('reports', FIF.DOCUMENT, 'Reports', self.show_reports)
219

220
# Set initial selection
221
nav_bar.setCurrentItem('overview')
222
```
223

224
### Pivot Navigation
225

226
Tabbed navigation component for switching between related content areas.
227

228
```python { .api }
229
class Pivot(QWidget):
230
    def __init__(self, parent=None): ...
231
    def addItem(self, routeKey: str, text: str, onClick=None, icon: Union[QIcon, str, FluentIconBase] = None) -> PivotItem: ...
232
    def setCurrentItem(self, routeKey: str): ...
233
    def currentRouteKey(self) -> str: ...
234

235
class PivotItem(QWidget):
236
    def __init__(self, routeKey: str, text: str, parent=None): ...
237
    def setSelected(self, isSelected: bool): ...
238
```
239

240
**Usage Example:**
241
```python
242
from qfluentwidgets import Pivot, FluentIcon as FIF
243

244
# Create pivot navigation
245
pivot = Pivot(self)
246

247
# Add pivot items
248
pivot.addItem('emails', 'Emails', self.show_emails, FIF.MAIL)
249
pivot.addItem('calendar', 'Calendar', self.show_calendar, FIF.CALENDAR)
250
pivot.addItem('contacts', 'Contacts', self.show_contacts, FIF.CONTACT)
251

252
# Set current pivot
253
pivot.setCurrentItem('emails')
254

255
# Connect to content switching
256
pivot.currentItemChanged.connect(self.switch_content)
257
```
258

259
### Segmented Controls
260

261
Compact navigation for closely related options and view modes.
262

263
```python { .api }
264
class SegmentedWidget(QWidget):
265
    def __init__(self, parent=None): ...
266
    def addItem(self, routeKey: str, text: str, onClick=None, icon: Union[QIcon, str, FluentIconBase] = None) -> SegmentedItem: ...
267
    def setCurrentItem(self, routeKey: str): ...
268

269
class SegmentedItem(QWidget): ...
270

271
class SegmentedToolWidget(QWidget):
272
    def __init__(self, parent=None): ...
273
    def addItem(self, routeKey: str, icon: Union[QIcon, str, FluentIconBase], onClick=None) -> SegmentedToolItem: ...
274

275
class SegmentedToggleToolWidget(SegmentedToolWidget): ...
276
```
277

278
**Usage Example:**
279
```python
280
from qfluentwidgets import SegmentedWidget, SegmentedToolWidget, FluentIcon as FIF
281

282
# Text-based segmented control
283
view_segments = SegmentedWidget(self)
284
view_segments.addItem('list', 'List View', self.show_list_view)
285
view_segments.addItem('grid', 'Grid View', self.show_grid_view)
286
view_segments.addItem('detail', 'Detail View', self.show_detail_view)
287

288
# Icon-based segmented tools
289
tool_segments = SegmentedToolWidget(self)
290
tool_segments.addItem('bold', FIF.BOLD, self.toggle_bold)
291
tool_segments.addItem('italic', FIF.ITALIC, self.toggle_italic)
292
tool_segments.addItem('underline', FIF.UNDERLINE, self.toggle_underline)
293
```
294

295
### Breadcrumb Navigation
296

297
Hierarchical navigation showing the current location within nested content.
298

299
```python { .api }
300
class BreadcrumbBar(QWidget):
301
    def __init__(self, parent=None): ...
302
    def addItem(self, routeKey: str, text: str, onClick=None) -> BreadcrumbItem: ...
303
    def clear(): ...
304
    def setCurrentItem(self, routeKey: str): ...
305

306
class BreadcrumbItem(QWidget):
307
    def __init__(self, routeKey: str, text: str, parent=None): ...
308
    def setText(self, text: str): ...
309
    def setSelected(self, isSelected: bool): ...
310
```
311

312
**Usage Example:**
313
```python
314
from qfluentwidgets import BreadcrumbBar
315

316
# Create breadcrumb navigation
317
breadcrumb = BreadcrumbBar(self)
318

319
# Build breadcrumb path
320
breadcrumb.addItem('home', 'Home', self.navigate_home)
321
breadcrumb.addItem('documents', 'Documents', self.navigate_documents)
322
breadcrumb.addItem('projects', 'Projects', self.navigate_projects)
323
breadcrumb.addItem('current', 'My Project', self.navigate_current)
324

325
# Set current location
326
breadcrumb.setCurrentItem('current')
327

328
# Update breadcrumb when navigating
329
def update_breadcrumb(self, path_items):
330
    breadcrumb.clear()
331
    for item in path_items:
332
        breadcrumb.addItem(item['key'], item['text'], item['callback'])
333
```
334

335
### Title Bars
336

337
Custom title bars with fluent design styling and system window controls.
338

339
```python { .api }
340
class FluentTitleBar(QWidget):
341
    def __init__(self, parent=None): ...
342
    def setTitle(self, title: str): ...
343
    def setIcon(self, icon: QIcon): ...
344

345
class MSFluentTitleBar(FluentTitleBar): ...
346
class SplitTitleBar(FluentTitleBar): ...
347
```
348

349
## Navigation Item Positions
350

351
```python { .api }
352
class NavigationItemPosition(Enum):
353
    TOP = 0
354
    SCROLL = 1
355
    BOTTOM = 2
356
```
357

358
## Navigation Display Modes
359

360
```python { .api }
361
class NavigationDisplayMode(Enum):
362
    EXPAND = 0
363
    COMPACT = 1
364
    MINIMAL = 2
365
```
366

367
## Common Navigation Patterns
368

369
### Multi-level Navigation
370
```python
371
# Create hierarchical navigation structure
372
nav.addItem('media', FIF.MEDIA, 'Media')
373
nav.addItem('music', FIF.MUSIC, 'Music', parentRouteKey='media')
374
nav.addItem('videos', FIF.VIDEO, 'Videos', parentRouteKey='media')
375
nav.addItem('photos', FIF.PHOTO, 'Photos', parentRouteKey='media')
376
```
377

378
### Dynamic Navigation Updates
379
```python
380
# Add items dynamically
381
def add_recent_file(self, filename, filepath):
382
    route_key = f"recent_{filename}"
383
    self.navigationInterface.addItem(
384
        route_key, FIF.DOCUMENT, filename,
385
        lambda: self.open_file(filepath),
386
        position=NavigationItemPosition.TOP
387
    )
388
```
389

390
### Navigation with Custom Actions
391
```python
392
# Add items with custom click handling
393
nav.addItem('export', FIF.SHARE, 'Export Data', self.show_export_dialog)
394
nav.addItem('import', FIF.DOWNLOAD, 'Import Data', self.show_import_dialog)
395
```