API docs.

Updated Button scenario

Terminal.Gui/Input/Command.cs

@@ -4,7 +4,7 @@
 namespace Terminal.Gui;
 
 /// <summary>
-///     Actions which can be performed by a <see cref="View"/>. Commands are typically bound to keys via
+///     Actions which can be performed by a <see cref="View"/>. Commands are typically invoked via
 ///     <see cref="View.KeyBindings"/> and mouse events.
 ///     See also <see cref="View.InvokeCommand"/>.
 /// </summary>
@@ -17,13 +17,15 @@ public enum Command
     ///     <para>
     ///         The default implementation in <see cref="View"/> calls <see cref="View.RaiseAcceptEvent"/> which raises the
     ///         <see cref="View.Accept"/> event. If the event is not handled,
-    ///         the command is invoked on <see cref="View.SuperView"/>. This enables default Accept behavior.
+    ///         the command is invoked on
+    ///             - Any peer-view that is a <see cref="Button"/> with <see cref="Button.IsDefault"/> set to <see langword="true"/>.
+    ///             - The <see cref="View.SuperView"/>. This enables default Accept behavior.
     ///     </para>
     /// </summary>
     Accept,
 
     /// <summary>
-    ///     Performs a hotkey action (e.g. setting focus, accepting, and/or moving focus to the next View).
+    ///     Performs a hot key action (e.g. setting focus, accepting, and/or moving focus to the next View).
     ///     <para>
     ///         The default implementation in <see cref="View"/> calls <see cref="View.SetFocus"/> and then
     ///         <see cref="View.RaiseHotKeyCommandEvent"/> which raises the

Terminal.Gui/Views/Button.cs

@@ -7,18 +7,23 @@
 
 namespace Terminal.Gui;
 
-/// <summary>Button is a <see cref="View"/> that provides an item that invokes raises the <see cref="View.Accept"/> event.</summary>
+/// <summary>
+///     A View that raises the <see cref="View.Accept"/> event when clicked with the mouse or when the
+///     <see cref="View.HotKey"/>, <c>Enter</c>, or <c>Space</c> key is pressed.
+/// </summary>
 /// <remarks>
 ///     <para>
 ///         Provides a button showing text that raises the <see cref="View.Accept"/> event when clicked on with a mouse or
-///         when the user presses SPACE, ENTER, or the <see cref="View.HotKey"/>. The hot key is the first letter or digit
+///         when the user presses <c>Enter</c>, <c>Space</c> or the <see cref="View.HotKey"/>. The hot key is the first
+///         letter or digit
 ///         following the first underscore ('_') in the button text.
 ///     </para>
 ///     <para>Use <see cref="View.HotKeySpecifier"/> to change the hot key specifier from the default of ('_').</para>
 ///     <para>
-///         When the button is configured as the default (<see cref="IsDefault"/>) and the user presses the ENTER key, if
-///         no other <see cref="View"/> processes the key, the <see cref="Button"/>'s <see cref="View.Accept"/> event will
-///         be fired.
+///         When the button is configured as the default (<see cref="IsDefault"/>) and the user causes the button to be
+///         accepted the <see cref="Button"/>'s <see cref="View.Accept"/> event will be raised. If the Accept event is not
+///         handled, the Accept event on the <see cref="View.SuperView"/>. will be raised. This enables default Accept
+///         behavior.
 ///     </para>
 ///     <para>
 ///         Set <see cref="View.WantContinuousButtonPressed"/> to <see langword="true"/> to have the
@@ -78,7 +83,7 @@ public class Button : View, IDesignable
 
                         SetFocus ();
 
-                        // TODO: If `IsDefault` were a property on `View` *any* View could work this way. That's theoretical as 
+                        // TODO: If `IsDefault` were a property on `View` *any* View could work this way. That's theoretical as
                         // TODO: no use-case has been identified for any View other than Button to act like this.
                         // If Accept was not handled...
                         if (cachedIsDefault && SuperView is { })
@@ -150,9 +155,12 @@ public class Button : View, IDesignable
     }
 
     /// <summary>
-    ///     Gets or sets whether the <see cref="Button"/> will show an indicator indicating it is the default Button. If <see langword="true"/>
-    ///     <see cref="Command.Accept"/> will be invoked when the user presses <c>Enter</c> and no other peer-<see cref="View"/> processes the key.
-    ///     If <see cref="View.Accept"/> is not handled, the Gets or sets whether the <see cref="Button"/> will show an indicator indicating it is the default Button. If <see langword="true"/>
+    ///     Gets or sets whether the <see cref="Button"/> will show an indicator indicating it is the default Button. If
+    ///     <see langword="true"/>
+    ///     <see cref="Command.Accept"/> will be invoked when the user presses <c>Enter</c> and no other peer-
+    ///     <see cref="View"/> processes the key.
+    ///     If <see cref="View.Accept"/> is not handled, the Gets or sets whether the <see cref="Button"/> will show an
+    ///     indicator indicating it is the default Button. If <see langword="true"/>
     ///     <see cref="Command.Accept"/> command on the <see cref="View.SuperView"/> will be invoked.
     /// </summary>
     public bool IsDefault

UICatalog/Scenarios/Buttons.cs

@@ -32,9 +32,12 @@ public class Buttons : Scenario
         // This is the default button (IsDefault = true); if user presses ENTER in the TextField
         // the scenario will quit
         var defaultButton = new Button { X = Pos.Center (), Y = Pos.AnchorEnd (), IsDefault = true, Text = "_Quit" };
-        main.Accept += (s, e) => Application.RequestStop ();
+
         main.Add (defaultButton);
 
+        // Note we handle Accept on main, not defaultButton
+        main.Accept += (s, e) => Application.RequestStop ();
+
         var swapButton = new Button
         {
             X = 50,
@@ -50,6 +53,16 @@ public class Buttons : Scenario
                                  defaultButton.IsDefault = !defaultButton.IsDefault;
                                  swapButton.IsDefault = !swapButton.IsDefault;
                              };
+
+        defaultButton.Accept += (s, e) =>
+                                {
+                                    e.Handled = !defaultButton.IsDefault;
+
+                                    if (e.Handled)
+                                    {
+                                        MessageBox.ErrorQuery ("Error", "This button is no longer the Quit button; the Swap Default button is.", "_Ok");
+                                    }
+                                };
         main.Add (swapButton);
 
         static void DoMessage (Button button, string txt)