8.2.1. Schnellstart

Der Einstieg verwendet zwei getrennte Checkouts: NeitzelLib enthält die Laufzeitbibliothek und die Beispielanwendung, NeitzelFXDesigner den Editor und seine Projektwerkzeuge. Die folgenden Befehle werden jeweils im genannten Verzeichnis ausgeführt. Absolute Pfade sind durch die eigenen Installationspfade zu ersetzen.

Falls die Checkouts noch nicht vorhanden sind, werden beide Repositories in einem gemeinsamen Arbeitsverzeichnis geklont:

git clone https://gitea.neitzel.de/konrad/NeitzelLib.git
git clone https://gitea.neitzel.de/konrad/NeitzelFXDesigner.git

Für eingerichteten SSH-Zugriff lautet die kanonische Designer-Remote ssh://git@gitea.neitzel.de:2222/konrad/NeitzelFXDesigner.git. Die Dokumentation beschreibt den aktuellen Entwicklungsstand auf main; lokale Änderungen in bestehenden Checkouts werden für den Einstieg nicht verworfen.

Im NeitzelLib-Checkout werden mit einem vollständigen JDK 21 und Maven das Beispiel und seine benötigten Module installiert. Anschließend startet nur das Anwendungsmodul.

export JAVA_HOME=/absoluter/pfad/zum/jdk-21
mvn -B -ntp -pl fx-example -am -Dmaven.test.failure.ignore=false install
mvn -pl fx-example javafx:run

Beim zweiten Befehl darf -am nicht ergänzt werden: Die übergeordneten Bibliotheksmodule haben keinen Anwendungseinstieg. Der Launcher Main startet DeskApp. Diese Klasse erzeugt die Person und den Injection-Kontext und lädt view/Desk.fxml über den NeitzelLib-ViewLoader.

Die Person heißt zunächst Ada Lovelace. Name und Adresse lassen sich bearbeiten, Besuche und Tags ergänzen. Die Besuchsliste versorgt sowohl die Tabelle als auch die wiederholten Besuchsformulare. Die Beschreibung des Referenzbeispiels erklärt dessen Aufbau und Bindings. Vor dem nächsten Schritt wird die Anwendung wieder geschlossen.

Testergebnisse prüfen: Der NeitzelLib-Parent setzt derzeit testFailureIgnore=true fest. Die zusätzliche Kommandozeilenoption überschreibt diese Einstellung nicht. Deshalb sind die vorhandenen TEST-*.xml unter target/surefire-reports in core, injection, fx und fx-example auf Fehler zu prüfen. Ein Maven-Ergebnis BUILD SUCCESS allein reicht nicht.

Wer ein eigenes JavaFX-Projekt beginnt, richtet zunächst mit dem JavaFX-Schnellstart der Bibliothek eine unabhängig startbare NeitzelLib-Anwendung ein. Die Designer-Konfiguration kommt danach hinzu. Die Anwendung benötigt weder Scene Builder Kit noch eine Abhängigkeit auf den Editor.

Im Designer-Checkout wird JDK 25 verwendet:

export JAVA_HOME=/absoluter/pfad/zum/jdk-25
./mvnw -B -ntp install
./mvnw -B -ntp -pl designer-standalone \
  org.apache.maven.plugins:maven-dependency-plugin:3.6.1:build-classpath \
  -DincludeScope=runtime -Dmdep.outputFile=target/runtime-classpath.txt

Dadurch stehen die gemeinsamen Module, die kleine Preview-API, der Model-Prozessor und das Maven-Werkzeug zur Erfassung der Anwendung im lokalen Repository bereit. Der Befehl veröffentlicht nichts und baut noch kein IntelliJ-Plugin.

Ein frisch gebautes NeitzelLib-JAR kann wegen geänderter Archiv-Zeitstempel andere Prüfsummen haben als der im Designer dokumentierte Referenzstand. Die strengen Skripte check-bootstrap.py und package-standalone.py prüfen genau diese gespeicherten Artefakte. Nach einem eigenen Bibliotheks-Build wird deshalb zunächst der unten beschriebene Entwicklungsstart verwendet. Die gespeicherten Prüfsummen werden nicht einfach ersetzt, um eine Prüfung zu umgehen. Das Vorgehen zur erneuten Qualifikation steht unter Prüfen und Weiterentwickeln.

Das Beispiel enthält bereits die notwendigen Dateien:

Mit JDK 21 im NeitzelLib-Checkout lässt sich das Profil prüfen:

export JAVA_HOME=/absoluter/pfad/zum/jdk-21
mvn -B -ntp -pl fx-example -am -Pdesigner-preview \
  -Dmaven.test.failure.ignore=false verify

Auch hier sind die Testberichte maßgeblich. Das Profil erzeugt Metadaten für Person, Address und Note. Es ersetzt den vorhandenen, handgeschriebenen PersonViewModel nicht durch eine generierte Standardklasse. Ohne das Profil hat die normale Anwendung keine Preview-API-Abhängigkeit. Beim Wechsel zwischen Profilen entfernt ein clean alte generierte Dateien und Testklassen.

Im Designer-Checkout erzeugt der folgende Helfer die lokalen Einstellungen:

python3 scripts/configure-library-example.py \
  --library /absoluter/pfad/zu/NeitzelLib \
  --target-java-home /absoluter/pfad/zum/jdk-21

Er schreibt .neitzel-fx-designer/runtimes.json und host.properties in den Bibliotheks-Checkout. Diese Dateien werden nicht versioniert. Sie enthalten JDK-Pfade, den Designer-Maven-Wrapper als ausdrücklich gewählten Ersatz und die gebauten Worker-JARs. Vorhandene Einstellungen werden nicht überschrieben; sie werden bei Bedarf direkt bearbeitet.

Im Designer-Checkout wird wieder JDK 25 gewählt:

export JAVA_HOME=/absoluter/pfad/zum/jdk-25
"$JAVA_HOME/bin/java" --enable-native-access=ALL-UNNAMED \
  -cp "designer-standalone/target/classes:$(cat designer-standalone/target/runtime-classpath.txt)" \
  de.neitzel.fxdesigner.standalone.Launcher \
  /absoluter/pfad/zu/NeitzelLib/.neitzel-fx-designer/host.properties \
  /absoluter/pfad/zu/NeitzelLib/fx-example/src/main/resources/de/neitzel/fx/example/view/Desk.fxml

Der Klassenpfadtrenner : gehört zum hier geprüften macOS-Aufruf. Dieser Befehl ist kein Windows-Startskript.

Wenn bereits ein qualifiziertes App-Abbild vorliegt, kann dessen gebündelte Laufzeit verwendet werden:

"/pfad/zu/NeitzelFXDesigner.app/Contents/MacOS/NeitzelFXDesigner" \
  --configuration /absoluter/pfad/zu/NeitzelLib/neitzel-fx-designer.json \
  --settings /absoluter/pfad/zu/NeitzelLib/.neitzel-fx-designer/runtimes.json \
  --maven /absoluter/pfad/zu/NeitzelFXDesigner/mvnw \
  /absoluter/pfad/zu/NeitzelLib/fx-example/src/main/resources/de/neitzel/fx/example/view/Desk.fxml

Die App bringt ihre Host-Laufzeit und Worker-Werkzeuge mit. Das konfigurierte JDK der Anwendung bleibt trotzdem erforderlich.

Bei mehreren Kontexten ist zusätzlich --context kontextname erforderlich; bei genau einem Kontext kann die Angabe entfallen. --maven dient als ausdrücklich gewählter Ersatz, wenn das Projekt keinen eigenen Maven-Wrapper besitzt. Die aktive Kontextauswahl wird in weitere Component-Editoren übernommen.

Ohne das abschließende FXML-Argument öffnet der konfigurierte Launcher eine Dateiauswahl für die View. --help und --version funktionieren ohne JavaFX-Fenster. Unbekannte, doppelte oder unvollständige Optionen enden mit einer Verwendungshilfe und Exitcode 2.

Die ältere Konfigurationsform bleibt verfügbar:

"/pfad/zu/NeitzelFXDesigner.app/Contents/MacOS/NeitzelFXDesigner" \
  --launch /absoluter/pfad/zu/NeitzelLib/.neitzel-fx-designer/host.properties \
  /absoluter/pfad/zu/NeitzelLib/fx-example/src/main/resources/de/neitzel/fx/example/view/Desk.fxml

Auch die bisherige positionale Form host.properties View.fxml wird unterstützt. Diese Formen behalten die ausdrücklichen Werkzeugpfade aus host.properties; die Projektoptionen verwenden dagegen die Werkzeuge des App-Bündels.

Der Start ist derzeit kommandozeilenorientiert. Ein Doppelklick auf eine unkonfigurierte App im Finder ist noch kein Projektstart. Finder-Projektauswahl, Dateizuordnungen und das grafische Auswählen oder Merken mehrerer Kontexte sind damit nicht umgesetzt. Die optionale Dateiauswahl für FXML ist kein Einrichtungsassistent und war nicht Teil der automatisierten nativen Auswahlprüfung.

Mit Build and Refresh wird die Anwendung in einer isolierten Kopie gebaut. Danach erscheinen die Components mit Bildern aus ihrer tatsächlichen Laufzeit. Unter Bindings → Direct bindings ist beispielsweise nameField.text mit name verbunden. Für das Alter verwendet die View den AgeConverter.

Interactive preview öffnet die bedienbare Anwendung mit einer frischen Person. Änderungen an deren Daten betreffen nur diese Vorschau. Open Component auf der Adresse öffnet AddressForm.fxml in einem weiteren Editor. Ein erneuter Aufruf aktiviert den vorhandenen Editor. Open Row Component öffnet entsprechend VisitRow.fxml.

Jede View hat ein eigenes Beispiel: desk, address, visit, row oder note. Der Auswahldialog der übergeordneten View zeigt nicht ungefiltert alle fünf an. Layoutänderungen, Undo/Redo, Speichern und erneutes Öffnen arbeiten auf derselben maßgeblichen FXML-Datei.

Die Rollenwerte der ChoiceBox werden im Beispiel durch DeskController.initialize() eingetragen. Das vermeidet eine derzeitige Einschränkung der Designer-Projektion bei importierten Anwendungs-Enums. NeitzelLib selbst verbietet FXML-Enum-Konstanten nicht.