0
# Menus and Popups
1

2
Complete menu bar and popup menu functionality for creating application menus, context menus, and modal dialogs. The menu system provides hierarchical navigation and context-sensitive actions, while popups offer flexible overlay windows for various UI patterns.
3

4
## Capabilities
5

6
### Main Menu Bar
7

8
Functions for creating application-wide menu bars at the top of the main window.
9

10
```python { .api }
11
def begin_main_menu_bar() -> bool:
12
    """Begin main application menu bar. Returns True if menu bar is visible."""
13

14
def end_main_menu_bar() -> None:
15
    """End main application menu bar."""
16
```
17

18
### Window Menu Bar
19

20
Functions for creating menu bars within individual windows.
21

22
```python { .api }
23
def begin_menu_bar() -> bool:
24
    """Begin window menu bar. Returns True if menu bar is visible."""
25

26
def end_menu_bar() -> None:
27
    """End window menu bar."""
28
```
29

30
### Menu Management
31

32
Functions for creating hierarchical menu structures.
33

34
```python { .api }
35
def begin_menu(label: str, enabled: bool = True) -> bool:
36
    """Begin a menu. Returns True if menu is open."""
37

38
def end_menu() -> None:
39
    """End the current menu."""
40

41
def menu_item(label: str, shortcut: str = "", selected: bool = False, enabled: bool = True) -> tuple[bool, bool]:
42
    """Menu item widget. Returns (clicked, selected_state)."""
43
```
44

45
### Popup Management
46

47
Functions for creating and managing popup windows and modal dialogs.
48

49
```python { .api }
50
def open_popup(label: str, flags: int = 0) -> None:
51
    """Open popup with given label."""
52

53
def open_popup_on_item_click(label: str = None, popup_flags: int = 1) -> None:
54
    """Open popup when last item is clicked."""
55

56
def begin_popup(label: str, flags: int = 0) -> bool:
57
    """Begin popup window. Returns True if popup is open."""
58

59
def begin_popup_modal(title: str, visible: bool = None, flags: int = 0) -> tuple[bool, bool]:
60
    """Begin modal popup. Returns (is_open, visible_state)."""
61

62
def begin_popup_context_item(label: str = None, mouse_button: int = 1) -> bool:
63
    """Begin context popup for last item. Returns True if popup is open."""
64

65
def begin_popup_context_window(label: str = None, popup_flags: int = 1, also_over_items: bool = True) -> bool:
66
    """Begin context popup for window. Returns True if popup is open."""
67

68
def begin_popup_context_void(label: str = None, popup_flags: int = 1) -> bool:
69
    """Begin context popup for void area. Returns True if popup is open."""
70

71
def end_popup() -> None:
72
    """End the current popup."""
73

74
def is_popup_open(label: str, flags: int = 0) -> bool:
75
    """Check if popup with given label is open."""
76

77
def close_current_popup() -> None:
78
    """Close the current popup programmatically."""
79
```
80

81
### Popup Flags
82

83
Constants for controlling popup behavior.
84

85
```python { .api }
86
POPUP_NONE: int
87
POPUP_MOUSE_BUTTON_LEFT: int      # Open with left mouse button
88
POPUP_MOUSE_BUTTON_RIGHT: int     # Open with right mouse button (default)
89
POPUP_MOUSE_BUTTON_MIDDLE: int    # Open with middle mouse button
90
POPUP_MOUSE_BUTTON_MASK: int
91
POPUP_MOUSE_BUTTON_DEFAULT: int
92
POPUP_NO_OPEN_OVER_EXISTING_POPUP: int  # Don't open over existing popup
93
POPUP_NO_OPEN_OVER_ITEMS: int     # Don't open over items
94
POPUP_ANY_POPUP_ID: int           # Match any popup ID
95
POPUP_ANY_POPUP_LEVEL: int        # Match any popup level
96
POPUP_ANY_POPUP: int              # Match any popup
97
```
98

99
## Usage Examples
100

101
### Main Menu Bar
102

103
```python
104
import imgui
105

106
# Main application menu bar
107
if imgui.begin_main_menu_bar():
108
    if imgui.begin_menu("File"):
109
        if imgui.menu_item("New", "Ctrl+N")[0]:
110
            print("New file")
111
        
112
        if imgui.menu_item("Open", "Ctrl+O")[0]:
113
            print("Open file")
114
        
115
        if imgui.menu_item("Save", "Ctrl+S")[0]:
116
            print("Save file")
117
        
118
        imgui.separator()
119
        
120
        if imgui.menu_item("Exit", "Alt+F4")[0]:
121
            print("Exit application")
122
        
123
        imgui.end_menu()
124
    
125
    if imgui.begin_menu("Edit"):
126
        if imgui.menu_item("Undo", "Ctrl+Z")[0]:
127
            print("Undo")
128
        
129
        if imgui.menu_item("Redo", "Ctrl+Y")[0]:
130
            print("Redo")
131
        
132
        imgui.separator()
133
        
134
        if imgui.menu_item("Copy", "Ctrl+C")[0]:
135
            print("Copy")
136
        
137
        if imgui.menu_item("Paste", "Ctrl+V")[0]:
138
            print("Paste")
139
        
140
        imgui.end_menu()
141
    
142
    if imgui.begin_menu("View"):
143
        show_demo = True
144
        clicked, show_demo = imgui.menu_item("Show Demo", "", show_demo)
145
        if clicked:
146
            print(f"Show demo: {show_demo}")
147
        
148
        imgui.end_menu()
149
    
150
    imgui.end_main_menu_bar()
151
```
152

153
### Window Menu Bar
154

155
```python
156
# Menu bar within a window
157
if imgui.begin("Window with Menu", True, imgui.WINDOW_MENU_BAR):
158
    if imgui.begin_menu_bar():
159
        if imgui.begin_menu("Options"):
160
            if imgui.menu_item("Option 1")[0]:
161
                print("Option 1 selected")
162
            
163
            if imgui.menu_item("Option 2")[0]:
164
                print("Option 2 selected")
165
            
166
            imgui.end_menu()
167
        
168
        if imgui.begin_menu("Tools"):
169
            if imgui.menu_item("Tool A")[0]:
170
                print("Tool A activated")
171
            
172
            if imgui.menu_item("Tool B")[0]:
173
                print("Tool B activated")
174
            
175
            imgui.end_menu()
176
        
177
        imgui.end_menu_bar()
178
    
179
    imgui.text("Window content goes here")
180
    
181
imgui.end()
182
```
183

184
### Context Menus
185

186
```python
187
# Context menu on item
188
imgui.text("Right-click me for context menu")
189

190
if imgui.begin_popup_context_item("item_context"):
191
    if imgui.menu_item("Action 1")[0]:
192
        print("Action 1 from context menu")
193
    
194
    if imgui.menu_item("Action 2")[0]:
195
        print("Action 2 from context menu")
196
    
197
    imgui.separator()
198
    
199
    if imgui.menu_item("Delete", "Del")[0]:
200
        print("Delete from context menu")
201
    
202
    imgui.end_popup()
203

204
# Context menu on window
205
if imgui.begin_popup_context_window("window_context"):
206
    imgui.text("Window Context Menu")
207
    imgui.separator()
208
    
209
    if imgui.menu_item("Window Action 1")[0]:
210
        print("Window action 1")
211
    
212
    if imgui.menu_item("Window Action 2")[0]:
213
        print("Window action 2")
214
    
215
    imgui.end_popup()
216

217
# Context menu on void area
218
if imgui.begin_popup_context_void("void_context"):
219
    imgui.text("Void Context Menu")
220
    imgui.separator()
221
    
222
    if imgui.menu_item("Create New")[0]:
223
        print("Create new from void")
224
    
225
    imgui.end_popup()
226
```
227

228
### Modal Dialogs
229

230
```python
231
# Modal dialog example
232
show_modal = False
233

234
if imgui.button("Open Modal"):
235
    show_modal = True
236
    imgui.open_popup("Modal Dialog")
237

238
if show_modal:
239
    opened, show_modal = imgui.begin_popup_modal("Modal Dialog", True)
240
    if opened:
241
        imgui.text("This is a modal dialog")
242
        imgui.text("You must close it to continue")
243
        
244
        imgui.separator()
245
        
246
        if imgui.button("OK"):
247
            show_modal = False
248
            imgui.close_current_popup()
249
        
250
        imgui.same_line()
251
        
252
        if imgui.button("Cancel"):
253
            show_modal = False
254
            imgui.close_current_popup()
255
    
256
    if opened:
257
        imgui.end_popup()
258
```
259

260
### Simple Popup
261

262
```python
263
# Simple popup (non-modal)
264
if imgui.button("Open Popup"):
265
    imgui.open_popup("simple_popup")
266

267
if imgui.begin_popup("simple_popup"):
268
    imgui.text("This is a simple popup")
269
    
270
    if imgui.button("Action 1"):
271
        print("Action 1 clicked")
272
        imgui.close_current_popup()
273
    
274
    if imgui.button("Action 2"):
275
        print("Action 2 clicked")
276
        imgui.close_current_popup()
277
    
278
    imgui.end_popup()
279
```
280

281
### Nested Menus
282

283
```python
284
# Nested menu structure
285
if imgui.begin_main_menu_bar():
286
    if imgui.begin_menu("File"):
287
        if imgui.begin_menu("Recent Files"):
288
            if imgui.menu_item("file1.txt")[0]:
289
                print("Open file1.txt")
290
            
291
            if imgui.menu_item("file2.txt")[0]:
292
                print("Open file2.txt")
293
            
294
            imgui.separator()
295
            
296
            if imgui.menu_item("Clear Recent")[0]:
297
                print("Clear recent files")
298
            
299
            imgui.end_menu()
300
        
301
        imgui.separator()
302
        
303
        if imgui.begin_menu("Export"):
304
            if imgui.menu_item("Export as PDF")[0]:
305
                print("Export as PDF")
306
            
307
            if imgui.menu_item("Export as Image")[0]:
308
                print("Export as Image")
309
            
310
            imgui.end_menu()
311
        
312
        imgui.end_menu()
313
    
314
    imgui.end_main_menu_bar()
315
```
316

317
### Conditional Menu Items
318

319
```python
320
# Menu items with dynamic states
321
file_saved = True
322
has_selection = False
323

324
if imgui.begin_main_menu_bar():
325
    if imgui.begin_menu("Edit"):
326
        # Disabled menu item
327
        if imgui.menu_item("Cut", "Ctrl+X", False, has_selection)[0]:
328
            print("Cut")
329
        
330
        if imgui.menu_item("Copy", "Ctrl+C", False, has_selection)[0]:
331
            print("Copy")
332
        
333
        if imgui.menu_item("Paste", "Ctrl+V")[0]:
334
            print("Paste")
335
        
336
        imgui.separator()
337
        
338
        # Menu item with checkmark
339
        clicked, file_saved = imgui.menu_item("Auto Save", "", file_saved)
340
        if clicked:
341
            print(f"Auto save: {file_saved}")
342
        
343
        imgui.end_menu()
344
    
345
    imgui.end_main_menu_bar()
346
```
347

348
### Popup with Custom Positioning
349

350
```python
351
# Custom popup positioning
352
if imgui.button("Custom Popup"):
353
    # Open popup at specific position
354
    imgui.open_popup("custom_positioned")
355

356
if imgui.begin_popup("custom_positioned"):
357
    imgui.text("Custom positioned popup")
358
    
359
    mouse_pos = imgui.get_mouse_pos()
360
    imgui.text(f"Mouse: {mouse_pos[0]:.0f}, {mouse_pos[1]:.0f}")
361
    
362
    if imgui.button("Close"):
363
        imgui.close_current_popup()
364
    
365
    imgui.end_popup()
366
```
367

368
### Confirmation Dialog
369

370
```python
371
# Confirmation dialog pattern
372
show_confirmation = False
373
item_to_delete = None
374

375
# List of items with delete buttons
376
items = ["Item 1", "Item 2", "Item 3"]
377

378
for i, item in enumerate(items):
379
    imgui.text(item)
380
    imgui.same_line()
381
    
382
    if imgui.small_button(f"Delete##{i}"):
383
        item_to_delete = item
384
        show_confirmation = True
385
        imgui.open_popup("Delete Confirmation")
386

387
# Confirmation modal
388
if show_confirmation and item_to_delete:
389
    opened, show_confirmation = imgui.begin_popup_modal("Delete Confirmation", True)
390
    if opened:
391
        imgui.text(f"Are you sure you want to delete '{item_to_delete}'?")
392
        imgui.text("This action cannot be undone.")
393
        
394
        imgui.separator()
395
        
396
        if imgui.button("Yes, Delete"):
397
            print(f"Deleting {item_to_delete}")
398
            # Actually delete the item here
399
            show_confirmation = False
400
            item_to_delete = None
401
            imgui.close_current_popup()
402
        
403
        imgui.same_line()
404
        
405
        if imgui.button("Cancel"):
406
            show_confirmation = False
407
            item_to_delete = None
408
            imgui.close_current_popup()
409
    
410
    if opened:
411
        imgui.end_popup()
412
```