python-cui 1.4.0.6__cp314-cp314-win_amd64.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
cui/ui.py ADDED
@@ -0,0 +1,606 @@
1
+ """The friendly, Pythonic facade over CUI's immediate-mode API.
2
+
3
+ with ui.column(pad=24, gap=12):
4
+ ui.heading("Settings", level=2)
5
+ notify = ui.switch("Notifications", value=notify)
6
+ name = ui.text_input("name", value=name, label="Name").text
7
+
8
+ Every method maps onto one CUI component. Containers are context managers, so
9
+ the C ``begin``/``end`` pair cannot get out of balance, even when the body
10
+ raises. Components whose C form returns the new state of a value return that
11
+ value directly: a switch returns a bool, a slider a float, a select an index.
12
+
13
+ The lower-level surface — one function per CUI function, option structs as
14
+ keyword arguments — is still reachable as ``ui.api`` or by importing
15
+ ``cui._api``.
16
+ """
17
+
18
+ from __future__ import annotations
19
+
20
+ from typing import Any, Callable, Iterable, Sequence
21
+
22
+ from . import _api
23
+ from ._cui import Context
24
+ from ._gen.constants import Token
25
+ from ._types import Color, Date, Rect, Size, TextResult
26
+
27
+ _FOREGROUND = Color.token(Token.FOREGROUND)
28
+
29
+
30
+ class _Block:
31
+ """A container opened by a ``with`` statement."""
32
+
33
+ def __init__(self, ui: "UI", begin: Callable[[], Any], end: Callable[[], Any]):
34
+ self._ui = ui
35
+ self._begin = begin
36
+ self._end = end
37
+ self.result: Any = None
38
+
39
+ def __enter__(self) -> "_Block":
40
+ self.result = self._begin()
41
+ return self
42
+
43
+ def __exit__(self, exc_type, exc, tb) -> bool:
44
+ self._end()
45
+ return False
46
+
47
+ def __getattr__(self, name: str) -> Any:
48
+ return getattr(self._ui, name)
49
+
50
+
51
+ class _Card(_Block):
52
+ """A card; ``clicked`` is available once the block has closed."""
53
+
54
+ @property
55
+ def clicked(self) -> bool:
56
+ return bool(self.result)
57
+
58
+ def __enter__(self) -> "_Card":
59
+ self.result = self._begin()
60
+ return self
61
+
62
+
63
+ class _Scope:
64
+ """An identity or disabled scope: ``with ui.id('row3'):``."""
65
+
66
+ def __init__(self, push: Callable[[], Any], pop: Callable[[], Any]):
67
+ self._push = push
68
+ self._pop = pop
69
+
70
+ def __enter__(self) -> "_Scope":
71
+ self._push()
72
+ return self
73
+
74
+ def __exit__(self, exc_type, exc, tb) -> bool:
75
+ self._pop()
76
+ return False
77
+
78
+
79
+ class _Split(_Block):
80
+ """A resizable split view; call :meth:`next` before the second pane."""
81
+
82
+ @property
83
+ def ratio(self) -> float:
84
+ """The split ratio after the user dragged the divider."""
85
+ return float(self.result) if self.result is not None else 0.0
86
+
87
+ def next(self) -> None:
88
+ self._ui.context.split_next()
89
+
90
+ def __exit__(self, exc_type, exc, tb) -> bool:
91
+ self.result = self._ui.context.split_end()
92
+ return False
93
+
94
+
95
+ class _Table(_Block):
96
+ """A table; ``row()`` starts a row, then use ``cell()`` / ``cell_text()``."""
97
+
98
+ def row(self, selected: bool = False) -> bool:
99
+ return _api.table_row(self._ui.context, selected)
100
+
101
+ def cell(self) -> None:
102
+ _api.table_cell(self._ui.context)
103
+
104
+ def cell_text(self, text: str) -> None:
105
+ _api.table_cell_text(self._ui.context, text)
106
+
107
+
108
+ class _Clip:
109
+ """A clip rectangle for custom painting: ``with ui.clip(rect):``."""
110
+
111
+ def __init__(self, context: Context, rect: Rect):
112
+ self._context = context
113
+ self._rect = rect
114
+
115
+ def __enter__(self) -> "_Clip":
116
+ _api.push_clip(self._context, self._rect)
117
+ return self
118
+
119
+ def __exit__(self, exc_type, exc, tb) -> bool:
120
+ _api.pop_clip(self._context)
121
+ return False
122
+
123
+
124
+ class UI:
125
+ """The component API, bound to one :class:`cui.Context`."""
126
+
127
+ __slots__ = ("_ctx",)
128
+
129
+ def __init__(self, context: Context):
130
+ self._ctx = context
131
+
132
+ def __repr__(self):
133
+ return f"<cui.UI {self._ctx!r}>"
134
+
135
+ # -- escape hatches ----------------------------------------------------
136
+
137
+ @property
138
+ def context(self) -> Context:
139
+ """The underlying :class:`cui.Context` (frame control, ids, rendering)."""
140
+ return self._ctx
141
+
142
+ @property
143
+ def api(self):
144
+ """The generated low-level module, for components without a facade yet."""
145
+ return _api
146
+
147
+ def __getattr__(self, name: str):
148
+ # Fall back to the generated wrapper layer so every CUI function is
149
+ # reachable as ui.<name>(...) without needing a facade method.
150
+ function = getattr(_api, name, None)
151
+ if function is None or name.startswith("_"):
152
+ raise AttributeError(name)
153
+ import functools
154
+
155
+ return functools.partial(function, self._ctx)
156
+
157
+ # -- containers --------------------------------------------------------
158
+
159
+ def column(self, **opts) -> _Block:
160
+ """A vertical box (CUI's default direction)."""
161
+ return _Block(self, lambda: _api.column_begin(self._ctx, **opts), lambda: _api.box_end(self._ctx))
162
+
163
+ def row(self, **opts) -> _Block:
164
+ """A horizontal box; ``gap`` and ``align`` do most of the work."""
165
+ return _Block(self, lambda: _api.row_begin(self._ctx, **opts), lambda: _api.box_end(self._ctx))
166
+
167
+ def box(self, dir: int | None = None, **opts) -> _Block:
168
+ """Any box: pick the direction with ``dir=Dir.ROW`` or ``Dir.GRID``."""
169
+ if dir is None:
170
+ return _Block(self, lambda: _api.box_begin(self._ctx, **opts), lambda: _api.box_end(self._ctx))
171
+ return _Block(
172
+ self,
173
+ lambda: _api.box_begin(self._ctx, dir=dir, **opts),
174
+ lambda: _api.box_end(self._ctx),
175
+ )
176
+
177
+ def grid(self, columns: int = 2, **opts) -> _Block:
178
+ """A grid with a fixed column count."""
179
+ from ._gen.constants import Dir
180
+
181
+ return _Block(
182
+ self,
183
+ lambda: _api.box_begin(self._ctx, dir=Dir.GRID, columns=columns, **opts),
184
+ lambda: _api.box_end(self._ctx),
185
+ )
186
+
187
+ def card(self, **opts) -> _Card:
188
+ """A bordered surface. ``with ui.card() as card:`` then ``card.clicked``."""
189
+ return _Card(self, lambda: _api.card_begin(self._ctx, **opts), lambda: _api.card_end(self._ctx))
190
+
191
+ def scroll(self, **opts) -> _Block:
192
+ """A scroll area with smooth scrolling and overlay scrollbars."""
193
+ return _Block(self, lambda: _api.scroll_begin(self._ctx, **opts), lambda: _api.scroll_end(self._ctx))
194
+
195
+ def split(self, id: str, ratio: float = 0.0, **opts) -> _Split:
196
+ """A resizable split view; call ``split.next()`` between the two panes."""
197
+ return _Split(
198
+ self,
199
+ lambda: self._ctx.split_begin(id, ratio, **opts),
200
+ lambda: self._ctx.split_end(),
201
+ )
202
+
203
+ def table(self, id: str, columns, **opts) -> _Table:
204
+ """A table; ``with ui.table(...) as table:`` then ``table.row()``."""
205
+ return _Table(
206
+ self,
207
+ lambda: _api.table_begin(self._ctx, id, columns, **opts),
208
+ lambda: _api.table_end(self._ctx),
209
+ )
210
+
211
+ def context_menu(self, id: str, *, body: Callable[["UI"], None]) -> bool:
212
+ """A right-click menu anchored to the previous component."""
213
+ visible = _api.context_menu_begin(self._ctx, id)
214
+ if visible:
215
+ body(self)
216
+ _api.context_menu_end(self._ctx)
217
+ return bool(visible)
218
+
219
+ def toolbar(self, id: str, **opts) -> _Block:
220
+ return _Block(self, lambda: _api.toolbar_begin(self._ctx, id, **opts), lambda: _api.toolbar_end(self._ctx))
221
+
222
+ def id(self, value: str | int) -> _Scope:
223
+ """Scope the identity of the widgets inside, like CUI's ``push_id``."""
224
+ return _Scope(lambda: self._ctx.push_id(value), self._ctx.pop_id)
225
+
226
+ def disabled(self, disabled: bool = True) -> _Scope:
227
+ """Draw the components inside in their disabled state."""
228
+ return _Scope(lambda: self._ctx.push_disabled(disabled), self._ctx.pop_disabled)
229
+
230
+ # -- text --------------------------------------------------------------
231
+
232
+ def text(self, text: str, **opts) -> None:
233
+ _api.text(self._ctx, text, **opts)
234
+
235
+ def heading(self, text: str, level: int = 1) -> None:
236
+ _api.heading(self._ctx, text, level)
237
+
238
+ def label(self, text: str, **opts) -> None:
239
+ # `label` has no options of its own in CUI; text_opts still apply.
240
+ _api.text(self._ctx, text, **opts)
241
+
242
+ def secondary(self, text: str) -> None:
243
+ _api.secondary(self._ctx, text)
244
+
245
+ def muted(self, text: str) -> None:
246
+ _api.muted(self._ctx, text)
247
+
248
+ def code(self, text: str) -> None:
249
+ _api.code(self._ctx, text)
250
+
251
+ def kbd(self, keys: str) -> None:
252
+ _api.kbd(self._ctx, keys)
253
+
254
+ def link(self, text: str) -> bool:
255
+ return _api.link(self._ctx, text)
256
+
257
+ def icon(self, icon: str, size: float = 16.0, color: Color | None = None) -> None:
258
+ _api.icon(self._ctx, icon, size, color)
259
+
260
+ def separator(self) -> None:
261
+ _api.separator(self._ctx)
262
+
263
+ def spacer(self) -> None:
264
+ _api.spacer(self._ctx)
265
+
266
+ def gap(self, size: float) -> None:
267
+ _api.gap(self._ctx, size)
268
+
269
+ # -- buttons -----------------------------------------------------------
270
+
271
+ def button(
272
+ self,
273
+ label: str,
274
+ *,
275
+ variant: int | None = None,
276
+ icon: str | None = None,
277
+ disabled: bool = False,
278
+ **opts,
279
+ ) -> bool:
280
+ """A button; true on the frame it is clicked."""
281
+ return _api.button(
282
+ self._ctx, label, variant=variant, icon=icon, disabled=disabled, **opts
283
+ )
284
+
285
+ def icon_button(
286
+ self,
287
+ icon: str,
288
+ *,
289
+ variant: int | None = None,
290
+ disabled: bool = False,
291
+ **opts,
292
+ ) -> bool:
293
+ """A square button with only an icon (give it a tooltip in ``opts``)."""
294
+ return _api.icon_button(self._ctx, icon, variant=variant, disabled=disabled, **opts)
295
+
296
+ def link_button(self, label: str, **opts) -> bool:
297
+ return _api.button(self._ctx, label, variant=6, **opts)
298
+
299
+ # -- selection ---------------------------------------------------------
300
+
301
+ def checkbox(self, label: str, value: bool = False, **opts) -> bool:
302
+ """A checkbox; returns the new value."""
303
+ return _api.checkbox(self._ctx, label, value=value, **opts)[1]
304
+
305
+ def switch(self, label: str, value: bool = False, **opts) -> bool:
306
+ """A switch; returns the new value."""
307
+ return _api.switch(self._ctx, label, value=value, **opts)[1]
308
+
309
+ def radio(self, label: str, value: int, option: int, **opts) -> int:
310
+ """One radio button; returns the selected index."""
311
+ return _api.radio(self._ctx, label, option, value=value, **opts)[1]
312
+
313
+ def radio_group(self, id: str, items: Sequence[str], index: int = 0) -> int:
314
+ return _api.radio_group(self._ctx, id, items, index=index)[1]
315
+
316
+ def slider(
317
+ self,
318
+ label: str,
319
+ value: float = 0.0,
320
+ minimum: float = 0.0,
321
+ maximum: float = 100.0,
322
+ **opts,
323
+ ) -> float:
324
+ """A slider; returns the new value."""
325
+ return _api.slider(self._ctx, label, minimum, maximum, value=value, **opts)[1]
326
+
327
+ def range_slider(
328
+ self,
329
+ label: str,
330
+ lo: float,
331
+ hi: float,
332
+ minimum: float = 0.0,
333
+ maximum: float = 100.0,
334
+ ) -> tuple[float, float]:
335
+ changed, low, high = _api.range_slider(self._ctx, label, lo, hi, minimum, maximum)
336
+ return (low, high)
337
+
338
+ def rating(self, id: str, max: int = 5, value: int = 0) -> int:
339
+ return _api.rating(self._ctx, id, max, value=value)[1]
340
+
341
+ def segmented(self, id: str, items: Sequence[str], index: int = 0, **opts) -> int:
342
+ return _api.segmented(self._ctx, id, items, index=index, **opts)[1]
343
+
344
+ def chip(self, label: str, selected: bool = False, **opts) -> bool:
345
+ return _api.chip(self._ctx, label, selected=selected, **opts)[1]
346
+
347
+ def toggle_group(self, id: str, labels: Sequence[str], values=False, **opts):
348
+ """A row of toggles; returns the new values (a bool or a list)."""
349
+ return _api.toggle_group(self._ctx, id, labels, values=values, **opts)[1]
350
+
351
+ # -- text input --------------------------------------------------------
352
+
353
+ def text_input(self, id: str, value: str = "", **opts) -> TextResult:
354
+ """Single-line text field; the result carries the edited text and flags."""
355
+ return _api.input(self._ctx, id, text=value, **opts)
356
+
357
+ # `input` is CUI's name for the same component.
358
+ input_text = text_input
359
+
360
+ def textarea(self, id: str, value: str = "", **opts) -> TextResult:
361
+ return _api.textarea(self._ctx, id, text=value, **opts)
362
+
363
+ def search(self, id: str, value: str = "", **opts) -> TextResult:
364
+ return _api.search(self._ctx, id, text=value, **opts)
365
+
366
+ def tag_input(self, id: str, value: str = "", **opts) -> TextResult:
367
+ return _api.tag_input(self._ctx, id, text=value, **opts)
368
+
369
+ def number(
370
+ self,
371
+ id: str,
372
+ value: float = 0.0,
373
+ minimum: float = 0.0,
374
+ maximum: float = 100.0,
375
+ **opts,
376
+ ) -> float:
377
+ return _api.number(self._ctx, id, minimum, maximum, value=value, **opts)[1]
378
+
379
+ def money_input(self, id: str, value: float = 0.0, **opts) -> float:
380
+ return _api.money_input(self._ctx, id, value=value, **opts)[1]
381
+
382
+ def inline_edit(self, id: str, value: str = "", **opts) -> TextResult:
383
+ return _api.inline_edit(self._ctx, id, text=value, **opts)
384
+
385
+ # -- pickers -----------------------------------------------------------
386
+
387
+ def select(self, id: str, items: Sequence[str], index: int = 0, **opts) -> int:
388
+ """A select/dropdown; returns the selected index."""
389
+ return _api.select(self._ctx, id, items, index=index, **opts)[1]
390
+
391
+ def multi_select(self, id: str, items: Sequence[str], selected=False, **opts):
392
+ return _api.multi_select(self._ctx, id, items, selected=selected, **opts)[1]
393
+
394
+ def tabs(self, id: str, items: Sequence[str], index: int = 0, **opts) -> int:
395
+ """Tab strip; returns the selected index."""
396
+ return _api.tabs(self._ctx, id, items, index=index, **opts)[1]
397
+
398
+ def date_picker(self, id: str, value: Date | None = None, **opts) -> Date:
399
+ return _api.date_picker(self._ctx, id, value=value, **opts)[1]
400
+
401
+ def calendar(self, id: str, value: Date | None = None) -> Date:
402
+ return _api.calendar(self._ctx, id, value=value)[1]
403
+
404
+ def color_picker(self, id: str, value: Color | None = None) -> Color:
405
+ return _api.color_picker(self._ctx, id, value=value)[1]
406
+
407
+ def time_picker(self, id: str, hour: int = 0, minute: int = 0, **opts):
408
+ return _api.time_picker(self._ctx, id, hour, minute, **opts)
409
+
410
+ # -- navigation --------------------------------------------------------
411
+
412
+ def nav_item(self, label: str, **opts) -> bool:
413
+ return _api.nav_item(self._ctx, label, **opts)
414
+
415
+ def nav_section(self, title: str) -> None:
416
+ _api.nav_section(self._ctx, title)
417
+
418
+ def breadcrumb(self, items: Sequence[str]) -> int:
419
+ """Returns the clicked index, or -1."""
420
+ return _api.breadcrumb(self._ctx, items)
421
+
422
+ def pagination(self, id: str, page_count: int, page: int = 0) -> int:
423
+ return _api.pagination(self._ctx, id, page_count, page=page)[1]
424
+
425
+ def stepper(self, steps: Sequence[str], current: int) -> None:
426
+ _api.stepper(self._ctx, steps, current)
427
+
428
+ # -- data display ------------------------------------------------------
429
+
430
+ def badge(self, text: str, **opts) -> None:
431
+ _api.badge(self._ctx, text, **opts)
432
+
433
+ def avatar(self, name: str, **opts) -> None:
434
+ _api.avatar(self._ctx, name, **opts)
435
+
436
+ def progress(self, value: float, **opts) -> None:
437
+ """A progress bar; ``value`` is 0..1."""
438
+ _api.progress(self._ctx, value, **opts)
439
+
440
+ def spinner(self, size: float = 16.0) -> None:
441
+ _api.spinner(self._ctx, size)
442
+
443
+ def skeleton(self, width: float = 200.0, height: float = 12.0) -> None:
444
+ _api.skeleton(self._ctx, width, height)
445
+
446
+ def alert(self, title: str, **opts) -> None:
447
+ _api.alert(self._ctx, title, **opts)
448
+
449
+ def toast(self, title: str, **opts) -> None:
450
+ _api.toast(self._ctx, title, **opts)
451
+
452
+ def metric(self, label: str, value: str, **opts) -> None:
453
+ _api.metric(self._ctx, label, value, **opts)
454
+
455
+ def empty_state(self, title: str, **opts) -> bool:
456
+ """An empty view; returns true when its action button was clicked."""
457
+ return _api.empty_state(self._ctx, title, **opts)
458
+
459
+ def tooltip(self, text: str) -> None:
460
+ """Attach a tooltip to the previous component."""
461
+ _api.tooltip(self._ctx, text)
462
+
463
+ def image(self, texture: int, rect: Rect, **opts) -> None:
464
+ _api.image(self._ctx, texture, rect, **opts)
465
+
466
+ # -- charts and custom paint ------------------------------------------
467
+
468
+ def canvas(self, id: str, width, height, paint: Callable[[Rect], None]) -> Any:
469
+ """A box painted by ``paint(rect)`` while the frame is drawn.
470
+
471
+ Draw with this same ``ui`` inside the callback; the callback runs after
472
+ layout, so the rectangle is final.
473
+ """
474
+ return self._ctx.canvas(id, width, height, paint)
475
+
476
+ def line_chart(self, id: str, series, **opts) -> None:
477
+ """A line chart from :class:`cui.Series` values."""
478
+ self._ctx.line_chart(id, series, **opts)
479
+
480
+ def bar_chart(self, id: str, series, **opts) -> None:
481
+ """A bar chart from :class:`cui.Series` values."""
482
+ self._ctx.bar_chart(id, series, **opts)
483
+
484
+ def donut_chart(self, id: str, values, labels=None, **opts) -> None:
485
+ """A donut chart from values and their labels."""
486
+ self._ctx.donut_chart(id, values, labels, **opts)
487
+
488
+ def dot_chart(self, id: str, series, count: int = 0, **opts):
489
+ """A dot-matrix chart from :class:`cui.DotSeries` values."""
490
+ return self._ctx.dot_chart(id, series, count, **opts)
491
+
492
+ def event_track(self, id: str, times, capacity: int, minimum: float, maximum: float,
493
+ selected: int = -1, **opts):
494
+ """A draggable event track; returns an :class:`cui.EventTrackResult`."""
495
+ return self._ctx.event_track(id, times, capacity, minimum, maximum, selected, **opts)
496
+
497
+ # -- immediate drawing, for canvas paint callbacks ---------------------
498
+
499
+ def draw_rect(self, rect: Rect, fill: Color, radius=0.0) -> None:
500
+ _api.draw_rect(self._ctx, rect, radius, fill)
501
+
502
+ def draw_rect_border(self, rect: Rect, fill: Color, border: Color,
503
+ radius=0.0, border_width: float = 1.0) -> None:
504
+ _api.draw_rect_border(self._ctx, rect, radius, fill, border, border_width)
505
+
506
+ def draw_rect_gradient(self, rect: Rect, top: Color, bottom: Color, radius=0.0) -> None:
507
+ _api.draw_rect_gradient(self._ctx, rect, radius, top, bottom)
508
+
509
+ def draw_shadow(self, rect: Rect, blur: float, spread: float, offset,
510
+ color: Color, radius=0.0) -> None:
511
+ _api.draw_shadow(self._ctx, rect, radius, blur, spread, offset, color)
512
+
513
+ def draw_line(self, a, b, thickness: float, color: Color) -> None:
514
+ _api.draw_line(self._ctx, a, b, thickness, color)
515
+
516
+ def draw_polyline(self, points, thickness: float, color: Color, closed: bool = False) -> None:
517
+ self._ctx.draw_polyline(points, thickness, color, closed)
518
+
519
+ def draw_polygon(self, points, color: Color) -> None:
520
+ self._ctx.draw_polygon(points, color)
521
+
522
+ def draw_circle(self, center, radius: float, color: Color) -> None:
523
+ _api.draw_circle(self._ctx, center, radius, color)
524
+
525
+ def draw_arc(self, center, radius: float, a0: float, a1: float,
526
+ thickness: float, color: Color) -> None:
527
+ _api.draw_arc(self._ctx, center, radius, a0, a1, thickness, color)
528
+
529
+ def draw_text(self, text: str, pos, color: Color | None = None,
530
+ font: int = 0, size: float = 13.0) -> None:
531
+ encoded = text.encode("utf-8")
532
+ _api.draw_text(self._ctx, font, size, pos, color if color is not None else _FOREGROUND,
533
+ text, len(encoded))
534
+
535
+ def draw_icon(self, icon: str, rect: Rect, size: float, color: Color) -> None:
536
+ _api.draw_icon(self._ctx, icon, rect, size, color)
537
+
538
+ def clip(self, rect: Rect) -> _Clip:
539
+ """Clip custom painting to ``rect`` for the duration of the block."""
540
+ return _Clip(self._ctx, rect)
541
+
542
+ # -- overlays (callback style) ----------------------------------------
543
+
544
+ def dialog(self, title: str, *, open: bool, body: Callable[["UI"], None] | None = None, **opts) -> bool:
545
+ """A modal dialog. Returns the new ``open`` state."""
546
+ visible, new_open = _api.dialog_begin(self._ctx, title, open=open, **opts)
547
+ if visible and body is not None:
548
+ body(self)
549
+ _api.dialog_end(self._ctx)
550
+ return bool(new_open)
551
+
552
+ def sheet(self, title: str, *, open: bool, body: Callable[["UI"], None] | None = None, **opts) -> bool:
553
+ visible, new_open = _api.sheet_begin(self._ctx, title, open=open, **opts)
554
+ if visible and body is not None:
555
+ body(self)
556
+ _api.sheet_end(self._ctx)
557
+ return bool(new_open)
558
+
559
+ def menu(self, label: str, *, body: Callable[["UI"], None], **opts) -> bool:
560
+ """A dropdown menu anchored to the previous component."""
561
+ visible = _api.menu_begin(self._ctx, label, **opts)
562
+ if visible:
563
+ body(self)
564
+ _api.menu_end(self._ctx)
565
+ return bool(visible)
566
+
567
+ def user_menu(self, name: str, *, body: Callable[["UI"], None], **opts) -> bool:
568
+ """A user menu with an avatar, name and status."""
569
+ visible = _api.user_menu_begin(self._ctx, name, **opts)
570
+ if visible:
571
+ body(self)
572
+ _api.user_menu_end(self._ctx)
573
+ return bool(visible)
574
+
575
+ def reasoning(self, id: str, *, body: Callable[["UI"], None] | None = None, **opts) -> bool:
576
+ """A collapsible reasoning block."""
577
+ visible = _api.reasoning_begin(self._ctx, id, **opts)
578
+ if visible and body is not None:
579
+ body(self)
580
+ _api.reasoning_end(self._ctx)
581
+ return bool(visible)
582
+
583
+ def popover(self, id: str, *, body: Callable[["UI"], None], **opts) -> None:
584
+ visible = _api.popover_begin(self._ctx, id, **opts)
585
+ if visible:
586
+ body(self)
587
+ _api.popover_end(self._ctx)
588
+
589
+ def accordion(self, title: str, *, open: bool = False, body: Callable[["UI"], None] | None = None, **opts) -> bool:
590
+ visible, new_open = _api.accordion_begin(self._ctx, title, open=open, **opts)
591
+ if visible and body is not None:
592
+ body(self)
593
+ _api.accordion_end(self._ctx)
594
+ return bool(new_open)
595
+
596
+ def menu_item(self, label: str, **opts) -> bool:
597
+ """A row inside a menu."""
598
+ return _api.menu_item(self._ctx, label, **opts)
599
+
600
+ def menu_separator(self) -> None:
601
+ _api.menu_separator(self._ctx)
602
+
603
+ def dialog_footer(self, body: Callable[["UI"], None]) -> None:
604
+ _api.dialog_footer_begin(self._ctx)
605
+ body(self)
606
+ _api.dialog_footer_end(self._ctx)