Home Powershell Tips Creating Custom TUI Interfaces

Creating Custom TUI Interfaces

In the previous part, we looked at the Microsoft module Microsoft.PowerShell.ConsoleGuiTools and how it uses TUI binaries to add a text-based version of Out-GridView to PowerShell 7.

In this part, we’ll explore how that works and how you can create custom dialogs. This still requires PowerShell 7, but in a later part, we’ll make everything work in Windows PowerShell as well.

Using TUI Binaries

To start working with TUI yourself, first install the Microsoft module—if you haven’t already done so in the previous part.

Note: Everything in this section must be done in PowerShell 7, not in Windows PowerShell.
If you're using Windows PowerShell, download and install PowerShell 7 to follow along.

PS> Install-Module Microsoft.PowerShell.ConsoleGuiTools -Scope CurrentUser

Next, identify the installation location of the module:

PS> $module = (Get-Module Microsoft.PowerShell.ConsoleGuiTools -List).ModuleBasePS>$module

Typically, it is installed in your user profile:

C:\Users\USERNAME\Documents\PowerShell\Modules\Microsoft.PowerShell.ConsoleGuiTools\0.7.7

‍

The crucial step now is to load the binary Terminal.Gui.dll, which you can do with the following line:

PS> Add-Type -Path (Join-path $module Terminal.Gui.dll) -PassThru

IsPublic IsSerial Name                                     BaseType                                                                                             
-------- -------- ----                                     --------                                                                                             
False    False    CursesDriver                             Terminal.Gui.ConsoleDriver                                                                           
False    False    Platform                                 System.Object                                                                                        
False    False    CursesClipboard                          Terminal.Gui.ClipboardBase                                                                           
False    False    BashRunner                               System.Object                                                                                        
False    False    MacOSXClipboard                          Terminal.Gui.ClipboardBase 
(etc.)

This adds a long list of new .NET types to your session, which you can now use to design your own custom TUI dialogs.

Here is a script that demonstrates how to create a very simple TUI window:

#requires -version 7

#region Load TUI Binaries
$module = (Get-Module Microsoft.PowerShell.ConsoleGuiTools -List).ModuleBase
$exists = Test-Path -Path $module -PathType Container
if (!$exists) {
    throw "TUI module not found. Did you install 'Microsoft.PowerShell.ConsoleGuiTools' from PowerShell Gallery yet?"
}
Add-Type -Path (Join-Path $module Terminal.Gui.dll)
#endregion

#region Sample TUI Window
[Terminal.Gui.Application]::Init()
$Window = [Terminal.Gui.Window]::new()
$Window.Title = 'Hello, World'

$Button = [Terminal.Gui.Button]::new()
$Button.Text = 'Button'
$Window.Add($Button)

[Terminal.Gui.Application]::Top.Add($Window)
[Terminal.Gui.Application]::Run()
#endregion

The basic window is displayed; however, it does not respond to any user interaction, and your PowerShell session essentially hangs. So, there is clearly a bit of extra work to do.

Since we are now dealing with more complex script code, using a development editor is helpful. You can develop TUI scripts in VSCode, provided you are targeting PowerShell 7 (not Windows PowerShell). You might need to click the PowerShell Session Menu in the VSCode status bar to change the PowerShell version.

‍
There are two things to note: the VSCode console can forward key presses to your TUI application, but not mouse clicks. Therefore, mouse support is limited to the true PowerShell 7 console. Also, since the sample code currently does not respond to user interaction at all, running it will freeze your PowerShell session inside VSCode. You will need to restart your PowerShell session or VSCode.

Responding to user input and closing the TUI window gracefully is what we will cover in the next part.

‍

Your ultimate PowerShell Cheat Sheet

Unleash the full potential of PowerShell with our handy poster. Whether you're a beginner or a seasoned pro, this cheat sheet is designed to be your go-to resource for the most important and commonly used cmdlets. The poster is available for download and in paper form.

Get your poster here!

Creating Custom TUI Interfaces

Using TUI Binaries

Your ultimate PowerShell Cheat Sheet

Related links