python-cui 1.4.0.6__cp311-cp311-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/_gen/model.py ADDED
@@ -0,0 +1,202 @@
1
+ """Value classes for the plain data structs that CUI takes as arrays.
2
+
3
+ GENERATED FILE: produced by tools/gen_cui.py; do not edit by hand.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ from typing import NamedTuple
9
+
10
+
11
+ class Candle(NamedTuple):
12
+ """Candlestick chart: open, high, low and close per period with volume under it, for prices. The wheel zooms around the pointer, dragging (or Shift+wheel) pans, a crosshair shows each candle's values, and the price axis fits the candles in view. Zoomed out past a few points per candle, candles merge per pixel column, so a long history stays fast. When the view shows the newest candle it follows new ones as they are appended. With the chart focused, Left and Right move the crosshair (Shift: ten at a time), Home and End jump to the ends, + and - zoom and 0 fits everything. cui_candlestick(ui, "btc", candles, count, .labels = dates, .overlays = &sma, .overlay_count = 1);"""
13
+
14
+ open: float = None
15
+ high: float = None
16
+ low: float = None
17
+ close: float = None
18
+ volume: float = None
19
+
20
+
21
+ class Choice(NamedTuple):
22
+ """Radio cards: larger selectable cards for choices that need a description (plans, templates)."""
23
+
24
+ title: str = None
25
+ description: str = None
26
+ icon: str = None
27
+ badge: str = None
28
+
29
+
30
+ class Command(NamedTuple):
31
+ """------------------------------------------------------------------------ */ /* Command palette (block) */ /* ------------------------------------------------------------------------"""
32
+
33
+ title: str = None
34
+ icon: str = None
35
+ group: str = None
36
+ shortcut: str = None
37
+
38
+
39
+ class CurveKey(NamedTuple):
40
+
41
+ x: float = None
42
+ y: float = None
43
+ in_dx: float = None
44
+ in_dy: float = None
45
+ out_dx: float = None
46
+ out_dy: float = None
47
+ mode: int = None
48
+
49
+
50
+ class FlameSpan(NamedTuple):
51
+ """Flame graph / profiler timeline: time runs left to right, call depth top to bottom (row d holds the spans at depth d). You own the spans, the view and the selection; the component pans and zooms *view and writes *selected. static cui_flame_view view; (zeroed: fits every span) static int selected = -1; cui_flame_sort(spans, count); (once, after recording) cui_flame_result r = cui_flame_graph(ui, "profile", spans, count, &view, &selected); if (r.selection_changed && selected >= 0) show_details(&spans[selected]); Times are seconds (any origin; the ruler counts from the earliest span). Spans must be sorted by depth, then start (cui_flame_sort does it), and spans of one depth must not overlap: a child lies within its parent. Only the spans in view are visited (binary searches per row), so captures of 100k spans stay fast; spans thinner than a pixel merge into a neutral run. The spans need to be valid only during the call. color_key picks the color (0: hashed from the name), so the same function keeps its color. Mouse: the wheel zooms around the pointer, Shift+wheel or a sideways scroll pans, drag pans (sideways and, for deep stacks, up and down). Click selects a span (empty space clears), double-click zooms to fit it (on empty space: fits everything). Hover shows a tooltip: name, duration and its share of the parent (or of the view, at depth 0). Keys when focused: Left/Right move to the previous/next span in the row, Up to the parent, Down to the first child (the view follows); Shift+Left/ Right pan; + and - zoom; Enter or Space zooms to the selection; Home or F fits everything; Esc fits everything, or when already fitted clears the selection. Zooming to a span or fitting animates (snaps with reduced motion). Not included: an aggregated (merged call tree) flame graph mode."""
52
+
53
+ name: str = None
54
+ start: float = None
55
+ end: float = None
56
+ depth: int = None
57
+ color_key: int = None
58
+
59
+
60
+ class GradientStop(NamedTuple):
61
+ """Gradient editor: a color ramp over a checkerboard (so alpha shows) with the stops underneath. You own the stops; the editor edits them in place and keeps them sorted by position. Drag a stop to move it (it may pass its neighbours), drag it off the ramp or press Delete to remove it (never fewer than two), click the ramp or the empty track to add a stop with the color found there. Double click a stop (or Enter on a focused one) to open the color picker; the row under the ramp shows the selected stop's color, location and opacity. Stops are focusable: Tab moves through them, Left and Right nudge (Shift for fine steps)."""
62
+
63
+ pos: float = None
64
+ color: Color = None
65
+
66
+
67
+ class GridColumn(NamedTuple):
68
+ """A virtualized table for large data: sticky header, resizable and sortable columns, checkbox selection (click, Ctrl+click, Shift+click, Ctrl+A), keyboard navigation and editable cells. Build only the rows in [first, last): int first, last; if (cui_data_grid_begin(ui, "people", cols, 4, count, &first, &last, .selected = sel)) { for (int r = first; r < last; r++) { cui_data_grid_row(ui, r); cui_data_grid_cell_text(ui, people[r].name); ... } cui_data_grid_end(ui); }"""
69
+
70
+ title: str = None
71
+ width: float = None
72
+ align: int = None
73
+ sortable: bool = None
74
+ fixed: bool = None
75
+ priority: int = None
76
+
77
+
78
+ class MarkdownResult(NamedTuple):
79
+
80
+ link: str = None
81
+ hovered_link: str = None
82
+ task_offset: int = None
83
+ task_line: int = None
84
+ task_checked: bool = None
85
+ height: float = None
86
+
87
+
88
+ class Model(NamedTuple):
89
+ """Model picker: the current model on a button; a list with details opens."""
90
+
91
+ name: str = None
92
+ detail: str = None
93
+ badge: str = None
94
+ icon: str = None
95
+
96
+
97
+ class PlanStep(NamedTuple):
98
+ """Agent plan: steps with their status on a connected rail, and progress."""
99
+
100
+ title: str = None
101
+ detail: str = None
102
+ status: int = None
103
+
104
+
105
+ class PresenceUser(NamedTuple):
106
+ """Presence: who is here now. Overlapping avatars with a colored ring each, that spread out on hover and name themselves."""
107
+
108
+ name: str = None
109
+ color: Color = None
110
+ avatar: int = None
111
+ idle: bool = None
112
+
113
+
114
+ class PromptSuggestion(NamedTuple):
115
+ """Prompt suggestions: cards to start a conversation with."""
116
+
117
+ icon: str = None
118
+ title: str = None
119
+ detail: str = None
120
+
121
+
122
+ class SankeyLink(NamedTuple):
123
+ """Sankey: flows between nodes; columns follow the links from the sources."""
124
+
125
+ from_: int = None
126
+ to: int = None
127
+ value: float = None
128
+
129
+
130
+ class Source(NamedTuple):
131
+ """Sources: cards for the documents an answer used, and inline citations that show a card on hover. Both return true / the index when clicked."""
132
+
133
+ title: str = None
134
+ url: str = None
135
+ snippet: str = None
136
+
137
+
138
+ class SpeedAction(NamedTuple):
139
+ """Speed dial: a round floating action button that fans out related actions. Returns the chosen action index, or -1."""
140
+
141
+ icon: str = None
142
+ label: str = None
143
+
144
+
145
+ class SwipeAction(NamedTuple):
146
+ """Swipe actions: drag a row sideways (or swipe on a trackpad) to reveal actions behind it. A long swipe triggers the first action. The row content goes between begin and end; end returns the chosen action: 0..left_count-1 for left actions, 100 + i for right actions, or -1."""
147
+
148
+ icon: str = None
149
+ label: str = None
150
+ tone: int = None
151
+
152
+
153
+ class TabBarItem(NamedTuple):
154
+ """Bottom tab bar for compact layouts, with a pill that glides to the selection."""
155
+
156
+ icon: str = None
157
+ label: str = None
158
+ badge: int = None
159
+
160
+
161
+ class TableColumn(NamedTuple):
162
+ """Table"""
163
+
164
+ title: str = None
165
+ width: Size = None
166
+ align: int = None
167
+ sortable: bool = None
168
+
169
+
170
+ class TickerItem(NamedTuple):
171
+ """Ticker: items that scroll by continuously, pausing on hover."""
172
+
173
+ label: str = None
174
+ value: str = None
175
+ delta: float = None
176
+ lower_is_better: bool = None
177
+
178
+
179
+ class TocItem(NamedTuple):
180
+ """Table of contents for a scroll area: highlights the section in view on a progress rail, and scrolls to a section when clicked. Put cui_toc_anchor(ui, "anchor") at each heading inside the scroll area, and call cui_toc in the same scope as the scroll area. Returns the active index."""
181
+
182
+ title: str = None
183
+ anchor: str = None
184
+ level: int = None
185
+
186
+
187
+ class TourStep(NamedTuple):
188
+ """Guided tour: a spotlight on one control at a time, with a card beside it that says what the control does, for onboarding and "what's new". The rest of the window dims; the spotlight glides from one control to the next. Call it after the controls it points at, every frame while *step is 0 or more; it sets *step to -1 when the tour ends. Right or Enter go to the next step, Left goes back and Esc ends the tour. static int step = 0; cui_button(ui, "Export"); steps[1].target = cui_last_id(ui); ... if (step >= 0) cui_tour(ui, "intro", steps, 4, &step);"""
189
+
190
+ target: int = None
191
+ title: str = None
192
+ body: str = None
193
+ placement: int = None
194
+
195
+
196
+ class VizItem(NamedTuple):
197
+ """Treemap: rectangles with areas proportional to their values."""
198
+
199
+ label: str = None
200
+ value: float = None
201
+ color: Color = None
202
+
cui/_types.py ADDED
@@ -0,0 +1,287 @@
1
+ """Value types shared by the high-level API and the generated wrappers.
2
+
3
+ Everything here is a small immutable value: it converts to one of CUI's plain
4
+ C structs at the call site and costs nothing to pass around.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from typing import NamedTuple, Sequence
10
+
11
+ __all__ = [
12
+ "Color",
13
+ "Size",
14
+ "SizeKind",
15
+ "TextResult",
16
+ "TextFlags",
17
+ "Date",
18
+ "Rect",
19
+ "Vec2",
20
+ "TextMetrics",
21
+ "Corners",
22
+ "KeyCombo",
23
+ "Series",
24
+ "DotSeries",
25
+ "ChartAnnotation",
26
+ "CanvasResult",
27
+ "DotChartResult",
28
+ "EventTrackResult",
29
+ ]
30
+
31
+
32
+ class Color(NamedTuple):
33
+ """An RGBA color, or a semantic theme token.
34
+
35
+ Three ways to write one, all accepted by every ``color=`` argument::
36
+
37
+ Color(255, 0, 0) # plain RGBA
38
+ Color.rgb(0xE5484D) # packed RGB
39
+ Color.token(Token.ACCENT) # follows the theme and the accent
40
+ """
41
+
42
+ r: int
43
+ g: int
44
+ b: int
45
+ a: int = 255
46
+
47
+ def __repr__(self): # pragma: no cover - cosmetic
48
+ return f"Color(0x{self.r:02x}{self.g:02x}{self.b:02x}, a={self.a})"
49
+
50
+ @classmethod
51
+ def rgb(cls, value: int, alpha: int = 255) -> Color:
52
+ """Build from a packed ``0xRRGGBB`` integer."""
53
+ return cls((value >> 16) & 0xFF, (value >> 8) & 0xFF, value & 0xFF, alpha)
54
+
55
+ @classmethod
56
+ def rgba(cls, value: int) -> Color:
57
+ """Build from a packed ``0xRRGGBBAA`` integer."""
58
+ return cls((value >> 24) & 0xFF, (value >> 16) & 0xFF, (value >> 8) & 0xFF, value & 0xFF)
59
+
60
+ @classmethod
61
+ def token(cls, token) -> Color:
62
+ """Build the placeholder CUI resolves against the current theme.
63
+
64
+ CUI encodes a token color as ``(token index, 0xC5, 0x1D, 0)``; that is
65
+ what ``cui_color`` values produced by ``CUI_TOKEN_COLOR`` look like, and
66
+ exactly what this returns.
67
+ """
68
+ return cls(int(token), 0xC5, 0x1D, 0)
69
+
70
+ def with_alpha(self, alpha: int) -> Color:
71
+ return Color(self.r, self.g, self.b, alpha)
72
+
73
+ @property
74
+ def is_token(self) -> bool:
75
+ """True when this color is a theme token rather than a literal."""
76
+ return self.g == 0xC5 and self.b == 0x1D and self.a == 0
77
+
78
+ @property
79
+ def packed(self) -> int:
80
+ """``0xRRGGBBAA``."""
81
+ return (self.r << 24) | (self.g << 16) | (self.b << 8) | self.a
82
+
83
+
84
+ class SizeKind:
85
+ """How a :class:`Size` is resolved (mirrors ``cui_size_kind``)."""
86
+
87
+ FIT = 0
88
+ GROW = 1
89
+ FIXED = 2
90
+ PERCENT = 3
91
+
92
+
93
+ class Size(NamedTuple):
94
+ """A width or height: fit the content, grow, fixed points or a percent.
95
+
96
+ Most arguments take a plain number (points) or one of the constructors::
97
+
98
+ Size.FILL # grow to fill the parent
99
+ Size.fit() # the smallest that fits the content
100
+ Size.px(240) # 240 points
101
+ Size.percent(50) # half the parent
102
+ Size.grow(2) # share of the free space, weighted
103
+ """
104
+
105
+ kind: int
106
+ value: float = 0.0
107
+
108
+ def __repr__(self): # pragma: no cover - cosmetic
109
+ names = {0: "fit", 1: "grow", 2: "px", 3: "%"}
110
+ return f"Size.{names.get(self.kind, self.kind)}({self.value:g})"
111
+
112
+ @classmethod
113
+ def fit(cls) -> Size:
114
+ return cls(SizeKind.FIT, 0.0)
115
+
116
+ @classmethod
117
+ def grow(cls, weight: float = 1.0) -> Size:
118
+ return cls(SizeKind.GROW, weight)
119
+
120
+ @classmethod
121
+ def px(cls, points: float) -> Size:
122
+ return cls(SizeKind.FIXED, points)
123
+
124
+ @classmethod
125
+ def percent(cls, percent: float) -> Size:
126
+ return cls(SizeKind.PERCENT, percent)
127
+
128
+
129
+ Size.FILL = Size(SizeKind.GROW, 1.0) # type: ignore[attr-defined]
130
+ Size.FIT = Size(SizeKind.FIT, 0.0) # type: ignore[attr-defined]
131
+
132
+
133
+ class TextFlags:
134
+ """Bits returned by CUI's editable text components."""
135
+
136
+ CHANGED = 1
137
+ SUBMITTED = 2
138
+ FOCUSED = 4
139
+ BLURRED = 8
140
+
141
+
142
+ class TextResult(NamedTuple):
143
+ """What a text field returned this frame.
144
+
145
+ The text is the buffer *after* the call: CUI edits it in place, so
146
+ ``state.name = ui.text_input("name", value=state.name).text`` keeps the
147
+ caret and selection working across frames.
148
+ """
149
+
150
+ text: str
151
+ flags: int = 0
152
+
153
+ @property
154
+ def changed(self) -> bool:
155
+ return bool(self.flags & TextFlags.CHANGED)
156
+
157
+ @property
158
+ def submitted(self) -> bool:
159
+ return bool(self.flags & TextFlags.SUBMITTED)
160
+
161
+ @property
162
+ def focused(self) -> bool:
163
+ return bool(self.flags & TextFlags.FOCUSED)
164
+
165
+ @property
166
+ def blurred(self) -> bool:
167
+ return bool(self.flags & TextFlags.BLURRED)
168
+
169
+
170
+ class Date(NamedTuple):
171
+ """A calendar date (month is 1..12)."""
172
+
173
+ year: int
174
+ month: int
175
+ day: int
176
+
177
+ @classmethod
178
+ def today(cls) -> Date:
179
+ import datetime
180
+
181
+ now = datetime.date.today()
182
+ return cls(now.year, now.month, now.day)
183
+
184
+ @classmethod
185
+ def from_date(cls, value) -> Date:
186
+ return cls(value.year, value.month, value.day)
187
+
188
+ def to_date(self):
189
+ import datetime
190
+
191
+ return datetime.date(self.year, self.month, self.day)
192
+
193
+ def __repr__(self): # pragma: no cover - cosmetic
194
+ return f"Date({self.year}, {self.month}, {self.day})"
195
+
196
+
197
+ class Rect(NamedTuple):
198
+ x: float
199
+ y: float
200
+ w: float
201
+ h: float
202
+
203
+
204
+ class Vec2(NamedTuple):
205
+ x: float
206
+ y: float
207
+
208
+
209
+ class TextMetrics(NamedTuple):
210
+ width: float
211
+ height: float
212
+ ascent: float
213
+ descent: float
214
+ line_height: float
215
+
216
+
217
+ class Corners(NamedTuple):
218
+ """Per-corner radii; a plain number means the same radius everywhere."""
219
+
220
+ tl: float = 0.0
221
+ tr: float = 0.0
222
+ br: float = 0.0
223
+ bl: float = 0.0
224
+
225
+
226
+ class KeyCombo(NamedTuple):
227
+ """A recorded keyboard shortcut: modifier bits plus a key."""
228
+
229
+ mods: int = 0
230
+ key: int = 0
231
+
232
+
233
+ class Series(NamedTuple):
234
+ """One line or bar in a chart: a legend name, the values and an optional color."""
235
+
236
+ name: str | None
237
+ values: Sequence[float]
238
+ color: Color | None = None
239
+
240
+
241
+ class DotSeries(NamedTuple):
242
+ """One stacked band in a dot-matrix chart."""
243
+
244
+ values: Sequence[float]
245
+ name: str | None = None
246
+ accent: bool = False
247
+
248
+
249
+ class ChartAnnotation(NamedTuple):
250
+ """A threshold line, a vertical marker or a point drawn over a chart."""
251
+
252
+ kind: int = 0
253
+ x: float = 0.0
254
+ y: float = 0.0
255
+ label: str | None = None
256
+ detail: str | None = None
257
+ accent: bool = False
258
+
259
+
260
+ class CanvasResult(NamedTuple):
261
+ """What a :meth:`cui.UI.canvas` call returned this frame."""
262
+
263
+ rect: Rect
264
+ hovered: bool = False
265
+ pressed: bool = False
266
+ clicked: bool = False
267
+ mouse: Vec2 = Vec2(0.0, 0.0)
268
+
269
+
270
+ class DotChartResult(NamedTuple):
271
+ """The hovered sample and the click position of a dot-matrix chart."""
272
+
273
+ hovered: int = -1
274
+ x: float = 0.0
275
+ value: float = 0.0
276
+ clicked: bool = False
277
+
278
+
279
+ class EventTrackResult(NamedTuple):
280
+ """The times an event track kept, plus what happened to them this frame."""
281
+
282
+ times: list[float]
283
+ selected: int = -1
284
+ changed: bool = False
285
+ added: int = 0
286
+ removed: int = 0
287
+ dragging: bool = False
cui/py.typed ADDED
File without changes