From be72c142b2abbd7809e821c5ecb30e6eaabe6abb Mon Sep 17 00:00:00 2001 From: Ioannis G Date: Sun, 18 Jun 2023 21:36:36 +0300 Subject: [PATCH 1/5] readme: document Ctrl+R hotkey --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index fdd33f3f866..b78bb3e3ead 100644 --- a/README.md +++ b/README.md @@ -276,6 +276,7 @@ And you can download executed by a plugin /// public class Result { @@ -17,6 +17,8 @@ public class Result private string _icoPath; + private string _copyText = string.Empty; + /// /// The title of the result. This is always required. /// @@ -28,13 +30,13 @@ public class Result public string SubTitle { get; set; } = string.Empty; /// - /// This holds the action keyword that triggered the result. + /// This holds the action keyword that triggered the result. /// If result is triggered by global keyword: *, this should be empty. /// public string ActionKeywordAssigned { get; set; } /// - /// This holds the text which can be provided by plugin to be copied to the + /// This holds the text which can be provided by plugin to be copied to the /// user's clipboard when Ctrl + C is pressed on a result. If the text is a file/directory path /// flow will copy the actual file/folder instead of just the path text. /// @@ -46,16 +48,17 @@ public string CopyText /// /// This holds the text which can be provided by plugin to help Flow autocomplete text - /// for user on the plugin result. If autocomplete action for example is tab, pressing tab will have + /// for user on the plugin result. If autocomplete action for example is tab, pressing tab will have /// the default constructed autocomplete text (result's Title), or the text provided here if not empty. /// + /// When a value is not set, the will be used. public string AutoCompleteText { get; set; } /// - /// Image Displayed on the result - /// Relative Path to the Image File - /// GlyphInfo is prioritized if not null + /// The image to be displayed for the result. /// + /// Can be a local file path or a URL. + /// GlyphInfo is prioritized if not null public string IcoPath { get { return _icoPath; } @@ -76,22 +79,22 @@ public string IcoPath } } } + /// /// Determines if Icon has a border radius /// public bool RoundedIcon { get; set; } = false; /// - /// Delegate function, see + /// Delegate function that produces an /// /// public delegate ImageSource IconDelegate(); /// - /// Delegate to Get Image Source + /// Delegate to load an icon for this result. /// public IconDelegate Icon; - private string _copyText = string.Empty; /// /// Information for Glyph Icon (Prioritized than IcoPath/Icon if user enable Glyph Icons) @@ -100,25 +103,29 @@ public string IcoPath /// - /// Delegate. An action to take in the form of a function call when the result has been selected - /// - /// true to hide flowlauncher after select result - /// + /// An action to take in the form of a function call when the result has been selected. /// + /// + /// The function is invoked with an as the only parameter. + /// Its result determines what happens to Flow Launcher's query form: + /// when true, the form will be hidden; when false, it will stay in focus. + /// public Func Action { get; set; } /// - /// Delegate. An Async action to take in the form of a function call when the result has been selected - /// - /// true to hide flowlauncher after select result - /// + /// An async action to take in the form of a function call when the result has been selected. /// + /// + /// The function is invoked with an as the only parameter and awaited. + /// Its result determines what happens to Flow Launcher's query form: + /// when true, the form will be hidden; when false, it will stay in focus. + /// public Func> AsyncAction { get; set; } /// /// Priority of the current result - /// default: 0 /// + /// default: 0 public int Score { get; set; } /// @@ -183,10 +190,10 @@ public override string ToString() /// /// Additional data associated with this result + /// /// /// As external information for ContextMenu /// - /// public object ContextData { get; set; } /// @@ -230,10 +237,13 @@ public ValueTask ExecuteAsync(ActionContext context) /// #26a0da (blue) public string ProgressBarColor { get; set; } = "#26a0da"; + /// + /// Contains data used to populate the the preview section of this result. + /// public PreviewInfo Preview { get; set; } = PreviewInfo.Default; /// - /// Info of the preview image. + /// Info of the preview section of a /// public record PreviewInfo { @@ -241,13 +251,28 @@ public record PreviewInfo /// Full image used for preview panel /// public string PreviewImagePath { get; set; } + /// /// Determines if the preview image should occupy the full width of the preview panel. /// public bool IsMedia { get; set; } + + /// + /// Result description text that is shown at the bottom of the preview panel. + /// + /// + /// When a value is not set, the will be used. + /// public string Description { get; set; } + + /// + /// Delegate to get the preview panel's image + /// public IconDelegate PreviewDelegate { get; set; } + /// + /// Default instance of + /// public static PreviewInfo Default { get; } = new() { PreviewImagePath = null, From 6ebac4e4b12d119045d91e10c2707e5c7f285f7c Mon Sep 17 00:00:00 2001 From: Ioannis G Date: Sun, 18 Jun 2023 22:29:40 +0300 Subject: [PATCH 3/5] update documentation in Query --- Flow.Launcher.Plugin/Query.cs | 26 +++++++++++++++++++++----- 1 file changed, 21 insertions(+), 5 deletions(-) diff --git a/Flow.Launcher.Plugin/Query.cs b/Flow.Launcher.Plugin/Query.cs index c3bd82c744e..edc5b1277bf 100644 --- a/Flow.Launcher.Plugin/Query.cs +++ b/Flow.Launcher.Plugin/Query.cs @@ -36,13 +36,14 @@ public Query(string rawQuery, string search, string[] terms, string[] searchTerm /// /// Search part of a query. /// This will not include action keyword if exclusive plugin gets it, otherwise it should be same as RawQuery. - /// Since we allow user to switch a exclusive plugin to generic plugin, + /// Since we allow user to switch a exclusive plugin to generic plugin, /// so this property will always give you the "real" query part of the query /// public string Search { get; internal init; } /// /// The search string split into a string array. + /// Does not include the . /// public string[] SearchTerms { get; init; } @@ -59,6 +60,7 @@ public Query(string rawQuery, string search, string[] terms, string[] searchTerm [Obsolete("Typo")] public const string TermSeperater = TermSeparator; + /// /// User can set multiple action keywords seperated by ';' /// @@ -69,15 +71,22 @@ public Query(string rawQuery, string search, string[] terms, string[] searchTerm /// - /// '*' is used for System Plugin + /// Wildcard action keyword. Plugins using this value will be queried on every search. /// public const string GlobalPluginWildcardSign = "*"; + /// + /// The action keyword part of this query. + /// For global plugins this value will be empty. + /// public string ActionKeyword { get; init; } /// - /// Return first search split by space if it has + /// Splits by spaces and returns the first item. /// + /// + /// returns an empty string when does not have enough items. + /// public string FirstSearch => SplitSearch(0); private string _secondToEndSearch; @@ -88,13 +97,19 @@ public Query(string rawQuery, string search, string[] terms, string[] searchTerm public string SecondToEndSearch => SearchTerms.Length > 1 ? (_secondToEndSearch ??= string.Join(' ', SearchTerms[1..])) : ""; /// - /// Return second search split by space if it has + /// Splits by spaces and returns the second item. /// + /// + /// returns an empty string when does not have enough items. + /// public string SecondSearch => SplitSearch(1); /// - /// Return third search split by space if it has + /// Splits by spaces and returns the third item. /// + /// + /// returns an empty string when does not have enough items. + /// public string ThirdSearch => SplitSearch(2); private string SplitSearch(int index) @@ -102,6 +117,7 @@ private string SplitSearch(int index) return index < SearchTerms.Length ? SearchTerms[index] : string.Empty; } + /// public override string ToString() => RawQuery; } } From bb5e1d3a1919caf5d22ecbb72b0cc30c3e62ff03 Mon Sep 17 00:00:00 2001 From: Ioannis G Date: Sun, 18 Jun 2023 22:53:01 +0300 Subject: [PATCH 4/5] more documentation in Plugin package --- Flow.Launcher.Plugin/ActionContext.cs | 29 +++++++++++++++++++ .../Interfaces/IContextMenu.cs | 11 ++++++- .../Interfaces/IPluginI18n.cs | 8 ++++- Flow.Launcher.Plugin/Interfaces/ISavable.cs | 14 ++++++--- Flow.Launcher.Plugin/PluginInitContext.cs | 6 ++++ 5 files changed, 62 insertions(+), 6 deletions(-) diff --git a/Flow.Launcher.Plugin/ActionContext.cs b/Flow.Launcher.Plugin/ActionContext.cs index d898972da8c..d6ba4894e6b 100644 --- a/Flow.Launcher.Plugin/ActionContext.cs +++ b/Flow.Launcher.Plugin/ActionContext.cs @@ -2,18 +2,47 @@ namespace Flow.Launcher.Plugin { + /// + /// Context provided as a parameter when invoking a + /// or + /// public class ActionContext { + /// + /// Contains the press state of certain special keys. + /// public SpecialKeyState SpecialKeyState { get; set; } } + /// + /// Contains the press state of certain special keys. + /// public class SpecialKeyState { + /// + /// True if the Ctrl key is pressed. + /// public bool CtrlPressed { get; set; } + + /// + /// True if the Shift key is pressed. + /// public bool ShiftPressed { get; set; } + + /// + /// True if the Alt key is pressed. + /// public bool AltPressed { get; set; } + + /// + /// True if the Windows key is pressed. + /// public bool WinPressed { get; set; } + /// + /// Get this object represented as a flag combination. + /// + /// public ModifierKeys ToModifierKeys() { return (CtrlPressed ? ModifierKeys.Control : ModifierKeys.None) | diff --git a/Flow.Launcher.Plugin/Interfaces/IContextMenu.cs b/Flow.Launcher.Plugin/Interfaces/IContextMenu.cs index 5befbf5c986..06398fb1bc2 100644 --- a/Flow.Launcher.Plugin/Interfaces/IContextMenu.cs +++ b/Flow.Launcher.Plugin/Interfaces/IContextMenu.cs @@ -1,9 +1,18 @@ -using System.Collections.Generic; +using System.Collections.Generic; namespace Flow.Launcher.Plugin { + /// + /// Adds support for presenting additional options for a given from a context menu. + /// public interface IContextMenu : IFeatures { + /// + /// Load context menu items for the given result. + /// + /// + /// The for which the user has activated the context menu. + /// List LoadContextMenus(Result selectedResult); } } \ No newline at end of file diff --git a/Flow.Launcher.Plugin/Interfaces/IPluginI18n.cs b/Flow.Launcher.Plugin/Interfaces/IPluginI18n.cs index 61662b671a2..bbc998fcb8e 100644 --- a/Flow.Launcher.Plugin/Interfaces/IPluginI18n.cs +++ b/Flow.Launcher.Plugin/Interfaces/IPluginI18n.cs @@ -1,4 +1,4 @@ -using System.Globalization; +using System.Globalization; namespace Flow.Launcher.Plugin { @@ -7,8 +7,14 @@ namespace Flow.Launcher.Plugin /// public interface IPluginI18n : IFeatures { + /// + /// Get a localised version of the plugin's title + /// string GetTranslatedPluginTitle(); + /// + /// Get a localised version of the plugin's description + /// string GetTranslatedPluginDescription(); /// diff --git a/Flow.Launcher.Plugin/Interfaces/ISavable.cs b/Flow.Launcher.Plugin/Interfaces/ISavable.cs index 2d13eaa6e1c..77bd304e4ea 100644 --- a/Flow.Launcher.Plugin/Interfaces/ISavable.cs +++ b/Flow.Launcher.Plugin/Interfaces/ISavable.cs @@ -1,12 +1,18 @@ -namespace Flow.Launcher.Plugin +namespace Flow.Launcher.Plugin { /// - /// Save addtional plugin data. Inherit this interface if additional data e.g. cache needs to be saved, - /// Otherwise if LoadSettingJsonStorage or SaveSettingJsonStorage has been callded, - /// plugin settings will be automatically saved (see Flow.Launcher/PublicAPIInstance.SavePluginSettings) by Flow + /// Inherit this interface if additional data e.g. cache needs to be saved. /// + /// + /// For storing plugin settings, prefer + /// or . + /// Once called, your settings will be automatically saved by Flow. + /// public interface ISavable : IFeatures { + /// + /// Save additional plugin data, such as cache. + /// void Save(); } } \ No newline at end of file diff --git a/Flow.Launcher.Plugin/PluginInitContext.cs b/Flow.Launcher.Plugin/PluginInitContext.cs index 233ead8f9d3..f040752bd60 100644 --- a/Flow.Launcher.Plugin/PluginInitContext.cs +++ b/Flow.Launcher.Plugin/PluginInitContext.cs @@ -1,5 +1,8 @@ namespace Flow.Launcher.Plugin { + /// + /// Carries data passed to a plugin when it gets initialized. + /// public class PluginInitContext { public PluginInitContext() @@ -12,6 +15,9 @@ public PluginInitContext(PluginMetadata currentPluginMetadata, IPublicAPI api) API = api; } + /// + /// The metadata of the plugin being initialized. + /// public PluginMetadata CurrentPluginMetadata { get; internal set; } /// From da41f2c4f17903ebb091bd4a3f535ee3b1c016ae Mon Sep 17 00:00:00 2001 From: Ioannis G Date: Sun, 18 Jun 2023 23:32:15 +0300 Subject: [PATCH 5/5] update plugin readme, include in nupkg --- Flow.Launcher.Plugin/Flow.Launcher.Plugin.csproj | 3 ++- Flow.Launcher.Plugin/README.md | 11 ++++++----- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/Flow.Launcher.Plugin/Flow.Launcher.Plugin.csproj b/Flow.Launcher.Plugin/Flow.Launcher.Plugin.csproj index 28344cf4696..e72672a5bf5 100644 --- a/Flow.Launcher.Plugin/Flow.Launcher.Plugin.csproj +++ b/Flow.Launcher.Plugin/Flow.Launcher.Plugin.csproj @@ -26,6 +26,7 @@ flowlauncher true true + Readme.md @@ -56,7 +57,7 @@ - + diff --git a/Flow.Launcher.Plugin/README.md b/Flow.Launcher.Plugin/README.md index 5c5b7c3edc1..f3091a1fcaf 100644 --- a/Flow.Launcher.Plugin/README.md +++ b/Flow.Launcher.Plugin/README.md @@ -1,6 +1,7 @@ -What does Flow.Launcher.Plugin do? -==== +Reference this package to develop a plugin for [Flow Launcher](https://github.com/Flow-Launcher/Flow.Launcher). -* Defines base objects and interfaces for plugins -* Plugin authors making C# plugins should reference this DLL via nuget -* Contains commands and models that can be used by plugins +Useful links: + +* [General plugin development guide](https://www.flowlauncher.com/docs/#/plugin-dev) +* [.Net plugin development guide](https://www.flowlauncher.com/docs/#/develop-dotnet-plugins) +* [Package API Reference](https://www.flowlauncher.com/docs/#/API-Reference/Flow.Launcher.Plugin)