diff --git a/.gitignore b/.gitignore index 1c9d8c393..1399d6656 100644 --- a/.gitignore +++ b/.gitignore @@ -17,6 +17,6 @@ UnitTests/TestResults .vscode/ -demo.txt +demo.* *.deb diff --git a/README.md b/README.md index 356c4e306..4a3524d9f 100644 --- a/README.md +++ b/README.md @@ -6,15 +6,15 @@ [![License](https://img.shields.io/github/license/migueldeicaza/gui.cs.svg)](LICENSE) ![Bugs](https://img.shields.io/github/issues/migueldeicaza/gui.cs/bug) -# Terminal.Gui - Cross Platform Terminal GUI toolkit for .NET +# Terminal.Gui - Cross Platform Terminal UI toolkit for .NET -A toolkit for building console GUI apps for .NET, .NET Core, and Mono that works on Windows, the Mac, and Linux/Unix. +A toolkit for building rich console apps for .NET, .NET Core, and Mono that works on Windows, the Mac, and Linux/Unix. ![Sample app](https://raw.githubusercontent.com/migueldeicaza/gui.cs/master/docfx/sample.gif) -## Controls & Features +## Controls and Views -*Terminal.Gui* contains various controls for building text user interfaces: +*Terminal.Gui* provides a rich set of views and controls for building terminal user interfaces: * [Button](https://migueldeicaza.github.io/gui.cs/api/Terminal.Gui/Terminal.Gui.Button.html) * [CheckBox](https://migueldeicaza.github.io/gui.cs/api/Terminal.Gui/Terminal.Gui.CheckBox.html) @@ -43,21 +43,21 @@ A toolkit for building console GUI apps for .NET, .NET Core, and Mono that works * [StatusBar](https://migueldeicaza.github.io/gui.cs/api/Terminal.Gui/Terminal.Gui.StatusBar.html) * [Window](https://migueldeicaza.github.io/gui.cs/api/Terminal.Gui/Terminal.Gui.Window.html) -In addition, a complete Xterm/Vt100 terminal emulator that you can embed is now part of [XtermSharp](https://github.com/migueldeicaza/XtermSharp/blob/master/GuiCsHost/TerminalView.cs) - you just need to pull [`TerminalView.cs`](https://github.com/migueldeicaza/XtermSharp/blob/master/GuiCsHost/TerminalView.cs) into your project. - ### Features -* **Cross Platform** - Works on Windows, Mac, and Linux. Terminal drivers for Curses, [Windows Console](https://github.com/migueldeicaza/gui.cs/issues/27), and the .NET Console mean **Terminal.Gui** works well on both color and monochrome terminals and has mouse support on terminal emulators that support it. -* **Keyboard and Mouse Input** - Both keyboard and mouse input are supported, including limited support for drag & drop. -* **[Flexible Layout](https://migueldeicaza.github.io/gui.cs/articles/overview.html#layout)** - **Terminal.Gui** supports both *Absolute layout* and an innovative UI layout system referred to as *Computed Layout*. *Computed Layout* makes it easy to layout controls relative to each other and enables dynamic console GUIs. +* **Cross Platform** - Windows, Mac, and Linux. Terminal drivers for Curses, [Windows Console](https://github.com/migueldeicaza/gui.cs/issues/27), and the .NET Console mean apps will work well on both color and monochrome terminals. +* **Keyboard and Mouse Input** - Both keyboard and mouse input are supported, including support for drag & drop. +* **[Flexible Layout](https://migueldeicaza.github.io/gui.cs/articles/overview.html#layout)** - Supports both *Absolute layout* and an innovative *Computed Layout* system. *Computed Layout* makes it easy to layout controls relative to each other and enables dynamic terminal UIs. * **Clipboard support** - Cut, Copy, and Paste of text provided through the [`Clipboard`](https://migueldeicaza.github.io/gui.cs/api/Terminal.Gui/Terminal.Gui.Clipboard.html) class. * **[Arbitrary Views](https://migueldeicaza.github.io/gui.cs/api/Terminal.Gui/Terminal.Gui.View.html)** - All visible UI elements are subclasses of the `View` class, and these in turn can contain an arbitrary number of sub-views. * **Advanced App Features** - The [Mainloop](https://migueldeicaza.github.io/gui.cs/api/Terminal.Gui/Terminal.Gui.MainLoop.html) supports processing events, idle handlers, timers, and monitoring file -descriptors. -* **Reactive Extensions Support** - Use [reactive extensions](https://github.com/dotnet/reactive) and benefit from increased code readability, and the ability to apply the MVVM pattern and [ReactiveUI](https://www.reactiveui.net/) data bindings. See the [source code](https://github.com/migueldeicaza/gui.cs/tree/master/ReactiveExample) of a sample app in order to learn how to achieve this. +descriptors. Most classes are safe for threading. +* **Reactive Extensions** - Use [reactive extensions](https://github.com/dotnet/reactive) and benefit from increased code readability, and the ability to apply the MVVM pattern and [ReactiveUI](https://www.reactiveui.net/) data bindings. See the [source code](https://github.com/migueldeicaza/gui.cs/tree/master/ReactiveExample) of a sample app in order to learn how to achieve this. ### Keyboard Input Handling +**Terminal.Gui** respects common Linux, Mac, and Windows keyboard idioms. For example, clipboard operations use the familiar `Control/Command-C, X, V` model. `CTRL-Q` is used for exiting views (and apps). + The input handling of **Terminal.Gui** is similar in some ways to Emacs and the Midnight Commander, so you can expect some of the special key combinations to be active. The key `ESC` can act as an Alt modifier (or Meta in Emacs parlance), to allow input on terminals that do not have an alt key. So to produce the sequence `Alt-F`, you can press either `Alt-F`, or `ESC` followed by the key `F`. @@ -66,25 +66,9 @@ To enter the key `ESC`, you can either press `ESC` and wait 100 milliseconds, or `ESC-0`, and `ESC-1` through `ESC-9` have a special meaning, they map to `F10`, and `F1` to `F9` respectively. -**Terminal.Gui** respects common Mac and Windows keyboard idoms as well. For example, clipboard operations use the familiar `Control/Command-C, X, V` model. +Apps can change key bindings using the `AddKeyBinding` API. -`CTRL-Q` is used for exiting views (and apps). - -**Terminal.Gui** supports rebinding keys. For example the default key for activating a button is Enter. You can change this using the `ClearKeybinding` and `AddKeybinding` methods: - -```csharp -var btn = new Button ("Press Me"); -btn.ClearKeybinding (Command.Accept); -btn.AddKeyBinding (Key.b, Command.Accept); -``` - -The `Command` enum lists generic operations that are implemented by views. For example `Command.Accept` in a Button results in the `Clicked` event firing while in `TableView` it is bound to `CellActivated`. Not all commands are implemented by all views (e.g. you cannot scroll in a Button). To see which commands are implemented by a View you can use the `GetSupportedCommands()` method. - -Not all controls have the same key bound for a given command, for example `Command.Accept` defaults to `Key.Enter` in a `Button` but defaults to `Key.Space` in `RadioGroup`. - -Keybindings only operate while a view has focus. To register global hotkeys you can override a view's `bool ProcessHotKey (KeyEvent kb)` method. - -### Driver model +### Driver Model **Terminal.Gui** has support for [ncurses](https://github.com/migueldeicaza/gui.cs/blob/master/Terminal.Gui/ConsoleDrivers/CursesDriver/CursesDriver.cs), [`System.Console`](https://github.com/migueldeicaza/gui.cs/blob/master/Terminal.Gui/ConsoleDrivers/NetDriver.cs), and a full [Win32 Console](https://github.com/migueldeicaza/gui.cs/blob/master/Terminal.Gui/ConsoleDrivers/WindowsDriver.cs) front-end. @@ -99,8 +83,7 @@ You can force the use of `System.Console` on Unix as well; see `Core.cs`. * **[Example (aka `demo.cs`)](https://github.com/migueldeicaza/gui.cs/tree/master/Example)** - Run `dotnet run` in the `Example` directory to run the simple demo. * **[Standalone Example](https://github.com/migueldeicaza/gui.cs/tree/master/StandaloneExample)** - A trivial .NET core sample application can be found in the `StandaloneExample` directory. Run `dotnet run` in directory to test. * **[F# Example](https://github.com/migueldeicaza/gui.cs/tree/master/FSharpExample)** - An example showing how to build a Terminal.Gui app using F#. -* **[Powershell Sample]()** - (Coming soon! See PR #952. Shows how to build Terminal.Gui apps using Powershell. -* **PowerShell's Out-ConsoleGridView** - The [`Out-ConsoleGridView` PowerShell Cmdlet](https://github.com/PowerShell/GraphicalTools/blob/master/docs/Microsoft.PowerShell.ConsoleGuiTools/Out-ConsoleGridView.md) sends the output from a command to a grid view window where the output is displayed in an interactive table. sends the output from a command to a grid view window where the output is displayed in an interactive table, using Terminal.Gui. +* **[PowerShell's `Out-ConsoleGridView`](https://github.com/PowerShell/GraphicalTools/blob/master/docs/Microsoft.PowerShell.ConsoleGuiTools/Out-ConsoleGridView.md)** - `OCGV` sends the output from a command to an interactive table. * **[PoshRedisViewer](https://github.com/En3Tho/PoshRedisViewer)** - A compact Redis viewer module for PowerShell written in F# and Gui.cs ## Documentation @@ -112,7 +95,7 @@ You can force the use of `System.Console` on Unix as well; see `Core.cs`. See the [`Terminal.Gui/` README](https://github.com/migueldeicaza/gui.cs/tree/master/Terminal.Gui) for an overview of how the library is structured. The [Conceptual Documentation](https://migueldeicaza.github.io/gui.cs/articles/index.html) provides insight into core concepts. ### Sample Usage -The code below is done with the new [Top-level statements](https://docs.microsoft.com/en-us/dotnet/csharp/whats-new/csharp-9#top-level-statements) in C# 9.0. +(This code uses C# 9.0 [Top-level statements](https://docs.microsoft.com/en-us/dotnet/csharp/whats-new/csharp-9#top-level-statements).) ```csharp using Terminal.Gui; using NStack; @@ -191,6 +174,8 @@ Application.Run(); Application.Shutdown(); ``` +The example above shows adding views using both styles of layout supported by **Terminal.Gui**: **Absolute layout** and **[Computed layout](https://migueldeicaza.github.io/gui.cs/articles/overview.html#layout)**. + Alternatively, you can encapsulate the app behavior in a new `Window`-derived class, say `App.cs` containing the code above, and simplify your `Main` method to: ```csharp @@ -205,8 +190,6 @@ class Demo { } ``` -The example above shows how to add views using both styles of layout supported by **Terminal.Gui**: **Absolute layout** and **[Computed layout](https://migueldeicaza.github.io/gui.cs/articles/overview.html#layout)**. - ## Installing Use NuGet to install the `Terminal.Gui` NuGet package: https://www.nuget.org/packages/Terminal.Gui @@ -221,10 +204,10 @@ dotnet add package Terminal.Gui ## Running and Building -* Windows, Mac, and Linux - Build and run using the .NET SDK command line tools (`dotnet build` in the root directory). Run `UICatalog` with `dotnet run --project ./UICatalog` or by directly executing `./UICatalog/bin/Debug/net5.0/UICatalog.exe`. +* Windows, Mac, and Linux - Build and run using the .NET SDK command line tools (`dotnet build` in the root directory). Run `UICatalog` with `dotnet run --project UICatalog`. * Windows - Open `Terminal.Gui.sln` with Visual Studio 2019. -Building in Release requires the [git command line tool](https://git-scm.com/) (a dependency of the [MinVer](https://github.com/adamralph/minver#can-i-disable-minver) build tool) +Building in `Release` requires the [git command line tool](https://git-scm.com/) (a dependency of the [MinVer](https://github.com/adamralph/minver#can-i-disable-minver) build tool) ## Contributing diff --git a/Terminal.Gui/README.md b/Terminal.Gui/README.md index 1c9920406..2de6cf82c 100644 --- a/Terminal.Gui/README.md +++ b/Terminal.Gui/README.md @@ -1,20 +1,20 @@ # Terminal.Gui Project -Contains all files required to build the **Terminal.Gui** library (and nuget package). +Contains all files required to build the **Terminal.Gui** library (and NuGEt package). ## Project Folder Structure -- `Terminal.Gui.sln` - The Visual Studio 2019 solution +- `Terminal.Gui.sln` - The Visual Studio solution - `Core/` - Source files for all types that comprise the core building blocks of **Terminal-Gui** - `Application` - A `static` class that provides the base 'application driver'. Given it defines a **Terminal.Gui** application it is both logically and literally (because `static`) a singleton. It has direct dependencies on `MainLoop`, `Events.cs` `NetDriver`, `CursesDriver`, `WindowsDriver`, `Responder`, `View`, and `TopLevel` (and nothing else). - `MainLoop` - Defines `IMainLoopDriver` and implements the and `MainLoop` class. - `ConsoleDriver` - Definition for the Console Driver API. - `Events.cs` - Defines keyboard and mouse related structs & classes. - - `PosDim.cs` - Implements **Terminal-Gui's** *Computed Layout* system. These classes have deep dependencies on `View`. + - `PosDim.cs` - Implements *Computed Layout* system. These classes have deep dependencies on `View`. - `Responder` - Base class for the windowing class hierarchy. Implements support for keyboard & mouse input. - `View` - Derived from `Responder`, the base class for non-modal visual elements such as controls. - - `Toplevel` - Drived from `View`, the base class for modal visual elements such as top-level windows and dialogs. Supports the concept of `MenuBar` and `StatusBar`. - - `Window` - Drived from `TopLevel`, implements Toplevel views with a visible frame and Title. + - `Toplevel` - Derived from `View`, the base class for modal visual elements such as top-level windows and dialogs. Supports the concept of `MenuBar` and `StatusBar`. + - `Window` - Derived from `TopLevel`; implements top level views with a visible frame and Title. - `Types/` - A folder (not namespace) containing implementations of `Point`, `Rect`, and `Size` which are ancient versions of the modern `System.Drawing.Point`, `System.Drawing.Size`, and `System.Drawning.Rectangle`. - `ConsoleDrivers/` - Source files for the three `ConsoleDriver`-based drivers: .NET: `NetDriver`, Unix & Mac: `UnixDriver`, and Windows: `WindowsDriver`. - `Views/` - A folder (not namespace) containing the source for all built-in classes that drive from `View` (non-modals). diff --git a/Terminal.Gui/Terminal.Gui.csproj b/Terminal.Gui/Terminal.Gui.csproj index 61575815d..61d819451 100644 --- a/Terminal.Gui/Terminal.Gui.csproj +++ b/Terminal.Gui/Terminal.Gui.csproj @@ -18,7 +18,6 @@ - @@ -60,6 +59,29 @@ Terminal.Gui is a framework for creating console user interfaces + v1.6.0 + * Adds ColorPicker control + * Adds Context Menu to TreeView + * Adds support for custom colors in TreeView + * Adds Data field to MenuItem + * Adds Timeout thread safety + * Adds better docs for Application.Shutdown () + * Fixes #1699. Menu closes on button press and menu hot-key text renders correctly + * Fixes #1675. ContextMenu MenuItems typo + * Fixes #1715. UI Catalog about box version + * Fixes #1712. Intermittent Github Action build failures + * Fixes remaining wide runes render issues including #1693 Character Map + * Fixes the draw clip bounds issue visible on ScrollView. + * Fixes UpdateScreen running twice on Application.Refresh because Driver. Refresh already does. + * Fixes TextView throwing when WordWrap is true on constructor initialization. + * Fixes RunTimers not checking for key collisions in list when adding to timeouts + * Fixes erroneous namespace on LineView to match other views + * Fixes #1723. ProgressBar with Percentage has extra spaces on the right + * Fixes nullref on unclean shutdown + * Fixes Thin tabview + * Fixes #1732. Toplevel shouldn't clear the buffer. + * Fixes #1730. AllViewsTester throw exception on Dim.Percent. + v1.5.0 * Localization support added. en-US, Japanese, fr-FR, and pt-PT * Adds Key Binding support. Also refactors Autocomplete. diff --git a/UICatalog/Properties/launchSettings.json b/UICatalog/Properties/launchSettings.json index 73a06de90..427554a49 100644 --- a/UICatalog/Properties/launchSettings.json +++ b/UICatalog/Properties/launchSettings.json @@ -2,6 +2,7 @@ "profiles": { "UICatalog": { "commandName": "Project", + "commandLineArgs": "\"ProgressBar Styles\"" }, "UICatalog : -usc": { "commandName": "Project", diff --git a/docfx/sample.gif b/docfx/sample.gif index 06d84aba0..93dabf105 100644 Binary files a/docfx/sample.gif and b/docfx/sample.gif differ