0
# Widget System
1

2
Comprehensive collection of interactive UI elements including buttons, text inputs, sliders, checkboxes, combo boxes, color pickers, and more. These widgets handle user input and return their current state, forming the core interactive elements of ImGui applications.
3

4
## Capabilities
5

6
### Text Display Widgets
7

8
Functions for displaying various types of text content with different formatting and behavior.
9

10
```python { .api }
11
def text(text: str) -> None:
12
    """Display regular text."""
13

14
def text_colored(text: str, r: float, g: float, b: float, a: float = 1.0) -> None:
15
    """Display colored text."""
16

17
def text_disabled(text: str) -> None:
18
    """Display disabled (grayed out) text."""
19

20
def text_wrapped(text: str) -> None:
21
    """Display text with word wrapping."""
22

23
def text_unformatted(text: str) -> None:
24
    """Display large amounts of text efficiently."""
25

26
def label_text(label: str, text: str) -> None:
27
    """Display text with a label prefix."""
28

29
def bullet_text(text: str) -> None:
30
    """Display text with a bullet point."""
31

32
def bullet() -> None:
33
    """Display a bullet point and keep cursor on same line."""
34
```
35

36
### Button Widgets
37

38
Various types of clickable button widgets for user interaction.
39

40
```python { .api }
41
def button(label: str, width: float = 0, height: float = 0) -> bool:
42
    """Regular button. Returns True when clicked."""
43

44
def small_button(label: str) -> bool:
45
    """Small button with minimal padding. Returns True when clicked."""
46

47
def arrow_button(label: str, direction: int) -> bool:
48
    """Square button with arrow. Returns True when clicked."""
49

50
def invisible_button(identifier: str, width: float, height: float, flags: int = 0) -> bool:
51
    """Invisible button for custom drawing areas. Returns True when clicked."""
52

53
def color_button(desc_id: str, r: float, g: float, b: float, a: float = 1.0, flags: int = 0, width: float = 0, height: float = 0) -> bool:
54
    """Color square button. Returns True when clicked."""
55

56
def image_button(texture_id: int, width: float, height: float, uv0: tuple = (0,0), uv1: tuple = (1,1), bg_color: tuple = (0,0,0,0), tint_color: tuple = (1,1,1,1)) -> bool:
57
    """Image button. Returns True when clicked."""
58
```
59

60
### Selection Widgets
61

62
Widgets for selecting options, including checkboxes, radio buttons, and selection lists.
63

64
```python { .api }
65
def checkbox(label: str, state: bool) -> tuple[bool, bool]:
66
    """Checkbox widget. Returns (changed, current_state)."""
67

68
def checkbox_flags(label: str, flags: int, flags_value: int) -> tuple[bool, int]:
69
    """Checkbox for integer flags. Returns (changed, new_flags)."""
70

71
def radio_button(label: str, active: bool) -> bool:
72
    """Radio button. Returns True when clicked."""
73

74
def selectable(label: str, selected: bool = False, flags: int = 0, width: float = 0, height: float = 0) -> tuple[bool, bool]:
75
    """Selectable item. Returns (clicked, selected_state)."""
76

77
def listbox(label: str, current: int, items: list[str], height_in_items: int = -1) -> tuple[bool, int]:
78
    """Simple listbox. Returns (changed, selected_index)."""
79

80
def begin_list_box(label: str, width: float = 0, height: float = 0) -> bool:
81
    """Begin manual listbox. Returns True if listbox is open."""
82

83
def end_list_box() -> None:
84
    """End manual listbox."""
85
```
86

87
### Text Input Widgets
88

89
Widgets for text entry and editing with various input modes and validation.
90

91
```python { .api }
92
def input_text(label: str, value: str, buffer_length: int, flags: int = 0) -> tuple[bool, str]:
93
    """Single-line text input. Returns (changed, new_text)."""
94

95
def input_text_multiline(label: str, value: str, buffer_length: int, width: float = 0, height: float = 0, flags: int = 0) -> tuple[bool, str]:
96
    """Multi-line text input. Returns (changed, new_text)."""
97

98
def input_text_with_hint(label: str, hint: str, value: str, buffer_length: int, flags: int = 0) -> tuple[bool, str]:
99
    """Text input with placeholder hint. Returns (changed, new_text)."""
100
```
101

102
### Numeric Input Widgets
103

104
Widgets for entering and editing numeric values with validation and formatting.
105

106
```python { .api }
107
def input_float(label: str, value: float, step: float = 0.0, step_fast: float = 0.0, format: str = "%.3f", flags: int = 0) -> tuple[bool, float]:
108
    """Float input field. Returns (changed, new_value)."""
109

110
def input_float2(label: str, values: tuple[float, float], format: str = "%.3f", flags: int = 0) -> tuple[bool, tuple[float, float]]:
111
    """2-component float input. Returns (changed, (x, y))."""
112

113
def input_float3(label: str, values: tuple[float, float, float], format: str = "%.3f", flags: int = 0) -> tuple[bool, tuple[float, float, float]]:
114
    """3-component float input. Returns (changed, (x, y, z))."""
115

116
def input_float4(label: str, values: tuple[float, float, float, float], format: str = "%.3f", flags: int = 0) -> tuple[bool, tuple[float, float, float, float]]:
117
    """4-component float input. Returns (changed, (x, y, z, w))."""
118

119
def input_int(label: str, value: int, step: int = 1, step_fast: int = 100, flags: int = 0) -> tuple[bool, int]:
120
    """Integer input field. Returns (changed, new_value)."""
121

122
def input_int2(label: str, values: tuple[int, int], flags: int = 0) -> tuple[bool, tuple[int, int]]:
123
    """2-component integer input. Returns (changed, (x, y))."""
124

125
def input_int3(label: str, values: tuple[int, int, int], flags: int = 0) -> tuple[bool, tuple[int, int, int]]:
126
    """3-component integer input. Returns (changed, (x, y, z))."""
127

128
def input_int4(label: str, values: tuple[int, int, int, int], flags: int = 0) -> tuple[bool, tuple[int, int, int, int]]:
129
    """4-component integer input. Returns (changed, (x, y, z, w))."""
130

131
def input_double(label: str, value: float, step: float = 0.0, step_fast: float = 0.0, format: str = "%.6f", flags: int = 0) -> tuple[bool, float]:
132
    """Double precision input field. Returns (changed, new_value)."""
133
```
134

135
### Slider Widgets
136

137
Interactive slider controls for numeric value selection within specified ranges.
138

139
```python { .api }
140
def slider_float(label: str, value: float, v_min: float, v_max: float, format: str = "%.3f", flags: int = 0) -> tuple[bool, float]:
141
    """Float slider. Returns (changed, new_value)."""
142

143
def slider_float2(label: str, values: tuple[float, float], v_min: float, v_max: float, format: str = "%.3f", flags: int = 0) -> tuple[bool, tuple[float, float]]:
144
    """2-component float slider. Returns (changed, (x, y))."""
145

146
def slider_float3(label: str, values: tuple[float, float, float], v_min: float, v_max: float, format: str = "%.3f", flags: int = 0) -> tuple[bool, tuple[float, float, float]]:
147
    """3-component float slider. Returns (changed, (x, y, z))."""
148

149
def slider_float4(label: str, values: tuple[float, float, float, float], v_min: float, v_max: float, format: str = "%.3f", flags: int = 0) -> tuple[bool, tuple[float, float, float, float]]:
150
    """4-component float slider. Returns (changed, (x, y, z, w))."""
151

152
def slider_int(label: str, value: int, v_min: int, v_max: int, format: str = "%d", flags: int = 0) -> tuple[bool, int]:
153
    """Integer slider. Returns (changed, new_value)."""
154

155
def slider_int2(label: str, values: tuple[int, int], v_min: int, v_max: int, format: str = "%d", flags: int = 0) -> tuple[bool, tuple[int, int]]:
156
    """2-component integer slider. Returns (changed, (x, y))."""
157

158
def slider_int3(label: str, values: tuple[int, int, int], v_min: int, v_max: int, format: str = "%d", flags: int = 0) -> tuple[bool, tuple[int, int, int]]:
159
    """3-component integer slider. Returns (changed, (x, y, z))."""
160

161
def slider_int4(label: str, values: tuple[int, int, int, int], v_min: int, v_max: int, format: str = "%d", flags: int = 0) -> tuple[bool, tuple[int, int, int, int]]:
162
    """4-component integer slider. Returns (changed, (x, y, z, w))."""
163

164
def slider_angle(label: str, v_rad: float, v_degrees_min: float = -360.0, v_degrees_max: float = 360.0, format: str = "%.0f deg", flags: int = 0) -> tuple[bool, float]:
165
    """Angle slider in radians. Returns (changed, new_value)."""
166

167
def v_slider_float(label: str, width: float, height: float, value: float, v_min: float, v_max: float, format: str = "%.3f", flags: int = 0) -> tuple[bool, float]:
168
    """Vertical float slider. Returns (changed, new_value)."""
169

170
def v_slider_int(label: str, width: float, height: float, value: int, v_min: int, v_max: int, format: str = "%d", flags: int = 0) -> tuple[bool, int]:
171
    """Vertical integer slider. Returns (changed, new_value)."""
172
```
173

174
### Drag Widgets
175

176
Drag controls for fine-tuned numeric value adjustment with mouse movement.
177

178
```python { .api }
179
def drag_float(label: str, value: float, v_speed: float = 1.0, v_min: float = 0.0, v_max: float = 0.0, format: str = "%.3f", flags: int = 0) -> tuple[bool, float]:
180
    """Float drag control. Returns (changed, new_value)."""
181

182
def drag_float2(label: str, values: tuple[float, float], v_speed: float = 1.0, v_min: float = 0.0, v_max: float = 0.0, format: str = "%.3f", flags: int = 0) -> tuple[bool, tuple[float, float]]:
183
    """2-component float drag. Returns (changed, (x, y))."""
184

185
def drag_float3(label: str, values: tuple[float, float, float], v_speed: float = 1.0, v_min: float = 0.0, v_max: float = 0.0, format: str = "%.3f", flags: int = 0) -> tuple[bool, tuple[float, float, float]]:
186
    """3-component float drag. Returns (changed, (x, y, z))."""
187

188
def drag_float4(label: str, values: tuple[float, float, float, float], v_speed: float = 1.0, v_min: float = 0.0, v_max: float = 0.0, format: str = "%.3f", flags: int = 0) -> tuple[bool, tuple[float, float, float, float]]:
189
    """4-component float drag. Returns (changed, (x, y, z, w))."""
190

191
def drag_int(label: str, value: int, v_speed: float = 1.0, v_min: int = 0, v_max: int = 0, format: str = "%d", flags: int = 0) -> tuple[bool, int]:
192
    """Integer drag control. Returns (changed, new_value)."""
193

194
def drag_int2(label: str, values: tuple[int, int], v_speed: float = 1.0, v_min: int = 0, v_max: int = 0, format: str = "%d", flags: int = 0) -> tuple[bool, tuple[int, int]]:
195
    """2-component integer drag. Returns (changed, (x, y))."""
196

197
def drag_int3(label: str, values: tuple[int, int, int], v_speed: float = 1.0, v_min: int = 0, v_max: int = 0, format: str = "%d", flags: int = 0) -> tuple[bool, tuple[int, int, int]]:
198
    """3-component integer drag. Returns (changed, (x, y, z))."""
199

200
def drag_int4(label: str, values: tuple[int, int, int, int], v_speed: float = 1.0, v_min: int = 0, v_max: int = 0, format: str = "%d", flags: int = 0) -> tuple[bool, tuple[int, int, int, int]]:
201
    """4-component integer drag. Returns (changed, (x, y, z, w))."""
202

203
def drag_float_range2(label: str, v_current_min: float, v_current_max: float, v_speed: float = 1.0, v_min: float = 0.0, v_max: float = 0.0, format: str = "%.3f", format_max: str = None, flags: int = 0) -> tuple[bool, float, float]:
204
    """Float range drag control. Returns (changed, new_min, new_max)."""
205

206
def drag_int_range2(label: str, v_current_min: int, v_current_max: int, v_speed: float = 1.0, v_min: int = 0, v_max: int = 0, format: str = "%d", format_max: str = None, flags: int = 0) -> tuple[bool, int, int]:
207
    """Integer range drag control. Returns (changed, new_min, new_max)."""
208
```
209

210
### Color Widgets
211

212
Color selection and editing widgets with various display modes and formats.
213

214
```python { .api }
215
def color_edit3(label: str, r: float, g: float, b: float, flags: int = 0) -> tuple[bool, float, float, float]:
216
    """RGB color editor. Returns (changed, r, g, b)."""
217

218
def color_edit4(label: str, r: float, g: float, b: float, a: float, flags: int = 0) -> tuple[bool, float, float, float, float]:
219
    """RGBA color editor. Returns (changed, r, g, b, a)."""
220
```
221

222
### Combo Box Widgets
223

224
Dropdown selection widgets for choosing from predefined options.
225

226
```python { .api }
227
def combo(label: str, current: int, items: list[str], height_in_items: int = -1) -> tuple[bool, int]:
228
    """Simple combo box. Returns (changed, selected_index)."""
229

230
def begin_combo(label: str, preview_value: str, flags: int = 0) -> bool:
231
    """Begin manual combo box. Returns True if combo is open."""
232

233
def end_combo() -> None:
234
    """End manual combo box."""
235
```
236

237
### Tree and Hierarchy Widgets
238

239
Widgets for displaying hierarchical data and collapsible content sections.
240

241
```python { .api }
242
def tree_node(text: str, flags: int = 0) -> bool:
243
    """Tree node widget. Returns True if open."""
244

245
def tree_pop() -> None:
246
    """Pop tree node from stack."""
247

248
def collapsing_header(text: str, visible: bool = None, flags: int = 0) -> tuple[bool, bool]:
249
    """Collapsing header widget. Returns (open, visible)."""
250

251
def set_next_item_open(is_open: bool, condition: int = 0) -> None:
252
    """Set next tree node open state."""
253

254
def get_tree_node_to_label_spacing() -> float:
255
    """Get spacing between tree node and label."""
256
```
257

258
### Plot Widgets
259

260
Simple plotting widgets for displaying data visualizations.
261

262
```python { .api }
263
def plot_lines(label: str, values: list[float], values_count: int = 0, values_offset: int = 0, overlay_text: str = "", scale_min: float = None, scale_max: float = None, graph_width: float = 0, graph_height: float = 0) -> None:
264
    """Plot lines graph."""
265

266
def plot_histogram(label: str, values: list[float], values_count: int = 0, values_offset: int = 0, overlay_text: str = "", scale_min: float = None, scale_max: float = None, graph_width: float = 0, graph_height: float = 0) -> None:
267
    """Plot histogram."""
268
```
269

270
### Other Widgets
271

272
Miscellaneous widgets for specialized functionality.
273

274
```python { .api }
275
def image(texture_id: int, width: float, height: float, uv0: tuple = (0,0), uv1: tuple = (1,1), tint_color: tuple = (1,1,1,1), border_color: tuple = (0,0,0,0)) -> None:
276
    """Display image."""
277

278
def progress_bar(fraction: float, size: tuple = (-1, 0), overlay: str = "") -> None:
279
    """Progress bar widget."""
280

281
def set_tooltip(text: str) -> None:
282
    """Set tooltip text for last item."""
283

284
def begin_tooltip() -> bool:
285
    """Begin custom tooltip window."""
286

287
def end_tooltip() -> None:
288
    """End custom tooltip window."""
289
```
290

291
## Usage Examples
292

293
### Basic Widgets
294

295
```python
296
import imgui
297

298
# Text display
299
imgui.text("Regular text")
300
imgui.text_colored("Colored text", 1.0, 0.0, 0.0)  # Red
301
imgui.text_disabled("Disabled text")
302

303
# Buttons
304
if imgui.button("Click Me"):
305
    print("Button clicked!")
306

307
if imgui.small_button("Small"):
308
    print("Small button clicked!")
309

310
# Checkbox
311
checkbox_state = True
312
changed, checkbox_state = imgui.checkbox("Enable option", checkbox_state)
313
if changed:
314
    print(f"Checkbox now: {checkbox_state}")
315
```
316

317
### Input Widgets
318

319
```python
320
# Text input
321
text_buffer = "Hello World"
322
changed, text_buffer = imgui.input_text("Text", text_buffer, 256)
323

324
# Numeric inputs
325
float_value = 3.14
326
changed, float_value = imgui.input_float("Float", float_value)
327

328
int_value = 42
329
changed, int_value = imgui.input_int("Integer", int_value)
330

331
# Multi-component inputs
332
vec3 = (1.0, 2.0, 3.0)
333
changed, vec3 = imgui.input_float3("Vector3", vec3)
334
```
335

336
### Sliders and Drags
337

338
```python
339
# Sliders
340
slider_value = 0.5
341
changed, slider_value = imgui.slider_float("Slider", slider_value, 0.0, 1.0)
342

343
# Drag controls
344
drag_value = 10.0
345
changed, drag_value = imgui.drag_float("Drag", drag_value, 0.1, 0.0, 100.0)
346

347
# Range controls
348
min_val, max_val = 10.0, 90.0
349
changed, min_val, max_val = imgui.drag_float_range2("Range", min_val, max_val, 1.0, 0.0, 100.0)
350
```
351

352
### Selection Widgets
353

354
```python
355
# Combo box
356
current_item = 0
357
items = ["Item 1", "Item 2", "Item 3"]
358
changed, current_item = imgui.combo("Combo", current_item, items)
359

360
# Listbox
361
listbox_item = 0
362
changed, listbox_item = imgui.listbox("List", listbox_item, items)
363

364
# Selectable items
365
selected = False
366
clicked, selected = imgui.selectable("Selectable item", selected)
367
```
368

369
### Color Editing
370

371
```python
372
# RGB color
373
color_rgb = (1.0, 0.5, 0.2)
374
changed, *color_rgb = imgui.color_edit3("RGB Color", *color_rgb)
375

376
# RGBA color with alpha
377
color_rgba = (1.0, 0.5, 0.2, 0.8)
378
changed, *color_rgba = imgui.color_edit4("RGBA Color", *color_rgba)
379
```
380

381
### Tree Hierarchy
382

383
```python
384
# Simple tree node
385
if imgui.tree_node("Tree Node"):
386
    imgui.text("Content inside tree node")
387
    imgui.tree_pop()
388

389
# Collapsing header
390
opened, visible = imgui.collapsing_header("Collapsing Header")
391
if opened:
392
    imgui.text("Content inside collapsing header")
393
```