0
# Menu System
1

2
The MenuBar widget provides application-level menus for organizing commands and actions. It creates standard menu bars with dropdown menus containing menu items that can execute commands when selected.
3

4
## Capabilities
5

6
### Menu Bar
7

8
The MenuBar widget creates a menu bar that can be attached to application windows, providing standard menu functionality.
9

10
```python { .api }
11
class MenuBar:
12
    def __init__(self, master, toplevel=[], options=[]):
13
        """
14
        Create a menu bar widget.
15
        
16
        Args:
17
            master (App): Parent application window
18
            toplevel (list): List of top-level menu names
19
            options (list): List of menu item configurations
20
        """
21
```
22

23
## Menu Configuration
24

25
Menus are configured using a nested list structure that defines the menu hierarchy:
26

27
### Basic Menu Structure
28

29
```python
30
from guizero import App, MenuBar
31

32
app = App()
33

34
def file_new():
35
    print("New file")
36

37
def file_open():
38
    print("Open file")
39

40
def file_exit():
41
    app.destroy()
42

43
def help_about():
44
    print("About this application")
45

46
# Define menu structure
47
menubar = MenuBar(app,
48
    toplevel=["File", "Help"],
49
    options=[
50
        [
51
            ["New", file_new],
52
            ["Open", file_open],
53
            ["---"],  # Separator
54
            ["Exit", file_exit]
55
        ],
56
        [
57
            ["About", help_about]
58
        ]
59
    ]
60
)
61

62
app.display()
63
```
64

65
### Menu Item Types
66

67
Menu items can be configured in several ways:
68

69
```python
70
# Basic menu item with command
71
["Menu Text", callback_function]
72

73
# Menu separator
74
["---"]
75

76
# Menu with keyboard shortcut (display only)
77
["Copy\tCtrl+C", copy_function]
78

79
# Submenu (nested menu)
80
["Submenu", [
81
    ["Submenu Item 1", function1],
82
    ["Submenu Item 2", function2]
83
]]
84
```
85

86
## Complete Menu Example
87

88
```python
89
from guizero import App, MenuBar, TextBox, select_file, select_color, info
90

91
class TextEditor:
92
    def __init__(self):
93
        self.app = App(title="Simple Text Editor", width=600, height=400)
94
        
95
        # Text area
96
        self.text_area = TextBox(
97
            self.app, 
98
            multiline=True, 
99
            scrollbar=True,
100
            width="fill",
101
            height="fill"
102
        )
103
        
104
        # Create menu bar
105
        self.create_menus()
106
        
107
    def create_menus(self):
108
        self.menubar = MenuBar(self.app,
109
            toplevel=["File", "Edit", "Format", "Help"],
110
            options=[
111
                # File menu
112
                [
113
                    ["New\tCtrl+N", self.file_new],
114
                    ["Open\tCtrl+O", self.file_open],
115
                    ["Save\tCtrl+S", self.file_save],
116
                    ["Save As", self.file_save_as],
117
                    ["---"],
118
                    ["Exit\tCtrl+Q", self.file_exit]
119
                ],
120
                # Edit menu  
121
                [
122
                    ["Cut\tCtrl+X", self.edit_cut],
123
                    ["Copy\tCtrl+C", self.edit_copy],
124
                    ["Paste\tCtrl+V", self.edit_paste],
125
                    ["---"],
126
                    ["Select All\tCtrl+A", self.edit_select_all],
127
                    ["Clear", self.edit_clear]
128
                ],
129
                # Format menu
130
                [
131
                    ["Font Size", [
132
                        ["Small", lambda: self.set_font_size(10)],
133
                        ["Medium", lambda: self.set_font_size(12)],
134
                        ["Large", lambda: self.set_font_size(14)]
135
                    ]],
136
                    ["Text Color", self.format_color]
137
                ],
138
                # Help menu
139
                [
140
                    ["About", self.help_about],
141
                    ["Help", self.help_help]
142
                ]
143
            ]
144
        )
145
    
146
    # File menu methods
147
    def file_new(self):
148
        self.text_area.clear()
149
        
150
    def file_open(self):
151
        filepath = select_file(
152
            title="Open File",
153
            filetypes=[["Text files", "*.txt"], ["All files", "*.*"]],
154
            master=self.app
155
        )
156
        if filepath:
157
            try:
158
                with open(filepath, 'r') as f:
159
                    content = f.read()
160
                self.text_area.value = content
161
            except IOError as e:
162
                info("Error", f"Could not open file: {e}", self.app)
163
                
164
    def file_save(self):
165
        # Simplified save - in real app would track current file
166
        self.file_save_as()
167
        
168
    def file_save_as(self):
169
        filepath = select_file(
170
            title="Save File As",
171
            filetypes=[["Text files", "*.txt"], ["All files", "*.*"]],
172
            save=True,
173
            master=self.app
174
        )
175
        if filepath:
176
            try:
177
                with open(filepath, 'w') as f:
178
                    f.write(self.text_area.value)
179
                info("Success", "File saved successfully!", self.app)
180
            except IOError as e:
181
                info("Error", f"Could not save file: {e}", self.app)
182
                
183
    def file_exit(self):
184
        self.app.destroy()
185
    
186
    # Edit menu methods
187
    def edit_cut(self):
188
        # Note: Actual cut/copy/paste would require tkinter clipboard access
189
        print("Cut operation")
190
        
191
    def edit_copy(self):
192
        print("Copy operation")
193
        
194
    def edit_paste(self):
195
        print("Paste operation")
196
        
197
    def edit_select_all(self):
198
        print("Select all operation")
199
        
200
    def edit_clear(self):
201
        self.text_area.clear()
202
    
203
    # Format menu methods
204
    def set_font_size(self, size):
205
        self.text_area.text_size = size
206
        
207
    def format_color(self):
208
        color = select_color(master=self.app)
209
        if color:
210
            self.text_area.text_color = color
211
    
212
    # Help menu methods
213
    def help_about(self):
214
        info("About", "Simple Text Editor v1.0\nBuilt with guizero", self.app)
215
        
216
    def help_help(self):
217
        info("Help", "Use the File menu to open and save files.\nUse Edit menu for text operations.", self.app)
218
    
219
    def run(self):
220
        self.app.display()
221

222
# Create and run the application
223
editor = TextEditor()
224
editor.run()
225
```
226

227
## Menu Best Practices
228

229
### Menu Organization
230

231
Follow standard menu conventions:
232

233
```python
234
# Standard menu order
235
toplevel=["File", "Edit", "View", "Tools", "Help"]
236

237
# Common File menu items
238
file_menu = [
239
    ["New", new_function],
240
    ["Open", open_function], 
241
    ["---"],
242
    ["Save", save_function],
243
    ["Save As", save_as_function],
244
    ["---"],
245
    ["Exit", exit_function]
246
]
247
```
248

249
### Keyboard Shortcuts
250

251
Display keyboard shortcuts in menu text (display only - actual keyboard handling requires additional implementation):
252

253
```python
254
menu_items = [
255
    ["New\tCtrl+N", new_function],
256
    ["Open\tCtrl+O", open_function],
257
    ["Save\tCtrl+S", save_function]
258
]
259
```
260

261
### Menu Separators
262

263
Use separators to group related menu items:
264

265
```python
266
menu_items = [
267
    ["New", new_function],
268
    ["Open", open_function],
269
    ["---"],  # Separator
270
    ["Save", save_function],
271
    ["Save As", save_as_function],
272
    ["---"],  # Separator  
273
    ["Exit", exit_function]
274
]
275
```
276

277
### Submenus
278

279
Create submenus for related options:
280

281
```python
282
format_menu = [
283
    ["Font", [
284
        ["Arial", lambda: set_font("Arial")],
285
        ["Times", lambda: set_font("Times")],
286
        ["Courier", lambda: set_font("Courier")]
287
    ]],
288
    ["Size", [
289
        ["10pt", lambda: set_size(10)],
290
        ["12pt", lambda: set_size(12)],
291
        ["14pt", lambda: set_size(14)]
292
    ]]
293
]
294
```
295

296
## Menu Limitations
297

298
The guizero MenuBar has some limitations compared to full-featured menu systems:
299

300
- **No menu item states**: Items cannot be enabled/disabled or checked/unchecked dynamically
301
- **No icons**: Menu items cannot display icons
302
- **Limited styling**: Menu appearance follows system defaults
303
- **Keyboard shortcuts**: Display only - requires separate keyboard event handling for functionality
304

305
For applications requiring advanced menu features, consider using the underlying Tkinter Menu widget directly through the `.tk` property.
306

307
## Platform Behavior
308

309
Menu behavior follows platform conventions:
310

311
- **Windows**: Menu bar appears below title bar
312
- **macOS**: Menu bar may appear at top of screen (system menu bar)
313
- **Linux**: Menu bar appears below title bar, styling depends on desktop environment