From f50a8e0e433191e5f5524d9ee3f89d3433a9fb7d Mon Sep 17 00:00:00 2001 From: Aaron Junker-Wildi Date: Mon, 14 Oct 2024 14:45:53 +0000 Subject: [PATCH 1/7] [WIP] WinGet manifest Keyboard Shortcuts extension --- ...t Manifest Keyboard Shortcuts extension.md | 81 +++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 doc/specs/WinGet Manifest Keyboard Shortcuts extension.md diff --git a/doc/specs/WinGet Manifest Keyboard Shortcuts extension.md b/doc/specs/WinGet Manifest Keyboard Shortcuts extension.md new file mode 100644 index 000000000000..6ae9dffc1db9 --- /dev/null +++ b/doc/specs/WinGet Manifest Keyboard Shortcuts extension.md @@ -0,0 +1,81 @@ +# Winget Manifest Keyboard Shortcuts extension v1.0 + +## 1 What this spec is about + +## 2 Save location of manifests + +All manifests and one index file are saved under `%localappdata%/Microsoft/Windows/KeyboardShortcuts`. All apps are allowed to add their manifest files there. In addition Package Managers (like WinGet) and manifest interpreters (like PowerToys Shortcut Guide) can control and add other manifests themselves. + +### 2.1 File names + +The file name of a keyboard shortcuts file is the WinGet package identifier, plus the locale of the strings of the file and at last the `.KBSC.yml` file extension. + +For example the package "test.bar" saves its manifest with `en-US` strings in `test.bar.en-US.KBSC.yml" + +#### 2.1.1 No winget package available + +If an application has no corresponding WinGet package its name starts with a plus symbol. + +### 2.2 Reserved namespaces + +Every name starting with `+WindowsNT` is reserved for the Windows OS and its components. + +## 3 File syntax + +All relevant files are written in the + +### 3.1 Keyboard shortcuts manifest + +#### 3.1.1 `PackageName` field + +#### 3.1.2 `Filter` field + +#### 3.1.3 `Shortcuts` field + +##### 3.1.3.1 `SectionName` field + +**Special sections**: + +Special sections start with an identifier enclosed between `<` and `>`. This declares the category as a special display. If the interpreter of the manifest file can't understand the content this section should be left out. + +##### 3.1.3.2 `Properties` field + +###### 3.1.3.2.1 `Name` field + +###### 3.1.3.2.2 `Win` field + +###### 3.1.3.2.3 `Ctrl` field + +###### 3.1.3.2.4 `Shift` field + +###### 3.1.3.2.5 `Alt` field + +###### 3.1.3.2.6 `Description` field + +###### 3.1.3.2.7 `Recommended` field + +###### 3.1.3.2.8 `Keys` field + +An string array of all the keys that need to be pressed. + +**Special keys**: + +Special keys are enclosed between `<` and `>` and correspond to a key that should be displayed in a certain way + +|Name|Description| +|----|-----------| +|``| Corresponds to the Office key on some Windows keyboards | +|``| Corresponds to the Copilot key on some Windows keyboards | + +### 3.2 `index.yml` file + +#### 3.2.1 `DefaultShellName` field + +This declares the package identifier of the default shell used in Windows. Most commenly it is `+WindowsNT.Shell`. Although not enforced, only the shell declared in the registry key `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon\Shell` should be used here. + +#### 3.2.2 `Index` field + +##### 3.2.2.1 `Filter` field + +##### 3.2.2.2 `Apps` field + From 9f0ac84caef643e0fa1c0ab25d19624c457c80de Mon Sep 17 00:00:00 2001 From: Aaron Junker-Wildi Date: Sun, 3 Nov 2024 21:58:24 +0000 Subject: [PATCH 2/7] Finish --- ...t Manifest Keyboard Shortcuts extension.md | 207 +++++++++++++++--- 1 file changed, 179 insertions(+), 28 deletions(-) diff --git a/doc/specs/WinGet Manifest Keyboard Shortcuts extension.md b/doc/specs/WinGet Manifest Keyboard Shortcuts extension.md index 6ae9dffc1db9..ca3ddacb1c08 100644 --- a/doc/specs/WinGet Manifest Keyboard Shortcuts extension.md +++ b/doc/specs/WinGet Manifest Keyboard Shortcuts extension.md @@ -1,81 +1,232 @@ -# Winget Manifest Keyboard Shortcuts extension v1.0 +# Winget Manifest Keyboard Shortcuts schema ## 1 What this spec is about +This spec provides an extension to the existing [WinGet manifest schema](https://github.com/microsoft/winget-pkgs/blob/master/doc/manifest/README.md), that allows saving keyboard shortcuts of an application in form of an additional yaml file. + +These yaml files are saved on a per-user base and so called manifest interpreters can then display these manifests in a human-friendly version. + ## 2 Save location of manifests -All manifests and one index file are saved under `%localappdata%/Microsoft/Windows/KeyboardShortcuts`. All apps are allowed to add their manifest files there. In addition Package Managers (like WinGet) and manifest interpreters (like PowerToys Shortcut Guide) can control and add other manifests themselves. +### 2.1 WinGet + +These files are saved online along with the other manifest files in the [WinGet Package repository](https://github.com/microsoft/winget-pkgs). + +### 2.2 Locally + +All manifests and one index file are saved locally under `%LocalAppData%/Microsoft/Windows/KeyboardShortcuts`. All apps are allowed to add their manifest files there. In addition Package Managers (like WinGet) and manifest interpreters (like PowerToys Shortcut Guide) can control and add other manifests themselves. -### 2.1 File names +### 2.3 File names The file name of a keyboard shortcuts file is the WinGet package identifier, plus the locale of the strings of the file and at last the `.KBSC.yml` file extension. For example the package "test.bar" saves its manifest with `en-US` strings in `test.bar.en-US.KBSC.yml" -#### 2.1.1 No winget package available +#### 2.3.1 No winget package available -If an application has no corresponding WinGet package its name starts with a plus symbol. +If an application has no corresponding WinGet package its name starts with a plus (`+`) symbol. -### 2.2 Reserved namespaces +### 2.4 Reserved namespaces Every name starting with `+WindowsNT` is reserved for the Windows OS and its components. ## 3 File syntax -All relevant files are written in the +All relevant files are written in [YAML](https://yaml.org/spec). + +> Note: A JSON schema will be provided as soon as the spec reaches a further step + +### 3.1 Manifest Schema vNext Keyboard Shortcuts File + +``` +PackageName: # The package unique identifier +WindowFilter: # The filter of window processes to which the shortcuts apply to +BackgroundProcess: # Optionally allows applying WindowFilter to background processes +Shortcuts: # List of sections with keyboard shortcuts + - SectionName: # Name of the category of shortcuts + Properties: # List of shortcuts in the category + - Name: # Name of the shortcut + Win: # Determines if the Windows Key is part of the shortcut + Ctrl: # Determines if the Ctrl Key is part of the shortcut + Shift: # Determines if the Shift Key is part of the shortcut + Alt: # Determines if the Alt Key is part of the shortcut + Description: # Optionale description of the shortcut + AdditionalInfo: # Optional additional information about the shortcut + Recommended: # Optionally determines if the shortcut is displayed in a designated recommended area + Keys: # Array of keys that need to be pressed +``` + +Per Application/Package one or more Keyboard manifests can be declared. Every manifest must have a different locale and the same `PackageName`, `WindowFilter` and `BackgroundProcess` fields. -### 3.1 Keyboard shortcuts manifest +
+ PackageName - The package unique identifier -#### 3.1.1 `PackageName` field + Package identifier (see 2.1 for more information on the package identifier). -#### 3.1.2 `Filter` field +
-#### 3.1.3 `Shortcuts` field +
+ WindowFilter - The filter of window processes to which the shortcuts apply to -##### 3.1.3.1 `SectionName` field + This field declares for which process name the shortcuts should be showed (To rephrase: For which processes the shortcut will have an effect if pressed). You can use an asterisk to leave out a certain part. For example `*.PowerToys.*.exe` targets all PowerToys processes and `*` apply to any process. + +
+ +
+ BackgroundProcess - Optionally allows applying WindowFilter to background processes + + **Optional field** + + Defaults to `False`. Determines if WindowFilter should apply to background processes as well (Rephrased: When the process is running, the shortcuts will apply). + +
+ +
+ Shortcuts - List of sections with keyboard shortcuts + + List of different section (also called categories) of shortcuts. +
+ +
+ SectionName - Name of the category of shortcuts + + Name of the section of shortcuts. **Special sections**: Special sections start with an identifier enclosed between `<` and `>`. This declares the category as a special display. If the interpreter of the manifest file can't understand the content this section should be left out. -##### 3.1.3.2 `Properties` field +
+ +
+ Properties - List of shortcuts in the category +
-###### 3.1.3.2.1 `Name` field +
+ Name - Name of the shortcut -###### 3.1.3.2.2 `Win` field + Name of the shortcut. This is the name that will be displayed in the interpreter. -###### 3.1.3.2.3 `Ctrl` field +
-###### 3.1.3.2.4 `Shift` field +
+ Win - Determines if the Windows Key is part of the shortcut -###### 3.1.3.2.5 `Alt` field + Refers to the left Windows Key on the keyboard. +
-###### 3.1.3.2.6 `Description` field +
+ Ctrl - Determines if the Ctrl Key is part of the shortcut -###### 3.1.3.2.7 `Recommended` field + Refers to the left Ctrl Key on the keyboard. +
-###### 3.1.3.2.8 `Keys` field +
+ Shift - Determines if the Shift Key is part of the shortcut -An string array of all the keys that need to be pressed. + Refers to the left Shift Key on the keyboard. +
+ +
+ Alt - Determines if the Alt Key is part of the shortcut + + Refers to the left Alt Key on the keyboard. +
+ +
+ Description - Optionale description of the shortcut + + Optional description of the shortcut. This is the description that will be displayed by the interpreter. +
+ +
+ AdditionalInfo - Optional additional information about the shortcut + + Array of additional information about the shortcut. This is the additional information that will be displayed by the interpreter and are not part of this manifest. + + **Example**: + + For example, if the shortcut is only available on a certain Windows version, this information could be added here. + ```yaml + AdditionalInfo: + - MinWindowsVersion: "10.0.19041.0" + ``` +
+ +
+ Recommended - Optionally determines if the shortcut is displayed in a designated recommended area + + **Optional field** + + Defaults to `False`. Determines if the shortcut should be displayed in a designated recommended area. This is a visual hint for the user that this shortcut is important. + +
+ +
+ Keys - Array of keys that need to be pressed + + An string array of all the keys that need to be pressed. If a number is supplied, it should be read as a [KeyCode](https://learn.microsoft.com/windows/win32/inputdev/virtual-key-codes) and displayed accordingly (based on the Keyboard Layout of the user). **Special keys**: -Special keys are enclosed between `<` and `>` and correspond to a key that should be displayed in a certain way +Special keys are enclosed between `<` and `>` and correspond to a key that should be displayed in a certain way. If the interpreter of the manifest file can't understand the content, the brackets should be left out. |Name|Description| |----|-----------| |``| Corresponds to the Office key on some Windows keyboards | |``| Corresponds to the Copilot key on some Windows keyboards | +|``| Corresponds to the left arrow key | +|``| Corresponds to the right arrow key | +|``| Corresponds to the up arrow key | +|``| Corresponds to the down arrow key | +|``| Corresponds to the Enter key | +|``| Corresponds to the Space key | +|``| Corresponds to the Tab key | +|``| Corresponds to the Backspace key | +|``| Corresponds to the Delete key | +|``| Corresponds to the Insert key | +|``| Corresponds to the Home key | +|``| Corresponds to the End key | +|``| Corresponds to the Page Up key | +|``| Corresponds to the Page Down key | +|``| Corresponds to the Escape key | +|``| Corresponds to either the left, right, up or down arrow key | +|``| Corresponds to either the left or right arrow key | +|``| Corresponds to either the up or down arrow key | +|``| Corresponds to any letter that is _underlined_ in the UI | + +
+ ### 3.2 `index.yml` file -#### 3.2.1 `DefaultShellName` field +The `index.yml` file is a file that contains all the information about the different manifest files that are saved in the same directory. This file is only availabele locally and is not saved in the WinGet repository as it is specific to the user. + +```yaml +DefaultShellName: # The package identifier of the default shell used in Windows +Index: # List of all manifest files + - Filter: # The filter of window processes to which the shortcuts apply to + Apps: # List of all manifest files for the filter +``` + +
+ DefaultShellName - The package identifier of the default shell used in Windows + + This declares the package identifier of the default shell used in Windows. Most commonly it is `+WindowsNT.Shell`. Although not enforced, only the shell declared in the registry key `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon\Shell` should be used here. + +
-This declares the package identifier of the default shell used in Windows. Most commenly it is `+WindowsNT.Shell`. Although not enforced, only the shell declared in the registry key `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon\Shell` should be used here. +
+ Index - List of all manifest files +
-#### 3.2.2 `Index` field +
+ Filter - The filter of window processes to which the shortcuts apply to -##### 3.2.2.1 `Filter` field + See the `WindowFilter` field in the manifest file for more information. -##### 3.2.2.2 `Apps` field +
+
+ Apps - List of all the package identifiers applying for the filter +
From c4f331db416daaf1a8c2c73eca996d34a3a8c935 Mon Sep 17 00:00:00 2001 From: Aaron Junker-Wildi Date: Sun, 3 Nov 2024 22:02:12 +0000 Subject: [PATCH 3/7] Fix spelling errors --- .github/actions/spell-check/expect.txt | 1 + doc/specs/WinGet Manifest Keyboard Shortcuts extension.md | 6 +++--- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/.github/actions/spell-check/expect.txt b/.github/actions/spell-check/expect.txt index 83689c807171..f971bd7e232a 100644 --- a/.github/actions/spell-check/expect.txt +++ b/.github/actions/spell-check/expect.txt @@ -756,6 +756,7 @@ Jsons jsonval junja jxr +KBSC kdc keybd KEYBDDATA diff --git a/doc/specs/WinGet Manifest Keyboard Shortcuts extension.md b/doc/specs/WinGet Manifest Keyboard Shortcuts extension.md index ca3ddacb1c08..51ad36ab34cb 100644 --- a/doc/specs/WinGet Manifest Keyboard Shortcuts extension.md +++ b/doc/specs/WinGet Manifest Keyboard Shortcuts extension.md @@ -50,7 +50,7 @@ Shortcuts: # List of sections with keyboard shortcuts Ctrl: # Determines if the Ctrl Key is part of the shortcut Shift: # Determines if the Shift Key is part of the shortcut Alt: # Determines if the Alt Key is part of the shortcut - Description: # Optionale description of the shortcut + Description: # Optional description of the shortcut AdditionalInfo: # Optional additional information about the shortcut Recommended: # Optionally determines if the shortcut is displayed in a designated recommended area Keys: # Array of keys that need to be pressed @@ -134,7 +134,7 @@ Special sections start with an identifier enclosed between `<` and `>`. This dec
- Description - Optionale description of the shortcut + Description - Optional description of the shortcut Optional description of the shortcut. This is the description that will be displayed by the interpreter.
@@ -200,7 +200,7 @@ Special keys are enclosed between `<` and `>` and correspond to a key that shoul ### 3.2 `index.yml` file -The `index.yml` file is a file that contains all the information about the different manifest files that are saved in the same directory. This file is only availabele locally and is not saved in the WinGet repository as it is specific to the user. +The `index.yml` file is a file that contains all the information about the different manifest files that are saved in the same directory. This file is only available locally and is not saved in the WinGet repository as it is specific to the user. ```yaml DefaultShellName: # The package identifier of the default shell used in Windows From 2a6b856ee556a24ed9103a1a46db241d61e3670c Mon Sep 17 00:00:00 2001 From: Aaron Junker-Wildi Date: Sun, 3 Nov 2024 22:10:27 +0000 Subject: [PATCH 4/7] Rename file and add examples --- ...get Manifest Keyboard Shortcuts schema.md} | 42 +++++++++++++++++++ 1 file changed, 42 insertions(+) rename doc/specs/{WinGet Manifest Keyboard Shortcuts extension.md => Winget Manifest Keyboard Shortcuts schema.md} (91%) diff --git a/doc/specs/WinGet Manifest Keyboard Shortcuts extension.md b/doc/specs/Winget Manifest Keyboard Shortcuts schema.md similarity index 91% rename from doc/specs/WinGet Manifest Keyboard Shortcuts extension.md rename to doc/specs/Winget Manifest Keyboard Shortcuts schema.md index 51ad36ab34cb..fdc757a5be1e 100644 --- a/doc/specs/WinGet Manifest Keyboard Shortcuts extension.md +++ b/doc/specs/Winget Manifest Keyboard Shortcuts schema.md @@ -197,6 +197,33 @@ Special keys are enclosed between `<` and `>` and correspond to a key that shoul +#### 3.2.2 Example + +```yaml +PackageName: Microsoft.PowerToys +WindowFilter: "*" +BackgroundProcess: True +Shortcuts: + - SectionName: General + Properties: + - Name: Advanced Paste + Win: True + Ctrl: False + Alt: False + Shift: True + Description: Open Advanced Paste window + Keys: + - 86 + - Name: Advanced Paste + Win: True + Ctrl: True + Alt: True + Shift: False + Description: Paste as plain text directly + Keys: + - 86 +``` + ### 3.2 `index.yml` file @@ -230,3 +257,18 @@ Index: # List of all manifest files
Apps - List of all the package identifiers applying for the filter
+ +#### 3.2.1 Example + +```yaml +DefaultShellName: "+WindowsNT.Shell" +Index: + - Filter: "*" + Apps: ["+WindowsNT.Shell", "Microsoft.PowerToys"] + - Filter: "explorer.exe" + Apps: ["+WindowsNT.WindowsExplorer"] + - Filter: "taskmgr.exe" + Apps: ["+WindowsNT.TaskManager"] + - Filter: "msedge.exe" + Apps: ["+WindowsNT.Edge"] +``` \ No newline at end of file From cf86dd51d727c57a8652ae41899d4a4b38356799 Mon Sep 17 00:00:00 2001 From: Aaron Junker-Wildi Date: Sun, 3 Nov 2024 22:13:52 +0000 Subject: [PATCH 5/7] Fix spelling --- .github/actions/spell-check/expect.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/actions/spell-check/expect.txt b/.github/actions/spell-check/expect.txt index f971bd7e232a..0ef91fb820c7 100644 --- a/.github/actions/spell-check/expect.txt +++ b/.github/actions/spell-check/expect.txt @@ -1606,6 +1606,7 @@ targetentrypoint TARGETHEADER targetver taskkill +taskmgr taskschd tchar Tcollab From dd763042a2cccbc97e33ff3f58de5487eeb10455 Mon Sep 17 00:00:00 2001 From: Aaron Junker-Wildi Date: Sun, 3 Nov 2024 22:45:21 +0000 Subject: [PATCH 6/7] Change Yml tp yaml --- doc/specs/Winget Manifest Keyboard Shortcuts schema.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/specs/Winget Manifest Keyboard Shortcuts schema.md b/doc/specs/Winget Manifest Keyboard Shortcuts schema.md index fdc757a5be1e..a0e3ad351f5a 100644 --- a/doc/specs/Winget Manifest Keyboard Shortcuts schema.md +++ b/doc/specs/Winget Manifest Keyboard Shortcuts schema.md @@ -18,9 +18,9 @@ All manifests and one index file are saved locally under `%LocalAppData%/Microso ### 2.3 File names -The file name of a keyboard shortcuts file is the WinGet package identifier, plus the locale of the strings of the file and at last the `.KBSC.yml` file extension. +The file name of a keyboard shortcuts file is the WinGet package identifier, plus the locale of the strings of the file and at last the `.KBSC.yaml` file extension. -For example the package "test.bar" saves its manifest with `en-US` strings in `test.bar.en-US.KBSC.yml" +For example the package "test.bar" saves its manifest with `en-US` strings in `test.bar.en-US.KBSC.yaml" #### 2.3.1 No winget package available @@ -225,9 +225,9 @@ Shortcuts: ``` -### 3.2 `index.yml` file +### 3.2 `index.yaml` file -The `index.yml` file is a file that contains all the information about the different manifest files that are saved in the same directory. This file is only available locally and is not saved in the WinGet repository as it is specific to the user. +The `index.yaml` file is a file that contains all the information about the different manifest files that are saved in the same directory. This file is only available locally and is not saved in the WinGet repository as it is specific to the user. ```yaml DefaultShellName: # The package identifier of the default shell used in Windows From 1759a84f8c46f4278edfe11688b014a69c4ac585 Mon Sep 17 00:00:00 2001 From: Aaron Junker-Wildi Date: Sun, 10 Nov 2024 11:47:27 +0000 Subject: [PATCH 7/7] add new key to index file --- .../Winget Manifest Keyboard Shortcuts schema.md | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/doc/specs/Winget Manifest Keyboard Shortcuts schema.md b/doc/specs/Winget Manifest Keyboard Shortcuts schema.md index a0e3ad351f5a..66e93e83e337 100644 --- a/doc/specs/Winget Manifest Keyboard Shortcuts schema.md +++ b/doc/specs/Winget Manifest Keyboard Shortcuts schema.md @@ -232,7 +232,8 @@ The `index.yaml` file is a file that contains all the information about the diff ```yaml DefaultShellName: # The package identifier of the default shell used in Windows Index: # List of all manifest files - - Filter: # The filter of window processes to which the shortcuts apply to + - WindowFilter: # The filter of window processes to which the shortcuts apply to + BackgroundProcess: # Optionally allows applying WindowFilter to background processes Apps: # List of all manifest files for the filter ``` @@ -248,12 +249,21 @@ Index: # List of all manifest files
- Filter - The filter of window processes to which the shortcuts apply to + WindowFilter - The filter of window processes to which the shortcuts apply to See the `WindowFilter` field in the manifest file for more information.
+
+ BackgroundProcess - Optionally allows applying WindowFilter to background processes + + **Optional field** + + See the `BackgroundProcess` field in the manifest file for more information. + +
+
Apps - List of all the package identifiers applying for the filter
@@ -264,6 +274,7 @@ Index: # List of all manifest files DefaultShellName: "+WindowsNT.Shell" Index: - Filter: "*" + BackgroundProcess: True Apps: ["+WindowsNT.Shell", "Microsoft.PowerToys"] - Filter: "explorer.exe" Apps: ["+WindowsNT.WindowsExplorer"]