Skip to content
Pauta6.1.0

Confirm dialog

One question before anything the user made is removed, deleted, discarded or overwritten, asked the same way everywhere: the text names the thing and what happens to it, the confirming button is the action’s own verb in red, and Cancel is the way out and the default button. An action that can be taken back needs no question (CONF-01, CONF-07). One rule here reaches past the question before a destructive action: CONF-14, on where the buttons’ words come from, covers every dialog with two or more buttons.

Rules on this page 14
IDLevelRule
Rules
CONF-01MUST
Before anything the user made is removed, deleted, discarded or overwritten, the app asks first, unless the action can be taken back instead.
CONF-02MUST
In an app that asks before a destructive action (before it removes, deletes, discards or overwrites something, ends a running program, or runs a command that cannot be taken back), the question names the thing and what happens to it. A question that warns before something is run or pasted and destroys nothing (Termina’s before a multi-line paste), and a question before a harmless command (nux’s before a UPS command it does not count as risky), are not questions before a destructive action. This list says which questions the rules on a question’s form cover; it is wider than what CONF-01 requires a question or an undo for, which is only what the user made.
CONF-03MUST
In an app that asks before a destructive action, the question’s confirming button carries the action’s own verb (Delete files, Remove, Discard, Quit), never OK or Yes, and is drawn in red, the danger style (Editora’s style class for it is danger).
CONF-14MUST
Every dialog with two or more buttons words each button from the message catalog, never with JavaFX’s stock OK, Yes, No, Cancel, Apply or Close, which are worded in the JVM’s locale. That is every JavaFX Dialog the app shows, whatever it is for: a question, before a destructive action (CONF-02) or not, a text prompt, a pick from a list, a form. Only a message with one button is outside the rule. Like CONF-08 and CONF-12, it reaches past the question before a destructive action.
CONF-04MUST
In an app that asks before a destructive action, Cancel is the way out of the question: Escape and the window’s close button both answer Cancel, and nothing is lost on a dismissal.
CONF-13MUST
In an app that asks before a destructive action, every such question has one default button, and it is never the red one (Editora’s danger style class): Cancel where the only action is destructive, Save where saving is an option (CONF-05). The dialog opens with keyboard focus on the default button, so Enter in a question that has just opened keeps what the user has, on every OS, and the red action runs only from its own button: a click, or the focus moved to it with Tab and then Space, which presses the focused button on every OS.
States
CONF-05SHOULD
A question before unsaved changes are lost, where saving is an option, has three answers, drawn in this order: Cancel, Save in green and Discard in red (Editora’s style classes for the two are success and danger), with Cancel to the left of the actions as in every dialog (WIN-11). A Save that fails leaves the tab open.
CONF-06SHOULD
A question about ending a running program, which is not the user’s data, words the button Close, in red like every confirming button (CONF-03). Cancel is its default button, as in every question with a red action (CONF-13), so dismissing the dialog by any route keeps the program alive.
CONF-07SHOULD
Where the action can be taken back, the app asks nothing and offers Undo instead.
Behavior
CONF-08SHOULD
Every confirmation question, whether or not it is before a destructive action, comes before anything changes, and its action runs only on the action button. For a question before a destructive action both are MUSTs already (CONF-01, CONF-04); what this rule adds is every other question, such as a warning before something is pasted or run.
CONF-09SHOULD
One gesture asks one question. An action on many things asks once with the count (“Remove these 3 torrents?”, Torrenta’s “Apply to many torrents” for a bulk command). Closing every tab asks per unsaved buffer, selecting each tab first so the user sees what the question is about, and remembers a Discard answer for exactly the state that was shown.
CONF-10SHOULD
A delete that cannot be undone says so; one that leaves the files says that instead.
CONF-11SHOULD
A dangerous alternative (Force with Lease, Delete Anyway) is offered beside the safe one (Pull, then Push), in red, and only once the safe one has failed.
CONF-12SHOULD
A confirmation question can be tested without a screen: its words come from pure code, and a capture hook answers the dialog, so a UI test never presses a native button.
  • CONF-01 MUST Before anything the user made is removed, deleted, discarded or overwritten, the app asks first, unless the action can be taken back instead.
  • CONF-02 MUST In an app that asks before a destructive action (before it removes, deletes, discards or overwrites something, ends a running program, or runs a command that cannot be taken back), the question names the thing and what happens to it. A question that warns before something is run or pasted and destroys nothing (Termina’s before a multi-line paste), and a question before a harmless command (nux’s before a UPS command it does not count as risky), are not questions before a destructive action. This list says which questions the rules on a question’s form cover; it is wider than what CONF-01 requires a question or an undo for, which is only what the user made.
    • Check (code): the string of every question before a destructive action names the thing, by an argument for its name or count or in its own words (“Quit Editora?”), and says what happens to it.
    • Reference: Editora dialog.unsaved.header, dialog.discard.tracked; Torrenta RemoveConfirm.question, Actions.removeQuestion.
  • CONF-03 MUST In an app that asks before a destructive action, the question’s confirming button carries the action’s own verb (Delete files, Remove, Discard, Quit), never OK or Yes, and is drawn in red, the danger style (Editora’s style class for it is danger).
  • CONF-14 MUST Every dialog with two or more buttons words each button from the message catalog, never with JavaFX’s stock OK, Yes, No, Cancel, Apply or Close, which are worded in the JVM’s locale. That is every JavaFX Dialog the app shows, whatever it is for: a question, before a destructive action (CONF-02) or not, a text prompt, a pick from a list, a form. Only a message with one button is outside the rule. Like CONF-08 and CONF-12, it reaches past the question before a destructive action.
    • Why: a stock button is labeled from JavaFX’s own resources, in the JVM’s locale, so under menus in the language chosen in Settings a dialog can still say “Cancel” in another.
    • Check (code): in every Dialog the app shows with two or more buttons (an Alert of any type, a TextInputDialog, a ChoiceDialog, a Dialog the app fills itself), each button shows a string from the message catalog: its ButtonType is built with one, or its button’s text is set from the catalog before the dialog is shown. None is left as ButtonType.OK, ButtonType.YES, ButtonType.NO, ButtonType.CANCEL, ButtonType.APPLY or ButtonType.CLOSE, and none is the stock OK or Cancel that an Alert of type CONFIRMATION, a TextInputDialog and a ChoiceDialog come with. A dialog whose stock buttons are swapped for catalog-worded ones before it is shown passes (Torrenta’s StockButtons.translate). A dialog with one button is not judged. An app that shows no dialog with two or more buttons has nothing to judge, and passes.
    • Reference: Torrenta: RemoveConfirm.ask names the action from the catalog and takes Cancel from its StockButtons (cancel(), the catalog’s word on the CANCEL_CLOSE role), and every other dialog of two buttons goes through StockButtons.translate, which swaps the stock OK and Cancel for the catalog’s: the four alerts that ask in its Settings (ui/SettingsWindow.java: connecting and disconnecting sync, Reset to Defaults and the shortcuts), its nine text prompts and its two picks from a list (ui/MainWindow.java, ui/DetailPane.java and ui/SettingsWindow.java). Modula’s one dialog is a message with one button, so it has nothing to judge. The app template meets it: every dialog it shows goes through Dialogs.styled, which words the stock OK, Cancel, Yes, No, Apply and Close from the catalog before the dialog is shown and again when its buttons change, and its ui/Confirm.java names the action from the catalog (DialogsFxTest, everyDialogHasOneButtonOrderAndCatalogWords). Termina and Mirada meet it in their questions and not in their text prompts. Termina’s ui/Confirm.java, which its removals, its close-running-program question and its multi-line paste warning ask through, names both buttons from the catalog, and so does its Import configuration question (ui/ConfigTransfer.java); its Rename Tab prompt words OK from the catalog and keeps the stock Cancel (askForTabName in ui/TerminalWindow.java), and the prompt its setting commands ask a value through (settingHost in the same file) and its Create on GitHub prompt (createSyncRepositoryOnGitHub in ui/SettingsWindow.java) are TextInputDialogs with the stock OK and Cancel. Mirada’s ui/Confirm.java and its note form (ui/NoteDialog.java) name both buttons from the catalog; its Rename prompt (rename in ui/ViewerWindow.java) is a TextInputDialog with the stock OK and Cancel. Editora doesn’t yet. Its unsaved-changes and Quit questions name every button from the catalog (unsavedAlert and confirmQuit in ui/CloseCoordinator.java), but of its 64 CONFIRMATION alerts, 26 keep the stock OK and Cancel, the Project panel’s file delete (confirmDelete in ui/ProjectPanel.java) and Replace in Files (ui/SearchCoordinator.java) among them, and 22 more name the action beside a stock ButtonType.CANCEL, among them GitCoordinator.confirmDestructive, which every destructive Git action asks through. Its warnings that ask do the same: the four trust questions of ui/TrustPrompts.java name the action beside a stock Cancel, and the question before its MCP server is enabled (confirmEnableMcp in ui/MainController.java) keeps the stock OK and Cancel. So do its prompts and forms, these among them: the Create on GitHub prompt (ui/SettingsSyncPage.java), the reset-mode and revert-merge picks (ui/GitWindowCoordinator.java), the pick of a settings backup (ui/SettingsResetFlow.java), a macro’s command picker (ui/MacroSettingsPane.java) and the Java cleanups form (ui/JavaCleanupsDialog.java) keep the stock OK and Cancel, and the login form (ui/RemoteCoordinator.java) and the forms that export and import the configuration (ui/ExportConfigDialog.java, ui/ConfigImportFlow.java) name the action beside a stock ButtonType.CANCEL. nux doesn’t in any of its four dialogs of two buttons: the question before a risky command names Run beside a stock ButtonType.CANCEL, the one before a harmless command is a CONFIRMATION alert with the stock OK and Cancel (ui/CommandConfirmation.java), its credentials form adds ButtonType.OK and ButtonType.CANCEL (ui/CredentialsDialog.java), and its Save Profile prompt is a TextInputDialog with the stock pair (saveCurrentAsProfile in App.java).
  • CONF-04 MUST In an app that asks before a destructive action, Cancel is the way out of the question: Escape and the window’s close button both answer Cancel, and nothing is lost on a dismissal.
  • CONF-13 MUST In an app that asks before a destructive action, every such question has one default button, and it is never the red one (Editora’s danger style class): Cancel where the only action is destructive, Save where saving is an option (CONF-05). The dialog opens with keyboard focus on the default button, so Enter in a question that has just opened keeps what the user has, on every OS, and the red action runs only from its own button: a click, or the focus moved to it with Tab and then Space, which presses the focused button on every OS.
    • Why: Enter is the key a hurried hand presses, and Escape already cancels (CONF-04): with Cancel as the default, no single key destroys anything. JavaFX makes a button with the OK_DONE role the default by itself, so a named action is the default unless the dialog says otherwise. It also presses a focused button on Enter on Windows and Linux but not on macOS, so a question with no default button answers Enter differently on each OS. With Cancel as the default one difference is left, and it is JavaFX’s: once Tab has put the focus on the red button, Enter runs it on Windows and Linux and answers Cancel on macOS. Space is the key that does the same everywhere.
    • Check (code): in every question before a destructive action (CONF-02 says which those are), the code calls setDefaultButton(true) on Cancel, or on Save in the unsaved-changes question, and setDefaultButton(false) on the destructive action, so that one is not left a default button too, and it does both before the dialog is shown. JavaFX gives the opening focus to the first button that is a default button, so with one default button the dialog opens with the focus on it. No such question leaves the red action, or no button at all, as the default.
    • Reference: Termina ui/Confirm.java (Options.cancelIsDefault, which its close-running-program question sets), the app template’s ui/Confirm.java (dialog, which every destructive question of the template asks through) and nux ui/CommandConfirmation.java (a risky UPS command): each unsets the action’s default and sets Cancel’s as it builds the dialog, before it is shown. Editora does it in about twenty of its questions, each by hand: deleting for good what the trash cannot take (ProjectPanel.cancelByDefault), closing a terminal with a program running (ui/TerminalCoordinator.java), resetting settings (ui/SettingsResetFlow.java), trusting a folder (ui/TrustPrompts.java) among them. The rest don’t yet: Editora’s Git confirmations and Local History purges (ui/HistoryCoordinator.java), Torrenta’s RemoveConfirm, Mirada’s Confirm, and Termina’s removals and its Import configuration question leave the red action as the default, so Enter runs it; Torrenta’s four Settings questions (CONF-03) leave OK as the default, and so do questions of Editora’s that keep the stock OK, its delete to the trash (confirmDelete in ui/ProjectPanel.java, which moves the default only when a file cannot go to the trash), its Revert and its Save As overwrite among them; Editora’s unsaved-changes and Quit questions have no default button. nux’s question before a command it does not count as risky leaves the stock OK as the default too, but it is not a question before a destructive action (CONF-02).
  1. 1Window title: a short name for the question ("Remove feed", "Unsaved changes"). Torrenta's header repeats it; Editora's unsaved-changes question has the question itself as its header ("Save changes to Main.java before closing?"). A plain confirmation, no icon in the title and no app name.
  2. 2Header, when the question is long enough to need one. Editora's Git confirmations set none and put the whole message in the content; Torrenta's header names the action and the content asks the question.
  3. 3The question names the thing and the consequence. How many ("these 3 torrents", a {0,choice,…} plural), which one ("the feed “Linux ISOs” and its articles"), what stays ("The downloaded files stay on disk."), and "This cannot be undone." only when it is true. Termina's multi-line paste shows the text itself in an expandable area, so the decision is made on what will be sent.
  4. 4The action button carries the action's verb (Delete files, Remove, Discard, Quit, Close), never OK or Yes, and the danger style: red, not the accent. It sits to the right of Cancel on every OS, and it is never the default button.
  5. 5Cancel, in the catalog's word, with the CANCEL_CLOSE role: Escape and the window's close button both answer Cancel. It is the default button, so it wears the accent, holds the focus when the dialog opens, and Enter answers it too.
Unsaved changes
Save changes to Main.java before closing?
CancelSaveDiscard
Remove, files kept
Remove this torrent? The downloaded files stay on disk.
CancelRemove
A program is running
Close this tab? bash (top) is still running. Closing will end it.
CancelClose
Undo instead of a question
Undo Removed Ubuntu ISOC-z
  • CONF-05 SHOULD A question before unsaved changes are lost, where saving is an option, has three answers, drawn in this order: Cancel, Save in green and Discard in red (Editora’s style classes for the two are success and danger), with Cancel to the left of the actions as in every dialog (WIN-11). A Save that fails leaves the tab open.
    • Check (code): the unsaved-changes alert draws Cancel, Save and Discard in that order, on the ButtonBar’s one fixed order and not the order its ButtonTypes were added in, and styles Save and Discard; and when Save is chosen and the save fails, the close is abandoned, so the tab stays open.
    • Reference: Editora CloseCoordinator.unsavedAlert, MainController.styleUnsavedChangesButtons, for the three answers and their styles; it still draws them Save, Discard, Cancel.
  • CONF-06 SHOULD A question about ending a running program, which is not the user’s data, words the button Close, in red like every confirming button (CONF-03). Cancel is its default button, as in every question with a red action (CONF-13), so dismissing the dialog by any route keeps the program alive.
  • CONF-07 SHOULD Where the action can be taken back, the app asks nothing and offers Undo instead.
    • Check (by hand): close a clean tab and reopen it with Reopen Closed Tab; in Mirada, trash an image and undo.
    • Reference: Mirada moves an image to the trash at once and offers Undo; Torrenta asks before removing a torrent but also keeps the removal on its undo stack for ten minutes (UndoStack.KEEP_MS); Editora ClosedTabs.
PropertyValueReference
KindAlert(CONFIRMATION) owned by the window (initOwner), shown with showAndWait; the answer defaults to Cancel when the dialog is closed any other wayGitCoordinator.confirmDestructive, RemoveConfirm.ask
ButtonsA ButtonType with the action’s name and the OK_DONE role, and Cancel with CANCEL_CLOSE, both named from the catalog (CONF-14). Drawn in one fixed order on every OS, Cancel first (WIN-11)RemoveConfirm.ask, Torrenta’s StockButtons
Action buttondanger style class: the theme’s .button.danger fills it -color-danger-emphasis with emphasis text. Save in the unsaved question: successMainController.styleUnsavedChangesButtons, styleQuitButtonAsDanger
Default buttonCancel, or Save in the unsaved-changes question: setDefaultButton(true) on it and setDefaultButton(false) on the action, because JavaFX makes an OK_DONE button the default by itself. CONF-13 is the rule, and its Reference says which questions in which app do itTermina Confirm, nux CommandConfirmation
FontThe UI font sheet attached to the dialog pane, because a dialog is its own scene and inherits nothing from the windowTorrenta Fonts.installUiFont(DialogPane), Editora App.installUiFont (every window)
StylesheetDialogs.styled adds app.css to a dialog that needs the app’s own rules (About); the -color-* tokens and .button.danger resolve from the theme either wayDialogs
TextThe question in the content; a header only when the question needs a name over it. Counts as plurals, names in quotes, the consequence spelled outActions.removeQuestion, confirm.remove.<kind>
StringsOne key per kind, header and question both, tested to exist for every kindRemoveConfirm.Kind, RemoveConfirmTest
  • CONF-08 SHOULD Every confirmation question, whether or not it is before a destructive action, comes before anything changes, and its action runs only on the action button. For a question before a destructive action both are MUSTs already (CONF-01, CONF-04); what this rule adds is every other question, such as a warning before something is pasted or run.
    • Check (code): every confirmation helper returns true on the action button alone, and its caller acts only on true, for the questions that are not before a destructive action as for those that are.
    • Reference: Torrenta RemoveConfirm.ask; Editora GitCoordinator.confirmDestructive. For a question that is not before a destructive action: Termina’s multi-line paste warning, asked through ui/Confirm.java, whose ask is true for the action button alone, and nux’s question before a harmless command (ui/CommandConfirmation.java, confirmed).
  • CONF-09 SHOULD One gesture asks one question. An action on many things asks once with the count (“Remove these 3 torrents?”, Torrenta’s “Apply to many torrents” for a bulk command). Closing every tab asks per unsaved buffer, selecting each tab first so the user sees what the question is about, and remembers a Discard answer for exactly the state that was shown.
  • CONF-10 SHOULD A delete that cannot be undone says so; one that leaves the files says that instead.
    • Check (code): “This cannot be undone.” appears only in the strings of actions that cannot be undone.
    • Reference: Editora dialog.discard.tracked; Torrenta actions.removeQuestion.delete.
  • CONF-11 SHOULD A dangerous alternative (Force with Lease, Delete Anyway) is offered beside the safe one (Pull, then Push), in red, and only once the safe one has failed.
    • Check (code): the force path is reached only from the safe command’s failure result.
    • Reference: Editora GitBranchCoordinator.offerAfterRejection (Force with Lease after a rejected push), confirmForceDelete (Delete Anyway after NOT_FULLY_MERGED).
  • CONF-12 SHOULD A confirmation question can be tested without a screen: its words come from pure code, and a capture hook answers the dialog, so a UI test never presses a native button.
    • Check (code): the header and the question of every kind are built by pure functions, which need no dialog to call, and the confirmation helper has a hook that answers the dialog in a test without showing it. A test that asserts it is the surest evidence.
    • Reference: Torrenta RemoveConfirm.header, question, answerForCapture; RemoveConfirmTest.
KeyEnglish
dialog.unsaved.title / dialog.unsaved.headerUnsaved changes / Save changes to {0} before closing?
dialog.save / dialog.discard / dialog.cancelSave / Discard / Cancel
dialog.quit.header / dialog.quit.buttonQuit Editora? / Quit
dialog.discard.trackedDiscard all changes to “{0}”? This cannot be undone.
dialog.discardAll.actionDiscard All
dialog.deleteBranch.forceDelete Anyway
confirm.remove.feed.header / confirm.remove.feedRemove feed / Remove the feed “{0}” and its articles? The torrents already added stay.
actions.removeQuestion.deleteRemove this torrent and delete the downloaded files? This cannot be undone.
window.remove.button.delete / common.remove / common.cancelDelete files / Remove / Cancel
dialog.closeRunning / dialog.closeAnyway (Termina)Close this tab? / Close

Editora asks for unsaved changes, Quit with busy terminals, pinned tabs, Git discards and branch deletions, and Local History purges through Alert with named buttons. Not all of its questions do yet: 26 of its confirmations still offer JavaFX’s stock OK and Cancel, among them the Project panel’s file delete (ui/ProjectPanel.java, confirmDelete) and Replace in Files (ui/SearchCoordinator.java), which CONF-03 and CONF-14 do not allow, and 22 more, the Git confirmations’ helper among them, name the action but keep JavaFX’s stock Cancel, which CONF-14 does not allow. Torrenta’s RemoveConfirm serves the torrent list, feeds, rules, watched folders, search providers, engine profiles, categories, tags and saved views with one shape. Termina asks before closing a tab with a running program and before a multi-line paste. Mirada’s Confirm asks before removing a bookmark or discarding an edit, with a named red button; its trash is undoable. nux asks before a risky UPS command with a named Run button and Cancel as the default, though not in red, and its Cancel is JavaFX’s stock one; its question before a harmless command keeps the stock OK and Cancel. Modula asks nothing: the Remove row of a preset’s right-click menu removes it at once, with no undo, which CONF-01 does not allow; nor does it allow nux’s Profiles → Delete, which also asks nothing. Four of Torrenta’s questions in Settings (disconnecting sync, Reset to Defaults, Reset All Shortcuts and taking a shortcut back) are answered with a catalog-worded OK, not the action’s verb in red.

Pauta 6.1.0 · · Changelog · This page in the latest edition