Flow.Launcher.Plugin Codemap

Responsibility

The Flow.Launcher.Plugin module serves as the Plugin SDK for Flow.Launcher. It defines the essential building blocks, interfaces, and models required for developers to create plugins. It acts as the formal contract between the Flow.Launcher core application and its extensibility layer, ensuring a stable and consistent API for search results, UI interaction, and system integration across different plugin languages (C#, Python, JavaScript, etc.).

Design

The SDK is built on several key architectural patterns:

Interface-based Extensibility: The core functionality is driven by interfaces (IPlugin, IAsyncPlugin) that define how plugins are queried. Optional features are exposed via specialized interfaces like IContextMenu, ISettingProvider, and IReloadable.
Command/Action Pattern: The Result class encapsulates its own execution logic through Action and AsyncAction delegates. This decouples the search engine from the specific logic of what happens when a result is clicked.
Contextual Initialization: Plugins receive their environment data and a reference to the application's capabilities via PluginInitContext and the IPublicAPI interface during the Init phase.
Marker Interfaces: The IFeatures interface serves as a base for all optional capability interfaces, allowing the core system to dynamically discover and invoke plugin features.

Key Components:

Result: The primary model for search results, containing display data (Title, SubTitle, Icons) and execution delegates.
Query: Represents the user's input, providing parsed search terms and action keywords.
IPublicAPI: The interface providing plugins with access to global functions (logging, UI control, settings storage, HTTP utilities).
PluginMetadata: Identity and configuration data extracted from the plugin's plugin.json manifest.

Flow

The lifecycle and data flow of a plugin within Flow.Launcher follow a strictly defined sequence:

Discovery & Load: The PluginManager (in Core) scans the Plugins directory, parses plugin.json into PluginMetadata, and instantiates the plugin class.
Initialization: The Init(PluginInitContext) method is called. The plugin stores the IPublicAPI reference for future use.
Query Loop: When the user types, the system constructs a Query object. It then calls Query(Query) (Sync) or QueryAsync(Query, CancellationToken) (Async) on all relevant plugins.
Result Aggregation: Plugins return a List<Result>. The Core sorts these results based on Score and displays them in the UI.
Action Execution: When a result is selected, the Core invokes Result.ExecuteAsync(), which runs the plugin-defined delegate.
Feedback: Plugins use IPublicAPI to trigger side-effects, such as changing the current query, showing notifications, or saving persistent settings.

Integration

Search Integration: Plugins hook into the main launcher window by providing results that match user queries.
UI Integration: Plugins provide custom settings panels via ISettingProvider and additional context menu options via IContextMenu.
Storage Integration: Plugins persist their state using LoadSettingJsonStorage<T> (for configuration) or LoadCacheBinaryStorageAsync<T> (for high-performance data caching) provided by the API.
System Integration: Through IPublicAPI, plugins can execute shell commands, manage the clipboard, download files, and subscribe to system-wide events like theme changes or keyboard hooks.

3.6 KiB Raw Blame History