prehistoric-systems/Flow.Launcher
1
0
Fork 0
mirror of https://github.com/Flow-Launcher/Flow.Launcher.git synced 2026-03-11 08:54:32 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

merge PR #2193: Update Plugin documentation

Browse source
This commit is contained in:
Ioannis G 2023-06-26 14:03:19 +03:00 committed by GitHub
commit a48f06019e
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
10 changed files with 138 additions and 38 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

29
Flow.Launcher.Plugin/ActionContext.cs
View file

@ -2,18 +2,47 @@
namespace Flow.Launcher.Plugin
{
/// <summary>
/// Context provided as a parameter when invoking a
/// <see cref="Result.Action"/> or <see cref="Result.AsyncAction"/>
/// </summary>
public class ActionContext
{
/// <summary>
/// Contains the press state of certain special keys.
/// </summary>
public SpecialKeyState SpecialKeyState { get; set; }
}
/// <summary>
/// Contains the press state of certain special keys.
/// </summary>
public class SpecialKeyState
{
/// <summary>
/// True if the Ctrl key is pressed.
/// </summary>
public bool CtrlPressed { get; set; }
/// <summary>
/// True if the Shift key is pressed.
/// </summary>
public bool ShiftPressed { get; set; }
/// <summary>
/// True if the Alt key is pressed.
/// </summary>
public bool AltPressed { get; set; }
/// <summary>
/// True if the Windows key is pressed.
/// </summary>
public bool WinPressed { get; set; }
/// <summary>
/// Get this object represented as a <see cref="ModifierKeys"/> flag combination.
/// </summary>
/// <returns></returns>
public ModifierKeys ToModifierKeys()
{
return (CtrlPressed ? ModifierKeys.Control : ModifierKeys.None) |

3
Flow.Launcher.Plugin/Flow.Launcher.Plugin.csproj
View file

@ -26,6 +26,7 @@
<PackageTags>flowlauncher</PackageTags>
<GeneratePackageOnBuild>true</GeneratePackageOnBuild>
<PublishRepositoryUrl>true</PublishRepositoryUrl>
<PackageReadmeFile>Readme.md</PackageReadmeFile>
</PropertyGroup>
<PropertyGroup Condition="'$(APPVEYOR)' == 'True'">
@ -56,7 +57,7 @@
</PropertyGroup>
<ItemGroup>
<None Include="README.md" />
<None Include="Readme.md" Pack="true" PackagePath="\"/>
<None Include="FodyWeavers.xml" />
</ItemGroup>

11
Flow.Launcher.Plugin/Interfaces/IContextMenu.cs
View file

@ -1,9 +1,18 @@
using System.Collections.Generic;
using System.Collections.Generic;
namespace Flow.Launcher.Plugin
{
/// <summary>
/// Adds support for presenting additional options for a given <see cref="Result"/> from a context menu.
/// </summary>
public interface IContextMenu : IFeatures
{
/// <summary>
/// Load context menu items for the given result.
/// </summary>
/// <param name="selectedResult">
/// The <see cref="Result"/> for which the user has activated the context menu.
/// </param>
List<Result> LoadContextMenus(Result selectedResult);
}
}

8
Flow.Launcher.Plugin/Interfaces/IPluginI18n.cs
View file

@ -1,4 +1,4 @@
using System.Globalization;
using System.Globalization;
namespace Flow.Launcher.Plugin
{
@ -7,8 +7,14 @@ namespace Flow.Launcher.Plugin
/// </summary>
public interface IPluginI18n : IFeatures
{
/// <summary>
/// Get a localised version of the plugin's title
/// </summary>
string GetTranslatedPluginTitle();
/// <summary>
/// Get a localised version of the plugin's description
/// </summary>
string GetTranslatedPluginDescription();
/// <summary>

14
Flow.Launcher.Plugin/Interfaces/ISavable.cs
View file

@ -1,12 +1,18 @@
namespace Flow.Launcher.Plugin
namespace Flow.Launcher.Plugin
{
/// <summary>
/// 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.
/// </summary>
/// <remarks>
/// For storing plugin settings, prefer <see cref="IPublicAPI.LoadSettingJsonStorage{T}"/>
/// or <see cref="IPublicAPI.SaveSettingJsonStorage{T}"/>.
/// Once called, your settings will be automatically saved by Flow.
/// </remarks>
public interface ISavable : IFeatures
{
/// <summary>
/// Save additional plugin data, such as cache.
/// </summary>
void Save();
}
}

6
Flow.Launcher.Plugin/PluginInitContext.cs
View file

@ -1,5 +1,8 @@
namespace Flow.Launcher.Plugin
{
/// <summary>
/// Carries data passed to a plugin when it gets initialized.
/// </summary>
public class PluginInitContext
{
public PluginInitContext()
@ -12,6 +15,9 @@
API = api;
}
/// <summary>
/// The metadata of the plugin being initialized.
/// </summary>
public PluginMetadata CurrentPluginMetadata { get; internal set; }
/// <summary>

26
Flow.Launcher.Plugin/Query.cs
View file

@ -36,13 +36,14 @@ namespace Flow.Launcher.Plugin
/// <summary>
/// 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
/// </summary>
public string Search { get; internal init; }
/// <summary>
/// The search string split into a string array.
/// Does not include the <see cref="ActionKeyword"/>.
/// </summary>
public string[] SearchTerms { get; init; }
@ -59,6 +60,7 @@ namespace Flow.Launcher.Plugin
[Obsolete("Typo")]
public const string TermSeperater = TermSeparator;
/// <summary>
/// User can set multiple action keywords seperated by ';'
/// </summary>
@ -69,15 +71,22 @@ namespace Flow.Launcher.Plugin
/// <summary>
/// '*' is used for System Plugin
/// Wildcard action keyword. Plugins using this value will be queried on every search.
/// </summary>
public const string GlobalPluginWildcardSign = "*";
/// <summary>
/// The action keyword part of this query.
/// For global plugins this value will be empty.
/// </summary>
public string ActionKeyword { get; init; }
/// <summary>
/// Return first search split by space if it has
/// Splits <see cref="SearchTerms"/> by spaces and returns the first item.
/// </summary>
/// <remarks>
/// returns an empty string when <see cref="SearchTerms"/> does not have enough items.
/// </remarks>
public string FirstSearch => SplitSearch(0);
private string _secondToEndSearch;
@ -88,13 +97,19 @@ namespace Flow.Launcher.Plugin
public string SecondToEndSearch => SearchTerms.Length > 1 ? (_secondToEndSearch ??= string.Join(' ', SearchTerms[1..])) : "";
/// <summary>
/// Return second search split by space if it has
/// Splits <see cref="SearchTerms"/> by spaces and returns the second item.
/// </summary>
/// <remarks>
/// returns an empty string when <see cref="SearchTerms"/> does not have enough items.
/// </remarks>
public string SecondSearch => SplitSearch(1);
/// <summary>
/// Return third search split by space if it has
/// Splits <see cref="SearchTerms"/> by spaces and returns the third item.
/// </summary>
/// <remarks>
/// returns an empty string when <see cref="SearchTerms"/> does not have enough items.
/// </remarks>
public string ThirdSearch => SplitSearch(2);
private string SplitSearch(int index)
@ -102,6 +117,7 @@ namespace Flow.Launcher.Plugin
return index < SearchTerms.Length ? SearchTerms[index] : string.Empty;
}
/// <inheritdoc />
public override string ToString() => RawQuery;
}
}

11
Flow.Launcher.Plugin/README.md
View file

@ -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)

67
Flow.Launcher.Plugin/Result.cs
View file

@ -8,7 +8,7 @@ using System.Windows.Media;
namespace Flow.Launcher.Plugin
{
/// <summary>
/// Describes the result of a plugin
/// Describes a result of a <see cref="Query"/> executed by a plugin
/// </summary>
public class Result
{
@ -17,6 +17,8 @@ namespace Flow.Launcher.Plugin
private string _icoPath;
private string _copyText = string.Empty;
/// <summary>
/// The title of the result. This is always required.
/// </summary>
@ -28,13 +30,13 @@ namespace Flow.Launcher.Plugin
public string SubTitle { get; set; } = string.Empty;
/// <summary>
/// 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.
/// </summary>
public string ActionKeywordAssigned { get; set; }
/// <summary>
/// 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.
/// </summary>
@ -46,16 +48,17 @@ namespace Flow.Launcher.Plugin
/// <summary>
/// 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.
/// </summary>
/// <remarks>When a value is not set, the <see cref="Title"/> will be used.</remarks>
public string AutoCompleteText { get; set; }
/// <summary>
/// Image Displayed on the result
/// <value>Relative Path to the Image File</value>
/// <remarks>GlyphInfo is prioritized if not null</remarks>
/// The image to be displayed for the result.
/// </summary>
/// <value>Can be a local file path or a URL.</value>
/// <remarks>GlyphInfo is prioritized if not null</remarks>
public string IcoPath
{
get { return _icoPath; }
@ -76,22 +79,22 @@ namespace Flow.Launcher.Plugin
}
}
}
/// <summary>
/// Determines if Icon has a border radius
/// </summary>
public bool RoundedIcon { get; set; } = false;
/// <summary>
/// Delegate function, see <see cref="Icon"/>
/// Delegate function that produces an <see cref="ImageSource"/>
/// </summary>
/// <returns></returns>
public delegate ImageSource IconDelegate();
/// <summary>
/// Delegate to Get Image Source
/// Delegate to load an icon for this result.
/// </summary>
public IconDelegate Icon;
private string _copyText = string.Empty;
/// <summary>
/// Information for Glyph Icon (Prioritized than IcoPath/Icon if user enable Glyph Icons)
@ -100,25 +103,29 @@ namespace Flow.Launcher.Plugin
/// <summary>
/// Delegate. An action to take in the form of a function call when the result has been selected
/// <returns>
/// true to hide flowlauncher after select result
/// </returns>
/// An action to take in the form of a function call when the result has been selected.
/// </summary>
/// <remarks>
/// The function is invoked with an <see cref="ActionContext"/> 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.
/// </remarks>
public Func<ActionContext, bool> Action { get; set; }
/// <summary>
/// Delegate. An Async action to take in the form of a function call when the result has been selected
/// <returns>
/// true to hide flowlauncher after select result
/// </returns>
/// An async action to take in the form of a function call when the result has been selected.
/// </summary>
/// <remarks>
/// The function is invoked with an <see cref="ActionContext"/> 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.
/// </remarks>
public Func<ActionContext, ValueTask<bool>> AsyncAction { get; set; }
/// <summary>
/// Priority of the current result
/// <value>default: 0</value>
/// </summary>
/// <value>default: 0</value>
public int Score { get; set; }
/// <summary>
@ -183,10 +190,10 @@ namespace Flow.Launcher.Plugin
/// <summary>
/// Additional data associated with this result
/// </summary>
/// <example>
/// As external information for ContextMenu
/// </example>
/// </summary>
public object ContextData { get; set; }
/// <summary>
@ -230,10 +237,13 @@ namespace Flow.Launcher.Plugin
/// <default>#26a0da (blue)</default>
public string ProgressBarColor { get; set; } = "#26a0da";
/// <summary>
/// Contains data used to populate the the preview section of this result.
/// </summary>
public PreviewInfo Preview { get; set; } = PreviewInfo.Default;
/// <summary>
/// Info of the preview image.
/// Info of the preview section of a <see cref="Result"/>
/// </summary>
public record PreviewInfo
{
@ -241,13 +251,28 @@ namespace Flow.Launcher.Plugin
/// Full image used for preview panel
/// </summary>
public string PreviewImagePath { get; set; }
/// <summary>
/// Determines if the preview image should occupy the full width of the preview panel.
/// </summary>
public bool IsMedia { get; set; }
/// <summary>
/// Result description text that is shown at the bottom of the preview panel.
/// </summary>
/// <remarks>
/// When a value is not set, the <see cref="SubTitle"/> will be used.
/// </remarks>
public string Description { get; set; }
/// <summary>
/// Delegate to get the preview panel's image
/// </summary>
public IconDelegate PreviewDelegate { get; set; }
/// <summary>
/// Default instance of <see cref="PreviewInfo"/>
/// </summary>
public static PreviewInfo Default { get; } = new()
{
PreviewImagePath = null,

1
README.md
View file

@ -276,6 +276,7 @@ And you can download <a href="https://github.com/Flow-Launcher/Flow.Launcher/dis
| <kbd>Esc</kbd> | Back to results / hide search window |
| <kbd>Ctrl</kbd> +<kbd>C</kbd> | Copy the actual folder / file |
| <kbd>Ctrl</kbd> +<kbd>I</kbd> | Open flow's settings |
| <kbd>Ctrl</kbd> +<kbd>R</kbd> | Run the current query again (refresh results)|
| <kbd>F5</kbd> | Reload all plugin data |
| <kbd>Ctrl</kbd> + <kbd>F12</kbd> | Toggle Game Mode when in search window |
| <kbd>Ctrl</kbd> + <kbd>+</kbd>,<kbd>-</kbd> | Quickly change maximum results shown |