0
# Tables
1
2
Modern table system with sorting, resizing, reordering, and scrolling capabilities. The table API provides a powerful and flexible way to display structured data with interactive features, replacing the legacy column system with a more robust solution.
3
4
## Capabilities
5
6
### Table Management
7
8
Core functions for creating and managing table structures.
9
10
```python { .api }
11
def begin_table(label: str, column: int, flags: int = 0, outer_width: float = 0, outer_height: float = 0, inner_width: float = 0.0) -> bool:
12
"""Begin table definition. Returns True if table is visible."""
13
14
def end_table() -> None:
15
"""End table definition."""
16
17
def table_next_row(row_flags: int = 0, min_row_height: float = 0.0) -> None:
18
"""Move to next table row."""
19
20
def table_next_column() -> bool:
21
"""Move to next table column. Returns True if column is visible."""
22
23
def table_set_column_index(column_n: int) -> bool:
24
"""Set current table column by index. Returns True if column is visible."""
25
```
26
27
### Table Setup
28
29
Functions for configuring table columns and behavior before adding content.
30
31
```python { .api }
32
def table_setup_column(label: str, flags: int = 0, init_width_or_weight: float = 0.0, user_id: int = 0) -> None:
33
"""Setup table column properties."""
34
35
def table_setup_scroll_freeze(cols: int, rows: int) -> None:
36
"""Setup frozen columns and rows (like Excel freeze panes)."""
37
38
def table_headers_row() -> None:
39
"""Submit table headers row using column labels."""
40
41
def table_header(label: str) -> None:
42
"""Submit individual table header cell."""
43
```
44
45
### Table Information
46
47
Functions to query table state and properties.
48
49
```python { .api }
50
def table_get_sort_specs():
51
"""Get table sort specifications object."""
52
53
def table_get_column_count() -> int:
54
"""Get number of columns in current table."""
55
56
def table_get_column_index() -> int:
57
"""Get current column index."""
58
59
def table_get_row_index() -> int:
60
"""Get current row index."""
61
62
def table_get_column_name(column_n: int = -1) -> str:
63
"""Get column name by index (-1 for current column)."""
64
65
def table_get_column_flags(column_n: int = -1) -> int:
66
"""Get column flags by index (-1 for current column)."""
67
68
def table_set_background_color(target: int, color: int, column_n: int = -1) -> None:
69
"""Set table background color for row, cell, or column."""
70
```
71
72
### Table Flags
73
74
Constants for controlling table behavior and appearance.
75
76
```python { .api }
77
# Basic table flags
78
TABLE_NONE: int
79
TABLE_RESIZABLE: int # Enable column resizing
80
TABLE_REORDERABLE: int # Enable column reordering
81
TABLE_HIDEABLE: int # Enable column hiding
82
TABLE_SORTABLE: int # Enable sorting
83
TABLE_NO_SAVED_SETTINGS: int # Disable saving settings
84
TABLE_CONTEXT_MENU_IN_BODY: int # Right-click context menu in body
85
86
# Border flags
87
TABLE_BORDERS_INNER_HORIZONTAL: int
88
TABLE_BORDERS_OUTER_HORIZONTAL: int
89
TABLE_BORDERS_INNER_VERTICAL: int
90
TABLE_BORDERS_OUTER_VERTICAL: int
91
TABLE_BORDERS_HORIZONTAL: int # Inner + outer horizontal
92
TABLE_BORDERS_VERTICAL: int # Inner + outer vertical
93
TABLE_BORDERS_INNER: int # Inner horizontal + vertical
94
TABLE_BORDERS_OUTER: int # Outer horizontal + vertical
95
TABLE_BORDERS: int # All borders
96
TABLE_NO_BORDERS_IN_BODY: int
97
TABLE_NO_BORDERS_IN_BODY_UTIL_RESIZE: int
98
99
# Decoration flags
100
TABLE_ROW_BACKGROUND: int # Alternating row background colors
101
102
# Sizing flags
103
TABLE_SIZING_FIXED_FIT: int # Columns fit contents
104
TABLE_SIZING_FIXED_SAME: int # All columns same width
105
TABLE_SIZING_STRETCH_PROP: int # Columns stretch proportionally
106
TABLE_SIZING_STRETCH_SAME: int # Columns stretch equally
107
108
# Size constraint flags
109
TABLE_NO_HOST_EXTEND_X: int # Disable extending beyond outer_size.x
110
TABLE_NO_HOST_EXTEND_Y: int # Disable extending beyond outer_size.y
111
TABLE_NO_KEEP_COLUMNS_VISIBLE: int # Allow columns to be completely hidden
112
TABLE_PRECISE_WIDTHS: int # Disable distributing remainder width
113
114
# Clipping flags
115
TABLE_NO_CLIP: int # Disable clipping
116
117
# Padding flags
118
TABLE_PAD_OUTER_X: int # Enable outer padding
119
TABLE_NO_PAD_OUTER_X: int # Disable outer padding
120
TABLE_NO_PAD_INNER_X: int # Disable inner padding
121
122
# Scrolling flags
123
TABLE_SCROLL_X: int # Enable horizontal scrolling
124
TABLE_SCROLL_Y: int # Enable vertical scrolling
125
126
# Sorting flags
127
TABLE_SORT_MULTI: int # Enable multi-column sorting
128
TABLE_SORT_TRISTATE: int # Allow no sorting state
129
```
130
131
### Table Column Flags
132
133
Constants for controlling individual column behavior.
134
135
```python { .api }
136
# Basic column flags
137
TABLE_COLUMN_NONE: int
138
TABLE_COLUMN_DEFAULT_HIDE: int # Default as hidden column
139
TABLE_COLUMN_DEFAULT_SORT: int # Default as sorting column
140
TABLE_COLUMN_WIDTH_STRETCH: int # Column will stretch
141
TABLE_COLUMN_WIDTH_FIXED: int # Column has fixed width
142
TABLE_COLUMN_NO_RESIZE: int # Disable manual resizing
143
TABLE_COLUMN_NO_REORDER: int # Disable manual reordering
144
TABLE_COLUMN_NO_HIDE: int # Disable hiding
145
TABLE_COLUMN_NO_CLIP: int # Disable clipping for this column
146
TABLE_COLUMN_NO_SORT: int # Disable sorting on this column
147
TABLE_COLUMN_NO_SORT_ASCENDING: int # Disable ascending sort
148
TABLE_COLUMN_NO_SORT_DESCENDING: int # Disable descending sort
149
TABLE_COLUMN_NO_HEADER_WIDTH: int # Don't contribute to auto column width
150
TABLE_COLUMN_PREFER_SORT_ASCENDING: int # Prefer ascending sort
151
TABLE_COLUMN_PREFER_SORT_DESCENDING: int # Prefer descending sort
152
TABLE_COLUMN_INDENT_ENABLE: int # Use current indent
153
TABLE_COLUMN_INDENT_DISABLE: int # Ignore current indent
154
155
# Status flags (read-only)
156
TABLE_COLUMN_IS_ENABLED: int # Column is enabled
157
TABLE_COLUMN_IS_VISIBLE: int # Column is visible
158
TABLE_COLUMN_IS_SORTED: int # Column is sorted
159
TABLE_COLUMN_IS_HOVERED: int # Column is hovered
160
```
161
162
### Table Background Target
163
164
Constants for specifying background color targets.
165
166
```python { .api }
167
TABLE_BACKGROUND_TARGET_NONE: int
168
TABLE_BACKGROUND_TARGET_ROW_BG0: int # Row background color 0
169
TABLE_BACKGROUND_TARGET_ROW_BG1: int # Row background color 1
170
TABLE_BACKGROUND_TARGET_CELL_BG: int # Cell background color
171
```
172
173
### Table Row Flags
174
175
Constants for controlling table row behavior.
176
177
```python { .api }
178
TABLE_ROW_NONE: int
179
TABLE_ROW_HEADERS: int # Identify header row
180
```
181
182
## Usage Examples
183
184
### Basic Table
185
186
```python
187
import imgui
188
189
# Simple table with data
190
data = [
191
["Alice", 25, "Engineer"],
192
["Bob", 30, "Designer"],
193
["Charlie", 35, "Manager"],
194
]
195
196
if imgui.begin_table("Simple Table", 3):
197
# Setup columns
198
imgui.table_setup_column("Name")
199
imgui.table_setup_column("Age")
200
imgui.table_setup_column("Role")
201
imgui.table_headers_row()
202
203
# Add data rows
204
for row in data:
205
imgui.table_next_row()
206
for i, item in enumerate(row):
207
imgui.table_set_column_index(i)
208
imgui.text(str(item))
209
210
imgui.end_table()
211
```
212
213
### Advanced Table with Features
214
215
```python
216
# Table with borders, sorting, and resizing
217
table_flags = (imgui.TABLE_BORDERS | imgui.TABLE_RESIZABLE |
218
imgui.TABLE_SORTABLE | imgui.TABLE_ROW_BACKGROUND)
219
220
if imgui.begin_table("Advanced Table", 4, table_flags):
221
# Setup columns with specific properties
222
imgui.table_setup_column("ID", imgui.TABLE_COLUMN_WIDTH_FIXED, 50)
223
imgui.table_setup_column("Name", imgui.TABLE_COLUMN_DEFAULT_SORT)
224
imgui.table_setup_column("Score", imgui.TABLE_COLUMN_WIDTH_FIXED, 80)
225
imgui.table_setup_column("Actions", imgui.TABLE_COLUMN_NO_SORT, 100)
226
imgui.table_headers_row()
227
228
# Sample data
229
items = [
230
(1, "Alice", 95.5),
231
(2, "Bob", 87.2),
232
(3, "Charlie", 92.8),
233
(4, "Diana", 89.1),
234
]
235
236
for item_id, name, score in items:
237
imgui.table_next_row()
238
239
imgui.table_next_column()
240
imgui.text(str(item_id))
241
242
imgui.table_next_column()
243
imgui.text(name)
244
245
imgui.table_next_column()
246
imgui.text(f"{score:.1f}")
247
248
imgui.table_next_column()
249
if imgui.small_button(f"Edit##{item_id}"):
250
print(f"Edit {name}")
251
imgui.same_line()
252
if imgui.small_button(f"Delete##{item_id}"):
253
print(f"Delete {name}")
254
255
imgui.end_table()
256
```
257
258
### Scrolling Table
259
260
```python
261
# Large table with scrolling
262
if imgui.begin_table("Scrolling Table", 3,
263
imgui.TABLE_BORDERS | imgui.TABLE_SCROLL_Y,
264
0, 200): # Fixed height of 200 pixels
265
266
imgui.table_setup_column("Index")
267
imgui.table_setup_column("Value")
268
imgui.table_setup_column("Description")
269
imgui.table_headers_row()
270
271
# Generate many rows
272
for i in range(100):
273
imgui.table_next_row()
274
275
imgui.table_next_column()
276
imgui.text(str(i))
277
278
imgui.table_next_column()
279
imgui.text(f"Value {i}")
280
281
imgui.table_next_column()
282
imgui.text(f"Description for item {i}")
283
284
imgui.end_table()
285
```
286
287
### Table with Frozen Columns
288
289
```python
290
# Table with frozen first column and header
291
if imgui.begin_table("Frozen Table", 5,
292
imgui.TABLE_BORDERS | imgui.TABLE_SCROLL_X | imgui.TABLE_SCROLL_Y,
293
0, 200):
294
295
# Freeze first column and header row
296
imgui.table_setup_scroll_freeze(1, 1)
297
298
imgui.table_setup_column("Name", imgui.TABLE_COLUMN_WIDTH_FIXED, 100)
299
imgui.table_setup_column("Jan")
300
imgui.table_setup_column("Feb")
301
imgui.table_setup_column("Mar")
302
imgui.table_setup_column("Apr")
303
imgui.table_headers_row()
304
305
months_data = [
306
("Sales", [1200, 1350, 1180, 1420]),
307
("Marketing", [800, 920, 750, 1100]),
308
("Development", [2200, 2100, 2400, 2300]),
309
("Support", [600, 650, 580, 720]),
310
]
311
312
for department, values in months_data:
313
imgui.table_next_row()
314
315
imgui.table_next_column()
316
imgui.text(department)
317
318
for value in values:
319
imgui.table_next_column()
320
imgui.text(str(value))
321
322
imgui.end_table()
323
```
324
325
### Table with Custom Styling
326
327
```python
328
# Table with custom colors and styling
329
if imgui.begin_table("Styled Table", 3, imgui.TABLE_BORDERS):
330
imgui.table_setup_column("Status")
331
imgui.table_setup_column("Task")
332
imgui.table_setup_column("Progress")
333
imgui.table_headers_row()
334
335
tasks = [
336
("Complete", "Design UI", 100),
337
("In Progress", "Implement Backend", 75),
338
("Pending", "Write Tests", 0),
339
]
340
341
for status, task, progress in tasks:
342
imgui.table_next_row()
343
344
# Color-code status column
345
imgui.table_next_column()
346
if status == "Complete":
347
imgui.table_set_background_color(imgui.TABLE_BACKGROUND_TARGET_CELL_BG,
348
imgui.get_color_u32_rgba(0.2, 0.8, 0.2, 0.3))
349
elif status == "In Progress":
350
imgui.table_set_background_color(imgui.TABLE_BACKGROUND_TARGET_CELL_BG,
351
imgui.get_color_u32_rgba(0.8, 0.8, 0.2, 0.3))
352
else:
353
imgui.table_set_background_color(imgui.TABLE_BACKGROUND_TARGET_CELL_BG,
354
imgui.get_color_u32_rgba(0.8, 0.2, 0.2, 0.3))
355
imgui.text(status)
356
357
imgui.table_next_column()
358
imgui.text(task)
359
360
imgui.table_next_column()
361
imgui.progress_bar(progress / 100.0, (-1, 0), f"{progress}%")
362
363
imgui.end_table()
364
```
365
366
### Sortable Table
367
368
```python
369
# Table with sorting capabilities
370
if imgui.begin_table("Sortable Table", 3,
371
imgui.TABLE_BORDERS | imgui.TABLE_SORTABLE):
372
373
imgui.table_setup_column("Name", imgui.TABLE_COLUMN_DEFAULT_SORT)
374
imgui.table_setup_column("Score")
375
imgui.table_setup_column("Rank")
376
imgui.table_headers_row()
377
378
# Check if sorting is needed
379
sort_specs = imgui.table_get_sort_specs()
380
if sort_specs and sort_specs.specs_dirty:
381
# Sort your data based on sort_specs
382
print("Table needs sorting")
383
# In a real application, you would sort your data here
384
385
# Add table data (would be sorted in real application)
386
players = [
387
("Alice", 95, 1),
388
("Bob", 87, 3),
389
("Charlie", 92, 2),
390
]
391
392
for name, score, rank in players:
393
imgui.table_next_row()
394
imgui.table_next_column()
395
imgui.text(name)
396
imgui.table_next_column()
397
imgui.text(str(score))
398
imgui.table_next_column()
399
imgui.text(str(rank))
400
401
imgui.end_table()
402
```