From 9e61ae8912ddeded39c409ff42cdffdbe6638373 Mon Sep 17 00:00:00 2001 From: Tig Date: Mon, 17 Jun 2024 07:49:41 -0700 Subject: [PATCH] Improved API docs --- Terminal.Gui/Views/Shortcut.cs | 65 +++++++++++++++++++--------------- docfx/docs/keyboard.md | 11 +++--- docfx/docs/migratingfromv1.md | 22 +++++++++++- docfx/docs/newinv2.md | 21 +++++------ 4 files changed, 73 insertions(+), 46 deletions(-) diff --git a/Terminal.Gui/Views/Shortcut.cs b/Terminal.Gui/Views/Shortcut.cs index e235bb712..42c95ad70 100644 --- a/Terminal.Gui/Views/Shortcut.cs +++ b/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. /// /// -/// 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 to to reverse the order. /// /// -/// The command text can be set by setting the 's Text property. +/// The command text can be set by setting the 's Text property or by setting . /// /// /// The help text can be set by setting the property or by setting . @@ -38,8 +36,13 @@ namespace Terminal.Gui; public class Shortcut : View { /// - /// Creates a new instance of ; + /// Creates a new instance of . /// + /// + /// + /// This is a helper API that mimics the V1 API for creating StatusItems. + /// + /// /// /// /// @@ -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))); } } /// /// Creates a new instance of . /// - public Shortcut () : this (Gui.Key.Empty, string.Empty, null) { } + public Shortcut () : this (Key.Empty, string.Empty, null) { } /// /// Gets or sets the for this . The default is - /// , which is ideal for status bars and toolbars. If set to , + /// , which is ideal for status bars and toolbars. If set to + /// , /// the Shortcut will be configured for vertical layout, which is ideal for menus. /// public Orientation Orientation { get; set; } = Orientation.Horizontal; @@ -136,7 +143,8 @@ public class Shortcut : View private AlignmentModes _alignmentModes = AlignmentModes.StartToEnd | AlignmentModes.IgnoreFirstOrLast; /// - /// Gets or sets the for this . The default is . + /// Gets or sets the for this . The default is + /// . /// 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 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; - /// /// 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 } /// - /// 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. /// /// /// Note, the event is fired first, and if cancelled, the event will not be invoked. @@ -649,7 +655,6 @@ public class Shortcut : View } /// - /// /// 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 - /// + /// 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); } } diff --git a/docfx/docs/keyboard.md b/docfx/docs/keyboard.md index edc258ab4..d5eba8b3e 100644 --- a/docfx/docs/keyboard.md +++ b/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)** diff --git a/docfx/docs/migratingfromv1.md b/docfx/docs/migratingfromv1.md index 258e7c2a6..4d6c09267 100644 --- a/docfx/docs/migratingfromv1.md +++ b/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` (or other raw datatype) and `Action`. Now all events use the `EventHandler` [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) }); +``` diff --git a/docfx/docs/newinv2.md b/docfx/docs/newinv2.md index 9ea1d0749..a42158455 100644 --- a/docfx/docs/newinv2.md +++ b/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