Theming

[jdhitsolutions]

I am starting to experiment with theming. One thing that would really help is an annotated layout or some sort of documentation that defines theme properties. For example, what does CanvasBorder refer to?

It would also help to be able to resolve settings to human-readable values. For example, if I look at $o.theme.MarkerForegroundColor all I see is PowerShellRun.FontColor. I have no way of knowing what the actual color is.

[mdgrs-mei]

Yes, we should add one image that describes what each theme property means. I'll consider adding that.

Regarding the human-readable display, I haven't looked into it but is it something we can acheive by the PowerShell formating system?

[jdhitsolutions]

The theme object has a defined typename, PowerShellRun.Theme, so you could create a custom formatting file for it. However, you still need PowerShell commands that can resolve these properties.

So yes, a custom format file is the right direction. But it needs to be able to resolve a property like ActionWindowBorderForegroundColor to a human-readable color. Right now, all I can see is `PowerShellRun.FontColor'. You really need to display the value, not the object.

[mdgrs-mei]

It turned out that I just needed to override the ToString method of FontColor.

This will be included in the next release.

[jdhitsolutions]

I think this will make a big difference.

[mdgrs-mei]

v0.10.0 that includes the ToString() improvements has been published. Thank you!

[jdhitsolutions]

Another idea, which I know is not trivial, would be to revise the theming system to use ANSI escape sequences and $PSStyle.

[mdgrs-mei]

I also considered using PSStyle or escape sequences when I implemented the theme. Escape sequences are just strings, so users can set any string to the colors even if they are not color sequences. I chose the robustness and less error handling. It feels a bit late to think about rewriting all.

[jdhitsolutions]

I've been able to work out some theming changes.

But when I enter a nested entry or a group, I get the default settings.

I don't know if this is a bug or if there is a setting I'm not seeing to inherit values.

[jdhitsolutions]

This code is in my configuration script:

$option = [PowerShellRun.SelectorOption]::new()
$option.Prompt = '🤓 '
$option.Theme.Cursor = '▸ '
$option.Theme.CursorForegroundColor = [PowerShellRun.FontColor]::Cyan
$option.Theme.PreviewEnable = $false
$option.Theme.CanvasBorderForegroundColor = [PowerShellRun.FontColor]::Yellow
$roundBorder = [PowerShellRun.BorderSymbol]::new()
$roundBorder.TopLeft = '╭'
$roundBorder.TopRight = '╮'
$roundBorder.BottomLeft = '╰'
$roundBorder.BottomRight = '╯'
$option.Theme.CanvasBorderSymbol = $roundBorder
$option.Theme.PreviewBorderSymbol = $roundBorder
$option.Theme.ActionWindowBorderSymbol = $roundBorder
$option.Theme.ActionWindowBorderForegroundColor = [PowerShellRun.FontColor]::BrightCyan
$option.Theme.SearchBarBorderForegroundColor = [PowerShellRun.FontColor]::BrightGreen

$global:opt = $option
Set-PSRunDefaultSelectorOption $option

[mdgrs-mei]

Do you use -Option parameter for Invoke-PSRun? I don't remember why I added the -Option parameter. Set-PSRunDefaultSelectorOption is enough so I should remove that parameter.

If you pass a different SelectorOption instance to Set-PSRunDefaultSelectorOption and Invoke-PSRun, the issue happens. If that's not the case, it's more complex..

[jdhitsolutions]

I am running Invoke-PSRun with no parameters.

[jdhitsolutions]

I figured the nested theming issue. I added theme changes in a PowerShell session that I started with default theme settings. The ""nested" items were using the original theming not my defined settings. Then I started a new PowerShell session and everything is as I expect. I keep my PowerShell window open for days at a time. I should have thought to restart it.

[mdgrs-mei]

Open for days wow.. good hear it worked!

[jdhitsolutions]

I like the theme settings now in 0.10.0

PS C:\> (Get-PSRunDefaultSelectorOption).theme

CanvasHeightPercentage                      : 60
PreviewSizePercentage                       : 60
NameWidthPercentage                         : 30
PreviewPosition                             : Bottom
CanvasTopMargin                             : 1
CanvasBorderFlags                           : None
CanvasBorderSymbol                          : │ ─ ╭ ╮ ╰ ╯
CanvasBorderForegroundColor                 : Yellow
CanvasBorderBackgroundColor                 :
DefaultForegroundColor                      :
DefaultBackgroundColor                      :
CursorEnable                                : True
Cursor                                      : ▸
Marker                                      : ✓
PromptSymbol                                : >
PromptForegroundColor                       : BrightGreen

The next step is to make it easier for the user to set these values. First, the user should be able to use a command like this in the configuration script:

$option.Theme.CursorForegroundColor = "Magenta"

But this won't work. The user is forced to know the class name.

$option.Theme.CursorForegroundColor = [PowerShellRun.FontColor]::Magenta

I think related to this is what happens when I try to export theme settings. I have settings defined.

PS C:\> (Get-PSRunDefaultSelectorOption).theme | select *foregroundcolor

CanvasBorderForegroundColor                 : Yellow
DefaultForegroundColor                      :
PromptForegroundColor                       : BrightGreen
QueryForegroundColor                        :
SearchBarBorderForegroundColor              : BrightGreen
...

I'd like to export the settings so I can import them in a script.

But defined values are empty.

Now, cliXML will work.

(Get-PSRunDefaultSelectorOption).theme | select *foregroundcolor | Export-Clixml -Path d:\temp\p.xml

However, this doesn't necessarily make it easier to import settings. The user should be able to define settings by the enum value without requiring the full name. And JSON exports should work.

[mdgrs-mei]

I understand making this syntax possible is helpful sometimes although I prefer writing the class name because it supports tab completion and you can see what color names are available.

$option.Theme.CursorForegroundColor = "Magenta"

[mdgrs-mei]

However, supporting json export will not be trivial to implement. FontColor is not a simple Enum (e.g. it supports hex string colors) and it seems that a public property is needed to show up in the json export. That public string property is only needed for the json export, so it requires strong motivation to support json.

Also, how do you handle the json import? I think it might be hard to construct the theme object from json on the user side.

[jdhitsolutions]

This is do-able. I exported theme settings to a JSON file and manually set the colors.

{
  "ConsoleCursorShape": 0,
  "KeyRemapModeConsoleCursorShape": 6,
  "CanvasHeightPercentage": 75,
  "PreviewSizePercentage": 60,
  "NameWidthPercentage": 30,
  "PreviewPosition": 1,
  "CanvasTopMargin": 1,
  "CanvasBorderFlags": 0,
  "CanvasBorderSymbol": {
    "Vertical": "│",
    "Horizontal": "─",
    "TopLeft": "╭",
    "TopRight": "╮",
    "BottomLeft": "╰",
    "BottomRight": "╯"
  },
  "CanvasBorderForegroundColor": "Yellow",
  "CursorEnable": true,
  "Cursor": " 👉 ",
  "Marker": "✓ ",
  "PromptSymbol": null,
  "PromptForegroundColor": "BrightGreen",
  "QueryStyle": 0,
  "SearchBarBorderFlags": 8,
  "SearchBarBorderSymbol": {
    "Vertical": "│",
    "Horizontal": "─",
    "TopLeft": "┌",
    "TopRight": "┐",
    "BottomLeft": "└",
    "BottomRight": "┘"
  },
  "SearchBarBorderForegroundColor": "BrightGreen",
  "CursorForegroundColor": "Magenta",
  "MarkerForegroundColor": "Yellow",
  "IconEnable": true,
  "IconForegroundColor": null,
  "NameStyle": 0,
  "NameHighlightForegroundColor": "Cyan",
  "NameHighlightStyle": 0,
  "NameFocusStyle": 4,
  "NameFocusHighlightBackgroundColor": "Magenta",
  "NameFocusHighlightStyle": 4,
  "DescriptionEnable": true,
  "DescriptionForegroundColor": "BrightBlue",
  "DescriptionStyle": 0,
  "DescriptionHighlightForegroundColor": "Cyan",
  "DescriptionHighlightStyle": 0,
  "DescriptionFocusStyle": 4,
  "DescriptionFocusHighlightForegroundColor": "Magenta",
  "DescriptionFocusHighlightStyle": 4,
  "EntryBorderFlags": 0,
  "EntryBorderSymbol": {
    "Vertical": "│",
    "Horizontal": "─",
    "TopLeft": "┌",
    "TopRight": "┐",
    "BottomLeft": "└",
    "BottomRight": "┘"
  },
  "PreviewEnable": true,
  "PreviewStyle": 0,
  "PreviewBorderFlags": 15,
  "PreviewBorderSymbol": {
    "Vertical": "│",
    "Horizontal": "─",
    "TopLeft": "╭",
    "TopRight": "╮",
    "BottomLeft": "╰",
    "BottomRight": "╯"
  },
  "PreviewBorderForegroundColor": "BrightYellow",
  "ActionWindowKeyStyle": 0,
  "ActionWindowKeyFocusStyle": 4,
  "ActionWindowDescriptionForegroundColor": "BrightBlue",
  "ActionWindowDescriptionStyle": 0,
  "ActionWindowDescriptionFocusStyle": 4,
  "ActionWindowBorderEnable": true,
  "ActionWindowBorderSymbol": {
    "Vertical": "│",
    "Horizontal": "─",
    "TopLeft": "╭",
    "TopRight": "╮",
    "BottomLeft": "╰",
    "BottomRight": "╯"
  },
  "ActionWindowBorderForegroundColor": "BrightYellow",
  "ActionWindowScrollBarForegroundColor": "Magenta",
  "TabSize": 6
}

In my configuration script, I can import this file and set the theme properties.

$option = [PowerShellRun.SelectorOption]::new()

$data = Get-Content C:\Temp\psruntheme.json | ConvertFrom-Json
$option.Prompt = 'Hey Jeff! 🤓 --> '

($option.theme.PSObject.Properties).ForEach({
    if ($_.Name -match "color" -AND $data.$($_.Name)) {
        #Write-Host "Color: $($_.Name) = $($data.$($_.Name))"
        $_.Value = [PowerShellRun.FontColor]::$($data.$($_.Name))
    }
    else {
        $_.Value = $data.$($_.Name)
    }
})

I need an extra step to set the color. But I can live with it.

[mdgrs-mei]

v0.11.0 has been released with the string conversion to color support. You should now be able to remove the color specialization.

$option.Theme.CursorForegroundColor = 'Magenta'