From 3575473fa9a3055902896eb3b01856318d168709 Mon Sep 17 00:00:00 2001 From: Philipp Wagner Date: Wed, 18 Nov 2026 19:27:14 +0100 Subject: [PATCH] Open the setup wizard as a modal dialog Written-by: DeepSeek V4 Pro Written-by: Claude Fable 5.2 --- .../view/compose/wizard/SetupWizardWindow.kt | 156 ++++++++++++++++++ .../compose/wizard/SetupWizardLauncherTest.kt | 118 +++++++++++++ .../compose/wizard/SetupWizardWindowTest.kt | 78 +++++++++ 3 files changed, 352 insertions(+) create mode 100644 app-desktop/src/main/kotlin/kst4contest/view/compose/wizard/SetupWizardWindow.kt create mode 100644 app-desktop/src/test/kotlin/kst4contest/view/compose/wizard/SetupWizardLauncherTest.kt create mode 100644 app-desktop/src/test/kotlin/kst4contest/view/compose/wizard/SetupWizardWindowTest.kt diff --git a/app-desktop/src/main/kotlin/kst4contest/view/compose/wizard/SetupWizardWindow.kt b/app-desktop/src/main/kotlin/kst4contest/view/compose/wizard/SetupWizardWindow.kt new file mode 100644 index 00000000..edffa68a --- /dev/null +++ b/app-desktop/src/main/kotlin/kst4contest/view/compose/wizard/SetupWizardWindow.kt @@ -0,0 +1,156 @@ +package kst4contest.view.compose.wizard + +import androidx.compose.runtime.getValue +import androidx.compose.runtime.mutableStateOf +import androidx.compose.runtime.setValue +import androidx.compose.ui.awt.ComposeDialog +import kst4contest.controller.LoginConfiguration +import kst4contest.model.ChatPreferences +import kst4contest.view.compose.Kst4ContestTheme +import kst4contest.view.compose.WindowPlacementOnScreen +import kst4contest.view.compose.openOnEventThread +import java.awt.Dialog +import java.awt.Dimension +import java.util.concurrent.atomic.AtomicReference +import javax.swing.WindowConstants + +/** How a run of the setup wizard ended. */ +enum class SetupWizardOutcome { + /** The profile is set up, or its file could not be read: the wizard did not open. */ + NOT_SHOWN, + + /** Closed without saving; the file is as it was. */ + LATER, + + /** The answers are in the file. */ + SAVED, + + /** The answers are in the file and the operator wants the session started. */ + SAVED_AND_CONNECT, +} + +/** + * Writes the answers and says how the wizard ends. + * + * @return the outcome to close with, or null when the file could not be written -- the + * wizard then stays open, because "saved" would be a lie + */ +internal fun saveFromWizard( + state: SetupWizardState, + prefs: ChatPreferences, + connect: Boolean, +): SetupWizardOutcome? = + when { + !state.writeTo(prefs) -> null + connect -> SetupWizardOutcome.SAVED_AND_CONNECT + else -> SetupWizardOutcome.SAVED + } + +/** + * The setup wizard's window. + * + * A modal [ComposeDialog] opened through [openOnEventThread], the construction + * OperatorProfilePickerWindow uses and for the reason given there: a wait that does not + * pump events deadlocks once the caller is the event thread, and this one is called from + * `main` at startup and from the event thread when the menu rebuilds the runtime. + */ +object SetupWizardWindow { + + /** Runs before a profile's runtime exists, so there is no configured size to read. */ + private const val DIALOG_FONT_SIZE_SP = 12f + + private val DIALOG_SIZE = Dimension(640, 620) + + /** + * Opens the wizard and blocks until it is closed. + * + * @param prefs the profile's preferences; written only by Save + * @return never [SetupWizardOutcome.NOT_SHOWN] + */ + fun show(state: SetupWizardState, prefs: ChatPreferences): SetupWizardOutcome { + /* The window's X leaves this untouched: closing is "later". */ + val outcome = AtomicReference(SetupWizardOutcome.LATER) + + openOnEventThread { open(state, prefs, outcome) } + + return outcome.get() + } + + private fun open( + state: SetupWizardState, + prefs: ChatPreferences, + outcome: AtomicReference, + ) { + val languageStore = wizardLanguageStore(state) + var saveFailed by mutableStateOf(false) + + val dialog = ComposeDialog(owner = null, modalityType = Dialog.ModalityType.APPLICATION_MODAL) + dialog.title = languageStore.strings.wizardTitle + dialog.size = DIALOG_SIZE + WindowPlacementOnScreen.centreOnMainWindowScreen(dialog) + /* Disposed and not hidden: a hidden dialog keeps its window and Skia layer alive. */ + dialog.defaultCloseOperation = WindowConstants.DISPOSE_ON_CLOSE + + dialog.setContent { + Kst4ContestTheme( + darkMode = prefs.isGUI_darkModeActiveByDefault(), + baseFontSizeSp = DIALOG_FONT_SIZE_SP, + ) { + SetupWizardContent( + state = state, + languageStore = languageStore, + saveFailed = saveFailed, + onLater = { dialog.dispose() }, + onSave = { connect -> + val saved = saveFromWizard(state, prefs, connect) + if (saved == null) { + saveFailed = true + } else { + outcome.set(saved) + dialog.dispose() + } + }, + ) + } + } + + dialog.isVisible = true + } +} + +/** Decides whether the wizard opens for a profile, and opens it. */ +object SetupWizardLauncher { + + /** + * Opens the wizard when the profile needs it, before the profile's runtime is built. + * + * @param preferencesRelativeFileName the profile's preferences file below the + * application directory; a missing one is seeded from the bundled template, as + * the runtime itself would do + * @param forced the operator asked for the wizard from the menu + */ + @JvmStatic + fun runIfNeeded(preferencesRelativeFileName: String, forced: Boolean): SetupWizardOutcome = + run(ChatPreferences(preferencesRelativeFileName), forced, SetupWizardWindow::show) + + /** + * @param prefs bound to the profile's file and not read yet + * @param show opens the window; replaced in the tests + */ + internal fun run( + prefs: ChatPreferences, + forced: Boolean, + show: (SetupWizardState, ChatPreferences) -> SetupWizardOutcome, + ): SetupWizardOutcome { + /* + * A file that cannot be read is not a profile to set up: the wizard would start from + * compiled-in defaults and Save would write them over whatever the file holds. The + * runtime deals with such a file as it always did. + */ + if (!prefs.readPreferencesFromXmlFile()) return SetupWizardOutcome.NOT_SHOWN + + if (!forced && !LoginConfiguration.isUnconfigured(prefs)) return SetupWizardOutcome.NOT_SHOWN + + return show(SetupWizardState(prefs), prefs) + } +} diff --git a/app-desktop/src/test/kotlin/kst4contest/view/compose/wizard/SetupWizardLauncherTest.kt b/app-desktop/src/test/kotlin/kst4contest/view/compose/wizard/SetupWizardLauncherTest.kt new file mode 100644 index 00000000..6b76d42b --- /dev/null +++ b/app-desktop/src/test/kotlin/kst4contest/view/compose/wizard/SetupWizardLauncherTest.kt @@ -0,0 +1,118 @@ +package kst4contest.view.compose.wizard + +import kst4contest.model.ChatPreferences +import org.junit.jupiter.api.Assertions.assertArrayEquals +import org.junit.jupiter.api.Assertions.assertEquals +import org.junit.jupiter.api.Assertions.assertNull +import org.junit.jupiter.api.Assertions.assertTrue +import org.junit.jupiter.api.Test +import org.junit.jupiter.api.io.TempDir +import java.nio.file.Files +import java.nio.file.Path +import java.nio.file.StandardCopyOption + +/** When the wizard opens at all, decided without a window. */ +class SetupWizardLauncherTest(@TempDir private val directory: Path) { + + private fun templateFile(): Path { + val file = directory.resolve("preferences.xml") + ChatPreferences::class.java.getResourceAsStream(ChatPreferences.PREFERENCE_RESOURCE).use { template -> + Files.copy(requireNotNull(template), file, StandardCopyOption.REPLACE_EXISTING) + } + return file + } + + private fun configuredFile(): Path { + val file = templateFile() + ChatPreferences(file).apply { + assertTrue(readPreferencesFromXmlFile()) + setStn_loginCallSign("DL0TEST") + setStn_loginPassword("secret") + assertTrue(writePreferencesToXmlFile()) + } + return file + } + + private val neverShown: (SetupWizardState, ChatPreferences) -> SetupWizardOutcome = + { _, _ -> throw AssertionError("the wizard must not open here") } + + @Test + fun anUnconfiguredProfileOpensTheWizard() { + var shown = 0 + + val outcome = SetupWizardLauncher.run(ChatPreferences(templateFile()), forced = false) { _, _ -> + shown++ + SetupWizardOutcome.LATER + } + + assertEquals(1, shown) + assertEquals(SetupWizardOutcome.LATER, outcome) + } + + @Test + fun aConfiguredProfileStartsWithoutTheWizard() { + assertEquals( + SetupWizardOutcome.NOT_SHOWN, + SetupWizardLauncher.run(ChatPreferences(configuredFile()), forced = false, neverShown), + ) + } + + @Test + fun theMenuOpensItOnAConfiguredProfileToo() { + val outcome = SetupWizardLauncher.run(ChatPreferences(configuredFile()), forced = true) { state, _ -> + assertEquals(listOf(WizardSource.NEW, WizardSource.KEEP), state.loginSources) + SetupWizardOutcome.SAVED + } + + assertEquals(SetupWizardOutcome.SAVED, outcome) + } + + @Test + fun anUnreadableFileNeverOpensTheWizard() { + val garbage = directory.resolve("broken.xml") + Files.writeString(garbage, "this is not xml <<<") + val before = Files.readAllBytes(garbage) + + // Forced as well: a wizard over a file it could not read would save over it. + assertEquals( + SetupWizardOutcome.NOT_SHOWN, + SetupWizardLauncher.run(ChatPreferences(garbage), forced = true, neverShown), + ) + assertArrayEquals(before, Files.readAllBytes(garbage), "the unreadable file was touched") + } + + @Test + fun aFailedSaveKeepsTheWizardOpen() { + val source = ChatPreferences(templateFile()).apply { assertTrue(readPreferencesFromXmlFile()) } + val state = SetupWizardState(source).apply { + name = "Philipp" + next() + callsign = "DL0TEST" + password = "secret" + next() + locator = "JO50AA" + setBand(WizardBand.B144, true) + } + val unwritable = ChatPreferences(Files.createDirectory(directory.resolve("not-a-file"))) + + assertNull(saveFromWizard(state, unwritable, connect = true), "a failed write must not close the wizard") + } + + @Test + fun aSaveReportsWhetherToConnect() { + val file = templateFile() + val prefs = ChatPreferences(file).apply { assertTrue(readPreferencesFromXmlFile()) } + val state = SetupWizardState(prefs).apply { + name = "Philipp" + next() + callsign = "DL0TEST" + password = "secret" + next() + locator = "JO50AA" + setBand(WizardBand.B144, true) + } + + assertEquals(SetupWizardOutcome.SAVED, saveFromWizard(state, prefs, connect = false)) + assertEquals(SetupWizardOutcome.SAVED_AND_CONNECT, saveFromWizard(state, prefs, connect = true)) + } +} diff --git a/app-desktop/src/test/kotlin/kst4contest/view/compose/wizard/SetupWizardWindowTest.kt b/app-desktop/src/test/kotlin/kst4contest/view/compose/wizard/SetupWizardWindowTest.kt new file mode 100644 index 00000000..dfa87fc9 --- /dev/null +++ b/app-desktop/src/test/kotlin/kst4contest/view/compose/wizard/SetupWizardWindowTest.kt @@ -0,0 +1,78 @@ +package kst4contest.view.compose.wizard + +import kst4contest.model.ChatPreferences +import kst4contest.testing.Await.awaitUntil +import org.junit.jupiter.api.Assertions.assertEquals +import org.junit.jupiter.api.Assumptions.assumeFalse +import org.junit.jupiter.api.Test +import java.awt.EventQueue +import java.awt.GraphicsEnvironment +import java.awt.Window +import java.nio.file.Path +import java.time.Duration +import java.util.concurrent.Executors +import java.util.concurrent.Future +import java.util.concurrent.TimeUnit + +/** + * The wizard's dialog must open from both threads that open it: `main` at startup, and the + * event thread when the menu rebuilds the runtime. A latch-based wait deadlocked the profile + * picker in exactly the second case; see OperatorProfilePickerWindow. + */ +class SetupWizardWindowTest { + + private fun prefs() = ChatPreferences(Path.of("setup-wizard-window-test-unused.xml")) + + private fun showingDialog(): Window? = + Window.getWindows().firstOrNull { it.isShowing && it.javaClass.name.contains("ComposeDialog") } + + private val closer = Executors.newSingleThreadExecutor() + + /** Closes the dialog the way its X does, as soon as it is on screen. */ + private fun disposeOnceShowing(): Future<*> = + closer.submit { + awaitUntil(Duration.ofSeconds(10), "the wizard's dialog never appeared") { + showingDialog() != null + } + EventQueue.invokeLater { showingDialog()?.dispose() } + } + + @Test + fun closingTheWindowCountsAsLater() { + assumeFalse(GraphicsEnvironment.isHeadless(), "needs a display") + + try { + val closing = disposeOnceShowing() + val prefs = prefs() + + val outcome = SetupWizardWindow.show(SetupWizardState(prefs), prefs) + + assertEquals(SetupWizardOutcome.LATER, outcome) + assertEquals("", prefs.getStn_loginCallSign(), "closing the window wrote something") + closing.get(1, TimeUnit.SECONDS) + } finally { + closer.shutdownNow() + } + } + + @Test + fun opensAndReturnsWhenCalledOnTheEventThread() { + assumeFalse(GraphicsEnvironment.isHeadless(), "needs a display") + + val worker = Executors.newSingleThreadExecutor() + try { + val closing = disposeOnceShowing() + val prefs = prefs() + val call = worker.submit { + EventQueue.invokeAndWait { SetupWizardWindow.show(SetupWizardState(prefs), prefs) } + } + + // A deadlock here has no timeout of its own: without one this never completes. + call.get(20, TimeUnit.SECONDS) + closing.get(1, TimeUnit.SECONDS) + } finally { + worker.shutdownNow() + closer.shutdownNow() + } + } +}