[PTRun][ValueGenerator]Add result entries showing how to use (#33490)

## Summary of the Pull Request
Added usage suggestion in PTRun Value Generator. 

<!-- Provide a more detailed description of the PR, other things fixed
or any additional comments/features here -->
## Detailed Description of the Pull Request / Additional comments
Added dropdown and give a basic description about the usage of value
generator

![image](https://github.com/microsoft/PowerToys/assets/24465401/2f9e01d1-1f5a-42b5-9234-f768b27124db)

Using fuzzy match to filter relevant queries

![image](https://github.com/microsoft/PowerToys/assets/24465401/dd0594bb-328a-4a8d-9d7c-e3b5732a8573)

---------

Co-authored-by: Heiko <61519853+htcfreek@users.noreply.github.com>

.github/actions/spell-check/expect.txt

@@ -1686,6 +1686,7 @@ USESHOWWINDOW
 USESTDHANDLES
 USRDLL
 UType
+uuidv
 uwp
 uxtheme
 vabdq

src/modules/launcher/Plugins/Community.PowerToys.Run.Plugin.ValueGenerator/GeneratorData.cs

@@ -0,0 +1,15 @@
+// Copyright (c) Microsoft Corporation
+// The Microsoft Corporation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+namespace Community.PowerToys.Run.Plugin.ValueGenerator
+{
+    internal sealed class GeneratorData
+    {
+        public string Keyword { get; set; }
+
+        public string Description { get; set; }
+
+        public string Example { get; set; }
+    }
+}

src/modules/launcher/Plugins/Community.PowerToys.Run.Plugin.ValueGenerator/Helper/QueryHelper.cs

@@ -0,0 +1,173 @@
+// Copyright (c) Microsoft Corporation
+// The Microsoft Corporation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using System.Collections.Generic;
+using System.Globalization;
+using System.Text;
+using Community.PowerToys.Run.Plugin.ValueGenerator.Properties;
+
+namespace Community.PowerToys.Run.Plugin.ValueGenerator.Helper
+{
+    /// <summary>
+    /// Helper class to easier work with queries
+    /// </summary>
+    internal static class QueryHelper
+    {
+        /// <summary>
+        /// a list of all value generator descriptions
+        /// </summary>
+        private static readonly string GeneratorDescriptionUuid = Resources.generator_description_uuid;
+        private static readonly string GeneratorDescriptionUuidv1 = Resources.generator_description_uuidv1;
+        private static readonly string GeneratorDescriptionUuidv3 = Resources.generator_description_uuidv3;
+        private static readonly string GeneratorDescriptionUuidv4 = Resources.generator_description_uuidv4;
+        private static readonly string GeneratorDescriptionUuidv5 = Resources.generator_description_uuidv5;
+        private static readonly string GeneratorDescriptionHash = Resources.generator_description_hash;
+        private static readonly string GeneratorDescriptionBase64 = Resources.generator_description_base64;
+        private static readonly string GeneratorDescriptionBase64d = Resources.generator_description_base64d;
+        private static readonly string GeneratorDescriptionUrl = Resources.generator_description_url;
+        private static readonly string GeneratorDescriptionUrld = Resources.generator_description_urld;
+        private static readonly string GeneratorDescriptionEscData = Resources.generator_description_esc_data;
+        private static readonly string GeneratorDescriptionUescData = Resources.generator_description_uesc_data;
+        private static readonly string GeneratorDescriptionEscHex = Resources.generator_description_esc_hex;
+        private static readonly string GeneratorDescriptionUescHex = Resources.generator_description_uesc_hex;
+        private static readonly string GeneratorDescriptionYourInput = Resources.generator_description_your_input;
+        private static readonly string GeneratorExample = Resources.generator_example;
+        private static readonly string Or = Resources.or;
+
+        private static string GetStringFormat(string value, string arg)
+        {
+            return string.Format(CultureInfo.CurrentCulture, value, arg);
+        }
+
+        private static string GetStringFormat(string value)
+        {
+            return string.Format(CultureInfo.CurrentCulture, value);
+        }
+
+        internal static string GetResultTitle(GeneratorData generatorData)
+        {
+            return $"{generatorData.Keyword} - {generatorData.Description}";
+        }
+
+        internal static string GetResultSubtitle(GeneratorData generatorData)
+        {
+            return GetStringFormat(GeneratorExample, generatorData.Example);
+        }
+
+        /// <summary>
+        /// A list that contain all of the value generators and its descriptions
+        /// </summary>
+        internal static readonly List<GeneratorData> GeneratorDataList =
+        [
+            new()
+            {
+                Keyword = "uuid",
+                Description = GetStringFormat(GeneratorDescriptionUuid),
+                Example = $"uuid {GetStringFormat(Or)} guid",
+            },
+            new()
+            {
+                Keyword = "uuidv1",
+                Description = GetStringFormat(GeneratorDescriptionUuidv1),
+                Example = $"uuidv1 {GetStringFormat(Or)} uuid1",
+            },
+            new()
+            {
+                Keyword = "uuidv3",
+                Description = GetStringFormat(GeneratorDescriptionUuidv3),
+                Example = $"uuidv3 ns:<DNS, URL, OID, {GetStringFormat(Or)} X500> <{GetStringFormat(GeneratorDescriptionYourInput)}>",
+            },
+            new()
+            {
+                Keyword = "uuidv4",
+                Description = GetStringFormat(GeneratorDescriptionUuidv4),
+                Example = $"uuidv4 {GetStringFormat(Or)} uuid4",
+            },
+            new()
+            {
+                Keyword = "uuidv5",
+                Description = GetStringFormat(GeneratorDescriptionUuidv5),
+                Example = $"uuidv5 ns:<DNS, URL, OID, {GetStringFormat(Or)} X500> <{GetStringFormat(GeneratorDescriptionYourInput)}>",
+            },
+            new()
+            {
+                Keyword = "md5",
+                Description = GetStringFormat(GeneratorDescriptionHash, "MD5"),
+                Example = $"md5 <{GetStringFormat(GeneratorDescriptionYourInput)}>",
+            },
+            new()
+            {
+                Keyword = "sha1",
+                Description = GetStringFormat(GeneratorDescriptionHash, "SHA1"),
+                Example = $"sha1 <{GetStringFormat(GeneratorDescriptionYourInput)}>",
+            },
+            new()
+            {
+                Keyword = "sha256",
+                Description = GetStringFormat(GeneratorDescriptionHash, "SHA256"),
+                Example = $"sha256 <{GetStringFormat(GeneratorDescriptionYourInput)}>",
+            },
+            new()
+            {
+                Keyword = "sha384",
+                Description = GetStringFormat(GeneratorDescriptionHash, "SHA384"),
+                Example = $"sha384 <{GetStringFormat(GeneratorDescriptionYourInput)}>",
+            },
+            new()
+            {
+                Keyword = "sha512",
+                Description = GetStringFormat(GeneratorDescriptionHash, "SHA512"),
+                Example = $"sha512 <{GetStringFormat(GeneratorDescriptionYourInput)}>",
+            },
+            new()
+            {
+                Keyword = "base64",
+                Description = GetStringFormat(GeneratorDescriptionBase64),
+                Example = $"base64 <{GetStringFormat(GeneratorDescriptionYourInput)}>",
+            },
+            new()
+            {
+                Keyword = "base64d",
+                Description = GetStringFormat(GeneratorDescriptionBase64d),
+                Example = $"base64d <{GetStringFormat(GeneratorDescriptionYourInput)}>",
+            },
+            new()
+            {
+                Keyword = "url",
+                Description = GetStringFormat(GeneratorDescriptionUrl),
+                Example = "url https://bing.com/?q=My Test query",
+            },
+            new()
+            {
+                Keyword = "urld",
+                Description = GetStringFormat(GeneratorDescriptionUrld),
+                Example = "urld https://bing.com/?q=My+Test+query",
+            },
+            new()
+            {
+                Keyword = "esc:data",
+                Description = GetStringFormat(GeneratorDescriptionEscData),
+                Example = "esc:data C:\\Program Files\\PowerToys\\PowerToys.exe",
+            },
+            new()
+            {
+                Keyword = "uesc:data",
+                Description = GetStringFormat(GeneratorDescriptionUescData),
+                Example = "uesc:data C%3A%5CProgram%20Files%5CPowerToys%5CPowerToys.exe",
+            },
+            new()
+            {
+                Keyword = "esc:hex",
+                Description = GetStringFormat(GeneratorDescriptionEscHex),
+                Example = "esc:hex z",
+            },
+            new()
+            {
+                Keyword = "uesc:hex",
+                Description = GetStringFormat(GeneratorDescriptionUescHex),
+                Example = "uesc:hex %7A",
+            },
+        ];
+    }
+}

src/modules/launcher/Plugins/Community.PowerToys.Run.Plugin.ValueGenerator/InputParser.cs

@@ -64,7 +64,7 @@ namespace Community.PowerToys.Run.Plugin.ValueGenerator
                         algorithmName = HashAlgorithmName.SHA512;
                         break;
                     default:
-                        throw new ArgumentException("Unknown SHA variant. Supported variants: SHA1, SHA256, SHA384, SHA512");
+                        throw new FormatException("Unknown SHA variant. Supported variants: SHA1, SHA256, SHA384, SHA512");
                 }
 
                 if (content == string.Empty)
@@ -93,7 +93,7 @@ namespace Community.PowerToys.Run.Plugin.ValueGenerator
 
                     if (!int.TryParse(versionQuery, null, out version))
                     {
-                        throw new ArgumentException("Could not determine requested GUID version");
+                        throw new FormatException("Could not determine requested GUID version. Supported versions are 1, 3, 4 and 5");
                     }
                 }
 
@@ -103,7 +103,7 @@ namespace Community.PowerToys.Run.Plugin.ValueGenerator
 
                     if (sParameters.Length != 2)
                     {
-                        throw new ArgumentException("GUID versions 3 and 5 require 2 parameters - a namespace GUID and a name");
+                        throw new ArgumentException($"GUID version {version} require 2 parameters - a namespace GUID and a name.\nExample: uuidv{version} ns:<DNS, URL, OID, or X500> <your input>");
                     }
 
                     string namespaceParameter = sParameters[0];

src/modules/launcher/Plugins/Community.PowerToys.Run.Plugin.ValueGenerator/Main.cs

@@ -7,8 +7,10 @@ using System.Collections.Generic;
 using System.Runtime.InteropServices;
 using System.Threading;
 using System.Windows;
+using Community.PowerToys.Run.Plugin.ValueGenerator.Helper;
 using Community.PowerToys.Run.Plugin.ValueGenerator.Properties;
 using ManagedCommon;
+using Wox.Infrastructure;
 using Wox.Plugin;
 using Wox.Plugin.Logger;
 
@@ -59,6 +61,19 @@ namespace Community.PowerToys.Run.Plugin.ValueGenerator
             }
         }
 
+        private static string GetIcoPath(bool isWarning = false)
+        {
+            var imageName = isWarning ? "Warning" : "ValueGenerator";
+            if (_isLightTheme)
+            {
+                return $"Images/{imageName}.light.png";
+            }
+            else
+            {
+                return $"Images/{imageName}.dark.png";
+            }
+        }
+
         protected virtual void Dispose(bool disposing)
         {
             if (!_disposed)
@@ -90,6 +105,11 @@ namespace Community.PowerToys.Run.Plugin.ValueGenerator
             ArgumentNullException.ThrowIfNull(query);
 
             var results = new List<Result>();
+            if (string.IsNullOrWhiteSpace(query?.Search) && !string.IsNullOrEmpty(query?.ActionKeyword))
+            {
+                return GetSuggestionResults(query, results);
+            }
+
             try
             {
                 IComputeRequest computeRequest = _inputParser.ParseInput(query);
@@ -110,7 +130,33 @@ namespace Community.PowerToys.Run.Plugin.ValueGenerator
             }
             catch (FormatException e)
             {
-               Log.Debug(GetTranslatedPluginTitle() + ": " + e.Message, GetType());
+                Log.Debug(GetTranslatedPluginTitle() + ": " + e.Message, GetType());
+                if (!string.IsNullOrEmpty(query.ActionKeyword))
+                {
+                    return GetSuggestionFuzzyResults(query, results);
+                }
+            }
+
+            return results;
+        }
+
+        private List<Result> GetSuggestionResults(Query query, List<Result> results)
+        {
+            foreach (var generatorData in QueryHelper.GeneratorDataList)
+            {
+                results.Add(new Result
+                {
+                    Title = QueryHelper.GetResultTitle(generatorData),
+                    SubTitle = QueryHelper.GetResultSubtitle(generatorData),
+                    IcoPath = GetIcoPath(),
+                    ToolTipData = new ToolTipData(QueryHelper.GetResultTitle(generatorData), QueryHelper.GetResultSubtitle(generatorData)),
+                    QueryTextDisplay = generatorData.Keyword + " ",
+                    Action = c =>
+                    {
+                        _context.API.ChangeQuery($"{query.ActionKeyword} {generatorData.Keyword} ", true);
+                        return false;
+                    },
+                });
             }
 
             return results;
@@ -124,7 +170,7 @@ namespace Community.PowerToys.Run.Plugin.ValueGenerator
             {
                 ContextData = request.Result,
                 Title = request.ResultToString(),
-                IcoPath = _isLightTheme ? "Images/ValueGenerator.light.png" : "Images/ValueGenerator.dark.png",
+                IcoPath = GetIcoPath(),
                 Score = 300,
                 SubTitle = request.Description,
                 Action = c =>
@@ -150,13 +196,42 @@ namespace Community.PowerToys.Run.Plugin.ValueGenerator
             };
         }
 
+        private List<Result> GetSuggestionFuzzyResults(Query query, List<Result> results)
+        {
+            foreach (var generatorData in QueryHelper.GeneratorDataList)
+            {
+                var matchScore = StringMatcher.FuzzySearch(query.Search.Trim(), generatorData.Keyword).Score;
+
+                if (matchScore > 0)
+                {
+                    results.Add(new Result
+                    {
+                        Title = QueryHelper.GetResultTitle(generatorData),
+                        SubTitle = QueryHelper.GetResultSubtitle(generatorData),
+                        IcoPath = GetIcoPath(),
+                        Score = matchScore,
+                        ToolTipData = new ToolTipData(QueryHelper.GetResultTitle(generatorData), QueryHelper.GetResultSubtitle(generatorData)),
+                        QueryTextDisplay = generatorData.Keyword + " ",
+                        Action = c =>
+                        {
+                            _context.API.ChangeQuery($"{query.ActionKeyword} {generatorData.Keyword} ", true);
+                            return false;
+                        },
+                    });
+                }
+            }
+
+            return results;
+        }
+
         private Result GetErrorResult(string errorMessage)
         {
             return new Result
             {
                 Title = Resources.error_title,
                 SubTitle = errorMessage,
-                IcoPath = _isLightTheme ? "Images/Warning.light.png" : "Images/Warning.dark.png",
+                ToolTipData = new ToolTipData(Resources.error_title, errorMessage),
+                IcoPath = GetIcoPath(isWarning: true),
                 Action = _ => { return true; },
             };
         }

src/modules/launcher/Plugins/Community.PowerToys.Run.Plugin.ValueGenerator/Properties/Resources.Designer.cs

@@ -87,6 +87,159 @@ namespace Community.PowerToys.Run.Plugin.ValueGenerator.Properties {
             }
         }
         
+        /// <summary>
+        ///   Looks up a localized string similar to Encode a string with Base64.
+        /// </summary>
+        public static string generator_description_base64 {
+            get {
+                return ResourceManager.GetString("generator_description_base64", resourceCulture);
+            }
+        }
+        
+        /// <summary>
+        ///   Looks up a localized string similar to Decode a string with Base64.
+        /// </summary>
+        public static string generator_description_base64d {
+            get {
+                return ResourceManager.GetString("generator_description_base64d", resourceCulture);
+            }
+        }
+        
+        /// <summary>
+        ///   Looks up a localized string similar to Escape a data string.
+        /// </summary>
+        public static string generator_description_esc_data {
+            get {
+                return ResourceManager.GetString("generator_description_esc_data", resourceCulture);
+            }
+        }
+        
+        /// <summary>
+        ///   Looks up a localized string similar to Escape a single hex character.
+        /// </summary>
+        public static string generator_description_esc_hex {
+            get {
+                return ResourceManager.GetString("generator_description_esc_hex", resourceCulture);
+            }
+        }
+        
+        /// <summary>
+        ///   Looks up a localized string similar to Hash a string with {0}.
+        /// </summary>
+        public static string generator_description_hash {
+            get {
+                return ResourceManager.GetString("generator_description_hash", resourceCulture);
+            }
+        }
+        
+        /// <summary>
+        ///   Looks up a localized string similar to Unescape a data string.
+        /// </summary>
+        public static string generator_description_uesc_data {
+            get {
+                return ResourceManager.GetString("generator_description_uesc_data", resourceCulture);
+            }
+        }
+        
+        /// <summary>
+        ///   Looks up a localized string similar to Unescape a single hex character.
+        /// </summary>
+        public static string generator_description_uesc_hex {
+            get {
+                return ResourceManager.GetString("generator_description_uesc_hex", resourceCulture);
+            }
+        }
+        
+        /// <summary>
+        ///   Looks up a localized string similar to Encode a URL.
+        /// </summary>
+        public static string generator_description_url {
+            get {
+                return ResourceManager.GetString("generator_description_url", resourceCulture);
+            }
+        }
+        
+        /// <summary>
+        ///   Looks up a localized string similar to Decode a URL.
+        /// </summary>
+        public static string generator_description_urld {
+            get {
+                return ResourceManager.GetString("generator_description_urld", resourceCulture);
+            }
+        }
+        
+        /// <summary>
+        ///   Looks up a localized string similar to Generate a random UUID.
+        /// </summary>
+        public static string generator_description_uuid {
+            get {
+                return ResourceManager.GetString("generator_description_uuid", resourceCulture);
+            }
+        }
+        
+        /// <summary>
+        ///   Looks up a localized string similar to Generate a version 1: Time based UUID.
+        /// </summary>
+        public static string generator_description_uuidv1 {
+            get {
+                return ResourceManager.GetString("generator_description_uuidv1", resourceCulture);
+            }
+        }
+        
+        /// <summary>
+        ///   Looks up a localized string similar to Generate a version 3 (MD5): Namespace and name based UUID.
+        /// </summary>
+        public static string generator_description_uuidv3 {
+            get {
+                return ResourceManager.GetString("generator_description_uuidv3", resourceCulture);
+            }
+        }
+        
+        /// <summary>
+        ///   Looks up a localized string similar to Generate a version 4: Randomly generated UUID.
+        /// </summary>
+        public static string generator_description_uuidv4 {
+            get {
+                return ResourceManager.GetString("generator_description_uuidv4", resourceCulture);
+            }
+        }
+        
+        /// <summary>
+        ///   Looks up a localized string similar to Generate a version 5 (SHA1): Namespace and name based UUID.
+        /// </summary>
+        public static string generator_description_uuidv5 {
+            get {
+                return ResourceManager.GetString("generator_description_uuidv5", resourceCulture);
+            }
+        }
+        
+        /// <summary>
+        ///   Looks up a localized string similar to your input.
+        /// </summary>
+        public static string generator_description_your_input {
+            get {
+                return ResourceManager.GetString("generator_description_your_input", resourceCulture);
+            }
+        }
+        
+        /// <summary>
+        ///   Looks up a localized string similar to Example: {0}.
+        /// </summary>
+        public static string generator_example {
+            get {
+                return ResourceManager.GetString("generator_example", resourceCulture);
+            }
+        }
+        
+        /// <summary>
+        ///   Looks up a localized string similar to or.
+        /// </summary>
+        public static string or {
+            get {
+                return ResourceManager.GetString("or", resourceCulture);
+            }
+        }
+        
         /// <summary>
         ///   Looks up a localized string similar to Calculates hashes and generate values.
         /// </summary>

src/modules/launcher/Plugins/Community.PowerToys.Run.Plugin.ValueGenerator/Properties/Resources.resx

@@ -126,6 +126,60 @@
   <data name="error_title" xml:space="preserve">
     <value>Value Generator Error</value>
   </data>
+  <data name="generator_description_base64" xml:space="preserve">
+    <value>Encode a string with Base64</value>
+  </data>
+  <data name="generator_description_base64d" xml:space="preserve">
+    <value>Decode a string with Base64</value>
+  </data>
+  <data name="generator_description_esc_data" xml:space="preserve">
+    <value>Escape a data string</value>
+  </data>
+  <data name="generator_description_esc_hex" xml:space="preserve">
+    <value>Escape a single hex character</value>
+  </data>
+  <data name="generator_description_hash" xml:space="preserve">
+    <value>Hash a string with {0}</value>
+  </data>
+  <data name="generator_description_uesc_data" xml:space="preserve">
+    <value>Unescape a data string</value>
+  </data>
+  <data name="generator_description_uesc_hex" xml:space="preserve">
+    <value>Unescape a single hex character</value>
+  </data>
+  <data name="generator_description_url" xml:space="preserve">
+    <value>Encode a URL</value>
+  </data>
+  <data name="generator_description_urld" xml:space="preserve">
+    <value>Decode a URL</value>
+  </data>
+  <data name="generator_description_uuid" xml:space="preserve">
+    <value>Generate a random UUID</value>
+  </data>
+  <data name="generator_description_uuidv1" xml:space="preserve">
+    <value>Generate a version 1: Time based UUID</value>
+  </data>
+  <data name="generator_description_uuidv3" xml:space="preserve">
+    <value>Generate a version 3 (MD5): Namespace and name based UUID</value>
+  </data>
+  <data name="generator_description_uuidv4" xml:space="preserve">
+    <value>Generate a version 4: Randomly generated UUID</value>
+  </data>
+  <data name="generator_description_uuidv5" xml:space="preserve">
+    <value>Generate a version 5 (SHA1): Namespace and name based UUID</value>
+  </data>
+  <data name="generator_description_your_input" xml:space="preserve">
+    <value>your input</value>
+    <comment>Usage example: "md5 &lt;your input&gt;"</comment>
+  </data>
+  <data name="generator_example" xml:space="preserve">
+    <value>Example: {0}</value>
+    <comment>The arg following is the usage example</comment>
+  </data>
+  <data name="or" xml:space="preserve">
+    <value>or</value>
+    <comment>Used to indicate alternatives or options available</comment>
+  </data>
   <data name="plugin_description" xml:space="preserve">
     <value>Calculates hashes and generate values</value>
   </data>