8000 The embedding point: WidgetKind.Platform and Prop.View, on GTK and Android (docs/17 step 1) by rleibman · Pull Request #146 · rleibman/thicket · GitHub
[go: up one dir, main page]

Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -359,12 +359,12 @@ SELFTEST=1 examples/todo-android/build.sh
```

`checkLinux` is what CI runs (`.github/workflows/ci.yml`), with the GTK self-tests under
xvfb; the Apple self-tests run on a self-hosted Mac (`apple.yml`). Counts as of 2026-10-21:
signals 30, core 170, effect-zio 25, storage 14, sqlite 2 and secrets 2 per backend,
xvfb; the Apple self-tests run on a self-hosted Mac (`apple.yml`). Counts as of 2026-11-02:
signals 30, core 172, effect-zio 25, storage 14, sqlite 2 and secrets 2 per backend,
storage-gtk 4, storage-apple 4, secrets-gtk 2, http-gtk 5, http-android 5, device 8,
location 7, motion 5, clipboard 1, haptics 2, pickers 4, camera 2 and share 5 per backend, shim-gen 15,
sbt-thicket 9; GTK 138 + 69 self-test checks, Android 90 + 84 (2026-10-30, the gallery's with
the HTTP checks and every device section's),
sbt-thicket 9; GTK 144 + 69 self-test checks, Android 95 + 84 (2026-11-02, the gallery's with
the HTTP checks, every device section's and the Platform section's),
the HTTP checks on Linux 12.

Coverage over the JVM-tested modules:
Expand Down
16 changes: 9 additions & 7 deletions docs/12-component-status.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,8 @@ Android gallery built, Apple gaps the review found filed as #73–#79).
8000 | Widgets implemented on at least one renderer | **24** |
| Widgets implemented on **every** renderer that exists | **24** — measured on all four since #45/#46, `Grid` since #62, `IconButton` since #66 and `TabView` since #69 |
| Renderers | **4** (GTK4, Android, AppKit, UIKit) |
| Props in the contract | **37** |
| Props implemented on every renderer | **37** |
| Props in the contract | **38** |
| Props implemented on every renderer | **37** — `View`, the embedding point's (`docs/17` §17.3, 2026-11-02), is GTK and Android so far; Apple shows a label in its place until the Mac's half (#145) |

**Twenty-four of thirty-two, every one on every renderer, and measured on every one.** `IconButton` reached AppKit and UIKit in #66, and `TabView` in #69. `Grid` reached AppKit and UIKit in #62: gallery **58/58** on macOS and **57/57** on the iOS simulator. `Picker` (#45), `ZStack`, `SegmentedControl` and `DatePicker` (#46) were written on Linux and first run on the Mac in #45/#46, which found one crash (below the table) and is otherwise what the gallery's new checks measure: **48/48** on macOS and **47/47** on the iOS simulator. The six phase 2 widgets landed on
AppKit and UIKit in #4 and the two presented ones, `Alert` and `Sheet`, in #18; context
Expand Down Expand Up @@ -167,6 +167,7 @@ Slice 2:
|---|---|---|---|---|---|---|
| `Slider` | `WidgetKind.Slider` | done | done | done | done | `GtkScale` / `SeekBar`. `Prop.Value` is in the **app's units**, not a fraction |
| `Picker` | `WidgetKind.Picker` | done | done | done | done | `GtkDropDown` over a `GtkStringList` model / `Spinner` / `NSPopUpButton` / a menu-backed `UIButton` — **not** `UIPickerView`, which is a wheel. Selection is an **index**: two options may share a label, and it survives new options. `-1` is a blank on all four (D13): an empty drop-down / a leading blank entry / no item chosen / a leading blank menu element (#77) |
| `Platform` | `WidgetKind.Platform`, `Prop.View` | done | done | partial | partial | **Not in the v1 catalogue: the embedding point** (`docs/17` §17.3, the owner's decision 2026-11-01), for a view made by a module of its own, such as a camera preview. A `GtkPlatformView` makes a `GtkWidget*`, an `AndroidPlatformView` a `View`; the renderer holds it in a `GtkBox` / `FrameLayout`, releases it (while it is still alive) before it goes, and replaces it when the view changes. A view with nothing for the renderer shows `<description>: not available on GTK` (or Android). AppKit and UIKit show that label for every view until the shims can host one (#145) |
| `TabView` | `WidgetKind.TabView`, `WidgetKind.Tab` | done | done | done | done | **A §12.2a exception** (#61): Android's framework tab controls are all deprecated, so its bottom bar is built from framework views. `AdwViewStack` + `AdwViewSwitcherBar` / `UITabBarController` / `NSTabViewController`. Every tab stays mounted; the selection is an index; inserting or removing tabs keeps the user on their tab and reports its new index |
| `IconButton` | `WidgetKind.IconButton` | done | done | done | done | Icon-only, so `Prop.AccessibleLabel` is required (screen reader and tooltip). `GtkButton` with a theme icon / a borderless `ImageButton` drawing bundled Material Symbols / an SF Symbol. Its own kind because Android's icon button is a different class. The 24 curated `Icon`s and the `Icon.Platform` escape hatch are #61 |
| `Grid` | `WidgetKind.Grid` | done | done | done | done | **A §12.2a exception** (#60, the project owner's decision): UIKit has no grid view. `GtkGrid` with cells placed through `GtkGridLayoutChild` / `GridLayout`'s own auto-flow / `NSGridView` / a constraint grid on UIKit. Children flow into `Prop.Columns` columns in child order; each column as wide as its widest cell |
Expand Down Expand Up @@ -348,7 +349,7 @@ someone who did not write the framework, running on all three targets.
|---|---|
| `signalsJVM` / `signalsNative` | 30 |
| `signalsJS` | 28 — no `ThreadGuardSpec`, JS has no threads |
| `coreJVM` / `coreJS` / `coreNative` | 170 |
| `coreJVM` / `coreJS` / `coreNative` | 172 (`PlatformSpec`'s 2, 2026-11-02) |
| `effectZioJVM` / `effectZioNative` | 25 — Native ran none until 2026-10-20: the specs were JVM-only |
| `storageJVM` / `storageNative` | 14 |
| `storageGtk` | 4 |
Expand All @@ -372,13 +373,14 @@ someone who did not write the framework, running on all three targets.

Measured 2026-10-20 with `sbt --error testFull`, which `sbt checkLinux` and CI run; the
storage and sqlite rows 2026-10-21, the secrets rows and `storageGtk` 2026-10-26. On top of
these, the self-tests drive the real toolkits: GTK gallery **137** and todo **69**
(`bin/gtk-selftests.sh`, which also fails on any `Gtk-CRITICAL`), Android gallery **90** and
these, the self-tests drive the real toolkits: GTK gallery **144** and todo **69**
(`bin/gtk-selftests.sh`, which also fails on any `Gtk-CRITICAL`), Android gallery **95** and
todo **84** on the `s2test` emulator (2026-10-30, the storage section's checks each included,
secrets among them, the 14 HTTP checks, the Device section's 5 on GTK and 9 on Android, and
the Location section's 1 on GTK and 7 on Android, the Motion section's 1 and 8, and the
Clipboard and haptics section's 3 and 5, the Pickers and camera section's 6 and 10, and the
Share section's 1 and 4).
Clipboard and haptics section's 3 and 5, the Pickers and camera section's 6 and 10, the
Share section's 1 and 4, and, 2026-11-02, the Platform section's 6 on GTK, its heading among
them, and 5 on Android).
The Android gallery's `build.sh` also checks that Back runs the terminate hook. HTTP on Linux: `examples/http/selftest.sh linux`,
**12**. Apple gallery (2026-10-22, #98): macOS **174**, iOS simulator **168**,
each with six storage checks; 2026-10-27 (#108): macOS **185**, iOS simulator **179**, the two
Expand Down
6 changes: 4 additions & 2 deletions docs/17-camera-preview.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
# 17. Live camera preview — a design for approval

Status: **approved, 2026-11-01; not built yet.** `docs/16` §16.3 puts the live camera
Status: **approved, 2026-11-01; step 1 of §17.7, the embedding point, built on GTK and
Android 2026-11-02** (`WidgetKind.Platform`, `Prop.View`, `GtkPlatformView`,
`AndroidPlatformView`; the Apple half is #145). **The preview itself is not built yet.** `docs/16` §16.3 puts the live camera
preview first in tier 3 ("each its own design"), and the owner said yes to tier 3 on
2026-11-01. This is that design. The owner answered §17.8's questions the same day, taking
every recommendation (decision log, 2026-11-01).
Expand Down Expand Up @@ -97,7 +99,7 @@ the device says otherwise.
The largest piece in the plan (`docs/16` §16.3 says so). Proposed order, each its own PR:

1. The embedding point (§17.3) on GTK and Android, with the gallery's trivial platform view;
Apple as a Mac issue.
Apple as a Mac issue. *Done on GTK and Android, 2026-11-02 (decision log).*
2. `thicket-camera-preview` and `-android`, measured on the emulator.
3. `-apple`, the Mac's (iOS and macOS).
4. `-gtk`, after Android and Apple (§17.8.2).
Expand Down
29 changes: 29 additions & 0 deletions docs/decisions.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,35 @@ Go decision (see `08` §8.1) is made after S1, S2, S3 have reports.

## Decision log

- 2026-11-02 — **The embedding point: `WidgetKind.Platform`, `Prop.View`, built on GTK and
Android** (`docs/17` §17.3, step 1 of §17.7; the Apple half is #145).
- **Shape:** `trait PlatformView { def description: String }` in `renderer-api`, and
`dsl.Platform(view | Signal[view])` in `core`. Each renderer extends the trait with how it
makes the native view: `GtkPlatformView.create(): Ptr[GtkWidget]`,
`AndroidPlatformView.create(context): View`, each with a `release` that defaults to doing
nothing. A module that provides a view (the camera preview next) implements the traits for
the platforms it supports; the renderers know nothing of it. No registry: the view itself is
the factory the renderer asks, which is all §17.3's "a factory the platform module
registered" needs.
- **Generic handling:** the handle is a container (`GtkBox`, `FrameLayout`) holding the one
native view, so a changed view replaces the child and the handle stays. `release` runs
while the native view is still alive and in its parent, then it is removed. The table that
tracks it is one of each renderer's per-handle tables, so it is swept on `destroy` and
counted by the self-tests' leak checks.
- **A view with nothing for the renderer** shows `<description>: not available on GTK` (or
Android), as a service's `Unavailable` does. **Apple** maps the kind to a label and shows
`… not available on AppKit/UIKit yet` for every view until the shims can host one (#145).
- **Measured.** `PlatformSpec` 2/2 (core 172). GTK gallery **144** (138 + 6: the section's
heading and 5 checks), todo 69, under a headless `gnome-shell` (the desktop was locked).
Android gallery **95** (90 + 5) on `s2test`. The host makes a `GtkLabel` / `TextView` itself;
the checks find that very widget in the window, then replace it and find the old one was
released while alive (GTK reads its text in `release`, Android its parent) and the
renderer's table count unchanged.
- **Falsified.** Skipping `release`, or calling it after the removal, fails "released while
still alive" on both (GTK also logs `Gtk-CRITICAL … GTK_IS_WIDGET`); an empty "not
available" label fails "says so" on both; a `Platform` that ignores its signal fails
`PlatformSpec`'s second test.

- 2026-11-02 — **Apple camera capture: `thicket-camera-apple` over `UIImagePickerController` on
iOS, a Swift library of its own; macOS `Camera.unavailable`; the iOS 27 simulator has a
camera screen whose shutter takes nothing** (#129, docs/16 §16.10 item 5).
Expand Down
6 changes: 5 additions & 1 deletion examples/gallery/README.md
Original file line number Diff line num 10000 ber Diff line change
Expand Up @@ -166,7 +166,11 @@ tappable `Row`, the screen's `Scroll` with both padding and `.safeArea()`, a pad
`Scroll` inside it whose child can be replaced by a taller one, keyed `ForEach`, virtualised `LazyColumn` whose first row
can be deleted and renamed, a per-row `ContextMenu`, subtree theming with `Provide`, a
handler that throws, a ZIO effect, the two presented widgets (`Alert` and `Sheet`), toolbar
`Action`s, a navigation push, a `TabView` with a tab inserted in the middle, and storage: a
`Action`s, a navigation push, a `TabView` with a tab inserted in the middle, a `Platform` view
(`docs/17` §17.3) that the host makes itself — a `GtkLabel`, a `TextView` — and replaces,
the self-test checking the host's own widget is the one on screen and was released while
still alive, beside one that no platform has and says so (Apple shows that label for both
until its half is built), and storage: a
launch counter in preferences and notes in SQLite, written on a worker thread, with the JDBC
conformance checks run against the platform's driver (GTK, Android, macOS and iOS),
Magnum's checks on GTK, macOS and iOS, and a secret in the platform's secure store, kept from
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,10 @@

package example.gallery.android

import _root_.android.content.Context
import _root_.android.os.Bundle
import _root_.android.view.View
import _root_.android.widget.TextView
import example.gallery.{Gallery, Services}
import thicket.core.AppRoot
import thicket.device.android.AndroidDevice
Expand All @@ -27,7 +30,8 @@ import thicket.haptics.android.AndroidHaptics
import thicket.pickers.android.AndroidPickers
import thicket.camera.android.AndroidCamera
import thicket.share.android.AndroidShare
import thicket.renderer.android.ThicketActivity
import thicket.renderer.android.{AndroidPlatformView, ThicketActivity}
import scala.collection.mutable
import thicket.signals.Owner
import thicket.sqlite.android.AndroidSqlite
import thicket.secrets.android.AndroidSecrets
Expand Down Expand Up @@ -63,7 +67,8 @@ class GalleryActivity extends ThicketActivity {
camera = Some(AndroidCamera(this)),
share = Some(AndroidShare(this))
)
)
),
nativeView = NativeLabel(_)
)

override protected def started(): Unit =
Expand All @@ -80,3 +85,31 @@ class GalleryActivity extends ThicketActivity {
} catch { case _: java.io.IOException => Array.emptyByteArray }

}

/** The Platform section's view on Android: a plain `TextView`, made here, outside the renderer, as a camera preview's
* module would make its view (docs/17 §17.3). It records what it made and what it was told to release, for
* [[GallerySelfTest]].
*/
final class NativeLabel(text: String) extends AndroidPlatformView {

val description = "A native label"

def create(context: Context): View = {
val v = TextView(context)
v.setText(text)
NativeLabel.made += v
if NativeLabel.made.length > 2 then NativeLabel.made.remove(0, NativeLabel.made.length - 2)
v
}
Comment thread
Copilot marked this conversation as resolved.
Resolved

/** Records whether the view was still in the layout: the renderer must release it before removing it. */
override def release(view: View): Unit = NativeLabel.released += (view -> (view.getParent != null))

}

object NativeLabel {

val made = mutable.ArrayBuffer.empty[View]
val released = mutable.ArrayBuffer.empty[(View, Boolean)]

}
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,7 @@ object GallerySelfTest {
private val Tag = "thicket"
private val Delay = 150L
private var failures = 0
private var platformEntries = 0
private val main = Handler(Looper.getMainLooper)

private def check(
Expand Down Expand Up @@ -208,6 +209,48 @@ object GallerySelfTest {
texts.filter(_.startsWith("Load")).toString
)
},
// The embedding point (docs/17 §17.3): the TextView the host's view made is the one on screen, a view Android
// has nothing for says so, and replacing the view releases the old one before it is removed.
() => {
def onScreen(v: View) = findAll(screen)(_ eq v).nonEmpty
val first = NativeLabel.made.headOption
check(
"Platform: the TextView the host's view made is on screen, with its text",
NativeLabel.made.length == 1 && first.exists(v =>
onScreen(v) && allTexts(v) == List(Gallery.nativeLabelText(1))
),
s"made ${NativeLabel.made.length}; on screen ${first.map(onScreen)}; texts ${first.map(allTexts)}"
)
val nowhere = s"${Gallery.nowhere.description}: not available on Android"
check(
"Platform: a view Android has nothing for says so",
texts.contains(nowhere),
texts.filter(_.contains("not available")).toString
)
platformEntries = activity.renderer0.tableEntries
click("Make the native view again")
},
() => {
val first = NativeLabel.made.headOption
val second = NativeLabel.made.lift(1)
check(
"Platform: a new view makes a new TextView, in the old one's place",
NativeLabel.made.length == 2 && second.exists(v =>
findAll(screen)(_ eq v).nonEmpty && allTexts(v) == List(Gallery.nativeLabelText(2))
) && !texts.contains(Gallery.nativeLabelText(1)),
s"made ${NativeLabel.made.length}; texts ${texts.filter(_.startsWith("A native"))}"
)
check(
"Platform: and the old view was released while still in the layout, then removed",
NativeLabel.released.toList == first.toList.map(_ -> true) && first.forall(_.getParent == null),
s"released ${NativeLabel.released.map(_._2)}; old parent now ${first.map(_.getParent)}"
)
check(
"Platform: replacing the view leaves the renderer's tables as they were",
activity.renderer0.tableEntries == platformEntries,
s"$platformEntries before, ${activity.renderer0.tableEntries} after"
)
},
// Device services (docs/16): SharedPreferences, the app's internal directories, and SQLite through
// Thicket's own JDBC driver over android.database.sqlite, held to the same conformance checks as the
// JVM's reference driver, all of which it must pass.
Expand Down
Loading
0