Git_Mirror/Terminal.Gui
1
0
Fork 0
mirror of https://github.com/gui-cs/Terminal.Gui.git synced 2025-12-26 15:57:56 +01:00
Code Issues Packages Projects Releases Wiki Activity

Improved API docs

Browse Source
This commit is contained in:
Tig
2024-06-17 07:49:41 -07:00
parent dfd4b9ed88
commit 9e61ae8912
4 changed files with 73 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files

65
Terminal.Gui/Views/Shortcut.cs
View File

@@ -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);
}
}

11
docfx/docs/keyboard.md
View File

@@ -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)**

22
docfx/docs/migratingfromv1.md
View File

@@ -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) });
```

21
docfx/docs/newinv2.md
View File

@@ -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