Mirrors/PowerToys
1
0
Fork 0
mirror of https://github.com/microsoft/PowerToys.git synced 2025-12-16 11:48:06 +01:00
Code Issues Packages Projects Releases Wiki Activity

Dev Documentation of PowerToys Run (#7333)

Browse Source 
* Architecture and  (#7267)

* Added debugging steps for PT Run

* Updated architecture markdown for launcher

* updated project architecture markdown for launcher

* Added telemetry docs for launcher

* Added the basic folder structure and files

* Added a basic overview of all common functionalities of the plugins

* Added information about the functioning of the calculator plugin

* update score section of overview

* added information about the uri plugin

* added info about the indexer plugin

* Added the documentation for the indexer plugin

* Added information about the program plugin

* Added info about the shell plugin

* updated some plugin info and added information about the ww plugin

* documenting the folder plugin

* updated window walker docs

* dev docs for the folder plugin

* added images to each of the plugins

* Added link to pt run documents

* fix typos and some minor corrections

* Add table of contents for pt run dev docs

* Fix image path and project link for Wox.plugin

Co-authored-by: Divyansh Srivastava <somm14divi@gmail.com>
This commit is contained in:
Alekhya
2020-10-20 14:28:23 -07:00
committed by GitHub
parent 18eb6b4ffd
commit 0314b570cd
24 changed files with 328 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
doc/devdocs/modules/launcher/plugins/calculator.md Normal file
View File

@@ -0,0 +1,23 @@
# Calculator Plugin
The Calculator plugin as the name suggests is used to perform calculations on the user entered query.
![Image of Calculator plugin](/doc/images/launcher/plugins/calculator.png)
### [`CalculateHelper`](src/modules/launcher/Plugins/Microsoft.Plugin.Calculator/CalculateHelper.cs)
- The [`CalculateHelper.cs`](src/modules/launcher/Plugins/Microsoft.Plugin.Calculator/CalculateHelper.cs) class checks to see if the user entered query is a valid input to the calculator and only if the input is valid does it perform the operation.
- It does so by matching the user query to a valid regex.
### [`CalculateEngine`](src/modules/launcher/Plugins/Microsoft.Plugin.Calculator/CalculateEngine.cs)
- The main computation is done in the [`CalculateEngine.cs`](src/modules/launcher/Plugins/Microsoft.Plugin.Calculator/CalculateEngine.cs) file using the `Mages` library.
```csharp
var result = CalculateEngine.Interpret(query.Search, CultureInfo.CurrentUICulture);
```
### [`CalculateResult`](src/modules/launcher/Plugins/Microsoft.Plugin.Calculator/CalculateResult.cs)
- The class which encapsulates the result of the computation.
- It comprises of the `Result` and `RoundedResult` properties.
### Score
The score of each result from the calculator plugin is `300`.

17
doc/devdocs/modules/launcher/plugins/folder.md Normal file
View File

@@ -0,0 +1,17 @@
# Folder Plugin
The Folder plugin is used to navigate the directory structure and display the sub-folders and files within a folder.
![Image of Folder plugin](/doc/images/launcher/plugins/folder.png)
### [`FolderHelper.cs`](src/modules/launcher/Plugins/Microsoft.Plugin.Folder/Sources/Path/FolderHelper.cs)
- The [`FolderHelper`](src/modules/launcher/Plugins/Microsoft.Plugin.Folder/Sources/Path/FolderHelper.cs) class leverages the `DriveInformation` and `folderLinks` to get the folder results for a user query.
- The [`DriveInformation`](src/modules/launcher/Plugins/Microsoft.Plugin.Folder/Sources/Path/DriveInformation.cs) class gets the list of all drives on the system.
- The [`FolderLink`](src/modules/launcher/Plugins/Microsoft.Plugin.Folder/Sources/FolderLink.cs) object corresponds to a user created link for frequently accessed projects. This was inherited from Wox but is presently not functional as we don't have the UI setup in settings to get this user input. Each folderLink object has a `nickname`, which is the name of the folder and this can be used to directly access that folder instead of entering the entire path.
### [`IFolderProcessor.cs`](src/modules/launcher/Plugins/Microsoft.Plugin.Folder/Sources/IFolderProcessor.cs)
The `IFolderProcessor` utilizes the `FolderHelper` class to extract the folders and return the results.
There are two types of Folder Processors, based on the type of information they are processing -
1. [`UserFolderProcessor`](src/modules/launcher/Plugins/Microsoft.Plugin.Folder/UserFolderProcessor.cs) - This Processor is currently not used in PT Run but it is used to process the user created folder links.
2. [`InternalDirectoryProcessor`](src/modules/launcher/Plugins/Microsoft.Plugin.Folder/InternalDirectoryProcessor.cs) - This processor is used to retrieve the files and folders located within the current drive or shared folder.
### Score
The first result is of score 500 and the following results are scored 10.

39
doc/devdocs/modules/launcher/plugins/indexer.md Normal file
View File

@@ -0,0 +1,39 @@
# Indexer Plugin
The indexer plugin is used to search for files within the indexed locations of the system.
![Image of Indexer plugin](/doc/images/launcher/plugins/indexer.png)
### [Drive Detection](src/modules/launcher/Plugins/Microsoft.Plugin.Indexer/DriveDetection)
- There are two indexing modes in Windows:
1. **Classic mode**: Only the desktop and certain customizable locations in the system are indexed. All the systems have the classic mode enabled by default.
2. **Enhanced Mode**: This mode indexes the entire PC when enabled. The user can exclude certain locations from being indexed in this mode from the Windows Search settings options.
- A drive detection warning is displayed to the users when only the custom mode is enabled on the system informing the user that not all the locations on their PC are indexed as this could lead to some results not showing up.
- The [`IndexerDriveDetection.cs`](src/modules/launcher/Plugins/Microsoft.Plugin.Indexer/DriveDetection/IndexerDriveDetection.cs) file gets the status of the drive detection checkbox in the settings UI and depending on whether the enhanced mode is enabled or disabled, displays the warning.
- To determine whether the `EnhancedMode` is enabled or not, we check the local machine registry entry for `EnableFindMyFiles`. If it is set to 1, the enhanced mode is enabled.
### [`OleDBSearch`](src/modules/launcher/Plugins/Microsoft.Plugin.Indexer/SearchHelper/OleDBSearch.cs)
- The `Query` function within the [`OleDBSearch.cs`](src/modules/launcher/Plugins/Microsoft.Plugin.Indexer/SearchHelper/OleDBSearch.cs) class takes in the query and the connection string to the SystemIndex catalog as arguments and returns a list of results.
- It first opens a [connection][OLEDBConnection] to the Windows Indexer database, creates an [OleDB command][OLEDBCommand] and executes the command to get a list of results.
### [`WindowsSearchAPI`](src/modules/launcher/Plugins/Microsoft.Plugin.Indexer/SearchHelper/WindowsSearchAPI.cs)
- The [`WindowsSearchAPI`](src/modules/launcher/Plugins/Microsoft.Plugin.Indexer/SearchHelper/WindowsSearchAPI.cs) class leverages the [`OleDBSearch.cs`](src/modules/launcher/Plugins/Microsoft.Plugin.Indexer/SearchHelper/OleDBSearch.cs) class to execute the query.
- It initializes the `QueryHelper` in the `InitQueryHelper()` function by creating a catalog manager to the SystemIndex catalog.
- The metadata is initialized within the query helper, such as the number of results to retrive, the type of information to retrieve for each file (currently we retrieve the item URL, the file name and the file attributes).
- The query helper matches results using the name of the file only and they are sorted by the last modified date, ensuring that the recently modified files are ranked higher.
- The File attributes are utilized to filter out hidden files from being displayed.
### Additional Information
- There are two major types of queries generated by the indexer plugin:
1. Full Text predicates - eg: [CONTAINS][Contains]
2. Non-Full Text predicates - eg: [LIKE][Like]
- The Full text predicates are much faster than non-full text predicates as they are based on finding matches rather than comparing the query with each item in the indexer database. Hence, queries which have the `CONTAINS` keyword are much faster than those which contain the `LIKE` keyword.
- To prevent the indexer query from taking a long time and blocking the UI thread, there are two types of indexer queries which are executed. A simplified query and a full query, without and with the `LIKE` keyword respectively.
- The result list is updated with the results of the full query once they are obtained.
### Score
Each of the indexer plugin results has a score set to 0 so they are present at the bottom of the list.
[OLEDBCommand]: https://docs.microsoft.com/en-us/dotnet/api/system.data.oledb.oledbcommand?view=dotnet-plat-ext-3.1
[OLEDBConnection]: https://docs.microsoft.com/en-us/dotnet/api/system.data.oledb.oledbconnection?view=dotnet-plat-ext-3.1
[Contains]: https://docs.microsoft.com/en-us/windows/win32/search/-search-sql-contains
[Like]: https://docs.microsoft.com/en-us/windows/win32/search/-search-sql-like

35
doc/devdocs/modules/launcher/plugins/overview.md Normal file
View File

@@ -0,0 +1,35 @@
# Structural Overview
The following basic functions are common to each of the plugins. They perform some rudimentary operations such as initialization of the plugin, executing the query that has been entered, loading context menu icons, updating settings when configurations are altered in the settings UI, and updating the theme of the icons when the theme changed event is triggered.
## IPlugin Interface
Each plugin implements the `IPlugin` interface which comprises of the `Init()` and `Query()` functions.
### `Init`
- The `Init()` function initializes the context, storage and settings of each plugin. This is equivalent to a contructor and is the first function to be called in the `Main.cs` file for each plugin.
### `Query`
- For every query that the user enters into PT Run, the `PluginManager.cs` executes the `Query()` function in the `Main.cs` file corresponding to each Plugin.
### Context Menu Icons
- The `ContextMenus` are loaded for each result based on the type of the result.
- The various types of `ContextMenu` functionalities are:
- Open containing folder
- Run as Administrator
- Open in console
- Copy path
### UpdateSettings
- This function updates the settings of each plugin based on the changes made by the user in the settings UI.
- Eg: To disable drive detection in the indexer plugin, when the user checks or unchecks the drive detection check box, the `UpdateSettings()` function dispatches the changes in the check box to the plugin.
### ThemeChanged
- This function is invoked when there is a change in the theme of PT Run.
- It is used to update the `IconPath` for each plugin based on the theme.
### Save
- This function saves the configurations of each plugin so that they can be loaded the next time.
### Score
- The user query is executed against each of the plugins and the result list view is updated with results from each of the plugins.
- The ordering of the results is based on the `Score` of each Result.
- Each plugin assigns a score to a result based on it's relevance. The results with higher scores are displayed higher in the list view and vice versa.

43
doc/devdocs/modules/launcher/plugins/program.md Normal file
View File

@@ -0,0 +1,43 @@
# Program Plugin
The program plugin as the name suggests is used to search for programs installed on the system.
![Image of Program plugin](/doc/images/launcher/plugins/program.png)
There are broadly two different categories of applications:
1. Packaged applications
2. Win32 applications
### [UWP](src/modules/launcher/Plugins/Microsoft.Plugin.Program/Programs/UWP.cs)
- The logic for indexing Packaged applications is present within the [`UWP.cs`](src/modules/launcher/Plugins/Microsoft.Plugin.Program/Programs/UWP.cs) file.
- There can be multiple applications present within a package. The [`UWPApplication.cs`](src/modules/launcher/Plugins/Microsoft.Plugin.Program/Programs/UWPApplication.cs) file encapsulates the properties of a packaged application.
- To index packaged applications, the `PackageManager` retrives all the packages for the current user and indexes all the applications.
- To retrieve the app icon for packaged applications, the assets path is retrieved from the `Application Manifest` file. There are multiple icons corresponding to each scale, target size and theme. The best icon is chosen given the theme of powerToys Run.
### [Win32Program](src/modules/launcher/Plugins/Microsoft.Plugin.Program/Programs/Win32Program.cs)
- Win32 programs in the following locations are indexed by PT Run-
1. Desktop
2. Public Desktop (Applications present on the desktop of all the users)
3. Registry (Some programs)
4. Start Menu
5. Common start menu (Applications which are common to all users)
8. Locations pointed to by the PATH environment variable.
- To prevent applications and shortcuts present in multiple locations from showing up as duplicate results, we consider apps with the same name, executable name and full path to be the same.
- The subtitle of the application result is set based on it's application type. It could be one of the following:
1. Lnk Shortcuts
2. Appref files
3. Internet shortcut - steam and epic games
4. PWAs
5. Run commands - these are indexed by the PATH environment variable
### Score
- The score for each application result is based on the how many letters are matched, how close the matched letters are to the actual word and the index of the matched characters.
- There is a threshold score to decide the apps which are to be displayed and applications which have a lower score are not displayed by PT Run.
### Update Program List in Runtime
- Packaged and Win32 app helpers exist to reflect changes in the list of indexed apps when applications are installed on the system while PT Run is executing.
- Packaged applications trigger events when the package is being installed and uninstalled. PT Run listens to those events to index applications which are newly installed or to delete an app which no longer exists from the database.
- No such events exist for Win32 applications. We therefore use FileSystem Watchers to monitor the locations that we index for newly created, deleted or renamed application files and update the indexed Win32 catalog accordingly.
### Additional Notes
- Arguments can be provided to the program plugin by entering them after `--` (a double dash).

14
doc/devdocs/modules/launcher/plugins/shell.md Normal file
View File

@@ -0,0 +1,14 @@
# Shell Plugin
- Shell plugin emulates the Windows Run Prompt (Win+R).
- Shell Plugin is one of the non-global plugins which has an action keyword set to `>`.
![Image of Shell plugin](/doc/images/launcher/plugins/shell.png)
### Functionality
- The Shell command expands environment variables, so `>%appdata%` works as expected.
- On inheriting the Shell plugin from Wox, there are three different ways of executing a command, using the command prompt, powershell or the run prompt. To uphold the name of PT Run, the Shell plugin always executes commands as the Run prompt would.
- The Shell plugin has a concept of history where the previously executed commands show up in the drop down list along with the number of times they have been executed.
- The Run prompt has the folder plugin function where we can navigate to different locations and entering the path to a directory displays all the sub-directories. To prevent reimplementing this logic, the shell plugin references the folder plugin to implement this functionality.
### Score
The Shell plugin results have a very high score of 5000. Hence, they are one of the first results in the list.

19
doc/devdocs/modules/launcher/plugins/uri.md Normal file
View File

@@ -0,0 +1,19 @@
# URI Plugin
The URI Plugin, as the name suggests is used to dierctly run the URI that has been entered by the user as a query. This is done by parsing the entry and validating the URI, followed by executing it.
![Image of URI plugin](/doc/images/launcher/plugins/uri.png)
### [`URI Parser`](src/modules/launcher/Plugins/Microsoft.Plugin.Uri/UriHelper/ExtendedUriParser.cs)
- The [`ExtendedUriParser.cs`](src/modules/launcher/Plugins/Microsoft.Plugin.Uri/UriHelper/ExtendedUriParser.cs) file tries to parse the user input and returns a `System.Uri` result by using the `UriBuilder`.
- It also captures other cases which the UriBuilder does not handle such as when the input ends with a `:`, `.` or `:/`.
### [`URI Resolver`](src/modules/launcher/Plugins/Microsoft.Plugin.Uri/UriHelper/UriResolver.cs)
- The [`UriResolver.cs`](src/modules/launcher/Plugins/Microsoft.Plugin.Uri/UriHelper/UriResolver.cs) file returns true for Valid hosts.
- Currently there is no additional logic for filtering out invalid hosts and it always returns true for a valid Uri that was created by parsing the user query. It can be expanded in the future to filter out certain hosts.
### Default Browser Icon
- The icon for each uri result is that of the default browser set by the user.
- These details are obtained from the user registry and updated each time the theme of PT Run is changed.
### Score
- All uri plugin results have a score of 0 which indicates that they would show up after each of the other plugins, other than the indexer plugin which also has a score of 0.

18
doc/devdocs/modules/launcher/plugins/windowwalker.md Normal file
View File

@@ -0,0 +1,18 @@
# Window Walker plugin
The window walker plugin matches the user entered query with the open windows on the system.
![Image of Window Walker plugin](/doc/images/launcher/plugins/windowwalker.png)
### [`OpenWindows.cs`](src/modules/launcher/Plugins/Microsoft.Plugin.WindowWalker/Components/OpenWindows.cs)
- The window walker plugin uses the `EnumWindows` function to enumerate all the open windows in the [`OpenWindows.cs`](src/modules/launcher/Plugins/Microsoft.Plugin.WindowWalker/Components/OpenWindows.cs) class.
### [`SearchController.cs`](src/modules/launcher/Plugins/Microsoft.Plugin.WindowWalker/Components/SearchController.cs)
- The [`SearchController`](src/modules/launcher/Plugins/Microsoft.Plugin.WindowWalker/Components/SearchController.cs) encapsulates the functions needed to search and find matches.
- It is responsible for updating the search text and performing a fuzzy search on all the open windows in an asynchronous manner.
### [`Window.cs`](src/modules/launcher/Plugins/Microsoft.Plugin.WindowWalker/Components/Window.cs)
- The [`Window`](src/modules/launcher/Plugins/Microsoft.Plugin.WindowWalker/Components/Window.cs) class represents a specific window and has functions to get the name of the process, the state of the window (whether it is visible or not), and the `SwitchTowindow` function which switches the desktop focus to the selected window. This action is performed when the user clicks on a window walker plugin result.
### Score
The window walker plugin uses [`FuzzyMatching`](src/modules/launcher/Plugins/Microsoft.Plugin.WindowWalker/Components/FuzzyMatching.cs) to get the matching indices and calculates the score by creating a 2 dimensional array of the window and the query text.