Improved API docs

Terminal.Gui/Views/Shortcut.cs

@@ -1,6 +1,4 @@
 using System.ComponentModel;
-using System.Reflection.Metadata;
-using Terminal.Gui.Analyzers.Internal.Attributes;
 
 namespace Terminal.Gui;
 
@@ -21,11 +19,11 @@ namespace Terminal.Gui;
 ///         be invoked regardless of what View has focus, enabling an application-wide keyboard shortcut.
 ///     </para>
 ///     <para>
-///         A Shortcut displays the command text on the left side, the help text in the middle, and the key binding on the
-///         right side.
+///         By default, a Shortcut displays the command text on the left side, the help text in the middle, and the key binding on the
+///         right side. Set <see cref="AlignmentModes"/> to <see cref="AlignmentModes.EndToStart"/> to reverse the order.
 ///     </para>
 ///     <para>
-///         The command text can be set by setting the <see cref="CommandView"/>'s Text property.
+///         The command text can be set by setting the <see cref="CommandView"/>'s Text property or by setting <see cref="View.Title"/>.
 ///     </para>
 ///     <para>
 ///         The help text can be set by setting the <see cref="HelpText"/> property or by setting <see cref="View.Text"/>.
@@ -38,8 +36,13 @@ namespace Terminal.Gui;
 public class Shortcut : View
 {
     /// <summary>
-    ///  Creates a new instance of <see cref="Shortcut"/>;
+    ///     Creates a new instance of <see cref="Shortcut"/>.
     /// </summary>
+    /// <remarks>
+    ///     <para>
+    ///         This is a helper API that mimics the V1 API for creating StatusItems.
+    ///     </para>
+    /// </remarks>
     /// <param name="key"></param>
     /// <param name="commandText"></param>
     /// <param name="action"></param>
@@ -63,7 +66,7 @@ public class Shortcut : View
         CommandView = new ()
         {
             Width = Dim.Auto (),
-            Height = Dim.Auto (),
+            Height = Dim.Auto ()
         };
 
         HelpView.Id = "_helpView";
@@ -117,18 +120,22 @@ public class Shortcut : View
         Dim GetWidthDimAuto ()
         {
             // TODO: PosAlign.CalculateMinDimension is a hack. Need to figure out a better way of doing this.
-            return Dim.Auto (DimAutoStyle.Content, minimumContentDim: Dim.Func (() => PosAlign.CalculateMinDimension (0, Subviews, Dimension.Width)), maximumContentDim: Dim.Func (() => PosAlign.CalculateMinDimension (0, Subviews, Dimension.Width)));
+            return Dim.Auto (
+                             DimAutoStyle.Content,
+                             Dim.Func (() => PosAlign.CalculateMinDimension (0, Subviews, Dimension.Width)),
+                             Dim.Func (() => PosAlign.CalculateMinDimension (0, Subviews, Dimension.Width)));
         }
     }
 
     /// <summary>
     ///     Creates a new instance of <see cref="Shortcut"/>.
     /// </summary>
-    public Shortcut () : this (Gui.Key.Empty, string.Empty, null) { }
+    public Shortcut () : this (Key.Empty, string.Empty, null) { }
 
     /// <summary>
     ///     Gets or sets the <see cref="Orientation"/> for this <see cref="Shortcut"/>. The default is
-    ///     <see cref="Orientation.Horizontal"/>, which is ideal for status bars and toolbars. If set to <see cref="Orientation.Vertical"/>,
+    ///     <see cref="Orientation.Horizontal"/>, which is ideal for status bars and toolbars. If set to
+    ///     <see cref="Orientation.Vertical"/>,
     ///     the Shortcut will be configured for vertical layout, which is ideal for menus.
     /// </summary>
     public Orientation Orientation { get; set; } = Orientation.Horizontal;
@@ -136,7 +143,8 @@ public class Shortcut : View
     private AlignmentModes _alignmentModes = AlignmentModes.StartToEnd | AlignmentModes.IgnoreFirstOrLast;
 
     /// <summary>
-    ///      Gets or sets the <see cref="AlignmentModes"/> for this <see cref="Shortcut"/>. The default is <see cref="AlignmentModes.StartToEnd"/>.
+    ///     Gets or sets the <see cref="AlignmentModes"/> for this <see cref="Shortcut"/>. The default is
+    ///     <see cref="AlignmentModes.StartToEnd"/>.
     /// </summary>
     public AlignmentModes AlignmentModes
     {
@@ -215,7 +223,7 @@ public class Shortcut : View
 
                     case 2:
                         // Scrunch just the right margin
-                        var t = GetMarginThickness ();
+                        Thickness t = GetMarginThickness ();
                         HelpView.Margin.Thickness = new (t.Right, t.Top, t.Left - 1, t.Bottom);
 
                         break;
@@ -241,6 +249,7 @@ public class Shortcut : View
                 // Reset to default
                 //SetCommandViewDefaultLayout();
                 SetHelpViewDefaultLayout ();
+
                 //SetKeyViewDefaultLayout ();
             }
         }
@@ -250,12 +259,10 @@ public class Shortcut : View
     {
         if (Orientation == Orientation.Vertical)
         {
-            return new Thickness (1, 0, 1, 0);
-        }
-        else
-        {
-            return new Thickness (1, 0, 1, 0);
+            return new (1, 0, 1, 0);
         }
+
+        return new (1, 0, 1, 0);
     }
 
     private Color? _savedForeColor;
@@ -304,7 +311,6 @@ public class Shortcut : View
         {
             SetFocus ();
         }
-
     }
 
     #region Command
@@ -374,6 +380,7 @@ public class Shortcut : View
 
             _commandView.MouseClick += Shortcut_MouseClick;
             _commandView.Accept += CommandViewAccept;
+
             _commandView.HotKeyChanged += (s, e) =>
                                           {
                                               if (e.NewKey != Key.Empty)
@@ -411,10 +418,9 @@ public class Shortcut : View
     {
         CommandView.Margin.Thickness = GetMarginThickness ();
         CommandView.X = Pos.Align (Alignment.End, AlignmentModes);
-        CommandView.Y = 0;//Pos.Center ();
+        CommandView.Y = 0; //Pos.Center ();
     }
 
-
     private void Shortcut_TitleChanged (object sender, StateEventArgs<string> e)
     {
         // If the Title changes, update the CommandView text.
@@ -436,7 +442,7 @@ public class Shortcut : View
     {
         HelpView.Margin.Thickness = GetMarginThickness ();
         HelpView.X = Pos.Align (Alignment.End, AlignmentModes);
-        HelpView.Y = 0;//Pos.Center ();
+        HelpView.Y = 0; //Pos.Center ();
         HelpView.Width = Dim.Auto (DimAutoStyle.Text);
         HelpView.Height = CommandView?.Visible == true ? Dim.Height (CommandView) : 1;
 
@@ -530,7 +536,6 @@ public class Shortcut : View
 
     private int _minimumKeyViewSize;
 
-
     /// <summary>
     /// </summary>
     public int MinimumKeyViewSize
@@ -558,7 +563,7 @@ public class Shortcut : View
     {
         KeyView.Margin.Thickness = GetMarginThickness ();
         KeyView.X = Pos.Align (Alignment.End, AlignmentModes);
-        KeyView.Y = 0;//Pos.Center ();
+        KeyView.Y = 0; //Pos.Center ();
         KeyView.Width = Dim.Auto (DimAutoStyle.Text, Dim.Func (GetMinimumKeyViewSize));
         KeyView.Height = CommandView?.Visible == true ? Dim.Height (CommandView) : 1;
 
@@ -596,6 +601,7 @@ public class Shortcut : View
         {
             case KeyBindingScope.Application:
                 handled = false;
+
                 break;
 
             case KeyBindingScope.Focused:
@@ -610,7 +616,6 @@ public class Shortcut : View
                 break;
         }
 
-
         if (handled == false)
         {
             if (base.OnAccept () is false)
@@ -625,7 +630,8 @@ public class Shortcut : View
     }
 
     /// <summary>
-    ///     Gets or sets the action to be invoked when the shortcut key is pressed or the shortcut is clicked on with the mouse. 
+    ///     Gets or sets the action to be invoked when the shortcut key is pressed or the shortcut is clicked on with the
+    ///     mouse.
     /// </summary>
     /// <remarks>
     ///     Note, the <see cref="View.Accept"/> event is fired first, and if cancelled, the event will not be invoked.
@@ -649,7 +655,6 @@ public class Shortcut : View
     }
 
     /// <summary>
-    /// 
     /// </summary>
     internal void SetColors ()
     {
@@ -688,6 +693,7 @@ public class Shortcut : View
     public override bool OnEnter (View view)
     {
         SetColors ();
+
         return base.OnEnter (view);
     }
 
@@ -695,12 +701,13 @@ public class Shortcut : View
     public override bool OnLeave (View view)
     {
         SetColors ();
+
         return base.OnLeave (view);
     }
 
     #endregion Focus
 
-    /// <inheritdoc />
+    /// <inheritdoc/>
     protected override void Dispose (bool disposing)
     {
         if (disposing)
@@ -709,16 +716,18 @@ public class Shortcut : View
             {
                 CommandView.Dispose ();
             }
+
             if (HelpView?.IsAdded == false)
             {
                 HelpView.Dispose ();
             }
+
             if (KeyView?.IsAdded == false)
             {
                 KeyView.Dispose ();
             }
         }
-        base.Dispose (disposing);
 
+        base.Dispose (disposing);
     }
 }

docfx/docs/keyboard.md

@@ -43,17 +43,14 @@ A **HotKey** is a keypress that selects a visible UI item. For selecting items a
 
 By default, the `Text` of a `View` is used to determine the `HotKey` by looking for the first occurrence of the [HotKeySpecifier](~/api/Terminal.Gui.View.yml#Terminal_Gui_View_HotKeySpecifier) (which is underscore (`_`) by default). The character following the underscore is the `HotKey`. If the `HotKeySpecifier` is not found in `Text`, the first character of `Text` is used as the `HotKey`. The `Text` of a `View` can be changed at runtime, and the `HotKey` will be updated accordingly. [HotKey](~/api/Terminal.Gui.View.yml#Terminal_Gui_View_HotKey) is `virtual` enabling this behavior to be customized.
 
-### **[Shortcut](~/api/Terminal.Gui.MenuItem.yml#Terminal_Gui_MenuItem_Shortcut)** 
+### **[Shortcut](~/api/Terminal.Gui.Shortcut.yml) - An opinionated (visually & API) View for displaying a command, helptext, key.
+**
 
-A **Shortcut** is a keypress that invokes a [Command](~/api/Terminal.Gui.Command.yml) or `View`-defined action regardless of whether the `View` that defines them is visible (but the `View` must be enabled). Shortcuts can be any keypress; `Key.A`, `Key.A | Key.Ctrl`, `Key.A | Key.Ctrl | Key.Alt`, `Key.Del`, and `Key.F1`, are all valid. 
+A **Shortcut** is a keypress that invokes a [Command](~/api/Terminal.Gui.Command.yml) or `View`-defined action even if the `View` that defines them is not focused or visible (but the `View` must be enabled). Shortcuts can be any keypress; `Key.A`, `Key.A | Key.Ctrl`, `Key.A | Key.Ctrl | Key.Alt`, `Key.Del`, and `Key.F1`, are all valid. 
 
 `Shortcuts` are used to define application-wide actions (e.g. `Quit`), or actions that are not visible (e.g. `Copy`).
 
-Not all `Views` support `Shortcut`s. [MenuBar](~/api/Terminal.Gui.MenuBar.yml), [ContextMenu](~/api/Terminal.Gui.ContextMenu.yml), and [StatusBar](~/api/Terminal.Gui.StatusBar.yml) support `Shortcut`s. However, the `Button` class does not. 
-
-The `Shortcut` is provided by setting the [Shortcut](~/api/Terminal.Gui.MenuItem.yml#Terminal_Gui_MenuItem_Shortcut) property on either a [MenuItem](~/api/Terminal.Gui.MenuItem.yml) or [StatusItem](~/api/Terminal.Gui.StatusItem.yml). 
-
-The [ShortcutDelimiter](~/api/Terminal.Gui.MenuBar.yml#Terminal_Gui_MenuBar_ShortcutDelimiter) (`+` by default) is used to separate the `Shortcut` from the `Text` of the `MenuItem` or `StatusItem`. For example, the `Shortcut` for `Quit` is `Ctrl+Q` and the `Text` is `Quit`. 
+[MenuBar](~/api/Terminal.Gui.MenuBar.yml), [ContextMenu](~/api/Terminal.Gui.ContextMenu.yml), and [StatusBar](~/api/Terminal.Gui.StatusBar.yml) support `Shortcut`s. 
 
 ### **[Handling Keyboard Events](~/api/Terminal.Gui.View.yml#Terminal_Gui_View_KeyDown)**
 

docfx/docs/migratingfromv1.md

@@ -164,6 +164,7 @@ In v1, scrolling was enabled by using `ScrollView` or `ScrollBarView`. In v2, th
 The API for handling keyboard input is significantly improved. See [Keyboard API](keyboard.md).
 
 * The [Key](~/api/Terminal.Gui.Key.yml) class replaces the `KeyEvent` struct and provides a platform-independent abstraction for common keyboard operations. It is used for processing keyboard input and raising keyboard events. This class provides a high-level abstraction with helper methods and properties for common keyboard operations. Use this class instead of the low-level [KeyCode](~/api/Terminal.Gui.KeyCode.yml) enum when possible. See [Key](~/api/Terminal.Gui.Key.yml) for more details.
+* The preferred way to enable Application-wide or View-heirarchy-dependent keystrokes is to use the [Shortcut](~/api/Terminal.Gui.Shortcut.yml) View or the built-in View's that utilize it, such as the [Bar](~/api/Terminal.Gui.Bar.yml)-based views.
 * The preferred way to handle single keystrokes is to use **Key Bindings**. Key Bindings map a key press to a [Command](~/api/Terminal.Gui.Command.yml). A view can declare which commands it supports, and provide a lambda that implements the functionality of the command, using `View.AddCommand()`. Use the [View.Keybindings](~/api/Terminal.Gui.View.Keybindings.yml) to configure the key bindings.
 
 ### How to Fix
@@ -201,7 +202,6 @@ The cursor and focus system has been redesigned in v2 to be more consistent and
 * Set [View.CursorVisibility](~/api/Terminal.Gui.View.CursorVisibility.yml) to the cursor style you want to use.
 * Remove any overrides of `OnEnter` and `OnLeave` that explicitly change the cursor.
 
-
 ## Events now use `object sender, EventArgs args` signature
 
 Previously events in Terminal.Gui used a mixture of `Action` (no arguments), `Action<string>` (or other raw datatype) and `Action<EventArgs>`. Now all events use the `EventHandler<EventArgs>` [standard .net design pattern](https://learn.microsoft.com/en-us/dotnet/csharp/event-pattern#event-delegate-signatures).
@@ -274,3 +274,23 @@ The [Aligner](~/api/Terminal.Gui.Aligner.yml) class makes it easy to align eleme
 ### How to Fix
 
 * Replace `VerticalAlignment.Middle` is now [Alignment.Center](~/api/Terminal.Gui.Alignment.Center.yml). 
+
+## `StatusBar`- `StatusItem` is replaced by `Shortcut`
+
+[StatusBar](~/api/Terminal.Gui.StatusBar.yml) has been upgraded to utilize [Shortcut](~/api/Terminal.Gui.Shortcut.yml).
+
+### How to Fix
+
+```diff
+-  var statusBar = new StatusBar (
+-                                       new StatusItem []
+-                                       {
+-                                           new (
+-                                                Application.QuitKey,
+-                                                $"{Application.QuitKey} to Quit",
+-                                                () => Quit ()
+-                                               )
+-                                       }
+-                                      );
++ var statusBar = new StatusBar (new Shortcut [] { new (Application.QuitKey, "Quit", Quit) });
+```

docfx/docs/newinv2.md

@@ -12,7 +12,7 @@ Apps built with Terminal.Gui now feel modern thanks to these improvements:
 * *Enhanced Borders and Padding* - Terminal.Gui now supports a `Border`, `Margin`, and `Padding` property on all views. This simplifies View development and enables a sophisticated look and feel. See [Adornments](https://gui-cs.github.io/Terminal.GuiV2Docs/docs/overview.html#adornments) for details.
 * *User Configurable Color Themes* - See [Color Themes](https://gui-cs.github.io/Terminal.GuiV2Docs/docs/overview.html#color-themes) for details.
 * *Enhanced Unicode/Wide Character support* - Terminal.Gui now supports the full range of Unicode/wide characters. See [Unicode](https://gui-cs.github.io/Terminal.GuiV2Docs/docs/overview.html#unicode) for details.
-* *Line Canvas* - Terminal.Gui now supports a line canvas enabling high-performance drawing of lines and shapes using box-drawing glyphs. `LineCanvas` provides *auto join*, a smart TUI drawing system that automatically selects the correct line/box drawing glyphs for intersections making drawing complex shapes easy. See [Line Canvas](https://gui-cs.github.io/Terminal.GuiV2Docs/docs/overview.html#line-canvas) for details.
+* *[LineCanvas](~/api/Terminal.Gui.Line Canvas.yml)* - Terminal.Gui now supports a line canvas enabling high-performance drawing of lines and shapes using box-drawing glyphs. `LineCanvas` provides *auto join*, a smart TUI drawing system that automatically selects the correct line/box drawing glyphs for intersections making drawing complex shapes easy. See [Line Canvas](https://gui-cs.github.io/Terminal.GuiV2Docs/docs/overview.html#line-canvas) for details.
 
 ## Simplified API
 
@@ -34,15 +34,16 @@ The entire library has been reviewed and simplified. As a result, the API is mor
 
 ## New and Improved Built-in Views
 
-* *DatePicker* - NEW!
-* *ScrollView* - Replaced by built-in scrolling.
-* *ScrollBar* - Replaces *ScrollBarView* with a much simpler view.
-* *Slider* - NEW!
-* *Bars* - NEW!
-* *StatusBar* - New implementation based on `Bar`
-* *MenuBar* - New implementation based on `Bar`
-* *ContextMenu* - New implementation based on `Bar`
-* *File Dialog* - The new, modern file dialog includes icons (in TUI!) for files/folders, search, and a `TreeView``. See [FileDialog](https://gui-cs.github.io/Terminal.GuiV2Docs/docs/overview.html#filedialog) for details.
+* *[DatePicker](~/api/Terminal.Gui.DatePicker.yml)* - NEW! 
+* *[ScrollView](~/api/Terminal.Gui.ScrollView.yml)* - Replaced by built-in scrolling.
+* *[ScrollBar](~/api/Terminal.Gui.ScrollBar.yml)* - Replaces *ScrollBarView* with a much simpler view.
+* *[Slider](~/api/Terminal.Gui.Slider.yml)* - NEW!
+* *[Shortcut](~/api/Terminal.Gui.Shortcut.yml)* - NEW! An opinionated (visually & API) View for displaying a command, helptext, key.
+* *[Bar](~/api/Terminal.Gui.Bar.yml)* - NEW! Building-block View for containing Shortcuts. Opinionated relative to Orientation but minimially so. The basis for the new StatusBar, MenuBar, and Menu views.
+* *[StatusBar](~/api/Terminal.Gui.StatusBar.yml)* - New implementation based on `Bar`
+* *[MenuBar](~/api/Terminal.Gui.MenuBar.yml)* - COMING SOON! New implementation based on `Bar`
+* *[ContextMenu](~/api/Terminal.Gui.ContextMenu.yml)* - COMING SOON! New implementation based on `Bar`
+* *[FileDialog](~/api/Terminal.Gui.FileDialog.yml)* - The new, modern file dialog includes icons (in TUI!) for files/folders, search, and a `TreeView``. See [FileDialog](https://gui-cs.github.io/Terminal.GuiV2Docs/docs/overview.html#filedialog) for details.
 
 ## Configuration Manager