1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
//! The backend contract. EXACTLY ONE backend is compiled in as `backend::Native`:
//! `mock` (feature "mock" or `cargo test`), else `gtk` / `win32` / `cocoa` per the cfgs from build.rs.
//!
//! # Division of labour
//! The core (`core.rs`, `layout.rs`, `a11y.rs`) owns the widget graph, mirrored widget state
//! (text, checked, value, items, selection...), layout and the accessible names/roles. A backend only
//! mirrors that graph into native objects, **keyed by [`WidgetId`]**: keep a private
//! `id -> native object` map and, in the native object, the id (g_object_set_data / GWLP_USERDATA /
//! ivar or associated object) so native callbacks can call back into [`crate::core::event`].
//!
//! # Rules every backend must follow
//! 1. Everything is called on the main (UI) thread, except [`Backend::wake`], which may be called
//! from any thread and must make the native loop call [`crate::core::drain_posted`] soon, on the
//! main thread (g_idle_add / PostMessage to a hidden window / dispatch_async(main)).
//! 2. Programmatic changes via [`Backend::set`] must NOT emit events (block signals / set a guard
//! flag; on Win32 ignore EN_CHANGE etc. while inside `set`). Only user actions emit events.
//! 3. [`Backend::preferred_size`], [`Backend::chrome`], [`Backend::native_handle`] are pure queries.
//! 4. Never hold backend-internal `RefCell` borrows while calling into `crate::core::*` (events can
//! re-enter the backend through user callbacks) and never call core while inside `create/set/destroy`.
//! 5. Never panic or unwind across FFI; report failures as `Err` / ignore unknown ids (stale ids
//! are normal: widgets can be destroyed while native messages are in flight).
//! 6. Coordinates are logical pixels, origin top-left, relative to the *native parent's client area*.
//! Scale for DPI internally (Win32 per-monitor DPI, Cocoa points are already logical).
//! 7. Text is UTF-8 `&str` at this boundary: convert to UTF-16 (Win32) / NSString (Cocoa) / C string (GTK).
//! 8. Unknown/unsupported `Kind`s or `Prop`s: return `Err(Unsupported)` from `create` for a kind
//! (core records the error and the widget is dead) and silently ignore unsupported props
//! (additive evolution: new `Prop`/`Kind`/`Event` variants may be added; use `_ =>` arms).
//!
//! # Layout decision
//! Layout lives in Rust (`layout.rs`): stack (H/V) and grid layouts computed from
//! `preferred_size` and then pushed with `Prop::Bounds`. HBox/VBox/Grid/Spacer are *virtual*
//! (no native object, never passed to the backend); real widgets are children of the nearest
//! native ancestor (Window, Page, GroupBox), which is a plain absolute-positioning container
//! (GtkFixed / child HWND / flipped NSView). This is identical on all three platforms and needs
//! no toolkit layout machinery.
//!
//! # Containers a backend must provide
//! * `Window`: top-level; children are placed in its client area *below the menu bar*.
//! `Prop::Bounds` on a window sets the CLIENT size (x/y ignored). `Event::Resized` reports the same.
//! * `GroupBox`: titled frame; children coordinates are relative to its inner client area.
//! `chrome()` = outer size minus client size (border + title).
//! * `Tabs` + `Page`: `create(page, Some(tabs))` appends a tab; `Prop::Text` on the page is the
//! title; children of the page use page-client coordinates. `chrome(tabs)` = header/border size.
//! `Prop::Bounds` on a Page is advisory (toolkits that size pages themselves may ignore it).
//! `Prop::Selected(Some(i))` on Tabs switches page; user switching emits `Event::Selected`.
//! * Menus: `MenuBar`(parent = window) > `Menu`(title in `Prop::Text`; parent = MenuBar or Menu =
//! submenu) > `MenuItem` / `CheckMenuItem` / `MenuSeparator`. Created in order. `Prop::Accel`
//! carries text like "Ctrl+S" (see [`crate::Accel::parse`]); the backend registers the shortcut
//! (Ctrl means Command on macOS) and shows it in the item. Activation -> `Event::Click`
//! (CheckMenuItem: `Event::Toggled`).
//!
//! # Splitters
//! `Splitter` is virtual like `HBox`: the core places its two panes (ordinary children,
//! parented to the nearest native ancestor) and, between them, a native `Kind::Sash` child it
//! creates itself. The sash is a thin, plain drag handle (a GtkEventBox / custom child HWND /
//! NSView subclass): it gets `Prop::Orientation` once, then the usual `Bounds`/`Visible`/`Enabled`,
//! shows a resize cursor and emits `Event::SashDragged(pos)` while dragged (see there). It must
//! also be keyboard-operable: reachable with Tab (and focused by a click), showing a focus
//! indicator, and turning the arrow keys along its axis (Shift = large step), Home and End into
//! `Event::SashKey` (see [`SashKey`]). Otherwise it needs no painting beyond the platform's usual
//! separator look.
//! A backend without a sash just returns `Err(Unsupported)` from `create(Kind::Sash)`: the core
//! keeps the splitter working (panes laid out at the default/app-set position, not draggable).
//!
//! # Radio buttons
//! `RadioButton` is just a toggle with radio appearance; exclusivity within a group is enforced
//! by the core (it sends `Prop::Checked(false)` to the others), so backends need no native grouping.
//!
//! # Event emission summary (backend -> core::event)
//! Button/MenuItem: `Click` | CheckBox/Radio/CheckMenuItem: `Toggled(bool)` | TextInput/TextArea/
//! PasswordInput/SpinBox-text: `Text(String)` (SpinBox uses `Value(f64)`) | Slider/SpinBox:
//! `Value(f64)` | ComboBox/ListBox/Tabs: `Selected(Option<usize>)` | ListBox double-click/Enter:
//! `Activated(usize)` | Window: `Resized{w,h}` and `core::close_requested(id)` (ALWAYS veto the native
//! close: the core destroys the window itself via `destroy` if the app allows it) | any focusable:
//! `Focus(bool)` | Table: `Selected(Option<usize>)` (row), `Activated(row)`, `ColumnClicked(col)` |
//! Tree: `TreeSelected`, `TreeActivated`, `TreeExpanded` | Sash: `SashDragged(pos)` | Window (optional):
//! `Moved{x,y}` | any widget: `ContextMenu{x,y}` | timers: `core::timer_fired(token)`.
use crate*;
pub use Mock as Native;
pub use Gtk as Native;
pub use Win32 as Native;
pub use Cocoa as Native;
/// Widget kinds the backend creates. Virtual layout kinds (HBox, VBox, Grid, Spacer) exist only in the core.
/// Property changes pushed to the backend. Initial values are pushed right after `create`.
/// Keyboard commands for a focused sash. `Prev`/`Next` are the arrow keys along the sash's
/// movement axis in SCREEN directions (Left/Up = `Prev`, Right/Down = `Next`; the backend does not
/// mirror them for right-to-left layouts, the core does), with Shift for the `Large` variants.
/// `Min`/`Max` (Home/End) make the first pane as small / as large as its limits allow.
/// Events from the backend (user actions only; see rule 2 in the module docs).
/// The platform backend. All functions are associated (no `self`): the backend keeps its state in
/// its own thread-locals/statics. Required methods have no default; optional ones may stay no-ops.