diff --git a/README.md b/README.md index 30c5246..310cb61 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ ## Welcome -Here you will find documentation on usage tips, design information, plugin development and more. +Here you will find documentation on usage tips, design information, plugin development, and more. -If you have just started using Flow, please head over to the [Usage Tips](/usage-tips.md) section to find out how you can get the most out of Flow. Otherwise if you are completely new to Flow and want to find out its features and give it a spin, please visit [here](https://github.com/Flow-Launcher/Flow.Launcher/#-features). +If you have just started using Flow, please head over to the [Usage Tips](/usage-tips.md) section to find out how you can get the most out of Flow. Otherwise, if you are completely new to Flow and want to find out its features and give it a spin, please visit [here](https://github.com/Flow-Launcher/Flow.Launcher/#-features). diff --git a/_coverpage.md b/_coverpage.md index 8a66e85..8c44996 100644 --- a/_coverpage.md +++ b/_coverpage.md @@ -1,8 +1,10 @@ -

- - - -

+ + Flow Launcher logo + # Flow Launcher diff --git a/_sidebar.md b/_sidebar.md index 3e92d52..4a473a8 100644 --- a/_sidebar.md +++ b/_sidebar.md @@ -22,9 +22,9 @@ - [**Plugin references**](/nodejs-plugin-references.md) - Testing Plugins - [**Testing Guide**](/testing.md) - - JSONRPC - - [**JSON RPC Introduction**](/json-rpc.md) - - [**JSON RPC Plugin Settings**](/json-rpc-settings.md) + - JSON-RPC + - [**Introduction**](/json-rpc.md) + - [**Plugin Settings**](/json-rpc-settings.md) - [**Visual SettingsTemplate.yaml editor**](/json-rpc-visual-settingstemplate-editor.md) - Porting Plugins - [**Porting Plugins Guide**](/port-plugins.md) diff --git a/bookmark-custom-locations.md b/bookmark-custom-locations.md index f2a1a70..cfdd7e1 100644 --- a/bookmark-custom-locations.md +++ b/bookmark-custom-locations.md @@ -1,8 +1,8 @@ ## Custom location list This page contains the information for setting custom browser locations for the Bookmark plugin that are not included by default. -- These locations may not be the exact path, but they are the typical bookmark location for each browser, you can use them as a reference guide. -- If you are using a browser that is not listed here, please update this document. It will help others. +- These locations may not be the exact path, but they are the typical bookmark location for each browser; you can use them as a reference guide. +- If you are using a browser not listed here, please update this document. It will help others. ---- @@ -14,4 +14,3 @@ This page contains the information for setting custom browser locations for the **LibreWolf** - Firefox Engine - C:\Users\username\AppData\RoamingRoaming\librewolf\Profiles\1tyx98jn.default-default - diff --git a/develop-dotnet-plugins.md b/develop-dotnet-plugins.md index 0cc5174..1f8496f 100644 --- a/develop-dotnet-plugins.md +++ b/develop-dotnet-plugins.md @@ -1,52 +1,52 @@ -Flow is written in C#, so plugins written in .Net platform can directly communicate with Flow without extra protocols. +Flow is written in C#, so plugins written in .NET platform can directly communicate with Flow without extra protocols. ## Initialization For C# Plugins, We recommend you use the [dotnet template](https://github.com/Flow-Launcher/dotnet-template) to generate a plugin template. -In order to be recognized as a Flow DotNet plugin, the directory needs to have at least two files -1. [`plugin.json`](plugin.json.md) -2. A Dotnet Assembly that implements **[IPlugin](API-Reference/Flow.Launcher.Plugin/iplugin.md)** or **[IAsyncPlugin](API-Reference/Flow.Launcher.Plugin/iasyncplugin.md)** (remember to reference [Flow.Launcher.Plugin](https://www.nuget.org/packages/Flow.Launcher.Plugin/) by Nuget). The plugin template will add the reference and create a `Main.cs` that implements `IPlugin`. +To be recognized as a Flow DotNet plugin, the directory needs to have at least two files +1. [`plugin.json`](/plugin.json.md) +2. A Dotnet Assembly that implements **[IPlugin](/API-Reference/Flow.Launcher.Plugin/IPlugin.md)** or **[IAsyncPlugin](/API-Reference/Flow.Launcher.Plugin/IAsyncPlugin.md)** (remember to reference [Flow.Launcher.Plugin](https://www.nuget.org/packages/Flow.Launcher.Plugin/) by Nuget). The plugin template will add the reference and create a `Main.cs` that implements `IPlugin`. -Find our API Reference [here](API-Reference/) +Find our API Reference [here](/API-Reference/Flow.Launcher.Plugin.md) A sample CSharp Plugin [here](https://github.com/Flow-Launcher/plugin-samples) ## IPlugin/IAsyncPlugin -The `Main`class that implements **[IPlugin](API-Reference/Flow.Launcher.Plugin/iplugin.md)** or **[IAsyncPlugin](API-Reference/Flow.Launcher.Plugin/iasyncplugin.md)** will handle the query search with Flow. +The `Main`class that implements **[IPlugin](/API-Reference/Flow.Launcher.Plugin/IPlugin.md)** or **[IAsyncPlugin](/API-Reference/Flow.Launcher.Plugin/IAsyncPlugin.md)** will handle the query search with Flow. -**[IPlugin](API-Reference/Flow.Launcher.Plugin/iplugin.md)** interface contains two required methods: +**[IPlugin](/API-Reference/Flow.Launcher.Plugin/IPlugin.md)** interface contains two required methods: 1. `void Init(PluginInitContext context)` - - [PluginInitContext](https://github.com/Flow-Launcher/Flow.Launcher/blob/master/API-Reference/Flow.Launcher.Plugin/PluginInitContext.cs) exposes some API from Flow and an metadata object for your plugin. + - [PluginInitContext](/API-Reference/Flow.Launcher.Plugin/PluginInitContext.md) exposes some API from Flow and a metadata object for your plugin. - It will be invoked before the invocation of `Query`, so you can do some preparation here. - We recommend you do expensive operations in this method instead of Object Constructor because this method will be executed in parallel with other plugins. 2. `List Query(Query query)` - - `Query` will be invoked when user activate this plugin with specific ActionKeyword. - - A `List` of [Result](/API-Reference/Flow.Launcher.Plugin/result.md) object should be returned. + - `Query` will be invoked when user activates this plugin with specific ActionKeyword. + - A `List` of [Result](/API-Reference/Flow.Launcher.Plugin/Result.md) object should be returned. - **[IAsyncPlugin](API-Reference/Flow.Launcher.Plugin/iasyncplugin.md)** is the async version of **[IPlugin](API-Reference/Flow.Launcher.Plugin/iplugin.md)** + **[IAsyncPlugin](/API-Reference/Flow.Launcher.Plugin/IAsyncPlugin.md)** is the async version of **[IPlugin](/API-Reference/Flow.Launcher.Plugin/IPlugin.md)** - Instead of implementing `Init` and `Query`, you will need to implement `InitAsync`and `QueryAsync`, which use `Task`,`Task` as return value to allow using `async/await` strategy - `QueryAsync` provides a `CancellationToken token` to allow you to check whether user has typed a new query. ## Additional interfaces -Besides the basic implementation of **IPlugin/IAsyncPlugin**, plugins can also implement a series of interfaces that belongs to **IFeatures** to control more communication with Flow. +Besides the basic implementation of **IPlugin/IAsyncPlugin**, plugins can also implement a series of interfaces that belong to **IFeatures** to control more communication with Flow. **Remarks**: You should implement these interfaces in the same class that implements **IPlugin/IAsyncPlugin**. -### [IContextMenu](API-Reference/Flow.Launcher.Plugin/icontextmenu.md) +### [IContextMenu](/API-Reference/Flow.Launcher.Plugin/IContextMenu.md) `LoadContextMenus` will be invoked when users expand the context menu of a specific Result. The return value of `LoadContextMenus` is similar to Results from `Query/QueryAsync`. -### [IReloadable](API-Reference/Flow.Launcher.Plugin/ireloadable.md)/[IAsyncReloadable](API-Reference/Flow.Launcher.Plugin/iasyncreloadable.md) +### [IReloadable](/API-Reference/Flow.Launcher.Plugin/IReloadable.md)/[IAsyncReloadable](API-Reference/Flow.Launcher.Plugin/IAsyncReloadable.md) `ReloadData/ReloadDataAsync` will be invoked when users click the `Reload Plugin Data` command from _sys_ plugin. Generally, it is used to reload some cache (such as the programs information cached in _Program_ plugin). -### [IPluginI18n](/API-Reference/Flow.Launcher.Plugin/iplugini18n.md) +### [IPluginI18n](/API-Reference/Flow.Launcher.Plugin/IPluginI18n.md) **IPluginI18n** means the plugin has been internationalized. Therefore, Flow will load the additional language resources from `/Languages` when loading the plugin. By implementing this interface with additional language files, Flow will be able to load plugin-specific localized language resources. You will be able to get the translated text with `IPublicAPI.GetTranslation(string key)`. @@ -60,13 +60,13 @@ The Language Resource file will need to be a list of **key/value** pair. Follow Plugins are required to implement **IPublicI18n** to let Flow load Language resources. -### [IResultUpdated](API-Reference/Flow.Launcher.Plugin/iresultupdated.md) +### [IResultUpdated](/API-Reference/Flow.Launcher.Plugin/IResultUpdated.md) -Implementing **IResultUpdated** provides a way to return part of the query results early. This is generally useful for plugins with long running queries. +Implementing **IResultUpdated** provides a way to return part of the query results early. This is generally useful for plugins with long-running queries. To early return a result to Flow, you will need to invoke `ResultUpdated` event with an `ResultUpdatedEventArgs`, which includes the current `Query` object and the List of `Result` objects similar to the return value in `Query(Async)`. ### [IDisposable](https://docs.microsoft.com/en-us/dotnet/api/system.idisposable) *Flow 1.8.0 or higher* -Implementing **IDisposable** to dispose unmanaged resource in the plugin. `Dispose()` will be called when Flow exit. \ No newline at end of file +Implementing **IDisposable** to dispose unmanaged resource in the plugin. `Dispose()` will be called when Flow exit. diff --git a/how-to-create-a-theme.md b/how-to-create-a-theme.md index 2d07893..a682fed 100644 --- a/how-to-create-a-theme.md +++ b/how-to-create-a-theme.md @@ -6,40 +6,40 @@ If you make a theme for the first time, refer to the existing theme. Copy the ** ## ⛔ Caution ⛔ -Place the theme you created in the Theme folder inside the UserData directory, for roaming this is located at **%APPDATA%\\FlowLauncher\\Themes\\** (AppData Roaming path) and for portable it is by default **%localappdata%\\FlowLauncher\app-\\\\UserData\\Themes\\** (AppData Local path). Flow will read from the UserData directory for custom themes and its own app directory for default themes, so make sure you do not place in the location outside of UserData because it will be erased along with the default theme files after an update. +Place the theme you created in the Theme folder inside the UserData directory, for roaming this is located at `%APPDATA%\FlowLauncher\Themes\` (AppData Roaming path) and for portable it is by default `%localappdata%\FlowLauncher\app-\UserData\Themes\` (AppData Local path). Flow will read from the UserData directory for custom themes and its own app directory for default themes. Make sure you do not place in the location outside UserData because it will be erased along with the default theme files after an update. ## Theme elements -The theme file allows you to set the following parts. Each style has a key, and there are items that can be modified. If theme have a key that is not described in this document, we recommend you not to modify it separately. +The theme file allows you to set the following parts. Each style has a key, and there are items that can be modified. If theme has a key not described in this document, we recommend you not to modify it separately. (*There is a possibility of changing/deleting this part depending on the version.*) - +![Flow Launcher screenshot](https://cdn.jsdelivr.net/gh/Flow-Launcher/docs@main/assets/themelayout.png) -
+
### WindowBorderStyle In this item, you can set the color, border size, border color, and corner radius of the basic window. -``` +```xml - ``` +``` -Window border thickness is recommended from 1 or 2. Corner radius recommends 0, 5 or less. +Window border thickness is recommended from 1 or 2. Recommended corner radius is 0, 5 or less. -
+
### QueryBoxStyle This is the style of the basic search window. You can set the font size, color of cursor, font color, input window height. If the font size is reduced, the height of the window is also reduced, so the height must be specified. -``` +```xml ``` -
+
### QuerySuggestionBoxStyle This is the style of the recommended search word that appears after the search word. The font size & Height should be the same as the QueryBoxStyle, and a more translucent color is recommended. -``` +```xml ``` -
+
### PendingLineStyle It is possible to set the color of the loading bar that is sometimes displayed. -``` +```xml ``` -
+
### SearchIconStyle This is the style of the magnifying glass icon displayed on the right side of the search window. Color & Size can be changed or hidden. (The picture change will be updated later.) -``` +```xml ``` -
+
### ItemTitleSelectedStyle You can specify a color that changes when the item is focused. The font size should be the same as ItemTitleStyle. -``` +```xml ``` -
+
### ItemSubTitleStyle This is the filepath part of the search result. The font size and color can be adjusted. -``` +```xml ``` -
+
### ItemSubTitleSelectedStyle You can specify a color that changes when the item is focused. The font size should be the same as ItemSubTitleStyle. -``` +```xml ``` -
+
### ItemHotkeyStyle Specifies the color and size of the Hotkey font. -``` +```xml ``` -
+
### ItemHotkeySelectedStyle -You can specify a color that changes when the item is focused. The font size should be the same as ItemHotkeyStyle. +You can specify a color that changes when the item is focused. The font size should be the same as `ItemHotkeyStyle`. -``` +```xml ``` -
+
### ItemSelectedBackgroundColor -This is the background color that is emphasized when the item is selected. +This is the background color emphasized when the item is selected. -```#3c454e``` +```xml +#3c454e +``` -
+
### HighlightStyle It emphasizes the part where the search word matches the result. Color and Font Weight can be set. -``` +```xml ``` -
+
### ThumbStyle Specifies the color and size of the scroll bar. -``` +```xml ``` -
+
### SeparatorStyle -Set the size, height, color, and margin of the horizontal line.If you don't think you need it, you can get rid of it. +Set the size, height, color, and margin of the horizontal line. If you don't think you need it, you can get rid of it. -``` +```xml @@ -251,5 +255,4 @@ Specifies the color of the glyph icon. ## Let's share it! Once you have crafted your perfect theme, why not share it with the community: -[Theme Gallery]( -https://github.com/Flow-Launcher/Flow.Launcher/discussions/1438) +[Theme Gallery](https://github.com/Flow-Launcher/Flow.Launcher/discussions/1438) diff --git a/index.html b/index.html index 48233e7..2975c47 100644 --- a/index.html +++ b/index.html @@ -7,11 +7,12 @@ - + + - - - + + + @@ -47,15 +48,9 @@ - - - + + + diff --git a/json-rpc.md b/json-rpc.md index cf31886..0c7bcca 100644 --- a/json-rpc.md +++ b/json-rpc.md @@ -6,21 +6,21 @@ In Flow Launcher, we use JSON-RPC as a **local** procedure call protocol to bind So we need to build a **common API** between Flow and Plugin. -![JSON RPC](/assets/jsonrpc.png) +![JSON-RPC](/assets/jsonrpc.png) ### Example - `-->` denotes data sent to FLow. - `<--` denotes data coming from Flow. -```json +```js --> {"method": "query", "parameters": [""]} <-- {"Title": "title", "SubTitle": "sub title", "IconPath": "favicon.ico"} ``` ## Flow Launcher API -API is located [here](https://github.com/Flow-Launcher/Flow.Launcher/blob/master/Flow.Launcher.Plugin/Interfaces/IPublicAPI.cs) +API is located [here](/API-Reference/Flow.Launcher.Plugin/IPublicAPI.md) ### API List @@ -42,7 +42,7 @@ API is located [here](https://github.com/Flow-Launcher/Flow.Launcher/blob/master ### JSON RPC Formatting -```json +```js { "method": "Flow Launcher API Name", "parameters": [] @@ -54,7 +54,7 @@ API is located [here](https://github.com/Flow-Launcher/Flow.Launcher/blob/master - `query`, string - `requery`, bool -```json +```js { "method": "Flow.Launcher.ChangeQuery", "parameters": [query, requery] @@ -65,7 +65,7 @@ API is located [here](https://github.com/Flow-Launcher/Flow.Launcher/blob/master - `cmd`, string -```json +```js { "method": "Flow.Launcher.ShellRun", "parameters": [cmd] @@ -78,7 +78,7 @@ API is located [here](https://github.com/Flow-Launcher/Flow.Launcher/blob/master - `sub_title`, string - `ico_path`, string(path) -```json +```js { "method": "Flow.Launcher.ShowMsg", "parameters": [title, sub_title, ico_path] diff --git a/nodejs-develop-plugins.md b/nodejs-develop-plugins.md index 6ad1637..24211d1 100644 --- a/nodejs-develop-plugins.md +++ b/nodejs-develop-plugins.md @@ -4,14 +4,14 @@ Plugins written in TypeScript/JavaScript use the [JSON-RPC](https://flow-launche Although not a hard requirement, this guide will use Node.js to run the TypeScript/JavaScript. We will refer to TypeScript/JavaScript plugin as Node.js plugin from here on. -When building a Node.js plugins there are several things to be mindful of: +When building a Node.js plugin, there are several things to be mindful of: * The most important thing is we do not expect users to have to manually install the dependencies via npm because we aim to provide a seamless experience for them. This can be achieved by adding the following three things to your project: - 1. Add a GitHub workflow- use a GitHub workflow that will install all your plugin's dependencies including the modules inside a folder called 'node_modules'. - 2. Publish all as a zip- zip up your project including a lib directory that contains the modules and publish it to GitHub Releases page. - 3. Point your module path to the node_modules directory- reference all the modules to that directory. + 1. Add a GitHub workflow — use a GitHub workflow that will install all your plugin's dependencies including the modules inside a folder called `node_modules`. + 2. Publish all as a zip — zip up your project including a lib directory that contains the modules and publish it to GitHub Releases page. + 3. Point your module path to the node_modules directory — reference all the modules to that directory. -* Users can use their system-installed Node.js with Flow Launcher, but in most circumstances, they will most likely be using Flow Launcher's download of [Node.js](https://nodejs.org/dist/v16.18.0/node-v16.18.0-win-x64.zip)). This download of portable Node.js version is isolated from the user's system and can be simply removed. +* Users can use their system-installed Node.js with Flow Launcher, but in most circumstances, they will most likely be using Flow Launcher's download of [Node.js](https://nodejs.org/dist/v16.18.0/node-v16.18.0-win-x64.zip). This download of portable Node.js version is isolated from the user's system and can be simply removed. ### Simple Example -Have a look at this simple example plugin [here](https://github.com/Flow-Launcher/Flow.Launcher.Plugin.HelloWorldNodeJS), notice it has a folder called '.github/workflows' and a file called 'Publish Release.yml'. This is the workflow file that GitHub Workflow uses to run the CI/CD for the project. Moving out of that folder you can go into the [main.js](https://github.com/Flow-Launcher/Flow.Launcher.Plugin.HelloWorldNodeJS/blob/main/main.js) file, this is the entry file for your plugin. +Have a look at this simple example plugin [here](https://github.com/Flow-Launcher/Flow.Launcher.Plugin.HelloWorldNodeJS), notice it has a folder called `.github/workflows` and a file called `Publish Release.yml`. This is the workflow file that GitHub Workflow uses to run the CI/CD for the project. Moving out of that folder, you can go into the [main.js](https://github.com/Flow-Launcher/Flow.Launcher.Plugin.HelloWorldNodeJS/blob/main/main.js) file; this is the entry file for your plugin. diff --git a/nodejs-plugin-references.md b/nodejs-plugin-references.md index 9c0978e..eca2608 100644 --- a/nodejs-plugin-references.md +++ b/nodejs-plugin-references.md @@ -1,6 +1,6 @@ ### Good references to follow -Here are some plugins which could help you build out your own or serve as a reference point: +Here are some plugins that could help you build out your own or serve as a reference point: - Plugin Template https://github.com/Joehoel/flow-launcher-plugin-template-node - Discord Timestamps https://github.com/Jessuhh/discord-timestamps-flowlauncher-plugin - NPM Search https://github.com/gabrielcarloto/flow-search-npm diff --git a/nodejs-release-project.md b/nodejs-release-project.md index 6791419..9b7bee5 100644 --- a/nodejs-release-project.md +++ b/nodejs-release-project.md @@ -1,2 +1,2 @@ ### Release your plugin to Flow's Plugin Store -When you are ready to release your plugin for people to enjoy, simply head over to Flow's [plugin repo](https://github.com/Flow-Launcher/Flow.Launcher.PluginsManifest) and follow the instructions there in the readme. +When you are ready to release your plugin for people to enjoy, head over to Flow's [plugin repo](https://github.com/Flow-Launcher/Flow.Launcher.PluginsManifest) and follow the instructions there in the readme. diff --git a/nodejs-setup-project.md b/nodejs-setup-project.md index ce82294..cf3e41d 100644 --- a/nodejs-setup-project.md +++ b/nodejs-setup-project.md @@ -20,7 +20,7 @@ push: node-version: '17.3.0' ``` -4. The project's release version is obtained from your plugin.json automatically by the ci, so when built it will be appended to the zip file later: +4. The project's release version is obtained from your plugin.json automatically by the CI, so when built, it will be appended to the zip file later: ```yml - name: get version @@ -31,7 +31,7 @@ push: prop_path: 'Version' ``` -5. The 'Install dependencies' section is where you will do most of your CI work. It will run `npm install`, which will output all the dependencies specified in package.json into the 'node_modules' directory. The workflow will then zip them up along with your project using `zip -r Flow.Launcher.Plugin.HelloWorldNodeJS.zip . -x '*.git*'`, where you replace this `Flow.Launcher.Plugin.HelloWorldNodeJS` with the name of your plugin. +5. The **Install dependencies** section is where you will do most of your CI work. It will run `npm install`, which will output all the dependencies specified in package.json into the 'node_modules' directory. The workflow will then zip them up along with your project using `zip -r Flow.Launcher.Plugin.HelloWorldNodeJS.zip . -x '*.git*'`, where you replace this `Flow.Launcher.Plugin.HelloWorldNodeJS` with the name of your plugin. ```yml - name: Install dependencies @@ -41,7 +41,7 @@ push: ``` ### 2. Publish as zip -The final step to the workflow file is this publish section, which will publish the zip file you generated, upload to GitHub Releases page and tag with the version generated from the previous step from your plugin.json file. Remember again to replace `Flow.Launcher.Plugin.HelloWorldNodeJS` with the name of your plugin. +The final step to the workflow file is this **Publish** section, which will publish the zip file you generated, upload to GitHub Releases page and tag with the version generated from the previous step from your plugin.json file. Remember again to replace `Flow.Launcher.Plugin.HelloWorldNodeJS` with the name of your plugin. ```yml - name: Publish @@ -56,7 +56,7 @@ The final step to the workflow file is this publish section, which will publish Feel free to also have a read of this [blog post](https://blog.ipswitch.com/how-to-build-your-first-github-actions-workflow) which does a simple explanation of how to use GitHub Actions Workflow. ### 3. Use node_modules directory -Once the 'node_modules' folder is included in your zip release, it can then be used without needing the user to manually npm install the plugin's dependencies. You just have to tell the plugin during runtime to find those modules in your local node_modules directory. Do this by using this exact copy of the following block of code in your [main.js](https://github.com/Flow-Launcher/Flow.Launcher.Plugin.HelloWorldNodeJS/blob/main/main.js): +Once the `node_modules` folder is included in your zip release, it can then be used without needing the user to manually npm install the plugin's dependencies. You just have to tell the plugin during runtime to find those modules in your local node_modules directory. Do this by using this exact copy of the following code block in your [main.js](https://github.com/Flow-Launcher/Flow.Launcher.Plugin.HelloWorldNodeJS/blob/main/main.js): ```javascript -const open = require('./node_modules/open') +const open = require('./node_modules/open'); ``` diff --git a/nodejs-write-code.md b/nodejs-write-code.md index e8cffa1..a0e8d83 100644 --- a/nodejs-write-code.md +++ b/nodejs-write-code.md @@ -5,10 +5,10 @@ It is a good practice that you create a branch for each of the new feature/fixes ### 2. main.js your main.js should look something like below: -``` -const open = require('./node_modules/open') +```js +const open = require('./node_modules/open'); -const { method, parameters } = JSON.parse(process.argv[2]) +const { method, parameters } = JSON.parse(process.argv[2]); if (method === "query") { console.log(JSON.stringify( @@ -28,8 +28,8 @@ if (method === "query") { } if (method === "do_something_for_query") { - url = parameters[0] - do_something_for_query(url) + url = parameters[0]; + do_something_for_query(url); } function do_something_for_query(url) { @@ -42,7 +42,7 @@ function do_something_for_query(url) { ### 3. Query entry point **if (method === "query")** -This if statement captures the args passed via JsonRPC defined as `const { method, parameters } = JSON.parse(process.argv[2])`, so if 'method' is 'query' then the console.log's code block will be run. As result is an array, you can also specify a single or multiple results. +This if statement captures the args passed via JSON-RPC defined as `const { method, parameters } = JSON.parse(process.argv[2])`, so if `method` is `'query'` then the console.log's code block will be run. As the `result` property is an array, you can also specify a single or multiple results. ### 4. Assigning an action to your results **JsonRPCAction** @@ -59,11 +59,11 @@ node "%plugin_dir%/main.js" %* ``` ### 6 Result score -The `score` field provides the ability to assign a weight to your score, the higher the score is, the higher the result from the plugin would show in flow's result list. The range in which you assign the score is usually between 0-100. You can keep it as 0 if your plugin generally uses an action keyword to trigger, but if you are using a global action keyword - `*` then the average weight for a plugin would be 50. Additionally users can also tweak the score via Flow's plugin setting as well. +The `score` field provides the ability to assign a weight to your score; the higher the score is, the higher the result from the plugin would show in flow's result list. The range in which you assign the score is usually between 0–100. You can keep it as 0 if your plugin generally uses an action keyword to trigger, but if you are using a global action keyword - `*` then the average weight for a plugin would be 50. Additionally, users can tweak the score via Flow's plugin setting as well. ### 7. Your plugin.json -You will also need to if not yet already, create a plugin.json file that will instruct Flow on how to load your plugin. +You will also need to, if not yet already, create a plugin.json file that will instruct Flow on how to load your plugin. This file should be placed in the top level folder. -To revisit what to include in your plugin.json, visit [here](https://flow-launcher.github.io/docs/#/plugin.json) +To revisit what to include in your plugin.json, visit [here](/plugin.json.md) diff --git a/plugin-explorer-usage.md b/plugin-explorer-usage.md index 250700b..2001a0d 100644 --- a/plugin-explorer-usage.md +++ b/plugin-explorer-usage.md @@ -1,6 +1,6 @@ ## Explorer Plugin -The Explorer plugin is a default plugin that installs with Flow Launcher. Previously there was an Explorer Plugin and an Everything Plugin but these were merged and you can now choose which search engine will search for what through Flow. If you don't already have the Everything search tool from Voidtools installed, Flow will automatically download and install it if you choose it as your search index engine. To trigger automatic install, fire a search and click the "Warning: Everything is not running" result. Flow Launcher currently only supports v1.4.x of Everything and not the 1.5 alpha branch. (For 1.5 alpha support please refer to [this](https://github.com/Flow-Launcher/Flow.Launcher/issues/1716) link) +The Explorer plugin is a default plugin that installs with Flow Launcher. Previously there was an Explorer Plugin and an Everything Plugin, but these were merged, and you can now choose which search engine will search for what through Flow. If you don't already have the Everything search tool from Voidtools installed, Flow will automatically download and install it if you choose it as your search index engine. To trigger automatic install, fire a search and click the "Warning: Everything is not running" result. Flow Launcher currently only supports v1.4.x of Everything and not the 1.5 alpha branch. (For 1.5 alpha support, please refer to [this](https://github.com/Flow-Launcher/Flow.Launcher/issues/1716) link) Here is how to configure this plugin: @@ -11,47 +11,45 @@ Here is how to configure this plugin: - *Use search result's location as the working directory of the executable* : tick this so Flow will set the working directory of any application you run through the Explorer plugin to the directory of the executable - *Hit enter to open folder in Default File Manager* : tick this box to have the ENTER key open the current directory in the default file manager rather than have Flow go into this directory for further browsing. - *File editor path* and *Folder editor path* : These two options allow you to set a program to open either files or folders, when you right mouse click / SHIFT + ENTER context menu a search result. Note these options will only appear in the context menu if you have set them here. -For example to set up this plugin so you can open any directory in Visual Studio Code, first add the path to your Visual Studio Code install in the Folder editor path setting: +For example, to set up this plugin, so you can open any directory in Visual Studio Code, first add the path to your Visual Studio Code install in the Folder editor path setting: - Folder editor path option +![Folder editor path option](/assets/explorer_1a.png) - then search for a folder, and then right mouse click / SHIFT + ENTER: +then search for a folder, and then right mouse click / SHIFT + ENTER: - Example folder search +![Example folder search](/assets/explorer_1b.png) - and then choose the *Open With Editor* option - - Context menu example +and then choose the *Open With Editor* option + +![Context menu example](/assets/explorer_1c.png) - *Shell path* : set the executable shell to be launched when the right mouse click / SHIFT + ENTER is chosen. This defaults to the Windows `cmd` -- *Index search engine*, *Content search engine* and *Directory recursive search engine*: These three options let you choose whether Windows Index or Everything (if you have it installed) for specific tasks. The Index is for general filename search, the Content is for searching within text files and the Directory recursive is for listing sub directories within a directory. -- *Open Windows index option*: this opens the Windows Indexing system setting so you can see and adjust exactlky what the Windows Index service is doing. +- *Index search engine*, *Content search engine* and *Directory recursive search engine*: These three options let you choose whether Windows Index or Everything (if you have it installed) for specific tasks. The Index is for general filename search, the Content is for searching within text files and the Directory recursive is for listing subdirectories within a directory. +- *Open Windows index option*: this opens the Windows Indexing system setting, so you can see and adjust exactly what the Windows Index service is doing. #### Everything Setting tab ---- ![Everything Setting tab](/assets/explorer_2.png) - *Search full path* : use the Everything option to search the full path and not just the filename. Equivalent to the `path:` modifier within Everything. - *Sort Option* : dropdown list to show how the search results are sorted. -- *Everything Path* : If you have Everything installed, Flow Launcher will try and find the installation to use but if you are having issues or it is installed in a non standard dirctory you can specify it explicitly here. +- *Everything Path* : If you have Everything installed, Flow Launcher will try and find the installation to use, but if you are having issues, or it is installed in a non-standard directory, you can specify it explicitly here. #### Customised Action Keywords tab ---- ![Customise Action Keywords tab](/assets/explorer_3.png) -- For each option here you can choose a custom keyword to trigger that specific type of search. Anything with a `*` is searched for when you type anything in Flow Launcher or if you give the Explorer plugin a global keyword. For example the default to search within documents is set to `doc:` (this is done as searching the contents of documents is slow and so should only trigger when that is definitely what you want to do). If you don't care about exactly what type of search is executed, just use the 'Search' keyword. +- For each option here you can choose a custom keyword to trigger that specific type of search. Anything with a `*` is searched for when you type anything in Flow Launcher or if you give the Explorer plugin a global keyword. For example, the default to search within documents is set to `doc:` (this is done as searching the contents of documents is slow and so should only trigger when that is definitely what you want to do). If you don't care about exactly what type of search is executed, just use the 'Search' keyword. #### Quick Access Links tab ---- ![Quick Access Links tab](/assets/explorer_4.png) -- Here you can add directories that you work with often, and would like to be returned as soon as you start typing their source location. Directories can also be added and removed from this list with the right mouse click / SHIFT + ENTER context menu from any search result that is a directory. +- Here you can add directories that you often work with, and would like to be returned as soon as you start typing their source location. Directories can also be added and removed from this list with the right mouse click / SHIFT + ENTER context menu from any search result that is a directory. #### Index Search Excluded Paths tab ---- ![Index Search Excluded Paths tab](/assets/explorer_5.png) -- Adding a directory here will exclude it from the Flow Launcher search, over riding any settings you maye have in Windows Indexing or Everything. +- Adding a directory here will exclude it from the Flow Launcher search, over-riding any settings you maye have in Windows Indexing or Everything. ### Using Everything If you do choose to use Everything to search, [these Everything commands](https://www.voidtools.com/support/everything/searching/) may be useful to reference. - - diff --git a/plugin.json.md b/plugin.json.md index 6591b31..3d8919d 100644 --- a/plugin.json.md +++ b/plugin.json.md @@ -3,7 +3,7 @@ `plugin.json` is the manifest files of your plugin. It is required for Flow to understand how to communicate with your plugin. It must be in the plugin root directory. -```json +```js { "ID":"", //Plugin ID，32 bit UUID "ActionKeyword":"", //Plugin default action keyword (* means no specific action keyword) diff --git a/port-plugins.md b/port-plugins.md index 9420830..d681144 100644 --- a/port-plugins.md +++ b/port-plugins.md @@ -3,17 +3,17 @@ ### Notes - When porting, please keep the author's commit history -- Flow Launcher targets minimum .Net 5, so older plugins should be upgraded to keep the continuity of their future developments +- Flow Launcher targets minimum .NET 5, so older plugins should be upgraded to keep the continuity of their future developments - All dll libraries used by the plugin should be outputted and included in the final build, to do this, set the attribute CopyLocalLockFileAssemblies in your project file to true ### Steps 1. To start off, you can fork/create a new repo, either way the project's commit history must be kept. If it's forked, you can just start updating it. If it's a new repo, do this by first cloning the repo, then add your new repo as a new repo remote, remove the original remote and then push to it -2. Use try convert tool from https://github.com/dotnet/try-convert -3. Try-convert -w path-to-folder-or-solution-or-project +2. Use `try-convert` tool from https://github.com/dotnet/try-convert +3. `try-convert -w path-to-folder-or-solution-or-project` 4. May need to fix on the project file, a good template to follow is the [Explorer plugin](https://github.com/Flow-Launcher/Flow.Launcher/blob/dev/Plugins/Flow.Launcher.Plugin.Explorer/Flow.Launcher.Plugin.Explorer.csproj) project: - - fix to net5.0-windows - - set the output location as 'Output\Release\' + - fix `` to `net5.0-windows` + - set the output location as `Output\Release\` - add `true` and `false` to the csproj file - bump version to 2.0.0 and fix up any missing attributes if necessary 5. Update code and fix plugin's setting layout if necessary diff --git a/py-develop-plugins.md b/py-develop-plugins.md index 642772b..a4e8145 100644 --- a/py-develop-plugins.md +++ b/py-develop-plugins.md @@ -2,21 +2,21 @@ Python plugins use the [JSON-RPC](https://flow-launcher.github.io/docs/#/json-rpc) protocol to communicate with Flow via JSON structured calls. -When building a Python plugins there are several things to be mindful of: +When building a Python plugins, there are several things to be mindful of: * The most important thing is we do not expect users to have to manually install the dependencies in requirements.txt because we aim to provide a seamless experience for them. This can be achieved by adding the following three things to your project: - 1. Add a GitHub workflow- use a GitHub workflow that will install all your plugin's dependencies including the Python flowlauncher module to a folder called Lib inside your plugin. - 2. Publish all as a zip- zip up your project including a lib directory that contains the modules and publish it to GitHub Releases page. - 3. Point your module imports to the lib directory- reference all the modules to that directory where they are first imported. + 1. Add a GitHub workflow — use a GitHub workflow that will install all your plugin's dependencies including the Python flowlauncher module to a folder called Lib inside your plugin. + 2. Publish all as a zip — zip up your project including a lib directory that contains the modules and publish it to GitHub Releases page. + 3. Point your module imports to the lib directory — reference all the modules to that directory where they are first imported. * Users can use their own system-installed Python with Flow Launcher, but in most circumstances they will most likely be using Flow Launcher's download of [Embedded Python](https://docs.python.org/3/using/windows.html#the-embeddable-package). This download is isolated from the users system and does not prepend the scripts run directory to the system `PATH`.[ref](https://bugs.python.org/issue28245) If you need to import external files please follow the example below. -* It should also be noted that external libraries that include compiled code can pose compatibility issues with different versions of Python. This is because the compiled code is platform-specific and tied to a specific version of Python. If you *must* use an external library with compiled code you may look at alternative packaging methods such as: [nuitka](http://nuitka.net/), or [pyinstaller](https://pyinstaller.org/en/stable/). +* It should also be noted that external libraries that include compiled code can pose compatibility issues with different versions of Python. This is because the compiled code is platform-specific and tied to a specific version of Python. If you *must* use an external library with compiled code, you may look at alternative packaging methods such as [nuitka](http://nuitka.net/), or [pyinstaller](https://pyinstaller.org/en/stable/). ### Simple Example -Have a look at this simple example plugin [here](https://github.com/Flow-Launcher/Flow.Launcher.Plugin.HelloWorldPython), notice it has a folder called '.github/workflows' and a file called 'Publish Release.yml'. This is the workflow file that GitHub Workflow uses to run the CI/CD for the project. +Have a look at this simple example plugin [here](https://github.com/Flow-Launcher/Flow.Launcher.Plugin.HelloWorldPython), notice it has a folder called `.github/workflows` and a file called 'Publish Release.yml'. This is the workflow file that GitHub Workflow uses to run the CI/CD for the project. -Moving out of that folder you can go into the [main.py](https://github.com/Flow-Launcher/Flow.Launcher.Plugin.HelloWorldPython/blob/main/main.py) file, this is the entry file for your plugin. Notice it has this code block: +Moving out of that folder, you can go into the [main.py](https://github.com/Flow-Launcher/Flow.Launcher.Plugin.HelloWorldPython/blob/main/main.py) file; this is the entry file for your plugin. Notice it has this code block: ```python import sys from pathlib import Path @@ -26,7 +26,7 @@ paths = (".", "lib", "plugin") sys.path = [str(plugindir / p) for p in paths] + sys.path ``` -Now that we've added our `lib` folder to the sys.path we can now import our external libraries like so: +Now that we've added our `lib` folder to `sys.path`, we can now import our external libraries like so: ```python from flowlauncher import FlowLauncher #external library import webbrowser #Not external @@ -38,9 +38,9 @@ We inherit from the FlowLauncher class provided by the FlowLauncher library we i class HelloWorld(FlowLauncher): ``` -When a user activates our plugin we can retrieve their query by providing a `query` method. Flow Launcher provides the argument `query` with the users text. +When a user activates our plugin, we can retrieve their query by providing a `query` method. Flow Launcher provides the argument `query` with the users text. -To send a response back we need to return a list of dictonaries as shown below. The `JsonRPCAction` dict allows you to provide a method that will be called by Flow Launcher with the parameters you provided. This method *must* be part of your plugin class. +To send a response back, we need to return a list of dictionaries as shown below. The `JsonRPCAction` dict allows you to provide a method that will be called by Flow Launcher with the parameters you provided. This method *must* be part of your plugin class. ```python def query(self, query): @@ -65,7 +65,7 @@ This method will be called when a user selects our result: webbrowser.open(url) ``` -The context menu is activated when the user uses shift+Enter or right clicks on a result. The context menu is similar to the `query` method except it does not receive a `query` argument but a `data` argument with a list of values from the result selected. +The context menu is activated when the user uses Shift+Enter or right-clicks on a result. The context menu is similar to the `query` method except it does not receive a `query` argument but a `data` argument with a list of values from the result selected. ```python def context_menu(self, data): diff --git a/py-plugin-references.md b/py-plugin-references.md index dcacb3e..98187bd 100644 --- a/py-plugin-references.md +++ b/py-plugin-references.md @@ -1,6 +1,6 @@ ### Good references to follow -Here are some plugins which could help you build out your own or serve as a reference point: +Here are some plugins that could help you build out your own or serve as a reference point: - IsPrime https://github.com/lvonkacsoh/Flow.Launcher.Plugin.IsPrime - RollDice https://github.com/lvonkacsoh/Flow.Launcher.RollDice - FancyEmoji https://github.com/Ma-ve/Flow.Launcher.Plugin.FancyEmoji diff --git a/py-release-project.md b/py-release-project.md index 0547cb1..334d38d 100644 --- a/py-release-project.md +++ b/py-release-project.md @@ -1,2 +1,2 @@ ### Release your plugin to Flow's Plugin Store -When you are ready to release your plugin for people to enjoy, simply head over to Flow's [plugin repo](https://github.com/Flow-Launcher/Flow.Launcher.PluginsManifest) and follow the instructions there in the readme. +When you are ready to release your plugin for people to enjoy, head over to Flow's [plugin repo](https://github.com/Flow-Launcher/Flow.Launcher.PluginsManifest) and follow the instructions there in the readme. diff --git a/py-setup-project.md b/py-setup-project.md index 3998e1c..90aeda9 100644 --- a/py-setup-project.md +++ b/py-setup-project.md @@ -18,7 +18,7 @@ push: python_ver: 3.11 ``` -4. The project's release version is obtained from your plugin.json automatically by the ci, so when built it will be appended to the zip file later: +4. The project's release version is obtained from your plugin.json automatically by the CI, so when built, it will be appended to the zip file later: ```yml - name: get version @@ -29,9 +29,9 @@ push: prop_path: 'Version' ``` -5. The 'Install dependencies' section is where you will do most of your CI work. Notice it installs the requirements.txt and outputs it with the `-t` parameter to the `./lib` folder. This tells pip to dump all the installed modules to the local lib folder which you will zip up along with your project using the `zip -r Flow.Launcher.Plugin.HelloWorldPython.zip . -x '*.git*'`, where you replace this `Flow.Launcher.Plugin.HelloWorldPython` with the name of your plugin. +5. The **Install dependencies** section is where you will do most of your CI work. Notice it installs the requirements.txt and outputs it with the `-t` parameter to the `./lib` folder. This tells pip to dump all the installed modules to the local lib folder which you will zip up along with your project using the `zip -r Flow.Launcher.Plugin.HelloWorldPython.zip . -x '*.git*'`, where you replace this `Flow.Launcher.Plugin.HelloWorldPython` with the name of your plugin. - You can also add additional steps here to unpack/install any additional dependencies your plugin requires, for example compiling additional translation files like [this](https://github.com/deefrawley/Flow.Launcher.Plugin.Currency/blob/23770ee929af059b1b1b7f9b5f3327b692ac9587/.github/workflows/Publish%20Release.yml#L34) + You can also add additional steps here to unpack/install any additional dependencies your plugin requires, for example, compiling additional translation files like [this](https://github.com/deefrawley/Flow.Launcher.Plugin.Currency/blob/23770ee929af059b1b1b7f9b5f3327b692ac9587/.github/workflows/Publish%20Release.yml#L34) ```yml - name: Install dependencies @@ -42,7 +42,7 @@ push: ``` ### 2. Publish as zip -The final step to the workflow file is this publish section, which will publish the zip file you generated, upload to GitHub Releases page and tag with the version generated from the previous step from your plugin.json file. Remember again to replace `Flow.Launcher.Plugin.HelloWorldPython` with the name of your plugin. +The final step to the workflow file is this **Publish** section, which will publish the zip file you generated, upload to GitHub Releases page and tag with the version generated from the previous step from your plugin.json file. Remember again to replace `Flow.Launcher.Plugin.HelloWorldPython` with the name of your plugin. ```yml - name: Publish if: success() @@ -57,7 +57,7 @@ The final step to the workflow file is this publish section, which will publish Feel free to also have a read of this [blog post](https://blog.ipswitch.com/how-to-build-your-first-github-actions-workflow) which does a simple explanation of how to use GitHub Actions Workflow. ### 3. Use lib directory -Once the lib folder is included in your zip release, it can then be used without needing the user to manually pip install. You just have to tell during runtime to find those modules in your local lib folder. Do this by using this exact copy of the following block of code: +Once the lib folder is included in your zip release, it can then be used without needing the user to manually pip install. You just have to tell during runtime to find those modules in your local lib folder. Do this by using this exact copy of the following code block: ```python import sys from pathlib import Path @@ -67,4 +67,4 @@ paths = (".", "lib", "plugin") sys.path = [str(plugindir / p) for p in paths] + sys.path ``` -Add the above code into your init file at the top, usually this is the [main.py](https://github.com/Flow-Launcher/Flow.Launcher.Plugin.HelloWorldPython/blob/main/main.py) file. This block of code appends the path of your lib and plugin directories on the user's machine to `sys.path`. `sys.path` is a built-in variable within the sys module, which contains a list of directories that the Python interpreter will search in for the required module. Effectively we are telling the interpreter if the required modules in your plugin are not found among its built-in modules then look through the list of directories defined by sys.path, which should have all the modules installed by your GitHub workflow in the 'lib' folder. +Add the above code into your init file at the top, usually this is the [main.py](https://github.com/Flow-Launcher/Flow.Launcher.Plugin.HelloWorldPython/blob/main/main.py) file. This block of code appends the path of your lib and plugin directories on the user's machine to `sys.path`. `sys.path` is a built-in variable within the sys module, which contains a list of directories that the Python interpreter will search in for the required module. Effectively, we are telling the interpreter if the required modules in your plugin are not found among its built-in modules then look through the list of directories defined by `sys.path`, which should have all the modules installed by your GitHub workflow in the 'lib' folder. diff --git a/py-write-code.md b/py-write-code.md index b19981f..ee861b6 100644 --- a/py-write-code.md +++ b/py-write-code.md @@ -1,10 +1,10 @@ ### 1. Start with a branch -Since we have created a CI for your plugin in the [previous step](https://flow-launcher.github.io/docs/#/py-setup-project), which includes creating a release when you push/merge to the 'main' branch, it is then necessary to create another git branch separate to your 'main' branch so you can continue to work on your plugin with git commits and pushes without creating a new release each time. +Since we have created a CI for your plugin in the [previous step](/py-setup-project.md), which includes creating a release when you push/merge to the 'main' branch, it is then necessary to create another git branch separate to your `main` branch, so you can continue to work on your plugin with git commits and pushes without creating a new release each time. -It is a good practice that you create a branch for each of the new feature/fixes you are releasing for your plugin, if you are not sure how to do so then follow this [video tutorial](https://www.gitkraken.com/learn/git/problems/create-git-branch). Once you have fully finished developing your plugin with your new branch, then you can merge it into the 'main' branch, which will consequently create a new release for your plugin with a version from your `plugin.json`. +It is a good practice that you create a branch for each of the new feature/fixes you are releasing for your plugin, if you are not sure how to do so, then follow this [video tutorial](https://www.gitkraken.com/learn/git/problems/create-git-branch). Once you have fully finished developing your plugin with your new branch, then you can merge it into the 'main' branch, which will consequently create a new release for your plugin with a version from your `plugin.json`. ### 2. main.py -your main.py should look something like below: +your `main.py` should look something like below: ```python import sys,os @@ -55,12 +55,12 @@ if __name__ == "__main__": ``` -
+
### 3. Query entry point **def query(self, query):** -This is the main entry to your plugin and the return block will be a list of the results that your plugin returns, which could be a single or many results. +This is the main entry to your plugin, and the return block will be a list of the results that your plugin returns, which could be a single or many results. ### 4. Assigning an action to your results **JsonRPCAction** @@ -71,17 +71,17 @@ In this example, if the user selects the result, the `open_url` method will be c ### 5. Create an additional context menu **def context_menu(self, data):** -This method creates a context menu for your results, where the user can carry out additional tasks when they go to the context menue via pressing `Shift + Enter`. A context menu could be helpful if you want some tasks specific to your returned results, for example the Explorer plugin would return a list of file results, and when going to the context menu of one of the result users can select to copy the file. +This method creates a context menu for your results, where the user can carry out additional tasks when they go to the context menu via pressing `Shift + Enter`. A context menu could be helpful if you want some tasks specific to your returned results. For example, the Explorer plugin would return a list of file results, and when going to the context menu of one of the result users can select to copy the file. -To attach a method to your context menu result, do the same as for normal results where you define a JsonRPCAction item with the method and parameters you want to call and pass through. In this case the context menu will simply open the HelloWorldPython plugin's GitHub repo. +To attach a method to your context menu result, do the same as for normal results where you define a JsonRPCAction item with the method and parameters you want to call and pass through. In this case, the context menu will simply open the HelloWorldPython plugin's GitHub repo. ### 6 Result score -The `score` field provides the ability to assign a weight to your score, the higher the score is, the higher the result from the plugin would show in flow's result list. The range in which you assign the score is usually between 0-100. You can keep it as 0 if your plugin generally uses an action keyword to trigger, but if you are using a global action keyword - `*` then the average weight for a plugin would be 50. Additionally users can also tweak the score via Flow's plugin setting as well. +The `score` field provides the ability to assign a weight to your score; the higher the score is, the higher the result from the plugin would show in flow's result list. The range in which you assign the score is usually between 0–100. You can keep it as 0 if your plugin generally uses an action keyword to trigger, but if you are using a global action keyword (`*`) then the average weight for a plugin would be 50. Additionally, users can tweak the score via Flow's plugin setting as well. ### 7. Your plugin.json -You will also need to if not yet already, create a plugin.json file that will instruct Flow on how to load your plugin. +You will also need to, if not yet already, create a plugin.json file that will instruct Flow on how to load your plugin. This file should be placed in the top level folder. -To revisit what to include in your plugin.json, visit [here](https://flow-launcher.github.io/docs/#/plugin.json) +To revisit what to include in your plugin.json, visit [here](/plugin.json.md) diff --git a/testing.md b/testing.md index f9848ec..4d1cc1f 100644 --- a/testing.md +++ b/testing.md @@ -1,6 +1,6 @@ ### Testing your plugin -After successfully building a plugin, it can be tested locally by moving the output files into Flow Launcher's `FlowLauncher\Plugins` directory accessible via the `userdata` command in Flow Launcher. Alternatively, if you are building .Net (C# or F#) plugins you can have your IDE build the artefact directly to that location (remember not to check this build output path into Git though). +After successfully building a plugin, it can be tested locally by moving the output files into Flow Launcher's `FlowLauncher\Plugins` directory accessible via the `userdata` command in Flow Launcher. Alternatively, if you are building .NET (C# or F#) plugins, you can have your IDE build the artifact directly to that location (remember not to check this build output path into Git though). ### Detail Steps @@ -11,4 +11,4 @@ After successfully building a plugin, it can be tested locally by moving the out 4. Copy and paste the newly built plugin folder into this folder. 5. Execute `Restart Flow Launcher` to reload the new plugin. -Tip: .Net plugins (e.g. C# and F#) will require you to restart flow every time you make a change and build a new artefact to reload the plugin, but Python and JS/TS plugins you can edit the plugin directly. +Tip: .NET plugins (e.g. C# and F#) will require you to restart flow every time you make a change and build a new artifact to reload the plugin, but Python and JS/TS plugins you can edit the plugin directly. diff --git a/usage-tips.md b/usage-tips.md index 93eb37b..c2d49d4 100644 --- a/usage-tips.md +++ b/usage-tips.md @@ -1,23 +1,23 @@ - Search programs, bookmarks and control panel items using: - - Acronyms eg. `gk` or `gp` for GitKraken Preview. + - Acronyms e.g. `gk` or `gp` for GitKraken Preview. - Fuzzy eg. `acr` or `rea` for Acrobat Reader DC. - - Single word eg.`code` or `visual` for Visual Studio Code. + - Single word e.g. `code` or `visual` for Visual Studio Code. - Press `F5` while in the query window or type `reload plugin data` to reload all plugin data. -- Right click on a result will also take you to the context menu for additional actions. +- Right-click on a result will also take you to the context menu for additional actions. - Flow's settings including installed plugins are located at: - If using roaming: `%APPDATA%\FlowLauncher` - If using portable, by default: `%localappdata%\FlowLauncher\app-\UserData` -- To back up your Flow's settings including installed plugins, simply back up your UserData folder. You can locate it quickly via querying `flow launcher userdata`. -- To restore your saved settings, ensure Flow is exited, simply delete the current UserData folder and copy yours in. Start Flow and all your settings will be setup. One exception however is your saved Quick Access files and folder paths in Explorer plugin you may need to update if the locations have changed. +- To back up your Flow's settings including installed plugins, back up your UserData folder. You can locate it quickly via querying `flow launcher userdata`. +- To restore your saved settings, ensure Flow is exited, delete the current UserData folder and copy yours in. Start Flow and all your settings will be setup. One exception, however, is your saved Quick Access files and folder paths in the Explorer plugin you may need to update if the locations have changed. - When migrating from a system with a high screen resolution to one with a lower resolution, it may be necessary to adjust "SettingWindowWidth", "SettingWindowHeight" "SettingWindowTop" and "SettingWindowLeft" as the settings may otherwise appear outside the visible area. Default values for 1920x1080: 1000, 700, 0, 0. -- Resetting Flow back to default settings is also easy, simply move/delete the UserData folder after closing the app and the defaults will be recreated. +- Resetting Flow back to default settings is also easy, move/delete the UserData folder after closing the app, and the defaults will be recreated. - Both Program and Bookmarks plugin will automatically detect new changes, so your newly installed apps or bookmarks will be available soon after they are added. - If your plugin is not triggering, open Flow's settings and go to the Plugins tab, click on the plugin and check if it is set to a particular action keyword. You can set the plugin's action keyword to global: `*` but be wary sometimes a plugin sets a dedicated keyword is because it may return lots of results cluttering the result list. - For Explorer plugin results, you can press `Ctrl + Enter` to open the folder directly instead of navigating into the folder. -- You can save your frequently used or favourite files/folder locations via Explorer plugin. Navigate to the file/location you want to save, then go to context menu and select `Add to Quick Access`. It will be particularly handy if you have set a custom action keyword instead of the default '*', which when used will display your list of saved Quick Access files and folders. You can change the default action keyword via the plugin's settings page. -- Flow is published as a self-contained app, this means on Windows machines (7 and up) Flow can run straight away without needing to install .Net runtime and framework. Coupled with portable mode, it can be stored on Dropbox or cloud storage provider and run on any Windows machines. The slight drawback is that the installed package size is slightly bigger at around 250mb because it needs to bundle the required .Net components together. -- Prioritize the plugin results order, this can be done by going to the plugin's settings page. Under the plugin's title and the description, click the number next to 'Priority', this is where you can assign weight to the plugin's result. The higher the weight is, the higher the selected plugin's results will be in Flow's result list. +- You can save your frequently used or favourite files/folder locations via Explorer plugin. Navigate to the file/location you want to save, then go to the context menu and select `Add to Quick Access`. It will be particularly handy if you have set a custom action keyword instead of the default '*', which when used will display your list of saved Quick Access files and folders. You can change the default action keyword via the plugin's settings page. +- Flow is published as a self-contained app, this means on Windows machines (7 and up) Flow can run straight away without needing to install .NET runtime and framework. Coupled with portable mode, it can be stored on Dropbox or cloud storage provider and run on any Windows machines. The slight drawback is that the installed package size is slightly bigger at around 250mb because it needs to bundle the required .NET components together. +- Prioritize the plugin results order, this can be done by going to the plugin's settings page. Under the plugin's title and the description, click the number next to 'Priority'; this is where you can assign weight to the plugin's result. The higher the weight is, the higher the selected plugin's results will be in Flow's result list. - Press ctrl + enter/click on a Shell plugin command will run it directly as admin. - In the plugins download list, you can press ctrl + enter/click to open the plugin's url. -- Explorer's Search action keyword combines both Path and Index search, so you can use it without worrying about which action keyword to use for what, just put in what you need to search for. Path (searches a specific path) and Index (search a file or folder name) search allows users to do just their specific searches and are disabled by default. +- Explorer's Search action keyword combines both Path and Index search, so you can use it without worrying about which action keyword to use for what, put in what you need to search for. Path (searches a specific path) and Index (search a file or folder name) search allows users to do just their specific searches and are disabled by default. - Whilst in the query window and searching inside a directory, pressing `Ctrl + Backspace` will go back up one level in the directory tree.