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

Add information about how to add new languages to monaco (#24906)

Browse Source 
* Add information about how to add new languages to monaco

* Update expect.txt

* Update doc/devdocs/modules/FileExplorer/monaco/readme.md

Co-authored-by: Jay <65828559+Jay-o-Way@users.noreply.github.com>

* Adress PR feedback

* fix spelling errors

* Update doc/devdocs/modules/FileExplorer/monaco/readme.md

Co-authored-by: Heiko <61519853+htcfreek@users.noreply.github.com>

* Update readme.md

* Update readme.md

* Address PR comments

* Fix spelling

* address PR comments

* address PR comments and move files

* Update expect.txt

* Update doc/devdocs/common/readme.md

Co-authored-by: Heiko <61519853+htcfreek@users.noreply.github.com>

* Update doc/devdocs/common/FilePreviewCommon.md

Co-authored-by: Heiko <61519853+htcfreek@users.noreply.github.com>

* Update doc/devdocs/common/FilePreviewCommon.md

Co-authored-by: Heiko <61519853+htcfreek@users.noreply.github.com>

* Update doc/devdocs/common/FilePreviewCommon.md

Co-authored-by: Heiko <61519853+htcfreek@users.noreply.github.com>

* Update doc/devdocs/common/FilePreviewCommon.md

Co-authored-by: Heiko <61519853+htcfreek@users.noreply.github.com>

* Update doc/devdocs/common/FilePreviewCommon.md

Co-authored-by: Stefan Markovic <57057282+stefansjfw@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Stefan Markovic <57057282+stefansjfw@users.noreply.github.com>

* Adress PR comments

* Fix spelling

* Adress PR comments

* Add peek stub documentation

* Update doc/devdocs/common/FilePreviewCommon.md

Co-authored-by: Stefan Markovic <57057282+stefansjfw@users.noreply.github.com>

* Update doc/devdocs/common/FilePreviewCommon.md

* Fix spelling

---------

Co-authored-by: Jay <65828559+Jay-o-Way@users.noreply.github.com>
Co-authored-by: Heiko <61519853+htcfreek@users.noreply.github.com>
Co-authored-by: Stefan Markovic <57057282+stefansjfw@users.noreply.github.com>
This commit is contained in:
Aaron Junker-Wildi
2023-12-11 16:45:16 +01:00
committed by GitHub
parent 93a422ca9b
commit a4260d7cbd
6 changed files with 98 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

75
doc/devdocs/common/FilePreviewCommon.md Normal file
View File

@@ -0,0 +1,75 @@
# [FilePreviewCommon](/src/common/FilePreviewCommon)
This project contains common code used for previewing and displaying files.
## Monaco preview
Monaco preview enables to display developer files. It is based on [Microsoft's Monaco Editor](https://microsoft.github.io/monaco-editor/) which is maintained by the Visual Studio Code team.
This previewer is used for the File Explorer Dev File Previewer, as well as PowerToys Peek.
### Update Monaco Editor
1. Download Monaco editor with [npm](https://www.npmjs.com/): Run `npm i monaco-editor` in the command prompt.
2. Delete everything except the `min` folder (the minimised code) from the downloaded files.
3. Copy the `min` folder into the `src/common/FilePreviewCommon/Assets/Monaco/monacoSRC` folder of the PowerToys project.
4. Generate the JSON file as described in the generate [monaco_languages.json file](#monaco_languagesjson) section.
### Add a new language definition
As an example on how to add a new language definition you can look at the one for [registry files](/src/common/FilePreviewCommon/Assets/Monaco/customLanguages/reg.js).
1. Add the new language definition (written with [Monarch](https://microsoft.github.io/monaco-editor/monarch.html)) as a new file to the [folder containing Monaco custom languages](/src/common/FilePreviewCommon/Assets/Monaco/customLanguages/) (Remember the file name and the string you used for "idDefinition" as you need it later.). The file should be formatted like in the example below. (Please change `idDefinition` to the name of your language.)
```javascript
export function idDefinition() {
return {
...
}
}
```
2. Add the following line to the [`monacoSpecialLanguages.js`](/src/common/FilePreviewCommon/Assets/Monaco/monacoSpecialLanguages.js) file, after the other import statements:
```javascript
import { idDefinition } from './customLanguages/file.js';
```
> Replace file.js with the name of your definition file from step 1. Please replace idDefinition with the string you used in step 1.
3. In the [`monacoSpecialLanguages.js`](/src/common/FilePreviewCommon/Assets/Monaco/monacoSpecialLanguages.js) file add the following line into the `registerAdditionalLanguages` function:
```javascript
registerAdditionalNewLanguage("id", [".fileExtension"], idDefinition(), monaco)
```
> Replace id and idDefinition with your id and string used in step 1. Replace fileExtension with a set of file extensions you want the language to register to.
* The id can be anything. Recommended is one of the file extensions. For example "php" or "reg".
4. Execute the steps described in the [monaco_languages.json](#monaco_languagesjson) section.
### Add a new file extension to an existing language
1. In the [`monacoSpecialLanguages.js`](/src/common/FilePreviewCommon/Assets/Monaco/monacoSpecialLanguages.js) file add the following line to the `registerAdditionalLanguages` function. (`existingId` is the id of the language you want to add the extension to. You can find these id's in the [`monaco_languages.json`](/src/common/FilePreviewCommon/Assets/Monaco/monaco_languages.json) file):
```javascript
registerAdditionalLanguage("id", [".fileExtension"], "existingId", monaco)
```
* If for instance you want to add more extensions to the php language set the id to `phpExt` and the existingId to `php`.
2. Copy the existing language definition into the `languageDefinitions` function in the same file. You can find the existing definitions in the following folder: [`/src/common/FilePreviewCommon/Assets/Monaco/monacoSRC/min/vs/basic-languages/`](/src/common/FilePreviewCommon/Assets/Monaco/monacoSRC/min/vs/basic-languages/).
3. Execute the steps described in the [monaco_languages.json](#monaco_languagesjson) section.
### monaco_languages.json
[`monaco_languages.json`](/src/common/FilePreviewCommon/Assets/Monaco/monaco_languages.json) contains all extensions and IDs for the languages supported by Monaco. The [`MonacoHelper`](/src/common/FilePreviewCommon/MonacoHelper.cs) class and the installer are using this file to register preview handlers for the defined extensions.
After updating Monaco Editor and/or adding a new language you should update the [`monaco_languages.json`](/src/common/FilePreviewCommon/Assets/Monaco/monaco_languages.json) file.
1. Run the [`generateLanguagesJson.html`](/src/common/FilePreviewCommon/Assets/Monaco/generateLanguagesJson.html) file on a local webserver (as webbrowsers will block certain needed features when running the file locally.)
* This can for example be achieved by using the [Preview Server](https://marketplace.visualstudio.com/items?itemName=yuichinukiyama.vscode-preview-server) extension for Visual Studio Code: Open the file in Visual Studio Code, right click in the code editor and select `vscode-preview-server: Launch on browser`. The file will be opened in a browser.
2. The browser will download the new `monaco_languages.json` file
3. Replace the old file with the newly downloaded one in the source code folder.

102
doc/devdocs/common/common.md Normal file
View File

@@ -0,0 +1,102 @@
# Classes and structures
> This document is outdated and will soon be renewed.
#### class Animation: [header](/src/common/animation.h) [source](/src/common/animation.cpp)
Animation helper class with two easing-in animations: linear and exponential.
#### class AsyncMessageQueue: [header](/src/common/async_message_queue.h)
Header-only asynchronous message queue. Used by `TwoWayPipeMessageIPC`.
#### class TwoWayPipeMessageIPC: [header](/src/common/two_way_pipe_message_ipc.h)
Header-only asynchronous IPC messaging class. Used by the runner to communicate with the settings window.
#### class DPIAware: [header](/src/common/dpi_aware.h) [source](/src/common/dpi_aware.cpp)
Helper class for creating DPI-aware applications.
#### struct MonitorInfo: [header](/src/common/monitors.h) [source](/src/common/monitors.cpp)
Class for obtaining information about physical displays connected to the machine.
#### class Settings, class PowerToyValues, class CustomActionObject: [header](/src/common/settings_objects.h) [source](/src/common/settings_objects.cpp)
Classes used to define settings screens for the PowerToys modules.
#### class Tasklist: [header](/src/common/tasklist_positions.h) [source](/src/common/tasklist_positions.cpp)
Class that can detect the position of the windows buttons on the taskbar. It also detects which window will react to pressing `WinKey + number`.
#### struct WindowsColors: [header](/src/common/windows_colors.h) [source](/src/common/windows_colors.cpp)
Class for detecting the current Windows color scheme.
# Helpers
#### Common helpers: [header](/src/common/common.h) [source](/src/common/common.cpp)
Various helper functions.
#### Settings helpers: [header](/src/common/settings_helpers.h)
Helper methods for the settings.
#### Start visible helper: [header](/src/common/start_visible.h) [source](/src/common/start_visible.cpp)
Contains function to test if the Start menu is visible.
# Toast Notifications
#### Notifications API [header](/src/common/notifications.h) [source](/src/common/notifications.cpp)
To use UWP-style toast notifications, simply include the header and call one of these functions:
```cpp
void show_toast(std::wstring_view message); // #1
void show_toast_background_activated( // #2
std::wstring_view message,
std::wstring_view background_handler_id,
std::vector<std::wstring_view> button_labels);
```
We might add more functions in the future if the need arises, e.g. `show_toast_xml` which will accept raw XML for rich customization.
Description:
- `#1` is for sending simple notifications without any callbacks or buttons
- `#2` is capable of showing a toast with multiple buttons and background activation
- `message` is a plain-text argument
Implement a toast activation handler/callback as a function in [handler_functions.cpp](/src/common/notifications_winrt/handler_functions.cpp) and register its `background_handler_id` via `handlers_map`, e.g.:
```cpp
// Your .cpp where you'd like to show a toast
#include <common/notifications.h>
void some_func() {
// ...
notifications::show_toast_background_activated(
L"Toast message!", // text displayed in a toast
L"awesome_toast", // activation handler id
{L"Press me!", L"Also could press me!", L"I'm here to be pressed!"} // buttons in a toast
);
```
```cpp
// handler_functions.cpp
void awesome_toast_handler(IBackgroundTaskInstance, const size_t button_id)
{
switch(button_id)
{
case 0:
// handle "Press me!" button click
case 1:
// handle "Also could press me!" button click
case 2:
// handle "I'm here to be pressed!" button click
}
}
namespace
{
const std::unordered_map<std::wstring_view, handler_function_t> handlers_map = {
// ...other handlers...
{L"awesome_toast", awesome_toast_handler}
};}
```
Note: since _background activation_ implies that your toast handler will be invoked in a separate process, you can't share data directly from within a handler and your PT process. Also, since PT is currently a Desktop Bridge app, _foreground activation_ is [handled the same as background](https://learn.microsoft.com/windows/uwp/design/shell/tiles-and-notifications/send-local-toast-desktop-cpp-wrl#foreground-vs-background-activation), therefore we don't make a dedicated API for it. You can read more on the rationale of the current design [here](https://github.com/microsoft/PowerToys/pull/1178#issue-368768337).

7
doc/devdocs/common/readme.md Normal file
View File

@@ -0,0 +1,7 @@
# Common
The [common](/src/common) folder contains projects with code, that is used in multiple projects.
## [FilePreviewCommon](FilePreviewCommon.md)
This project contains common code for file previewing.