0
# Layout & Containers
1

2
Organizational elements for structuring user interfaces including windows, groups, collapsing sections, tabs, menus, and child containers. These elements provide the foundation for organizing and presenting UI components in a logical hierarchy.
3

4
## Capabilities
5

6
### Windows
7

8
Primary containers for organizing interface elements.
9

10
```python { .api }
11
def add_window(*, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', width: int = '', height: int = '', indent: int = '', parent: Union[int, str] = '', before: Union[int, str] = '', payload_type: str = '', callback: Callable = '', drag_callback: Callable = '', drop_callback: Callable = '', show: bool = '', pos: Union[List[int], Tuple[int, ...]] = '', filter_key: str = '', delay_search: bool = '', tracked: bool = '', track_offset: float = '', min_size: Union[List[int], Tuple[int, ...]] = '', max_size: Union[List[int], Tuple[int, ...]] = '', menubar: bool = '', collapsed: bool = '', autosize: bool = '', no_resize: bool = '', no_title_bar: bool = '', no_move: bool = '', no_scrollbar: bool = '', no_collapse: bool = '', horizontal_scrollbar: bool = '', no_focus_on_appearing: bool = '', no_bring_to_front_on_focus: bool = '', no_close: bool = '', no_background: bool = '', modal: bool = '', popup: bool = '', no_saved_settings: bool = '', on_close: Callable = '') -> Union[int, str]:
12
    """
13
    Creates a window container.
14
    
15
    Parameters:
16
    - min_size, max_size (tuple): Size constraints
17
    - menubar (bool): Include menu bar
18
    - collapsed (bool): Start collapsed
19
    - autosize (bool): Auto-size to content
20
    - no_resize (bool): Disable resizing
21
    - no_title_bar (bool): Hide title bar
22
    - no_move (bool): Disable moving
23
    - no_scrollbar (bool): Disable scrollbars
24
    - no_collapse (bool): Disable collapse button
25
    - horizontal_scrollbar (bool): Enable horizontal scrolling
26
    - no_focus_on_appearing (bool): Don't focus when shown
27
    - no_bring_to_front_on_focus (bool): Don't bring to front
28
    - no_close (bool): Disable close button
29
    - no_background (bool): Transparent background
30
    - modal (bool): Modal window
31
    - popup (bool): Popup window
32
    - no_saved_settings (bool): Don't save window state
33
    - on_close (Callable): Close callback
34
    
35
    Returns:
36
    Union[int, str]: Window ID
37
    """
38

39
def add_child_window(*, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', width: int = '', height: int = '', indent: int = '', parent: Union[int, str] = '', before: Union[int, str] = '', payload_type: str = '', drop_callback: Callable = '', show: bool = '', pos: Union[List[int], Tuple[int, ...]] = '', filter_key: str = '', delay_search: bool = '', tracked: bool = '', track_offset: float = '', border: bool = '', autosize_x: bool = '', autosize_y: bool = '', no_scrollbar: bool = '', horizontal_scrollbar: bool = '', menubar: bool = '', no_scroll_with_mouse: bool = '', flattened_navigation: bool = '', always_use_window_padding: bool = '', resizable_x: bool = '', resizable_y: bool = '', always_auto_resize: bool = '', frame_style: bool = '', auto_resize_x: bool = '', auto_resize_y: bool = '') -> Union[int, str]:
40
    """
41
    Creates an embedded child window with independent scrolling.
42
    
43
    Parameters:
44
    - border (bool): Show border around child
45
    - autosize_x, autosize_y (bool): Auto-size to content
46
    - no_scrollbar (bool): Disable scrollbars
47
    - horizontal_scrollbar (bool): Enable horizontal scrolling
48
    - menubar (bool): Include menu bar
49
    - no_scroll_with_mouse (bool): Disable mouse wheel scrolling
50
    - flattened_navigation (bool): Flatten keyboard navigation
51
    - always_use_window_padding (bool): Use window padding
52
    - resizable_x, resizable_y (bool): Enable resizing
53
    - always_auto_resize (bool): Always auto-resize
54
    - frame_style (bool): Use frame styling
55
    - auto_resize_x, auto_resize_y (bool): Auto-resize axes
56
    
57
    Returns:
58
    Union[int, str]: Child window ID
59
    """
60
```
61

62
### Groups
63

64
Organizational containers for logical grouping of widgets.
65

66
```python { .api }
67
def add_group(*, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', width: int = '', indent: int = '', parent: Union[int, str] = '', before: Union[int, str] = '', payload_type: str = '', drag_callback: Callable = '', drop_callback: Callable = '', show: bool = '', pos: Union[List[int], Tuple[int, ...]] = '', filter_key: str = '', delay_search: bool = '', tracked: bool = '', track_offset: float = '', horizontal: bool = '', horizontal_spacing: float = '', xoffset: float = '') -> Union[int, str]:
68
    """
69
    Creates a group container for widget organization.
70
    
71
    Parameters:
72
    - horizontal (bool): Horizontal layout
73
    - horizontal_spacing (float): Spacing between horizontal items
74
    - xoffset (float): Horizontal offset
75
    
76
    Returns:
77
    Union[int, str]: Group ID
78
    """
79
```
80

81
### Collapsible Sections
82

83
Expandable/collapsible content containers.
84

85
```python { .api }
86
def add_collapsing_header(*, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', indent: int = '', parent: Union[int, str] = '', before: Union[int, str] = '', payload_type: str = '', drag_callback: Callable = '', drop_callback: Callable = '', show: bool = '', pos: Union[List[int], Tuple[int, ...]] = '', filter_key: str = '', delay_search: bool = '', tracked: bool = '', track_offset: float = '', closable: bool = '', default_open: bool = '', open_on_double_click: bool = '', open_on_arrow: bool = '', leaf: bool = '', bullet: bool = '') -> Union[int, str]:
87
    """
88
    Creates a collapsible header section.
89
    
90
    Parameters:
91
    - closable (bool): Show close button
92
    - default_open (bool): Start expanded
93
    - open_on_double_click (bool): Expand on double-click
94
    - open_on_arrow (bool): Expand only on arrow click
95
    - leaf (bool): No expand/collapse arrow
96
    - bullet (bool): Show bullet point
97
    
98
    Returns:
99
    Union[int, str]: Header ID
100
    """
101

102
def add_tree_node(*, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', indent: int = '', parent: Union[int, str] = '', before: Union[int, str] = '', payload_type: str = '', drag_callback: Callable = '', drop_callback: Callable = '', show: bool = '', pos: Union[List[int], Tuple[int, ...]] = '', filter_key: str = '', delay_search: bool = '', tracked: bool = '', track_offset: float = '', default_open: bool = '', open_on_double_click: bool = '', open_on_arrow: bool = '', leaf: bool = '', bullet: bool = '', selectable: bool = '') -> Union[int, str]:
103
    """
104
    Creates a tree node for hierarchical navigation.
105
    
106
    Parameters:
107
    - default_open (bool): Start expanded
108
    - open_on_double_click (bool): Expand on double-click
109
    - open_on_arrow (bool): Expand only on arrow click
110
    - leaf (bool): No expand/collapse functionality
111
    - bullet (bool): Show bullet point
112
    - selectable (bool): Allow selection
113
    
114
    Returns:
115
    Union[int, str]: Tree node ID
116
    """
117
```
118

119
### Tab Navigation
120

121
Tabbed interface containers for organizing related content.
122

123
```python { .api }
124
def add_tab_bar(*, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', indent: int = '', parent: Union[int, str] = '', before: Union[int, str] = '', payload_type: str = '', callback: Callable = '', drag_callback: Callable = '', drop_callback: Callable = '', show: bool = '', pos: Union[List[int], Tuple[int, ...]] = '', filter_key: str = '', delay_search: bool = '', tracked: bool = '', track_offset: float = '', reorderable: bool = '', callback_data: Any = '') -> Union[int, str]:
125
    """
126
    Creates a tab bar container.
127
    
128
    Parameters:
129
    - reorderable (bool): Allow tab reordering
130
    - callback_data (Any): Data passed to callback
131
    
132
    Returns:
133
    Union[int, str]: Tab bar ID
134
    """
135

136
def add_tab(*, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', indent: int = '', parent: Union[int, str] = '', before: Union[int, str] = '', payload_type: str = '', drag_callback: Callable = '', drop_callback: Callable = '', show: bool = '', pos: Union[List[int], Tuple[int, ...]] = '', filter_key: str = '', delay_search: bool = '', tracked: bool = '', track_offset: float = '', closable: bool = '', no_tooltip: bool = '', order_mode: int = '') -> Union[int, str]:
137
    """
138
    Creates a tab within a tab bar.
139
    
140
    Parameters:
141
    - closable (bool): Show close button
142
    - no_tooltip (bool): Disable tooltip
143
    - order_mode (int): Tab ordering mode
144
    
145
    Returns:
146
    Union[int, str]: Tab ID
147
    """
148

149
def add_tab_button(*, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', indent: int = '', parent: Union[int, str] = '', before: Union[int, str] = '', payload_type: str = '', callback: Callable = '', drag_callback: Callable = '', drop_callback: Callable = '', show: bool = '', pos: Union[List[int], Tuple[int, ...]] = '', filter_key: str = '', tracked: bool = '', track_offset: float = '', no_reorder: bool = '', leading: bool = '', trailing: bool = '', no_tooltip: bool = '') -> Union[int, str]:
150
    """
151
    Creates a tab button for custom tab functionality.
152
    
153
    Parameters:
154
    - no_reorder (bool): Disable reordering
155
    - leading (bool): Position at start
156
    - trailing (bool): Position at end
157
    - no_tooltip (bool): Disable tooltip
158
    
159
    Returns:
160
    Union[int, str]: Tab button ID
161
    """
162
```
163

164
### Menu Systems
165

166
Menu containers for application navigation and commands.
167

168
```python { .api }
169
def add_menu_bar(*, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', indent: int = '', parent: Union[int, str] = '', before: Union[int, str] = '', show: bool = '', delay_search: bool = '') -> Union[int, str]:
170
    """
171
    Creates a menu bar container.
172
    
173
    Returns:
174
    Union[int, str]: Menu bar ID
175
    """
176

177
def add_menu(*, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', indent: int = '', parent: Union[int, str] = '', before: Union[int, str] = '', payload_type: str = '', drag_callback: Callable = '', drop_callback: Callable = '', show: bool = '', enabled: bool = '', pos: Union[List[int], Tuple[int, ...]] = '', filter_key: str = '', delay_search: bool = '', tracked: bool = '', track_offset: float = '') -> Union[int, str]:
178
    """
179
    Creates a dropdown menu.
180
    
181
    Returns:
182
    Union[int, str]: Menu ID
183
    """
184

185
def add_menu_item(*, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', indent: int = '', parent: Union[int, str] = '', before: Union[int, str] = '', payload_type: str = '', callback: Callable = '', drag_callback: Callable = '', drop_callback: Callable = '', show: bool = '', enabled: bool = '', pos: Union[List[int], Tuple[int, ...]] = '', filter_key: str = '', tracked: bool = '', track_offset: float = '', shortcut: str = '', check: bool = '', default_value: bool = '') -> Union[int, str]:
186
    """
187
    Creates a menu item within a menu.
188
    
189
    Parameters:
190
    - shortcut (str): Keyboard shortcut text
191
    - check (bool): Show as checkbox
192
    - default_value (bool): Initial check state
193
    
194
    Returns:
195
    Union[int, str]: Menu item ID
196
    """
197

198
def add_viewport_menu_bar(*, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', show: bool = '') -> Union[int, str]:
199
    """
200
    Creates a viewport-level menu bar.
201
    
202
    Returns:
203
    Union[int, str]: Viewport menu bar ID
204
    """
205
```
206

207
### Performance Containers
208

209
Specialized containers for performance optimization.
210

211
```python { .api }
212
def add_clipper(*, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', width: int = '', indent: int = '', parent: Union[int, str] = '', before: Union[int, str] = '', show: bool = '', delay_search: bool = '') -> Union[int, str]:
213
    """
214
    Creates a clipper for efficient rendering of large lists.
215
    
216
    Helper to manually clip large list of items. Increases performance 
217
    by not searching or drawing widgets outside of the clipped region.
218
    
219
    Returns:
220
    Union[int, str]: Clipper ID
221
    """
222
```
223

224
## Usage Examples
225

226
### Window Layout
227

228
```python
229
import dearpygui.dearpygui as dpg
230

231
with dpg.window(label="Main Window", width=800, height=600, menubar=True):
232
    
233
    # Menu bar
234
    with dpg.menu_bar():
235
        with dpg.menu(label="File"):
236
            dpg.add_menu_item(label="New", shortcut="Ctrl+N")
237
            dpg.add_menu_item(label="Open", shortcut="Ctrl+O")
238
            dpg.add_menu_item(label="Save", shortcut="Ctrl+S")
239
        
240
        with dpg.menu(label="Edit"):
241
            dpg.add_menu_item(label="Undo", shortcut="Ctrl+Z")
242
            dpg.add_menu_item(label="Redo", shortcut="Ctrl+Y")
243
    
244
    # Main content area
245
    with dpg.group(horizontal=True):
246
        
247
        # Left sidebar
248
        with dpg.child_window(width=200, height=500, border=True):
249
            dpg.add_text("Sidebar")
250
            with dpg.collapsing_header(label="Settings", default_open=True):
251
                dpg.add_checkbox(label="Option 1")
252
                dpg.add_checkbox(label="Option 2")
253
                dpg.add_slider_float(label="Value")
254
        
255
        # Main content
256
        with dpg.child_window(width=550, height=500):
257
            with dpg.tab_bar():
258
                with dpg.tab(label="Tab 1"):
259
                    dpg.add_text("Content of tab 1")
260
                    dpg.add_button(label="Button 1")
261
                
262
                with dpg.tab(label="Tab 2"):
263
                    dpg.add_text("Content of tab 2")
264
                    dpg.add_input_text(label="Input")
265
```
266

267
### Tree Navigation
268

269
```python
270
import dearpygui.dearpygui as dpg
271

272
def item_selected(sender, value):
273
    print(f"Selected: {dpg.get_item_label(sender)}")
274

275
with dpg.window(label="Tree Navigation", width=400, height=600):
276
    
277
    with dpg.tree_node(label="Root Node", default_open=True):
278
        
279
        with dpg.tree_node(label="Branch 1", default_open=True):
280
            dpg.add_tree_node(label="Leaf 1.1", leaf=True, 
281
                            selectable=True, callback=item_selected)
282
            dpg.add_tree_node(label="Leaf 1.2", leaf=True, 
283
                            selectable=True, callback=item_selected)
284
        
285
        with dpg.tree_node(label="Branch 2"):
286
            dpg.add_tree_node(label="Leaf 2.1", leaf=True, 
287
                            selectable=True, callback=item_selected)
288
            
289
            with dpg.tree_node(label="Sub-branch 2.2"):
290
                dpg.add_tree_node(label="Leaf 2.2.1", leaf=True, 
291
                                selectable=True, callback=item_selected)
292
```
293

294
### Responsive Layout
295

296
```python
297
import dearpygui.dearpygui as dpg
298

299
def on_resize():
300
    # Get viewport size
301
    viewport_width = dpg.get_viewport_width()
302
    viewport_height = dpg.get_viewport_height()
303
    
304
    # Update window size
305
    dpg.configure_item("main_window", 
306
                      width=viewport_width - 20, 
307
                      height=viewport_height - 40)
308

309
with dpg.window(label="Responsive Layout", 
310
               tag="main_window", 
311
               width=800, height=600,
312
               no_close=True, no_collapse=True):
313
    
314
    with dpg.group(horizontal=True):
315
        
316
        # Resizable panels
317
        with dpg.child_window(width=300, height=500, 
318
                            resizable_x=True, border=True):
319
            dpg.add_text("Left Panel")
320
            dpg.add_text("Resize me!")
321
        
322
        with dpg.child_window(width=450, height=500, border=True):
323
            dpg.add_text("Right Panel")
324
            dpg.add_text("Auto-adjusts to available space")
325

326
# Set resize callback
327
dpg.set_viewport_resize_callback(lambda: on_resize())
328
```
329

330
### Modal Dialog
331

332
```python
333
import dearpygui.dearpygui as dpg
334

335
def show_modal():
336
    dpg.configure_item("modal_window", show=True)
337

338
def close_modal():
339
    dpg.configure_item("modal_window", show=False)
340

341
# Main window
342
with dpg.window(label="Main Window", width=400, height=300):
343
    dpg.add_text("Click the button to show modal dialog")
344
    dpg.add_button(label="Show Modal", callback=show_modal)
345

346
# Modal dialog (initially hidden)
347
with dpg.window(label="Modal Dialog", tag="modal_window", 
348
               modal=True, show=False, width=300, height=200,
349
               no_resize=True, no_move=True):
350
    dpg.add_text("This is a modal dialog")
351
    dpg.add_separator()
352
    
353
    with dpg.group(horizontal=True):
354
        dpg.add_button(label="OK", callback=close_modal)
355
        dpg.add_button(label="Cancel", callback=close_modal)
356
```
357

358
## Constants
359

360
Layout and container-related constants:
361

362
```python { .api }
363
# Window flags
364
mvWindowFlags_None: int
365
mvWindowFlags_NoTitleBar: int
366
mvWindowFlags_NoResize: int
367
mvWindowFlags_NoMove: int
368
mvWindowFlags_NoScrollbar: int
369
mvWindowFlags_NoScrollWithMouse: int
370
mvWindowFlags_NoCollapse: int
371
mvWindowFlags_AlwaysAutoResize: int
372
mvWindowFlags_NoBackground: int
373
mvWindowFlags_NoSavedSettings: int
374
mvWindowFlags_NoMouseInputs: int
375
mvWindowFlags_MenuBar: int
376
mvWindowFlags_HorizontalScrollbar: int
377
mvWindowFlags_NoFocusOnAppearing: int
378
mvWindowFlags_NoBringToFrontOnFocus: int
379
mvWindowFlags_AlwaysVerticalScrollbar: int
380
mvWindowFlags_AlwaysHorizontalScrollbar: int
381
mvWindowFlags_AlwaysUseWindowPadding: int
382
mvWindowFlags_NoNavInputs: int
383
mvWindowFlags_NoNavFocus: int
384
mvWindowFlags_UnsavedDocument: int
385

386
# Tree node flags
387
mvTreeNodeFlags_None: int
388
mvTreeNodeFlags_Selected: int
389
mvTreeNodeFlags_Framed: int
390
mvTreeNodeFlags_AllowItemOverlap: int
391
mvTreeNodeFlags_NoTreePushOnOpen: int
392
mvTreeNodeFlags_NoAutoOpenOnLog: int
393
mvTreeNodeFlags_DefaultOpen: int
394
mvTreeNodeFlags_OpenOnDoubleClick: int
395
mvTreeNodeFlags_OpenOnArrow: int
396
mvTreeNodeFlags_Leaf: int
397
mvTreeNodeFlags_Bullet: int
398
mvTreeNodeFlags_FramePadding: int
399
mvTreeNodeFlags_SpanAvailWidth: int
400
mvTreeNodeFlags_SpanFullWidth: int
401
mvTreeNodeFlags_NavLeftJumpsBackHere: int
402

403
# Tab bar flags
404
mvTabBarFlags_None: int
405
mvTabBarFlags_Reorderable: int
406
mvTabBarFlags_AutoSelectNewTabs: int
407
mvTabBarFlags_TabListPopupButton: int
408
mvTabBarFlags_NoCloseWithMiddleMouseButton: int
409
mvTabBarFlags_NoTabListScrollingButtons: int
410
mvTabBarFlags_NoTooltip: int
411
mvTabBarFlags_FittingPolicyResizeDown: int
412
mvTabBarFlags_FittingPolicyScroll: int
413

414
# Tab item flags
415
mvTabItemFlags_None: int
416
mvTabItemFlags_UnsavedDocument: int
417
mvTabItemFlags_SetSelected: int
418
mvTabItemFlags_NoCloseWithMiddleMouseButton: int
419
mvTabItemFlags_NoPushId: int
420
mvTabItemFlags_NoTooltip: int
421
mvTabItemFlags_NoReorder: int
422
mvTabItemFlags_Leading: int
423
mvTabItemFlags_Trailing: int
424
```