0
# Layout and Positioning
1
2
Tools for controlling widget placement, spacing, grouping, and alignment. The layout system provides precise control over how UI elements are arranged and positioned within windows and containers, enabling flexible and responsive interface designs.
3
4
## Capabilities
5
6
### Basic Layout Control
7
8
Core functions for controlling widget spacing and line arrangement.
9
10
```python { .api }
11
def separator() -> None:
12
"""Add a horizontal line separator."""
13
14
def same_line(position: float = 0.0, spacing: float = -1.0) -> None:
15
"""Keep next widget on same line with optional spacing."""
16
17
def new_line() -> None:
18
"""Add vertical spacing equivalent to a new line."""
19
20
def spacing() -> None:
21
"""Add vertical spacing between widgets."""
22
23
def dummy(width: float, height: float) -> None:
24
"""Add invisible dummy element of specified size."""
25
26
def indent(width: float = 0.0) -> None:
27
"""Move content horizontally to the right."""
28
29
def unindent(width: float = 0.0) -> None:
30
"""Move content horizontally to the left."""
31
```
32
33
### Cursor Position Control
34
35
Functions for precise cursor positioning within windows for custom layouts.
36
37
```python { .api }
38
def get_cursor_pos() -> tuple[float, float]:
39
"""Get cursor position in window coordinates as (x, y)."""
40
41
def get_cursor_pos_x() -> float:
42
"""Get cursor X position in window coordinates."""
43
44
def get_cursor_pos_y() -> float:
45
"""Get cursor Y position in window coordinates."""
46
47
def set_cursor_pos(pos: tuple[float, float]) -> None:
48
"""Set cursor position in window coordinates."""
49
50
def set_cursor_pos_x(x: float) -> None:
51
"""Set cursor X position in window coordinates."""
52
53
def set_cursor_pos_y(y: float) -> None:
54
"""Set cursor Y position in window coordinates."""
55
56
def get_cursor_start_pos() -> tuple[float, float]:
57
"""Get initial cursor position for current window."""
58
59
def get_cursor_screen_pos() -> tuple[float, float]:
60
"""Get cursor position in screen coordinates as (x, y)."""
61
62
def set_cursor_screen_pos(pos: tuple[float, float]) -> None:
63
"""Set cursor position in screen coordinates."""
64
65
def align_text_to_frame_padding() -> None:
66
"""Align text baseline to frame padding."""
67
```
68
69
### Grouping and Organization
70
71
Functions for logically grouping widgets and controlling their collective behavior.
72
73
```python { .api }
74
def begin_group() -> None:
75
"""Start item group for layout calculations."""
76
77
def end_group() -> None:
78
"""End item group."""
79
```
80
81
### Legacy Column System
82
83
Legacy column-based layout system (use Tables for new code).
84
85
```python { .api }
86
def columns(count: int = 1, identifier: str = None, border: bool = True) -> None:
87
"""Setup columns layout."""
88
89
def next_column() -> None:
90
"""Move to next column."""
91
92
def get_column_index() -> int:
93
"""Get current column index."""
94
95
def get_column_offset(column_index: int = -1) -> float:
96
"""Get column offset in pixels."""
97
98
def set_column_offset(column_index: int, offset_x: float) -> None:
99
"""Set column offset in pixels."""
100
101
def get_column_width(column_index: int = -1) -> float:
102
"""Get column width in pixels."""
103
104
def set_column_width(column_index: int, width: float) -> None:
105
"""Set column width in pixels."""
106
107
def get_columns_count() -> int:
108
"""Get number of columns."""
109
```
110
111
## Usage Examples
112
113
### Basic Layout
114
115
```python
116
import imgui
117
118
# Horizontal layout using same_line
119
imgui.text("First")
120
imgui.same_line()
121
imgui.text("Second")
122
imgui.same_line()
123
imgui.text("Third")
124
125
# Add spacing between elements
126
imgui.text("Before spacing")
127
imgui.spacing()
128
imgui.text("After spacing")
129
130
# Separator line
131
imgui.text("Above separator")
132
imgui.separator()
133
imgui.text("Below separator")
134
```
135
136
### Indentation and Alignment
137
138
```python
139
imgui.text("Normal text")
140
imgui.indent()
141
imgui.text("Indented text")
142
imgui.indent()
143
imgui.text("Double indented text")
144
imgui.unindent()
145
imgui.text("Single indented text")
146
imgui.unindent()
147
imgui.text("Back to normal")
148
```
149
150
### Custom Positioning
151
152
```python
153
# Save current cursor position
154
start_pos = imgui.get_cursor_pos()
155
156
# Draw something at a specific position
157
imgui.set_cursor_pos((100, 50))
158
imgui.text("Positioned text")
159
160
# Return to saved position and continue layout
161
imgui.set_cursor_pos((start_pos[0], start_pos[1] + 30))
162
imgui.text("Back to normal flow")
163
```
164
165
### Grouping Elements
166
167
```python
168
imgui.text("Before group")
169
170
imgui.begin_group()
171
imgui.text("Group item 1")
172
imgui.text("Group item 2")
173
imgui.text("Group item 3")
174
imgui.end_group()
175
176
# Same line after group
177
imgui.same_line()
178
imgui.text("Next to group")
179
```
180
181
### Creating Custom Layouts
182
183
```python
184
# Create a two-column layout manually
185
window_width = imgui.get_window_width()
186
column_width = window_width * 0.5
187
188
# Left column
189
imgui.text("Left Column")
190
imgui.button("Left Button")
191
192
# Move to right column
193
imgui.same_line(column_width)
194
imgui.text("Right Column")
195
imgui.same_line(column_width)
196
imgui.button("Right Button")
197
```
198
199
### Dummy Elements for Spacing
200
201
```python
202
imgui.text("Above dummy")
203
imgui.dummy(0, 20) # 20 pixel vertical space
204
imgui.text("Below dummy")
205
206
# Horizontal dummy for spacing
207
imgui.text("Left")
208
imgui.same_line()
209
imgui.dummy(50, 0) # 50 pixel horizontal space
210
imgui.same_line()
211
imgui.text("Right")
212
```
213
214
### Legacy Columns
215
216
```python
217
# Create 3 columns
218
imgui.columns(3, "MyColumns")
219
220
# Column 1
221
imgui.text("Column 1")
222
imgui.button("Button 1")
223
imgui.next_column()
224
225
# Column 2
226
imgui.text("Column 2")
227
imgui.button("Button 2")
228
imgui.next_column()
229
230
# Column 3
231
imgui.text("Column 3")
232
imgui.button("Button 3")
233
imgui.next_column()
234
235
# End columns
236
imgui.columns(1)
237
```