From 46c50ab87f1f84548d5a215aac491b478b9e2e13 Mon Sep 17 00:00:00 2001 From: Tig Date: Wed, 2 Oct 2024 14:20:19 -0600 Subject: [PATCH] API docs. Updated Button scenario --- Terminal.Gui/Input/Command.cs | 8 +++++--- Terminal.Gui/Views/Button.cs | 26 +++++++++++++++++--------- UICatalog/Scenarios/Buttons.cs | 15 ++++++++++++++- 3 files changed, 36 insertions(+), 13 deletions(-) diff --git a/Terminal.Gui/Input/Command.cs b/Terminal.Gui/Input/Command.cs index 5e17fe0df..98c681952 100644 --- a/Terminal.Gui/Input/Command.cs +++ b/Terminal.Gui/Input/Command.cs @@ -4,7 +4,7 @@ namespace Terminal.Gui; /// -/// Actions which can be performed by a . Commands are typically bound to keys via +/// Actions which can be performed by a . Commands are typically invoked via /// and mouse events. /// See also . /// @@ -17,13 +17,15 @@ public enum Command /// /// The default implementation in calls which raises the /// event. If the event is not handled, - /// the command is invoked on . This enables default Accept behavior. + /// the command is invoked on + /// - Any peer-view that is a with set to . + /// - The . This enables default Accept behavior. /// /// Accept, /// - /// 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). /// /// The default implementation in calls and then /// which raises the diff --git a/Terminal.Gui/Views/Button.cs b/Terminal.Gui/Views/Button.cs index 3f5b870ca..922357a38 100644 --- a/Terminal.Gui/Views/Button.cs +++ b/Terminal.Gui/Views/Button.cs @@ -7,18 +7,23 @@ namespace Terminal.Gui; -/// Button is a that provides an item that invokes raises the event. +/// +/// A View that raises the event when clicked with the mouse or when the +/// , Enter, or Space key is pressed. +/// /// /// /// Provides a button showing text that raises the event when clicked on with a mouse or -/// when the user presses SPACE, ENTER, or the . The hot key is the first letter or digit +/// when the user presses Enter, Space or the . The hot key is the first +/// letter or digit /// following the first underscore ('_') in the button text. /// /// Use to change the hot key specifier from the default of ('_'). /// -/// When the button is configured as the default () and the user presses the ENTER key, if -/// no other processes the key, the 's event will -/// be fired. +/// When the button is configured as the default () and the user causes the button to be +/// accepted the 's event will be raised. If the Accept event is not +/// handled, the Accept event on the . will be raised. This enables default Accept +/// behavior. /// /// /// Set to 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 } /// - /// Gets or sets whether the will show an indicator indicating it is the default Button. If - /// will be invoked when the user presses Enter and no other peer- processes the key. - /// If is not handled, the Gets or sets whether the will show an indicator indicating it is the default Button. If + /// Gets or sets whether the will show an indicator indicating it is the default Button. If + /// + /// will be invoked when the user presses Enter and no other peer- + /// processes the key. + /// If is not handled, the Gets or sets whether the will show an + /// indicator indicating it is the default Button. If /// command on the will be invoked. /// public bool IsDefault diff --git a/UICatalog/Scenarios/Buttons.cs b/UICatalog/Scenarios/Buttons.cs index 73275291c..bbe1601bc 100644 --- a/UICatalog/Scenarios/Buttons.cs +++ b/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)