Skip to content

Commit 484cd71

Browse files
ctruedenclaude
andcommitted
scijava-awt: a third binding, and where the shared code belongs
Three is where agnosticism gets believable, and AWT is the case that tests it: no spinner, no slider, no titled border, no collapsible pane, no icons in menus, and a MenuShortcut that cannot say alt. The number widget is a text field and a scroll bar honoring min, max, stepSize and the soft bounds; a collapsible group is a button that hides a panel; an accelerator AWT cannot express is dropped rather than approximated into some other key. None of it asked the contracts to change. What it did change is where shared code lives: - `AbstractWidget` moves into scijava-ui3. Three bindings had written the same bookkeeping -- find the node in the *current* tree, write through the model, do not mistake a refresh for the user typing. Two would have been a coincidence. - `Accelerator` moves into scijava-command. Swing wants a KeyStroke, JavaFX a KeyCombination, AWT a MenuShortcut: three ways of saying a shortcut, one thing being said. A binding that parses `^+C` itself is a binding that can disagree about what it means. On the four-component question. scijava-ui-swing imported exactly six things from scijava-ui-awt -- the input, drag-and-drop and window event dispatchers, colors, windows, clipboard -- and not one widget, because java.awt.Choice and JComboBox have nothing in common. So Swing depends on AWT for the *platform* and never for widgets; `Edt` is the first instance, the dispatch thread being AWT's and SwingUtilities a forwarder to it. The widget types stay siblings on purpose: SwingWidget could extend AwtWidget, but discovery filters on widgetType(), so that would mean a pure-AWT application quietly filling its dialogs with Swing controls as soon as scijava-swing was on the classpath. AWT also settled a difference worth recording: TextComponent.setText does not notify text listeners, where a Swing document would. mvn -o -pl scijava-awt test-compile exec:java -Denforcer.skip \ -Dexec.classpathScope=test -Dexec.mainClass=org.scijava.awt.AwtShell Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013gJpzGd3ksbME4CN6Tu2ni
1 parent 083a133 commit 484cd71

29 files changed

Lines changed: 2712 additions & 195 deletions

File tree

‎docs/migration-plan.md‎

Lines changed: 52 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -694,7 +694,7 @@ unless it says there is no replacement at all, which it says explicitly.
694694
| --- | --- | --- |
695695
| **0. Foundation** (built) | `spi`, `common3`, `collections`, `priority`, `progress`, `concurrent`, `discovery`, `index`, `struct`, `io3`, `events`, `context`, `execute` | nothing above |
696696
| **1. Application model** (built, less `scijava-desktop`) | `scijava-command` (a struct plus presentation metadata, the menu tree and its walk), `scijava-ui3` (toolkit-agnostic contracts), `scijava-desktop` | layer 0 |
697-
| **2. Toolkit bindings** | `scijava-swing`, `scijava-javafx`, headless | layer 1 |
697+
| **2. Toolkit bindings** | `scijava-awt` (and the AWT platform layer the others use), `scijava-swing`, `scijava-javafx`, headless | layer 1 |
698698
| **3. Application** | Fiji: which menus exist, branding, update sites, defaults | layer 2 |
699699

700700
Only layer 2 imports AWT or Swing. Layer 0 never mentions a user interface, so
@@ -953,6 +953,57 @@ after it.
953953
where Swing needs a hand-rolled header button; `KeyCombination.SHORTCUT_DOWN`
954954
says what Swing needs a `Toolkit` call to compute.
955955

956+
- **A third binding, `scijava-awt`**, is where "toolkit-agnostic" stops being
957+
a claim about two similar toolkits. It changed **nothing** in the contracts.
958+
What it did change is where the shared code lives:
959+
- `AbstractWidget` moved into `scijava-ui3`, because three bindings had
960+
written the same bookkeeping - find the node in the *current* tree, write
961+
through the model, do not mistake a refresh for the user typing. Two would
962+
have been a coincidence.
963+
- `Accelerator` moved into `scijava-command`, because Swing wants a
964+
`KeyStroke`, JavaFX a `KeyCombination` and AWT a `MenuShortcut`: three ways
965+
of *saying* a shortcut, one thing being said. A binding that parses `^+C`
966+
itself is a binding that can disagree about what it means.
967+
- AWT is the harshest case so far, and instructive for it: no spinner, no
968+
slider, no titled border, no collapsible pane, no icons in menus, and a
969+
`MenuShortcut` that cannot express alt. The number widget is a text field
970+
and a scroll bar honoring `min`, `max`, `stepSize` and the soft bounds;
971+
the collapsible group is a button that hides a panel; an accelerator AWT
972+
cannot say is dropped rather than approximated into some other key.
973+
**None of it asked the model or the contracts for anything.**
974+
- It also found a difference worth knowing: AWT's `TextComponent.setText`
975+
does not notify text listeners, where a Swing document would. Harmless
976+
here - the refresh guard covers it either way - but it is the kind of
977+
thing only a third toolkit tells you.
978+
979+
- **On the structure of `scijava-awt` and `scijava-swing`**, which SciJava
980+
Common got into four components (`scijava-ui-awt`, `scijava-ui-swing`,
981+
`imagej-ui-awt`, `imagej-ui-swing`): the evidence says the toolkit axis is
982+
not where the duplication was. `scijava-ui-swing` imported exactly six
983+
things from `scijava-ui-awt` - `AWTInputEventDispatcher`,
984+
`AWTDropTargetEventDispatcher`, `AWTColors`, `AWTWindowEventDispatcher`,
985+
`AWTWindows`, `AWTClipboard` - and **not one widget**, because
986+
`java.awt.Choice` and `JComboBox` have nothing whatever in common. So:
987+
- **Swing depends on AWT for the platform, never for widgets.** `Edt` is the
988+
first instance: the dispatch thread belongs to `java.awt.EventQueue`, and
989+
`SwingUtilities` merely forwards to it, so code that needs to reach the
990+
EDT need not drag in Swing. Colors, cursors, clipboard, drag-and-drop,
991+
window placement and screen geometry follow the same way.
992+
- **The widget types stay siblings.** `SwingWidget` could extend
993+
`AwtWidget` - `JComponent` is a `Component` - but discovery filters on
994+
`WidgetFactory.widgetType()`, so that would mean a pure-AWT application
995+
silently filling its dialogs with Swing controls the moment scijava-swing
996+
appeared on the classpath. Mixing the two is then an explicit adapter,
997+
which is what embedding an ImageJ 1.x canvas in a Swing frame will want
998+
anyway.
999+
- **The image-processing layer should not repeat the matrix.** What made
1000+
four components was (generic | ImageJ) x (AWT | Swing), and the ImageJ
1001+
half of that is mostly one thing: a canvas that paints a `BufferedImage`
1002+
and handles a tool's events. That is AWT code, and it works unchanged
1003+
inside a Swing frame - which is precisely what ImageJ 1.x has always done.
1004+
So the image layer wants an AWT canvas plus per-toolkit frames, not two
1005+
parallel implementations.
1006+
9561007
- **`scijava-ui3-test` is the anti-drift mechanism**: the sample commands and
9571008
a conformance suite that every binding extends - eight assertions about
9581009
widgets, three about menus. Swing and JavaFX render the same declarations

‎docs/migration.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -125,6 +125,7 @@ A **dropped** row is a successful outcome, not a gap.
125125
| `command` | `org.scijava.command`: `Command` is a `Runnable` whose `@Parameter` fields are its struct; `@Menu` (repeatable) carries the presentation metadata, read from the annotation index without loading the class. `CommandInfo` replaces `ModuleInfo` and needs no `Context`; `MenuTree` replaces `ShadowMenu`. There is no `DynamicCommand`: see `choicesFrom` and `@Group(membersFrom)` | ported |
126126
| `script`, `script.process` | scripting facade + `javax.script` / GraalVM polyglot / Appose adapters (Phase 3) | planned |
127127
| `widget` (`InputWidget`, `InputPanel`, `InputHarvester`, `WidgetModel`, `WidgetStyle`) | `org.scijava.ui3`: `Widget` is a view of a `ParameterNode`, `WidgetFactory` a discoverable `@Plugin`, `WidgetPanel` a widget holding widgets (so a group nests with no special case), and `WidgetPanels` walks the tree for every toolkit. `WidgetModel` has no equivalent - a widget reads the `ParameterModel` and the node directly, and `WidgetStyle`'s parsing is `Widgets.isStyle`/`styleValue`. `InputHarvester` is a `Preprocessor` that declines the run when the user dismisses the dialog, rather than setting a `canceled` flag on itself | ported |
128+
| `ui.awt` (satellite repo `scijava-ui-awt`) | `org.scijava.awt`: the widget set in pure `java.awt` - no spinner, so the number widget is a field and a scroll bar - plus `Edt`, the first of the AWT platform layer that the Swing binding shares. `AWTColors`, `AWTWindows`, `AWTClipboard`, `AWTInputEventDispatcher` and the drag-and-drop dispatchers belong there too, when the `input`/`tool` layer arrives; the `AWTUI`/`AWTApplicationFrame`/`AWTStatusBar` shell classes await the application layer | ported |
128129
| `ui.javafx` (satellite repo `scijava-ui-javafx`) | `org.scijava.javafx`: the same widget set as the Swing binding, plus `FxThread` for JavaFX's application thread. `JavaFXKeys`'s key-code mapping is worth keeping when the `input`/`tool` layer arrives; `JavaFXMenuCreator` is superseded by `FxMenus`, some 40 lines against `MenuCreator` | ported |
129130
| `ui.swing.widget` | `org.scijava.swing`: number (spinner, with an optional slider or scroll bar and labelled ticks), text (field, password, area, and `BigInteger`/`BigDecimal`, which a spinner cannot step), toggle, choice, file, message, and the panel and dialog. `SpinnerBigDecimalModel`, `SpinnerBigIntegerModel`, `SpinnerTypedNumberModel` and `SpinnerNumberModelFactory` have no equivalent: `SpinnerNumberModel` already steps in the type of the value it holds, and arbitrary precision goes to the text widget. MigLayout is gone, in favor of `GridBagLayout`: one fewer dependency, and one fewer automatic module. The button, color, date, file-list and radio-choice widgets are not ported yet - each earns its place when something asks for it | ported |
130131
| `menu` (`MenuCreator`, `AbstractMenuCreator`, `MenuService`, `ShadowMenu`) | `org.scijava.command`: `MenuTree` is the model and `MenuCreator`/`Menus` the toolkit-free walk, with `SwingMenus` the first implementation. `MenuService` has no equivalent: a menu bar is `MenuTree.of(Commands.discover(context))`, which is a line rather than a service | ported |

‎pom.xml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,7 @@
5757
<module>scijava-taglets</module>
5858
<!-- End implicit dependencies -->
5959

60+
<module>scijava-awt</module>
6061
<module>scijava-code-api</module>
6162
<module>scijava-collections</module>
6263
<module>scijava-command</module>

‎scijava-awt/pom.xml‎

Lines changed: 231 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,231 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
3+
<modelVersion>4.0.0</modelVersion>
4+
5+
<parent>
6+
<groupId>org.scijava</groupId>
7+
<artifactId>pom-scijava</artifactId>
8+
<version>44.0.0</version>
9+
<relativePath />
10+
</parent>
11+
12+
<artifactId>scijava-awt</artifactId>
13+
<version>1.0.0-SNAPSHOT</version>
14+
15+
<name>SciJava AWT</name>
16+
<description>AWT widgets and platform plumbing, with no Swing anywhere.</description>
17+
<url>https://github.com/scijava/scijava</url>
18+
<inceptionYear>2026</inceptionYear>
19+
<organization>
20+
<name>SciJava</name>
21+
<url>https://scijava.org/</url>
22+
</organization>
23+
<licenses>
24+
<license>
25+
<name>Simplified BSD License</name>
26+
<distribution>repo</distribution>
27+
</license>
28+
</licenses>
29+
30+
<developers>
31+
<developer>
32+
<id>ctrueden</id>
33+
<name>Curtis Rueden</name>
34+
<roles>
35+
<role>founder</role>
36+
<role>lead</role>
37+
<role>reviewer</role>
38+
<role>support</role>
39+
<role>maintainer</role>
40+
</roles>
41+
</developer>
42+
<developer>
43+
<id>gselzer</id>
44+
<name>Gabriel Selzer</name>
45+
<roles>
46+
<role>founder</role>
47+
<role>debugger</role>
48+
<role>reviewer</role>
49+
<role>support</role>
50+
</roles>
51+
</developer>
52+
</developers>
53+
<contributors>
54+
<contributor>
55+
<name>Johannes Schindelin</name>
56+
<properties><id>dscho</id></properties>
57+
</contributor>
58+
</contributors>
59+
60+
<mailingLists>
61+
<mailingList>
62+
<name>Image.sc Forum</name>
63+
<archive>https://forum.image.sc/tag/scijava</archive>
64+
</mailingList>
65+
</mailingLists>
66+
67+
<scm>
68+
<connection>scm:git:https://github.com/scijava/scijava</connection>
69+
<developerConnection>scm:git:git@github.com:scijava/scijava</developerConnection>
70+
<tag>HEAD</tag>
71+
<url>https://github.com/scijava/scijava</url>
72+
</scm>
73+
<issueManagement>
74+
<system>GitHub Issues</system>
75+
<url>https://github.com/scijava/scijava/issues</url>
76+
</issueManagement>
77+
<ciManagement>
78+
<system>GitHub Actions</system>
79+
<url>https://github.com/scijava/scijava/actions</url>
80+
</ciManagement>
81+
82+
<properties>
83+
<package-name>org.scijava.awt</package-name>
84+
85+
<license.licenseName>bsd_2</license.licenseName>
86+
<license.copyrightOwners>SciJava developers.</license.copyrightOwners>
87+
88+
<!-- Note: These versions must match across all component POMs! -->
89+
<scijava-command.version>1.0.0-SNAPSHOT</scijava-command.version>
90+
<scijava-context.version>1.0.0-SNAPSHOT</scijava-context.version>
91+
<scijava-discovery.version>1.0.1-SNAPSHOT</scijava-discovery.version>
92+
<scijava-index.version>1.0.0-SNAPSHOT</scijava-index.version>
93+
<scijava-ui3.version>3.0.0-SNAPSHOT</scijava-ui3.version>
94+
<scijava-ui3-test.version>3.0.0-SNAPSHOT</scijava-ui3-test.version>
95+
<scijava-common3.version>1.0.1-SNAPSHOT</scijava-common3.version>
96+
<scijava-execute.version>1.0.0-SNAPSHOT</scijava-execute.version>
97+
<scijava-harvest.version>1.0.0-SNAPSHOT</scijava-harvest.version>
98+
<scijava-priority.version>1.0.1-SNAPSHOT</scijava-priority.version>
99+
<scijava-struct.version>1.0.1-SNAPSHOT</scijava-struct.version>
100+
</properties>
101+
102+
<dependencies>
103+
<dependency>
104+
<groupId>org.scijava</groupId>
105+
<artifactId>scijava-common3</artifactId>
106+
<version>${scijava-common3.version}</version>
107+
</dependency>
108+
<dependency>
109+
<groupId>org.scijava</groupId>
110+
<artifactId>scijava-command</artifactId>
111+
<version>${scijava-command.version}</version>
112+
</dependency>
113+
<dependency>
114+
<groupId>org.scijava</groupId>
115+
<artifactId>scijava-context</artifactId>
116+
<version>${scijava-context.version}</version>
117+
</dependency>
118+
<dependency>
119+
<groupId>org.scijava</groupId>
120+
<artifactId>scijava-discovery</artifactId>
121+
<version>${scijava-discovery.version}</version>
122+
</dependency>
123+
<dependency>
124+
<groupId>org.scijava</groupId>
125+
<artifactId>scijava-index</artifactId>
126+
<version>${scijava-index.version}</version>
127+
</dependency>
128+
<dependency>
129+
<groupId>org.scijava</groupId>
130+
<artifactId>scijava-ui3</artifactId>
131+
<version>${scijava-ui3.version}</version>
132+
</dependency>
133+
<dependency>
134+
<groupId>org.scijava</groupId>
135+
<artifactId>scijava-execute</artifactId>
136+
<version>${scijava-execute.version}</version>
137+
</dependency>
138+
<dependency>
139+
<groupId>org.scijava</groupId>
140+
<artifactId>scijava-harvest</artifactId>
141+
<version>${scijava-harvest.version}</version>
142+
</dependency>
143+
<dependency>
144+
<groupId>org.scijava</groupId>
145+
<artifactId>scijava-priority</artifactId>
146+
<version>${scijava-priority.version}</version>
147+
</dependency>
148+
<dependency>
149+
<groupId>org.scijava</groupId>
150+
<artifactId>scijava-struct</artifactId>
151+
<version>${scijava-struct.version}</version>
152+
</dependency>
153+
154+
<!-- Third-party dependencies -->
155+
<dependency>
156+
<groupId>org.slf4j</groupId>
157+
<artifactId>slf4j-api</artifactId>
158+
</dependency>
159+
160+
<!-- Test scope dependencies -->
161+
<dependency>
162+
<groupId>org.scijava</groupId>
163+
<artifactId>scijava-ui3-test</artifactId>
164+
<version>${scijava-ui3-test.version}</version>
165+
<scope>test</scope>
166+
</dependency>
167+
<!--
168+
NB: so that the demos can say what they are doing. Turn it up with
169+
-Dorg.slf4j.simpleLogger.defaultLogLevel=debug
170+
-->
171+
<dependency>
172+
<groupId>org.slf4j</groupId>
173+
<artifactId>slf4j-simple</artifactId>
174+
<scope>test</scope>
175+
</dependency>
176+
<dependency>
177+
<groupId>org.junit.jupiter</groupId>
178+
<artifactId>junit-jupiter-api</artifactId>
179+
<scope>test</scope>
180+
</dependency>
181+
</dependencies>
182+
183+
<build>
184+
<plugins>
185+
<!--
186+
NB: the annotation index comes from scijava-index's annotation
187+
processor, which must be on the processor path: javac will not find
188+
it on the module path, and says nothing when it finds no processor at
189+
all, so the build would simply produce no index.
190+
-->
191+
<plugin>
192+
<artifactId>maven-compiler-plugin</artifactId>
193+
<configuration>
194+
<annotationProcessorPaths>
195+
<path>
196+
<groupId>org.scijava</groupId>
197+
<artifactId>scijava-index</artifactId>
198+
<version>${scijava-index.version}</version>
199+
</path>
200+
</annotationProcessorPaths>
201+
</configuration>
202+
</plugin>
203+
<plugin>
204+
<artifactId>maven-enforcer-plugin</artifactId>
205+
<executions>
206+
<execution>
207+
<id>enforce-package-rules</id>
208+
<goals>
209+
<goal>enforce</goal>
210+
</goals>
211+
<phase>test</phase>
212+
<configuration>
213+
<rules>
214+
<NoPackageCyclesRule implementation="org.scijava.maven.plugin.enforcer.NoPackageCyclesRule" />
215+
<NoSubpackageDependenceRule implementation="org.scijava.maven.plugin.enforcer.NoSubpackageDependenceRule" />
216+
</rules>
217+
</configuration>
218+
</execution>
219+
</executions>
220+
</plugin>
221+
<plugin>
222+
<artifactId>maven-javadoc-plugin</artifactId>
223+
<configuration>
224+
<links>
225+
<link>https://javadoc.scijava.org/Java11/</link>
226+
</links>
227+
</configuration>
228+
</plugin>
229+
</plugins>
230+
</build>
231+
</project>
Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
/*
2+
* #%L
3+
* AWT widgets and platform plumbing, with no Swing anywhere.
4+
* %%
5+
* Copyright (C) 2026 SciJava developers.
6+
* %%
7+
* Redistribution and use in source and binary forms, with or without
8+
* modification, are permitted provided that the following conditions are met:
9+
*
10+
* 1. Redistributions of source code must retain the above copyright notice,
11+
* this list of conditions and the following disclaimer.
12+
* 2. Redistributions in binary form must reproduce the above copyright notice,
13+
* this list of conditions and the following disclaimer in the documentation
14+
* and/or other materials provided with the distribution.
15+
*
16+
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17+
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18+
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19+
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
20+
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21+
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22+
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23+
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24+
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25+
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26+
* POSSIBILITY OF SUCH DAMAGE.
27+
* #L%
28+
*/
29+
30+
module org.scijava.awt {
31+
32+
exports org.scijava.awt;
33+
34+
// NB: one opens, to the container alone, so that it can inject and
35+
// construct these plugins. `opens` is not `exports`.
36+
opens org.scijava.awt to org.scijava.context;
37+
38+
requires transitive java.desktop;
39+
requires transitive org.scijava.ui3;
40+
requires transitive org.scijava.command;
41+
requires transitive org.scijava.context;
42+
requires org.scijava.discovery;
43+
requires org.scijava.priority;
44+
requires org.slf4j;
45+
46+
}

0 commit comments

Comments
 (0)