Skip to content

gui-cs/TerminalGuiDesigner

Repository files navigation

Terminal Gui Designer

example workflow NuGet Badge Code Coverage

Cross platform designer for Terminal.Gui applications.

Built with CodeDom and Roslyn, TerminalGuiDesigner lets you create complicated Views with drag and drop just like the WinForms designer you know and love (or hate).

V1

Install the tool from NuGet or follow the Hello World Tutorial:

dotnet tool install --global TerminalGuiDesigner

Update to the latest version using

dotnet tool update --global TerminalGuiDesigner

This project is in alpha. See the feature list for progress.

V2

If you are targetting Terminal.Gui version 2 (currently pre-alpha) then you will want to install version 2 of the designer

dotnet tool install --global TerminalGuiDesigner --prerelease

Ensure that you match the Terminal.Gui library version you reference to the designer version.

Demo

long-demo

Building


Build using the dotnet 6.0 sdk

cd src
dotnet run

Usage


Install the dotnet sdk and create a new console application with references to Terminal.Gui. Install the TerminalGuiDesigner and create a new dialog:

dotnet new console -n hello
cd hello
dotnet add package Terminal.Gui
dotnet tool install --global TerminalGuiDesigner
TerminalGuiDesigner MyDialog.cs

Enter a namespace then add a Button to the view. Save with Ctrl+S. Exit the designer with Ctrl+Q.

Enter the following into Program.cs

using Terminal.Gui;

Application.Init();

Application.Run(new YourNamespace.MyDialog());

Application.Shutdown();

Run your program with dotnet run

You can add new code to MyDialog.cs but avoid making any changes to MyDialog.Designer.cs as this will be rewritten when saving.

For example in MyDialog.cs after InitializeComponent() add the following:

button1.Accept += ()=>MessageBox.Query("Hello","Hello World","Ok");

Now when run clicking the button will trigger a message box.

msgbox

You can re-open the designer by running it from the command line with the file you want to edit/create.

TerminalGuiDesigner MyDialog.cs

You can remove the tool using the following:

dotnet tool uninstall --global TerminalGuiDesigner

Troubleshooting

If when running the tool you have issues seeing the colors add the --usc flag:

TerminalGuiDesigner --usc

The designer is built to be robust and has top level catch blocks but if you are still able to crash it you may find your console blocking input. If this happens you should be able to fix your console by typing reset<enter> but also ❤️ please report it ❤️

Keybindings & Controls


You can change keybindings by copying Keys.yaml into your current directory.

To edit MenuBar items use the following controls

Key Action
Shift Up/Down Move selected menu item up/down
Shift Right Move selected menu item to a submenu of the one above
Shift Left Move selected sub menu item up a level
Del Remove selected menu item
Enter Add a new menu item
Typing Edit the Title of the selected item
Ctrl + T Set Shortcut
Ctrl + R Set menu field name

New root level menus can be added by right clicking the MenuBar and selecting 'Add Menu'.

You can create a menu separator by typing ---

Features


The following feature list shows the current capabilities and the roadmap. Features in italics are experimental and require passing the -e flag when starting application.

  • Design classes
    • Window
    • Dialog
    • View
    • Top level
  • Configure root properties (e.g. Window.Width, Title etc)
  • Configure subview properties
    • (Name)
    • X/Y
    • Width/Height
    • Text
    • Color Schemes
  • Edit multiple Views' property at once (e.g. select 3 views and set all Width to 10)
  • Mouse Input
    • Drag to move
    • Drag into/out of sub view
    • Drag to resize
  • Undo/Redo
  • Direct editing of Text just by typing
  • Easy Menu Bar Designing
    • Create new items
    • Move items
    • Move in/out of submenus
    • Add menu bar separators (Type '---')
    • Assign shortcuts
    • Set fieldnames (Name)
  • Easy Status Bar Designing
  • Create Events e.g. MyButton_OnClick
  • View Dependency Management
    • Prevent deleting views where other Views hold RelativeTo dependencies
    • Write out dependant views to InitializeComponent before dependers
    • Order Multi Delete operations to delete dependers before dependants
  • Mutli select
    • Multi delete
    • Multi keyboard move
    • Multi mouse drag move
    • Multi set Property
    • Multi Copy/Paste
  • Copy/Paste
    • Single simple views
    • Cut
    • Container views (e.g. TabView)
    • To OS clipboard (e.g. open one Designer.cs View and copy to another)
    • Retain PosRelative mappings in pasted views (e.g. A LeftOf B)
  • Move views to subviews
    • With mouse
    • With keyboard
  • Read and present xmldoc comments when editing properties
  • Dev Environment Integration
    • Visual Studio plugin (e.g. right click a .Designer.cs to open in TerminalGuiDesigner console)
    • Visual Studio Code plugin
  • Comprehensive Tests
  • CI
  • Ability to lock some of the views (prevent changes). This prevents accidentally dragging a given control
  • Support adding user defined View Types e.g. MyCustomView
  • Corner Cases
    • Allow designing abstract classes
    • Allow designing generic classes (e.g. MyDialog<T>)
    • Allow designing classes that inherit from another e.g. class MyDialog : MyOtherDialog
      • Inherited views should be locked to prevent editing
  • Create and edit views
    • Button
    • Checkbox
    • ComboBox
    • DateField
    • FrameView
    • GraphView
    • HexView
    • Label
    • LineView
    • ListView
    • MenuBar
      • Copy/Paste preserve menu entries
    • ProgressBar
    • RadioGroup
    • SplitContainer (Unreleased)
      • Copy/Paste preserve split content panels
    • StatusBar
      • Copy/Paste preserve menu entries
    • TableView
      • Add/Remove Columns
      • Copy/Paste preserve table schema
    • TabView
      • Add/Remove new Tabs
      • Reorder Tabs
      • Copy/Paste preserve tabs/content
    • TextField
    • TextValidateField
    • TextView
    • TimeField
    • TreeView
    • View
    • Slider

Class Diagram


Terminal.Gui Class Diagram