From f5f1b1778c5a0352a5b36a2cb072a2405bccbecf Mon Sep 17 00:00:00 2001 From: Patrik Svensson Date: Sun, 27 Feb 2022 11:29:19 +0100 Subject: [PATCH] Add documentation for `TextPath` widget --- docs/Program.cs | 1 + docs/input/assets/casts/text-path-plain.cast | 6 ++ docs/input/assets/casts/text-path-rich.cast | 6 ++ docs/input/tailwind.css | 8 +++ docs/input/widgets/path.md | 71 +++++++++++++++++++ docs/package-lock.json | 1 - docs/src/Shortcodes/InfoShortcode.cs | 13 ++++ examples/Console/Paths/Program.cs | 8 +-- .../AsciiCast/Samples/TextPathSample.cs | 44 ++++++++++++ .../Extensions/TextPathExtensions.cs | 4 +- 10 files changed, 155 insertions(+), 7 deletions(-) create mode 100644 docs/input/assets/casts/text-path-plain.cast create mode 100644 docs/input/assets/casts/text-path-rich.cast create mode 100644 docs/input/widgets/path.md create mode 100644 docs/src/Shortcodes/InfoShortcode.cs create mode 100644 resources/scripts/Generator/Commands/AsciiCast/Samples/TextPathSample.cs diff --git a/docs/Program.cs b/docs/Program.cs index a7f857672..b89d60da3 100644 --- a/docs/Program.cs +++ b/docs/Program.cs @@ -38,6 +38,7 @@ await Bootstrapper.Factory .AddShortcode("ColorTable", typeof(ColorTableShortcode)) .AddShortcode("EmojiTable", typeof(EmojiTableShortcode)) .AddShortcode("Alert", typeof(AlertShortcode)) + .AddShortcode("Info", typeof(InfoShortcode)) .AddShortcode("AsciiCast", typeof(AsciiCastShortcode)) .AddShortcode("Example", typeof(ExampleSnippet)) .AddPipelines() diff --git a/docs/input/assets/casts/text-path-plain.cast b/docs/input/assets/casts/text-path-plain.cast new file mode 100644 index 000000000..8316b6711 --- /dev/null +++ b/docs/input/assets/casts/text-path-plain.cast @@ -0,0 +1,6 @@ +{"version": 2, "width": 42, "height": 23, "title": "text-path (plain)", "env": {"TERM": "Spectre.Console"}} +[0, "o", "\u001B[37m\u250C\u2500Windows path\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\u001B[0m\r\n\u001B[37m\u2502\u001B[0m \u001B[37m\u2502\u001B[0m\r\n\u001B[37m\u2502\u001B[0m C:/.../That/Will/Be/Truncated.txt \u001B[37m\u2502\u001B[0m\r\n\u001B[37m\u2502\u001B[0m \u001B[37m\u2502\u001B[0m\r\n\u001B[37m\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\u001B[0m\r\n"] +[0.015, "o", "\u001B[37m\u250C\u2500Unix path\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\u001B[0m\r\n\u001B[37m\u2502\u001B[0m \u001B[37m\u2502\u001B[0m\r\n\u001B[37m\u2502\u001B[0m /.../That/Will/Be/Truncated.txt \u001B[37m\u2502\u001B[0m\r\n\u001B[37m\u2502\u001B[0m \u001B[37m\u2502\u001B[0m\r\n\u001B[37m\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\u001B[0m\r\n"] +[0.015, "o", "\u001B[37m\u250C\u2500Styling\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\u001B[0m\r\n\u001B[37m\u2502\u001B[0m \u001B[37m\u2502\u001B[0m\r\n\u001B[37m\u2502\u001B[0m \u001B[32m/\u001B[0m\u001B[37m...\u001B[0m\u001B[31m/\u001B[0m\u001B[37mThat\u001B[0m\u001B[31m/\u001B[0m\u001B[37mWill\u001B[0m\u001B[31m/\u001B[0m\u001B[37mBe\u001B[0m\u001B[31m/\u001B[0m\u001B[34mTruncated.txt\u001B[0m \u001B[37m\u2502\u001B[0m\r\n\u001B[37m\u2502\u001B[0m \u001B[37m\u2502\u001B[0m\r\n\u001B[37m\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\u001B[0m\r\n"] +[0.015, "o", "\u001B[37m\u250C\u2500Alignment\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\u001B[0m\r\n\u001B[37m\u2502\u001B[0m \u001B[37m\u2502\u001B[0m\r\n\u001B[37m\u2502\u001B[0m /.../That/Will/Be/Truncated.txt \u001B[37m\u2502\u001B[0m\r\n\u001B[37m\u2502\u001B[0m /.../That/Will/Be/Truncated.txt \u001B[37m\u2502\u001B[0m\r\n\u001B[37m\u2502\u001B[0m /.../That/Will/Be/Truncated.txt \u001B[37m\u2502\u001B[0m\r\n\u001B[37m\u2502\u001B[0m \u001B[37m\u2502\u001B[0m\r\n\u001B[37m\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\u001B[0m\r\n"] + diff --git a/docs/input/assets/casts/text-path-rich.cast b/docs/input/assets/casts/text-path-rich.cast new file mode 100644 index 000000000..4188494fe --- /dev/null +++ b/docs/input/assets/casts/text-path-rich.cast @@ -0,0 +1,6 @@ +{"version": 2, "width": 42, "height": 23, "title": "text-path (rich)", "env": {"TERM": "Spectre.Console"}} +[0, "o", "\u001B[38;5;8m\u250C\u2500Windows path\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\u001B[0m\r\n\u001B[38;5;8m\u2502\u001B[0m \u001B[38;5;8m\u2502\u001B[0m\r\n\u001B[38;5;8m\u2502\u001B[0m C:/\u2026/Path/That/Will/Be/Truncated.txt \u001B[38;5;8m\u2502\u001B[0m\r\n\u001B[38;5;8m\u2502\u001B[0m \u001B[38;5;8m\u2502\u001B[0m\r\n\u001B[38;5;8m\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\u001B[0m\r\n"] +[0, "o", "\u001B[38;5;8m\u250C\u2500Unix path\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\u001B[0m\r\n\u001B[38;5;8m\u2502\u001B[0m \u001B[38;5;8m\u2502\u001B[0m\r\n\u001B[38;5;8m\u2502\u001B[0m /\u2026/Path/That/Will/Be/Truncated.txt \u001B[38;5;8m\u2502\u001B[0m\r\n\u001B[38;5;8m\u2502\u001B[0m \u001B[38;5;8m\u2502\u001B[0m\r\n\u001B[38;5;8m\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\u001B[0m\r\n"] +[0, "o", "\u001B[38;5;8m\u250C\u2500Styling\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\u001B[0m\r\n\u001B[38;5;8m\u2502\u001B[0m \u001B[38;5;8m\u2502\u001B[0m\r\n\u001B[38;5;8m\u2502\u001B[0m \u001B[38;5;2m/\u001B[0m\u001B[38;5;11m\u2026\u001B[0m\u001B[38;5;9m/\u001B[0m\u001B[38;5;11mPath\u001B[0m\u001B[38;5;9m/\u001B[0m\u001B[38;5;11mThat\u001B[0m\u001B[38;5;9m/\u001B[0m\u001B[38;5;11mWill\u001B[0m\u001B[38;5;9m/\u001B[0m\u001B[38;5;11mBe\u001B[0m\u001B[38;5;9m/\u001B[0m\u001B[38;5;12mTruncated.txt\u001B[0m \u001B[38;5;8m\u2502\u001B[0m\r\n\u001B[38;5;8m\u2502\u001B[0m \u001B[38;5;8m\u2502\u001B[0m\r\n\u001B[38;5;8m\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\u001B[0m\r\n"] +[0, "o", "\u001B[38;5;8m\u250C\u2500Alignment\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\u001B[0m\r\n\u001B[38;5;8m\u2502\u001B[0m \u001B[38;5;8m\u2502\u001B[0m\r\n\u001B[38;5;8m\u2502\u001B[0m /\u2026/Path/That/Will/Be/Truncated.txt \u001B[38;5;8m\u2502\u001B[0m\r\n\u001B[38;5;8m\u2502\u001B[0m /\u2026/Path/That/Will/Be/Truncated.txt \u001B[38;5;8m\u2502\u001B[0m\r\n\u001B[38;5;8m\u2502\u001B[0m /\u2026/Path/That/Will/Be/Truncated.txt \u001B[38;5;8m\u2502\u001B[0m\r\n\u001B[38;5;8m\u2502\u001B[0m \u001B[38;5;8m\u2502\u001B[0m\r\n\u001B[38;5;8m\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\u001B[0m\r\n"] + diff --git a/docs/input/tailwind.css b/docs/input/tailwind.css index bd3466dd9..4304f7e68 100644 --- a/docs/input/tailwind.css +++ b/docs/input/tailwind.css @@ -24,6 +24,14 @@ and the ascii terminal player. @apply m-0; } +.alert-info { + @apply p-4 border border-green-300 bg-green-100 text-green-800 dark:border-green-700/50 dark:bg-green-800/50 dark:text-gray-300/90 rounded shadow-sm text-sm; +} + +.alert-info p { + @apply m-0; +} + [type='search'] { @apply shadow-sm focus:ring-indigo-300 focus:border-indigo-300 block w-full sm:text-sm border-gray-300 rounded-md; } diff --git a/docs/input/widgets/path.md b/docs/input/widgets/path.md new file mode 100644 index 000000000..09eb2c559 --- /dev/null +++ b/docs/input/widgets/path.md @@ -0,0 +1,71 @@ +Title: Text Path +Order: 80 +Description: "The **TextPath** class is used to render a horizontal rule (line) to the terminal." +Highlights: + - Automatically shrinks paths to fit. + - Custom colors for segments of the path. + - Specify left, center or right aligned paths. +Reference: T:Spectre.Console.TextPath + +--- + +The `TextPath` class is used to render a Windows or Unix disk path. + + + +## Usage + +```csharp +var path = new TextPath("C:/This/Path/Is/Too/Long/To/Fit/In/The/Area.txt"); + +AnsiConsole.Write(path); +``` + +## Alignment + +```csharp +var path = new TextPath("C:/This/Path/Is/Too/Long/To/Fit/In/The/Area.txt"); +path.Alignment = Justify.Right; + +AnsiConsole.Write(path); +``` + +You can also specify styles via extension methods: + +```csharp +var path = new TextPath("C:/This/Path/Is/Too/Long/To/Fit/In/The/Area.txt") + .RightAligned(); +``` + +## Styling + +All the segments in the path can be customized to have different styles. + +```csharp +var path = new TextPath("C:/This/Path/Is/Too/Long/To/Fit/In/The/Area.txt"); + +path.RootStyle = new Style(foreground: Color.Red); +path.SeparatorStyle = new Style(foreground: Color.Green); +path.StemStyle = new Style(foreground: Color.Blue); +path.LeafStyle = new Style(foreground: Color.Yellow); +``` + +You can also specify styles via extension methods: + +```csharp +var path = new TextPath("C:/This/Path/Is/Too/Long/To/Fit/In/The/Area.txt") + .RootStyle(new Style(foreground: Color.Red)) + .SeparatorStyle(new Style(foreground: Color.Green)) + .StemStyle(new Style(foreground: Color.Blue)) + .LeafStyle(new Style(foreground: Color.Yellow)); +``` + +Or just set the colors via extension methods: + +```csharp +var path = new TextPath("C:/This/Path/Is/Too/Long/To/Fit/In/The/Area.txt") + .RootColor(Color.Red) + .SeparatorColor(Color.Green) + .StemColor(Color.Blue) + .LeafColor(Color.Yellow); +``` diff --git a/docs/package-lock.json b/docs/package-lock.json index 989b9b518..11fbdcdd5 100644 --- a/docs/package-lock.json +++ b/docs/package-lock.json @@ -5,7 +5,6 @@ "requires": true, "packages": { "": { - "name": "docs", "version": "1.0.0", "license": "MIT", "devDependencies": { diff --git a/docs/src/Shortcodes/InfoShortcode.cs b/docs/src/Shortcodes/InfoShortcode.cs new file mode 100644 index 000000000..cb4805bad --- /dev/null +++ b/docs/src/Shortcodes/InfoShortcode.cs @@ -0,0 +1,13 @@ +using System.Collections.Generic; +using Statiq.Common; + +namespace Docs.Shortcodes +{ + public class InfoShortcode : SyncShortcode + { + public override ShortcodeResult Execute(KeyValuePair[] args, string content, IDocument document, IExecutionContext context) + { + return $"
{content}
"; + } + } +} \ No newline at end of file diff --git a/examples/Console/Paths/Program.cs b/examples/Console/Paths/Program.cs index cb303864d..baeac890d 100644 --- a/examples/Console/Paths/Program.cs +++ b/examples/Console/Paths/Program.cs @@ -40,15 +40,15 @@ private static void WriteColorized(string windowsPath, string unixPath) new TextPath(windowsPath) .RootColor(Color.Blue) .SeparatorColor(Color.Yellow) - .StemStyle(Color.Red) - .LeafStyle(Color.Green)); + .StemColor(Color.Red) + .LeafColor(Color.Green)); table.AddRow(new Text("Unix"), new TextPath(unixPath) .RootColor(Color.Blue) .SeparatorColor(Color.Yellow) - .StemStyle(Color.Red) - .LeafStyle(Color.Green)); + .StemColor(Color.Red) + .LeafColor(Color.Green)); AnsiConsole.Write(table); } diff --git a/resources/scripts/Generator/Commands/AsciiCast/Samples/TextPathSample.cs b/resources/scripts/Generator/Commands/AsciiCast/Samples/TextPathSample.cs new file mode 100644 index 000000000..6e6543f4e --- /dev/null +++ b/resources/scripts/Generator/Commands/AsciiCast/Samples/TextPathSample.cs @@ -0,0 +1,44 @@ +using DocExampleGenerator; +using Spectre.Console; + +namespace Generator.Commands.Samples +{ + internal class TextPathSample : BaseSample + { + public override (int Cols, int Rows) ConsoleSize => (40, 23); + + public override void Run(IAnsiConsole console) + { + console.Write( + new Panel( + new Padder(new TextPath("C:/This/Is/A/Super/Long/Path/That/Will/Be/Truncated.txt"), new Padding(0,1))) + .BorderStyle(new Style(foreground: Color.Grey)) + .Header("Windows path")); + + console.Write( + new Panel( + new Padder(new TextPath("/This/Is/A/Super/Long/Path/That/Will/Be/Truncated.txt"), new Padding(0,1))) + .BorderStyle(new Style(foreground: Color.Grey)) + .Header("Unix path")); + + console.Write( + new Panel( + new Padder(new TextPath("/This/Is/A/Long/Path/That/Will/Be/Truncated.txt") + .RootColor(Color.Green) + .SeparatorColor(Color.Red) + .StemColor(Color.Yellow) + .LeafColor(Color.Blue), new Padding(0,1))) + .BorderStyle(new Style(foreground: Color.Grey)) + .Header("Styling")); + + console.Write( + new Panel( + new Padder(new Rows( + new TextPath("/This/Is/A/Long/Path/That/Will/Be/Truncated.txt").LeftAligned(), + new TextPath("/This/Is/A/Long/Path/That/Will/Be/Truncated.txt").Centered(), + new TextPath("/This/Is/A/Long/Path/That/Will/Be/Truncated.txt").RightAligned()), new Padding(0,1))) + .BorderStyle(new Style(foreground: Color.Grey)) + .Header("Alignment")); + } + } +} \ No newline at end of file diff --git a/src/Spectre.Console/Extensions/TextPathExtensions.cs b/src/Spectre.Console/Extensions/TextPathExtensions.cs index f118ac17a..26200bdcc 100644 --- a/src/Spectre.Console/Extensions/TextPathExtensions.cs +++ b/src/Spectre.Console/Extensions/TextPathExtensions.cs @@ -84,7 +84,7 @@ public static TextPath StemStyle(this TextPath obj, Style style) /// The path. /// The stem color. /// The same instance so that multiple calls can be chained. - public static TextPath StemStyle(this TextPath obj, Color color) + public static TextPath StemColor(this TextPath obj, Color color) { return StemStyle(obj, new Style(foreground: color)); } @@ -112,7 +112,7 @@ public static TextPath LeafStyle(this TextPath obj, Style style) /// The path. /// The leaf color. /// The same instance so that multiple calls can be chained. - public static TextPath LeafStyle(this TextPath obj, Color color) + public static TextPath LeafColor(this TextPath obj, Color color) { return LeafStyle(obj, new Style(foreground: color)); }