0
# Menu and Command System
1

2
Context menus, command bars, and system tray menus with fluent styling, animations, and modern interaction patterns. These components provide comprehensive command organization and user interaction capabilities.
3

4
## Capabilities
5

6
### Context Menus
7

8
Enhanced context menus with fluent design styling and smooth animations.
9

10
```python { .api }
11
class RoundMenu(QMenu):
12
    def __init__(self, parent=None): ...
13
    def addAction(self, action: QAction) -> QAction: ...
14
    def addAction(self, text: str, slot=None, shortcut=None) -> QAction: ...
15
    def addSeparator(self): ...
16
    def addMenu(self, menu: QMenu) -> QMenu: ...
17
    def exec(self, pos: QPoint, action: QAction = None) -> QAction: ...
18

19
class DWMMenu(QMenu):
20
    def __init__(self, parent=None): ...
21
    # System-integrated menu with Windows Desktop Window Manager integration
22

23
class LineEditMenu(RoundMenu):
24
    def __init__(self, parent=None): ...
25
    # Specialized menu for line edit controls with standard edit actions
26

27
class CheckableMenu(RoundMenu):
28
    def __init__(self, parent=None): ...
29
    def setDefaultAction(self, action: QAction): ...
30
    def defaultAction(self) -> QAction: ...
31
```
32

33
**Usage Example:**
34
```python
35
from qfluentwidgets import RoundMenu, Action, FluentIcon as FIF
36

37
# Create context menu
38
context_menu = RoundMenu(self)
39

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

45
context_menu.addAction(new_action)
46
context_menu.addAction(open_action)
47
context_menu.addSeparator()
48
context_menu.addAction(save_action)
49

50
# Connect actions
51
new_action.triggered.connect(self.create_new)
52
open_action.triggered.connect(self.open_file)
53
save_action.triggered.connect(self.save_file)
54

55
# Show menu on right-click
56
def show_context_menu(self, pos):
57
    context_menu.exec(self.mapToGlobal(pos))
58
    
59
widget.setContextMenuPolicy(Qt.CustomContextMenu)
60
widget.customContextMenuRequested.connect(show_context_menu)
61
```
62

63
### System Tray Menus
64

65
Specialized menus for system tray applications with proper system integration.
66

67
```python { .api }
68
class SystemTrayMenu(QMenu):
69
    def __init__(self, parent=None): ...
70
    def addAction(self, action: QAction) -> QAction: ...
71
    def addAction(self, text: str, slot=None) -> QAction: ...
72

73
class CheckableSystemTrayMenu(SystemTrayMenu):
74
    def __init__(self, parent=None): ...
75
    def setDefaultAction(self, action: QAction): ...
76
```
77

78
**Usage Example:**
79
```python
80
from qfluentwidgets import SystemTrayMenu, FluentIcon as FIF
81
from PyQt5.QtWidgets import QSystemTrayIcon
82

83
# System tray menu
84
tray_menu = SystemTrayMenu()
85

86
# Add tray actions
87
show_action = Action(FIF.VIEW, "Show Window", self)
88
settings_action = Action(FIF.SETTING, "Settings", self)
89
quit_action = Action(FIF.POWER_BUTTON, "Quit", self)
90

91
tray_menu.addAction(show_action)
92
tray_menu.addAction(settings_action)
93
tray_menu.addSeparator()
94
tray_menu.addAction(quit_action)
95

96
# Connect actions
97
show_action.triggered.connect(self.show_window)
98
settings_action.triggered.connect(self.show_settings)
99
quit_action.triggered.connect(self.quit_application)
100

101
# Create system tray icon
102
tray_icon = QSystemTrayIcon(FIF.APP.icon(), self)
103
tray_icon.setContextMenu(tray_menu)
104
tray_icon.show()
105
```
106

107
### Command Bars
108

109
Modern command organization with ribbon-style interfaces and grouped actions.
110

111
```python { .api }
112
class CommandBar(QWidget):
113
    def __init__(self, parent=None): ...
114
    def addAction(self, action: QAction): ...
115
    def addSeparator(self): ...
116
    def addWidget(self, widget: QWidget): ...
117
    def setToolButtonStyle(self, style: Qt.ToolButtonStyle): ...
118

119
class CommandButton(QToolButton):
120
    def __init__(self, parent=None): ...
121
    def __init__(self, icon: Union[FluentIconBase, QIcon, str], parent=None): ...
122
    def __init__(self, text: str, parent=None): ...
123
    def __init__(self, icon: Union[FluentIconBase, QIcon, str], text: str, parent=None): ...
124

125
class CommandBarView(QWidget):
126
    def __init__(self, parent=None): ...
127
    def addCommandBar(self, commandBar: CommandBar): ...
128
    def removeCommandBar(self, commandBar: CommandBar): ...
129
```
130

131
**Usage Example:**
132
```python
133
from qfluentwidgets import CommandBar, CommandButton, CommandBarView, FluentIcon as FIF
134

135
# Create command bar
136
command_bar = CommandBar(self)
137
command_bar.setToolButtonStyle(Qt.ToolButtonTextBesideIcon)
138

139
# Add command buttons
140
new_btn = CommandButton(FIF.ADD, "New")
141
open_btn = CommandButton(FIF.FOLDER, "Open")
142
save_btn = CommandButton(FIF.SAVE, "Save")
143

144
command_bar.addWidget(new_btn)
145
command_bar.addWidget(open_btn)
146
command_bar.addSeparator()
147
command_bar.addWidget(save_btn)
148

149
# Connect commands
150
new_btn.clicked.connect(self.create_new_document)
151
open_btn.clicked.connect(self.open_document)
152
save_btn.clicked.connect(self.save_document)
153

154
# Command bar container
155
command_view = CommandBarView(self)
156
command_view.addCommandBar(command_bar)
157

158
# Multiple command bars
159
edit_bar = CommandBar(self)
160
edit_bar.addWidget(CommandButton(FIF.CUT, "Cut"))
161
edit_bar.addWidget(CommandButton(FIF.COPY, "Copy"))
162
edit_bar.addWidget(CommandButton(FIF.PASTE, "Paste"))
163

164
command_view.addCommandBar(edit_bar)
165
```
166

167
## Action System
168

169
Enhanced action system with fluent design integration and icon support.
170

171
```python { .api }
172
class Action(QAction):
173
    def __init__(self, parent=None): ...
174
    def __init__(self, text: str, parent=None): ...
175
    def __init__(self, icon: Union[FluentIconBase, QIcon, str], text: str, parent=None): ...
176
    def setIcon(self, icon: Union[FluentIconBase, QIcon, str]): ...
177

178
class Icon(QIcon):
179
    def __init__(self, icon: Union[FluentIconBase, QIcon, str]): ...
180
```
181

182
**Usage Example:**
183
```python
184
from qfluentwidgets import Action, Icon, FluentIcon as FIF
185

186
# Create actions with fluent icons
187
file_actions = [
188
    Action(FIF.ADD, "New File", self),
189
    Action(FIF.FOLDER, "Open File", self),
190
    Action(FIF.SAVE, "Save File", self),
191
    Action(FIF.SAVE_AS, "Save As", self),
192
]
193

194
# Set shortcuts
195
file_actions[0].setShortcut("Ctrl+N")
196
file_actions[1].setShortcut("Ctrl+O")
197
file_actions[2].setShortcut("Ctrl+S")
198
file_actions[3].setShortcut("Ctrl+Shift+S")
199

200
# Connect to slots
201
for action in file_actions:
202
    action.triggered.connect(self.handle_file_action)
203

204
def handle_file_action(self):
205
    sender = self.sender()
206
    print(f"Action triggered: {sender.text()}")
207
```
208

209
## Menu Styling and Themes
210

211
All menu components automatically adapt to the current theme:
212

213
```python { .api }
214
# Menu styling is handled automatically
215
# Custom styling can be applied through stylesheets
216

217
class MenuStyleSheet:
218
    LIGHT_THEME = """
219
        QMenu {
220
            background-color: white;
221
            border: 1px solid #e0e0e0;
222
            border-radius: 8px;
223
        }
224
        QMenu::item {
225
            padding: 8px 20px;
226
            border-radius: 4px;
227
        }
228
        QMenu::item:selected {
229
            background-color: #f0f0f0;
230
        }
231
    """
232
    
233
    DARK_THEME = """
234
        QMenu {
235
            background-color: #2b2b2b;
236
            border: 1px solid #3c3c3c;
237
            border-radius: 8px;
238
        }
239
        QMenu::item {
240
            padding: 8px 20px;
241
            border-radius: 4px;
242
            color: white;
243
        }
244
        QMenu::item:selected {
245
            background-color: #404040;
246
        }
247
    """
248
```
249

250
**Usage Example:**
251
```python
252
from qfluentwidgets import isDarkTheme, FluentStyleSheet
253

254
# Apply fluent styling
255
FluentStyleSheet.MENU.apply(menu)
256

257
# Custom styling based on theme
258
if isDarkTheme():
259
    menu.setStyleSheet(MenuStyleSheet.DARK_THEME)
260
else:
261
    menu.setStyleSheet(MenuStyleSheet.LIGHT_THEME)
262
```
263

264
## Advanced Menu Features
265

266
### Hierarchical Menus
267

268
```python
269
# Create nested menus
270
file_menu = RoundMenu("File", self)
271
recent_menu = RoundMenu("Recent Files", self)
272

273
# Add recent files
274
recent_files = ["document1.txt", "document2.txt", "document3.txt"]
275
for file_name in recent_files:
276
    action = Action(FIF.DOCUMENT, file_name, self)
277
    action.triggered.connect(lambda checked, f=file_name: self.open_recent_file(f))
278
    recent_menu.addAction(action)
279

280
# Add submenu
281
file_menu.addMenu(recent_menu)
282
```
283

284
### Dynamic Menu Updates
285

286
```python
287
class DynamicMenu(RoundMenu):
288
    def __init__(self, parent=None):
289
        super().__init__(parent)
290
        self.aboutToShow.connect(self.update_menu)
291
        
292
    def update_menu(self):
293
        self.clear()
294
        
295
        # Rebuild menu based on current state
296
        current_items = self.get_current_items()
297
        for item in current_items:
298
            action = Action(item['icon'], item['text'], self)
299
            action.triggered.connect(item['callback'])
300
            self.addAction(action)
301
```
302

303
### Menu with Custom Widgets
304

305
```python
306
# Add custom widgets to menus
307
custom_menu = RoundMenu(self)
308

309
# Add standard actions
310
custom_menu.addAction(Action(FIF.SETTING, "Settings", self))
311
custom_menu.addSeparator()
312

313
# Add custom widget
314
widget_action = QWidgetAction(self)
315
custom_widget = QWidget()
316
layout = QHBoxLayout(custom_widget)
317

318
slider = Slider(Qt.Horizontal)
319
label = BodyLabel("Volume")
320
layout.addWidget(label)
321
layout.addWidget(slider)
322

323
widget_action.setDefaultWidget(custom_widget)
324
custom_menu.addAction(widget_action)
325
```
326

327
## Keyboard and Accessibility
328

329
Menu components include full keyboard navigation and accessibility support:
330

331
```python
332
# Keyboard shortcuts are automatically handled
333
action.setShortcut(QKeySequence("Ctrl+N"))
334

335
# Mnemonics for keyboard navigation
336
action.setText("&New File")  # Alt+N activates
337

338
# Accessibility
339
action.setToolTip("Create a new file")
340
action.setStatusTip("Create a new document")
341
action.setWhatsThis("This action creates a new file in the current directory")
342

343
# Screen reader support
344
menu.setAccessibleName("File Menu")
345
menu.setAccessibleDescription("Menu containing file operations")
346
```